diff --git a/.cursor/rules/code-review-agent.md b/.cursor/rules/code-review-agent.md index ef9f217..b920bac 100644 --- a/.cursor/rules/code-review-agent.md +++ b/.cursor/rules/code-review-agent.md @@ -80,6 +80,15 @@ Use this structure in **both** the saved document and (abbreviated if you want) In **chat only**, you may use Cursor line-number **code citations** when referencing existing code. For hypothetical fixes, use normal fenced code blocks everywhere. +## Resolved suggestions (mandatory when feedback is addressed) + +If you **implement** changes that resolve **blocking issues**, **suggestions**, or agreed **nits** from an existing **`docs/reviews/…`** file for the same work: + +- **Edit that review document** in the same commit or the immediate follow-up commit: add or update **`## Resolved suggestions`** / **`## Follow-up`** per [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up**. +- Do **not** ship code-only fixes while the saved review still reads as if those items were open. + +The **initial** review does not need an empty “Resolved” section; this rule applies when **closing the loop** after the review exists. + ## Boundaries - Do **not** skip writing `docs/reviews/…`; the document is mandatory output of this agent. diff --git a/.cursor/rules/commit-and-review.md b/.cursor/rules/commit-and-review.md index a22c4ba..63199f0 100644 --- a/.cursor/rules/commit-and-review.md +++ b/.cursor/rules/commit-and-review.md @@ -29,3 +29,7 @@ alwaysApply: true ## Scope - Applies to **all** commits the agent might make, including **documentation-only** changes (e.g. `docs/plans/`, `docs/reviews/`, README), not only application source. + +## Code review follow-up + +When commits **address** feedback from a saved **`docs/reviews/…`** file, include an update to **that review file** documenting what was resolved (or explicitly deferred/declined). See [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up** and [code-review-agent](code-review-agent.md) **Resolved suggestions**. diff --git a/.cursor/rules/docs-review-agent.md b/.cursor/rules/docs-review-agent.md index 2d810b7..f315c2f 100644 --- a/.cursor/rules/docs-review-agent.md +++ b/.cursor/rules/docs-review-agent.md @@ -66,6 +66,10 @@ In the saved file, use **normal fenced code blocks** and **backtick paths** — **Chat:** Short summary + **path to** `docs/reviews/YYYY-MM-DD-{slug}.md`. +## Resolved suggestions (mandatory when feedback is addressed) + +If later edits **address** **blocking issues**, **suggestions**, or **nits** from a **docs-review** `docs/reviews/…` file, **update that review file** with **`## Resolved suggestions`** / **`## Follow-up`** per [planning-implementation-docs](planning-implementation-docs.md) **Code review follow-up** (same audit trail as code reviews). + ## Boundaries - Do **not** skip writing `docs/reviews/…` unless the user explicitly asks for **chat-only** (then state that exception in chat and **do not** claim full agent output). diff --git a/.cursor/rules/planning-implementation-docs.md b/.cursor/rules/planning-implementation-docs.md index 160698e..a9466e0 100644 --- a/.cursor/rules/planning-implementation-docs.md +++ b/.cursor/rules/planning-implementation-docs.md @@ -15,6 +15,14 @@ Whenever you **decide** something during **story planning** or **implementation* | Cross-cutting or module contract | Relevant **`docs/decomposition/modules/*.md`**, **`docs/game-design/`**, or **`README`** / **`server/README.md`** / **`client/README.md`** when the decision affects how others integrate. | | Review findings | **`docs/reviews/…`** when using the code-review agent; link back to the plan if the review changed direction. | +## Code review follow-up (resolved suggestions) + +When **blocking issues**, **suggestions**, or agreed **nits** from a saved **`docs/reviews/YYYY-MM-DD-*.md`** are **fixed** in code or other docs, **update that review file** in the **same** change-set or the **next** commit on the story branch—do **not** only fix the code and leave the review implying feedback is still open. + +- Add or extend a section such as **`## Resolved suggestions`** or **`## Follow-up`**: for **each** item from the review that you addressed, record **what** changed and **where** (paths or commits). Match the review’s numbering or headings so readers can correlate. +- Items **declined**, **out of scope**, or **deferred** to a ticket: state that in the same section so the audit trail is honest. +- Applies to **any** agent pass that implements review feedback, not only a second invocation of the code-review agent—see [code-review-agent](code-review-agent.md) **Resolved suggestions**. + ## What to capture - **What** was chosen (or rejected) and **why** in one short paragraph or bullets. @@ -25,5 +33,6 @@ Whenever you **decide** something during **story planning** or **implementation* - After **kickoff**, the plan is living: **amend it** when implementation choices differ from the draft. - Before **closing** or **handing off** a story, skim the plan: open questions should be **resolved** or restated as follow-up tickets with pointers. +- After **implementing** review feedback, **edit the corresponding `docs/reviews/…` file** per **Code review follow-up** above—this step is easy to skip; treat it as **required** whenever suggestions were listed in that review. This complements [story-kickoff](story-kickoff.md) (plan creation) and [code-review-agent](code-review-agent.md) (documentation checked vs plans and decomposition). diff --git a/AGENTS.md b/AGENTS.md index a442721..8e360a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,8 @@ Optional **personas** for Cursor. Enable by **@ mentioning** the rule in chat or | Agent | Rule file | When to use | |--------|-----------|-------------| -| **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` with **Documentation checked** vs `docs/plans/` and `docs/decomposition/modules/`; short chat pointer | -| **Docs review** | [`.cursor/rules/docs-review-agent.md`](.cursor/rules/docs-review-agent.md) | Coherence / links / dev-guide fitness for `docs/` (especially `docs/game-design/` + decomposition); **writes** `docs/reviews/YYYY-MM-DD-{slug}.md`; use when working in **documents** or @ mention | +| **Code review** | [`.cursor/rules/code-review-agent.md`](.cursor/rules/code-review-agent.md) | PR / diff / pre-merge review; **always writes** `docs/reviews/YYYY-MM-DD-{slug}.md` with **Documentation checked** vs `docs/plans/` and `docs/decomposition/modules/`; **when suggestions are fixed, update that review file** ([planning-implementation-docs](.cursor/rules/planning-implementation-docs.md)); short chat pointer | +| **Docs review** | [`.cursor/rules/docs-review-agent.md`](.cursor/rules/docs-review-agent.md) | Coherence / links / dev-guide fitness for `docs/` (especially `docs/game-design/` + decomposition); **writes** `docs/reviews/YYYY-MM-DD-{slug}.md`; **when suggestions are fixed, update that review file** ([planning-implementation-docs](.cursor/rules/planning-implementation-docs.md)); use when working in **documents** or @ mention | Project-wide conventions live under [`.cursor/rules/`](.cursor/rules/) (many are `alwaysApply`). **Planning / implementation decisions** must be written into `docs/plans/` (and related docs)—[`.cursor/rules/planning-implementation-docs.md`](.cursor/rules/planning-implementation-docs.md). **Godot client layout** (thin `main.gd`, split by concern): [`.cursor/rules/godot-client-script-organization.md`](.cursor/rules/godot-client-script-organization.md). **Git:** agents may **commit** at discretion on story/ticket work; **never** `git push` unless the user asks — [`.cursor/rules/commit-and-review.md`](.cursor/rules/commit-and-review.md). **Story lifecycle:** kickoff [`.cursor/rules/story-kickoff.md`](.cursor/rules/story-kickoff.md); after merge / end of story — `checkout main`, `pull`, delete local story branch — [`.cursor/rules/story-end.md`](.cursor/rules/story-end.md). **PR / push text:** no “Made-with: Cursor” boilerplate (same file).