ping-mee-self-service-platform/.agents/skills/bmad-code-review/step-01-gather-context.md

diff_file, claims_file, plan_file, review_mode

diff_file	claims_file	plan_file	review_mode

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:
   • 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; 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.
   • 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) and treat its plan as a plan file from the request.
   • 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.
   • 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 %}

2. 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.

3. 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.

4. 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.

5. Set the plan context.

   • The request or conversation explicitly says there is no plan → review_mode = no-plan, plan_file = ''. Do not ask.
   • 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 %}

6. 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.

7. 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 loaded plan/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") }}