Starting a ticket

1. Read the ticket

Read the ticket and its comments in full. Then show it on the status line: bash .claude/skills/start-ticket/set-status.sh <ticket> "<title>" preparation, and label it for humans: gh issue edit <ticket> --add-label WIP (create the label first if it is missing).

Resuming: if a comment is a handoff from an earlier session, follow it instead of steps 2–5: check its plan still fits current main, report any change to the user, and start its next PR.

2. Explore the codebase

Find the code the ticket touches and what it can reuse, before asking anything: a question the code answers is not one to put to the user.

3. Settle the open questions

List what you need to get the intention and the details right. Sort each question:

• Obvious — one answer follows from the ticket, the code or the project's principles. Decide it yourself and report the decision.
• Not obvious — ask the user.

Both start the same way, explained step by step from what a user of the product would see, not in implementation terms:

• Where: UI — which part of the screen; backend — which route; edge case — how it happens; principle violation — which principle and which requirement.
• Problem: what is unsettled, in user terms.

A decision then gives:

• Decision: the choice made.
• Why: the reason, and the preference that would flip it — "the simplest design, unless correctness in every edge case is preferred" — so the user sees the tradeoff.

A question to the user then gives labeled choices (a, b, c), each with a concrete example — input and result, or for timing and concurrency a short lane timeline in a code block — the principles it keeps or bends, and its cost in one line. Ask one question at a time, in plain text, and invite a free-form answer; it is often a principle that makes a third option.

4. Choose the design route

Use the module-design skill for every change except trivial ones like a rename.

5. Plan and get approval

Show the plan to the user and wait for approval before coding. Obvious questions that come up after approval are decided and reported the same way; the important ones also go in the PR description.

The plan includes the PR split. Decide it yourself: 1 to 4 PRs. Do not ask the user how to split the ticket; they review the split in the plan and can object there. Each PR can be reviewed and merged on its own and leaves main working. The PRs go one at a time, each based on main and opened after the previous one merges, never stacked (open-pr says why). Prefer fewer PRs; split only where one PR would touch too many files to review, or where an early PR unblocks the rest. Give one line per PR: its scope and the files it touches.

When starting work on each PR, run bash .claude/skills/start-ticket/set-status.sh <ticket> "<title>" <i> <total>; it stays after the PR opens, as context for reviewing it. open-pr's cleanup removes the WIP label after the last PR. Run it from the main checkout, as a worktree has no .claude/skills; then create the PR's worktree and write the code there.

6. One PR per session

A session's cost grows with the square of its turns, so each session writes one PR. Once a PR that is not the last opens, post a handoff comment on the ticket. open-pr removes the worktree once the PR is pushed; review fixes happen in a new session. The next session starts after the merge, from step 1. The handoff holds only what main and the merged PRs do not:

• the remaining PRs, one line each, as in the plan;
• links to the PRs opened so far;
• decisions about the remaining PRs, the same shape as in step 3, that no PR description has.

The build docs reach the next session through main (module-design keeps them until the module's last PR).