---
description: Planning and implementation decisions must be written back into docs (plans, README, decomposition) so Jira chat and files stay aligned.
alwaysApply: true
---

# Planning and implementation documentation

Whenever you **decide** something during **story planning** or **implementation** (architecture pick, scope cut, “option A vs B”, test strategy, resolved risk), **reflect it in documentation** in the same pass or before the story is considered done—do not leave decisions only in chat.

## Where to write

| Situation | Update |
|-----------|--------|
| Ticketed story work | **`docs/plans/{JIRA_KEY}-implementation-plan.md`** — add or edit a **Decisions** subsection, **resolve** former open questions, refresh **Technical approach** / **Acceptance criteria** checkboxes, and **Files to add/modify** if reality diverged from kickoff. |
| 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.
- **Outcomes** of verification (e.g. “`dotnet test` N passed; double-dispose safe on Npgsql 10”).
- If the user **explicitly** chose an option (e.g. “Option 2”), record that label so future readers do not re-litigate.

## Agent behavior

- 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).