neon-sprawl/.cursor/rules/story-kickoff.md

description	alwaysApply
When starting Linear issue work, set status to In Progress when applicable, create story branch, load issue + repo context; no implementation code until a plan exists under docs/plans/.	true

Story kickoff (Linear)

When the user starts work on a Linear issue (e.g. issue key NEO-5, phrases like “begin work on story”, “implement NEO-…”), run this sequence before writing or changing application code.

Clarifications (ask the user)

• 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.
• 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 §4a for Linear state after “end story”) instead of only long prose lists. AskQuestion has no recommendation field — recommendations are never optional and never deferred to the plan alone.

AskQuestion + recommendations (required order)

When you use AskQuestion for kickoff blocking decisions, follow all of this in the same assistant turn:

1. Chat first (mandatory): In the user-visible message, include a Recommend: line (or compact table) for each topic — before any AskQuestion tool call. Format: topic → recommended option → one-line rationale (repo precedent, Linear AC, or decomposition doc).
2. Then AskQuestion: Invoke the tool only after step 1 is written in chat. A turn that calls AskQuestion without step 1 is a kickoff violation — do not draft or commit the implementation plan in that turn; fix the message and re-ask.
3. Label backup: Mark the recommended option in the AskQuestion option label as well (e.g. Engine only (recommended)). This does not replace step 1; it is a fallback if the preamble is truncated.

Invalid (do not do): AskQuestion alone with bare option lists and no Recommend: preamble. Invalid: recommendations only inside docs/plans/{KEY}-implementation-plan.md before the user has answered.

Clarifications gate (hard requirement)

• Do not create or update docs/plans/{KEY}-implementation-plan.md until clarification questions have been asked and the user has answered (or explicitly says no questions are needed).
• If at least one blocking decision exists in planning, use AskQuestion (Agent mode) per AskQuestion + recommendations (required order) above — not prose-only lists, and not AskQuestion without a Recommend: preamble.
• If kickoff has zero questions, explicitly record why in the plan under a Kickoff clarifications section with evidence from Linear + repo context.
• Do not commit a kickoff plan until the clarification step above is complete.

1. Load Linear context

• Fetch the issue when possible (Linear MCP get_issue / list_issues, server plugin-linear-linear), or use a URL / pasted description the user provides.
• Capture summary, description, acceptance criteria, and anything explicitly out of scope.
• Hierarchy: Expect Project → Issue (epics/modules map to Linear projects). Do not recreate a Jira-style Feature tier—module / slice grouping is labels on the issue (see Linear alignment in the decomposition README).

1a. Board status (To Do → In Progress)

• After the issue is known, if its status is To Do (or your workflow’s equivalent “not started” state), transition it to In Progress so the board matches active kickoff.
• When Linear MCP is available: save_issue with state set to In Progress (or your team’s equivalent); otherwise update status in the Linear UI.
• If the issue is already In Progress or later, do not move it backward.

1b. Story branch

• Create and use a new branch for this issue as soon as story work begins (planning counts). Name it with the Linear issue id first and a short kebab-case slug (e.g. NEO-6-position-state-api); see linear-git-naming and git workflow.
• If the user is already on a branch whose first path segment matches this issue key, continue on it unless they ask to rename.
• Do not wait for implementation to start before branching; the implementation plan and all story commits belong on this branch.

2. Load codebase context (read-only)

• Open only what the story implies: entry scenes/scripts, related modules, configs, tests/CI, and relevant docs/ files.
• No edits and no new implementation or test files in this phase.

3. No implementation yet

• Do not add or change source, Godot scenes/project, game data pipelines, or automated tests until step 4 is done and the user has moved past planning in chat (e.g. explicit go-ahead to implement).

4. Planning document

• Add docs/plans/{LINEAR_ISSUE_ID}-implementation-plan.md (example: docs/plans/NEO-5-implementation-plan.md). Create docs/plans/ if it does not exist.
• Commit the plan on the story branch from step 1b when it is ready (at agent discretion per commit-and-review); do not put ticketed plan-only work only on main while implementation stays on a branch—see git workflow.

Required sections in that file (do not ship a plan that omits any of these):

• Story reference (key, title, link if available)
• 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 — 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.

• The plan is living documentation: any decisions during planning chat or implementation (options A/B, resolved risks, scope changes) must be reflected in docs/plans/{KEY}-implementation-plan.md (and other docs/ when the decision affects integration). See planning-implementation-docs.

5. After the plan

• Implement only after the user confirms. All implementation commits stay on the same story branch from step 1b; follow git workflow.
• Before handoff or merge, reconcile the plan with what shipped (acceptance checkboxes, Decisions, open questions) per planning-implementation-docs.

When the story is done and merged to main, follow story-end to return to main, pull, and remove the local story branch.

When the user asks to open or create a PR for this story, follow commit-and-review Opening a PR when the user asks: use the GitHub MCP create_pull_request tool with a title that starts with the Linear key (e.g. NEO-25:), not GitHub’s default title from the web UI alone.