3.1 KiB
3.1 KiB
| description | alwaysApply |
|---|---|
| Planning and implementation decisions must be written back into docs (plans, README, decomposition) so Jira chat and files stay aligned. | 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 suggestionsor## 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 Resolved suggestions.
What to capture
- What was chosen (or rejected) and why in one short paragraph or bullets.
- Outcomes of verification (e.g. “
dotnet testN 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 (plan creation) and code-review-agent (documentation checked vs plans and decomposition).