30 lines
2.0 KiB
Markdown
30 lines
2.0 KiB
Markdown
---
|
|
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. |
|
|
|
|
## 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.
|
|
|
|
This complements [story-kickoff](story-kickoff.md) (plan creation) and [code-review-agent](code-review-agent.md) (documentation checked vs plans and decomposition).
|