don
/
neon-sprawl
mirror of https://github.com/ViPro-Technologies/neon-sprawl
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
neon-sprawl/.cursor/rules/planning-implementation-doc...

3.7 KiB
Raw Blame History

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

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.

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