---
description: 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/.
alwaysApply: 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](story-end.md) §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](../../docs/decomposition/README.md#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](linear-git-naming.md) and [git workflow](git-workflow.md).
- 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/`](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).

**Full-stack:** If the story is **server-only** but **player-visible** (HTTP API without Godot yet), the kickoff plan must **cross-link** the **client counterpart** Linear issue from the module backlog ([full-stack-epic-decomposition](full-stack-epic-decomposition.md)). Do not treat Bruno-only verification as prototype-complete.

## 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](commit-and-review.md)); do not put ticketed plan-only work only on `main` while implementation stays on a branch—see [git workflow](git-workflow.md).

**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](planning-implementation-docs.md).

## 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](git-workflow.md).
- Before handoff or merge, **reconcile the plan** with what shipped (acceptance checkboxes, **Decisions**, open questions) per [planning-implementation-docs](planning-implementation-docs.md).

When the story is **done** and merged to `main`, follow [story-end](story-end.md) 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](commit-and-review.md) **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.
