Step 1: Gather Context

RULES

• The triggering prompt and the conversation before it name the review target — act on them; do not start from a blank slate.
• Writing {diff_file} and the claims file is the only change this step may make. Otherwise it is read-only.

{% if not workflow.interactive %}

• No human can answer during this run: never ask and never HALT for input. Wherever an instruction below would ask, take the default it names instead; where it names none, stop and report what is missing.

{% endif %}

INSTRUCTIONS

1. Find the review target. Check in this order and stop at the first that identifies it:
2. Request or recent conversation. A PR (resolve via gh pr view; if that fails, ask for a SHA or branch), commit, branch, commit range, staged or uncommitted changes, a provided diff or file list, or a plan file. A plan sets plan_file, and when its frontmatter ticket is set, tickets.py find <the plan's folder> <ticket> (command form in the next bullet) names the ticket to read the same way; a non-empty frontmatter baseline_revision other than NO_VCS makes the diff source the plan baseline — otherwise say so and continue, since a plan without one does not identify the diff.
3. The ticket tree. Run uv run {project-root}/_bmad/method/scripts/tickets.py --project-root {project-root} status. On a non-zero exit, continue. Otherwise offer the tickets rows whose state is review, <ref> and <title> each, plus a choice of another target, and HALT for the user's pick. With none, or another target chosen, continue. For a picked ticket, run tickets.py find <ref> (same command form): set ticket_file to its story_file, else its epic_file, read that file in full (with story_file null, the entry's description and verify are in find's output), and treat its plan as a plan file from the request.
4. Current git state. If HEAD is not on the default branch, confirm: "I see HEAD is <short-sha> on <branch> — do you want to review this branch's changes?" If confirmed, it is a branch diff against the default branch.
5. Ask. Go to instruction 2.

{% if not workflow.interactive %} Skip the ticket-tree offer, take the current branch's diff against the default branch without confirming, and if HEAD is on the default branch and nothing else identifies a target, stop and report that there is nothing identified to review. {% endif %}

1. HALT. Ask the user what to review: uncommitted changes, staged changes, a branch diff (which base), a commit range, or a provided diff or file list.

1. Write the diff to {diff_file}, a uniquely-named temp file outside the repository, so concurrent reviews cannot collide. A plan baseline diffs every change since baseline_revision, untracked files included. A branch diff runs from the merge-base (<base>...HEAD), so later commits on the base do not show up as reverted. For a file list, include untracked files. If the source does not resolve, HALT and ask for a valid one; if the diff is empty, HALT — there is nothing to review. The review lenses read that file; the diff text is never pasted into their prompts. Read {diff_file} yourself when you need the diff later in this workflow.

1. Stage the claims file. Collect the change's own narrative: for a plan baseline, branch diff, or commit range, the commit messages it covers (git log <base>..<head>, where a plan baseline's head is HEAD); for other sources, whatever description of the change the user or conversation supplied. Write it verbatim to another uniquely-named temp file outside the repository and set claims_file to its path, or '' if there is none. Do not analyze or summarize it — it is input for one review lens, staged as a file so the other lenses never see it.

1. Set the plan context.
2. The request or conversation explicitly says there is no plan → review_mode = no-plan, plan_file = ''. Do not ask.
3. plan_file is set → verify it is readable; review_mode = full.

{% if workflow.interactive %}

• Otherwise, ask for a plan file path, or to continue without one, and set plan_file and review_mode accordingly. Do not assume no-plan just because none was given.

{% else %}

• Otherwise → review_mode = no-plan, plan_file = ''.

{% endif %}

1. If review_mode = full and {plan_file}'s frontmatter has a context list, load each referenced doc and warn about any that cannot be found. Open a file {ticket_file} lists in sources: or companions: only for a section the ticket cites; never re-derive requirements from it.

1. If {diff_file} exceeds about 3000 lines, warn the user and offer to chunk the review by file group. If they accept, agree on the first group, rebuild {diff_file} for it, and list the remaining groups for follow-up runs.

CHECKPOINT

Present a summary before proceeding: diff stats (files changed, lines added/removed), {review_mode}, and the loaded ticket, plan, and context docs (if any). {% if workflow.interactive %} HALT and wait for user confirmation to proceed. {% endif %}

NEXT

Read fully and follow {{ rendered("step-02-review.md") }}