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

description	alwaysApply
When starting Jira story work, move issue To Do → In Progress when applicable, create story branch, load issue + repo context; no implementation code until a plan exists under docs/plans/.	true

Story kickoff (Jira)

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

1. Load Jira context

• Fetch the issue when possible (e.g. Atlassian MCP getJiraIssue), or use a URL / pasted description the user provides.
• Capture summary, description, acceptance criteria, and anything explicitly out of scope.

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 Atlassian MCP is available: getTransitionsForJiraIssue to find the transition id for In Progress, then transitionJiraIssue; otherwise do the same in the Jira 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 Jira key first and a short kebab-case slug (e.g. NS-15-position-state-api); see jira-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/{JIRA_KEY}-implementation-plan.md (example: docs/plans/NS-14-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 Jira)
• Acceptance criteria checklist (from Jira)
• 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.

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.

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