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.

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

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.