diff --git a/.cursor/rules/planning-implementation-docs.md b/.cursor/rules/planning-implementation-docs.md index 50410d6..f28edf6 100644 --- a/.cursor/rules/planning-implementation-docs.md +++ b/.cursor/rules/planning-implementation-docs.md @@ -43,6 +43,7 @@ When **blocking issues**, **suggestions**, or agreed **nits** from a saved **`do - **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](story-kickoff.md) **Kickoff clarifications** and **Open questions / risks**); when resolved, move the outcome to **Decisions** and clear or update the open-question row. ## Agent behavior diff --git a/.cursor/rules/story-kickoff.md b/.cursor/rules/story-kickoff.md index b5d9503..fe17602 100644 --- a/.cursor/rules/story-kickoff.md +++ b/.cursor/rules/story-kickoff.md @@ -11,7 +11,8 @@ When the user starts work on a **Linear issue** (e.g. issue key `NEO-5`, phrases - During kickoff and while drafting the plan, **ask the user** about anything **unclear**, **underspecified**, or that **needs a decision** (scope, behavior, acceptance criteria, priorities, trade-offs, or what is out of scope). Do not guess or pick silent defaults when the issue, Linear notes, or repo context do not settle it. - Use **concrete questions**, often with short options when helpful; group related questions so the user can answer in one pass. -- When the Cursor session supports it (**Agent** mode), prefer **`AskQuestion`** multiple-choice for blocking decisions (same pattern as [story-end](story-end.md) §4a for **Linear state** after “end story”) instead of only long prose lists. +- For **every** question or blocking decision presented to the user, state the **agent’s recommendation**: which option to pick (or what to do) and a **one-line rationale** tied to repo precedent, Linear AC, or decomposition docs. Do not list options without a stated preference unless there is genuinely no basis to recommend—in that case, say why. +- When the Cursor session supports it (**Agent** mode), prefer **`AskQuestion`** multiple-choice for blocking decisions (same pattern as [story-end](story-end.md) §4a for **Linear state** after “end story”) instead of only long prose lists. Put the **agent recommendation** in the chat message that introduces the questions (`AskQuestion` has no recommendation field). ### Clarifications gate (hard requirement) @@ -55,14 +56,14 @@ When the user starts work on a **Linear issue** (e.g. issue key `NEO-5`, phrases **Required sections** in that file (do **not** ship a plan that omits any of these): - Story reference (key, title, link if available) -- Kickoff clarifications (questions asked + answers, or explicit “No clarifications needed” with reason) +- Kickoff clarifications — table with **Topic**, **Question**, **Agent recommendation**, **Answer** (or explicit “No clarifications needed” with reason; no table required when zero questions) - Goal, scope, and out-of-scope (from Linear) - Acceptance criteria checklist (from Linear) - Technical approach (concise) - **Files to add** — **mandatory:** explicit list of new file paths (or state “none” with one line why) - **Files to modify** — **mandatory:** explicit list of paths **with a one-line rationale each** (or state “none” with one line why) - **Tests** — **mandatory:** explicit list of test files to **add** or **change**, and what each will cover; if truly no automated tests, say why (e.g. no harness yet) and what manual verification replaces them -- Open questions / risks (if none, write “None.”) +- Open questions / risks — each item: **question or risk**, **agent recommendation**, **status** (`pending` / `adopted` / `deferred`); if none, write “None.” These three lists (**files to add**, **files to modify**, **tests**) must **always** be generated during kickoff—they are not optional prose and must not be left implicit inside “Technical approach” only.