neon-sprawl/.cursor/rules/planning-implementation-docs.md

description	alwaysApply
Planning and implementation decisions must be written back into docs (plans, README, decomposition) so Linear and the repo 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/{LINEAR_ISSUE_ID}-implementation-plan.md (e.g. NEO-7-…) — 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.
Manual QA steps for ticketed story work	docs/manual-qa/{LINEAR_ISSUE_ID}.md — see Manual QA checklist below.
Review findings	docs/reviews/… when using the code-review agent; link back to the plan if the review changed direction. When feedback is fixed, strike through + Done. on the original bullets in that review file — see Code review follow-up below.

Manual QA checklist

For ticketed story work that produces user-visible behavior (UI, input bindings, HTTP surfaces, scene wiring, runtime config, etc.), generate a checklist at docs/manual-qa/{LINEAR_ISSUE_ID}.md (example: docs/manual-qa/NEO-24.md) during implementation—not after handoff. The checklist complements automated tests; it captures the things a human needs to exercise end-to-end against real processes (server + client, database, input hardware) that unit / integration tests do not cover.

• When to create: at the end of implementation, once code is stable enough to exercise. Commit it on the story branch alongside the implementation commits; do not defer to a separate PR.
• When to skip: pure refactors, docs-only changes, or stories whose acceptance is fully covered by automated tests (state that reason in one line in the plan's Tests section instead of creating an empty checklist).
• File header: a small table with Key, Title, Linear link, Plan link back to docs/plans/{KEY}-implementation-plan.md, and the story Branch.
• Body: numbered sections grouped by concern (e.g. Setup sanity, Happy path, Edge cases / failure modes, No regressions), each with - [ ] checkbox bullets that are concrete and observable—name the UI label, the server route, the console message, the expected state. Avoid vague asks like "test it works."
• Coverage cues: include at least (a) a boot / baseline section, (b) each acceptance criterion from the plan exercised by a concrete user action, (c) relevant denial / failure paths (HTTP 4xx, server down, invalid input), (d) coexistence / no regressions with neighboring features the story touches.
• Keep it current: if implementation reveals a new failure mode or a changed binding, update the checklist in the same commit. Any Done. / Deferred follow-ups from a QA pass belong back in the plan's Decisions or Open questions, not as strikethroughs on the checklist.

The checklist is for the user (or a reviewer) to execute; the agent generates it but does not tick the boxes on the user's behalf unless the user explicitly confirms a section was exercised.

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, edit that same review file in the same change-set or the next commit—do not only fix the code and leave the review implying feedback is still open.

• In place under the original headings (## Suggestions, ## Nits, ## Blocking issues): strike through the resolved bullet with ~~…~~, then add Done. / Addressed. / Deferred… and a one-line note (what changed, paths, optional commit SHA). Optionally add a one-line Follow-up note under the title (after Scope/Base) when all suggestions are done, e.g. “suggestions below are done (strikethrough + Done.)”. Same pattern as docs/reviews/2026-03-30-NEO-8.md, 2026-04-05-NEO-14.md.
• Do not add a separate “Resolved suggestions” / “Follow-up implemented” section for items that already live under Suggestions or Nits—the strikethrough row is the audit trail.
• Items declined or deferred to a ticket: still strike through or annotate inline under the same bullet so the review stays honest.
• Applies to any agent pass that implements review feedback—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 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.
• For open questions still in the plan at kickoff or mid-story, keep the agent recommendation alongside each item (see story-kickoff Kickoff clarifications and Open questions / risks); when resolved, move the outcome to Decisions and clear or update the open-question row.

Agent behavior

• After kickoff, the plan is living: amend it when implementation choices differ from the draft.
• During implementation, generate docs/manual-qa/{KEY}.md per Manual QA checklist above for any story with user-visible behavior; commit it on the story branch before handoff.
• Before closing or handing off a story, skim the plan: open questions should be resolved or restated as follow-up tickets with pointers, and the manual QA checklist should exist (or be explicitly declined in the plan).
• After implementing review feedback, edit the corresponding docs/reviews/… file with strikethrough + Done on the original bullets 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).