BMAD-METHOD/src/bmm-skills/4-implementation/bmad-checkpoint-preview/step-01-orientation.md

Step 1: Orientation

Display: [Orientation] → Walkthrough → Detail Pass → Testing

RULES

• The conversation context before this skill was triggered IS your starting point — not a blank slate.
• The user may have already mentioned a spec file, a commit, a branch, a PR, or described the change. Use what they gave you.
• For PR references, resolve to a commit or branch using whatever tools are available (e.g., gh pr view for GitHub). If resolution fails, ask for a SHA or branch.

FIND THE CHANGE

1. What did the user already tell you? Look at the conversation for a spec path, commit ref, branch, PR, or description of the change.

2. Fill in the other half. If they gave a spec, look for baseline_commit in its frontmatter. If they gave a commit, check {implementation_artifacts} for a spec whose baseline_commit matches. If they gave both, use both.

3. If they gave nothing, check current branch and HEAD. Confirm: "I see HEAD is <short-sha> on <branch> — is this the change you want to review?"

4. If you still can't identify a change, ask:

   • What changed and why?
   • Which commit, branch, or PR should I look at?
   • Do you have a spec, bug report, or anything else that explains what this change is supposed to do?

   If after 3 exchanges you still can't identify a change, HALT.

DETERMINE WHAT YOU HAVE

Set change_type based on how the user referred to the change:

User referenced	change_type
A pull request	PR
A commit	commit
A branch	branch
A description (e.g. "the auth refactor")	use their words (e.g. auth refactor)
Nothing specific / ambiguous	change

What you have	Review Mode	Intent Source
Spec with ## Suggested Review Order	full-trail	Spec's Intent section
Spec without trail	spec-only	Spec's Intent section
Commit ref, no spec	bare-commit	Commit message

Terse commit messages (under 10 words): Scan the diff for the primary change pattern and draft a one-sentence intent. Confirm with the user before proceeding.

PRODUCE ORIENTATION

Intent Summary

• If intent comes from a spec's Intent section, display it verbatim regardless of length — it's already written to be concise.
• For other sources (commit messages, bug reports, user description): if ≤200 tokens, display verbatim. If longer, distill to ≤200 tokens and link to the full source.
• Format: > **Intent:** {summary}

Surface Area Stats

Compute from git diff --stat against the appropriate baseline:

• With spec: Use baseline_commit from frontmatter. If missing, diff HEAD~1..HEAD and tell the user stats reflect only the latest commit.
• Bare commit: Diff against parent (commit~1..commit). For merge commits, use --first-parent. For initial commits, diff against the empty tree (4b825dc..commit).

Display as:

N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces

• Files changed: from git diff --stat
• Modules touched: distinct top-level directories with changes
• Lines of logic: added/modified lines excluding blanks, imports, formatting. ~ because approximate.
• Boundary crossings: changes spanning more than one top-level module. 0 if single module.
• New public interfaces: new exports, endpoints, public methods. 0 if none.

If git is unavailable or a command fails, show what you can and note what's missing.

Present

[Orientation] → Walkthrough → Detail Pass → Testing

> **Intent:** {intent_summary}

{stats line}

FALLBACK TRAIL GENERATION

Skip this section if review mode is full-trail.

When no Suggested Review Order exists, generate one from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.

1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats).
2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss.
3. If a spec exists, use its Intent section to anchor concern identification.
4. Identify 2–5 concerns: cohesive design intents that each explain why behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
5. For each concern, select 1–4 path:line stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
7. Format each stop as a workspace-relative markdown link — basename and line as link text, path with #L anchor as target:

**{Concern name}**

- {one-line framing, ≤15 words}
  [`file.ts:42`](/src/path/to/file.ts#L42)

When there is only one concern, omit the bold label — just list the stops directly.

Present after the orientation output:

I built a review trail for this {change_type} (no author-produced trail was found):

{generated trail}

Set review mode to full-trail. The generated trail is the Suggested Review Order for subsequent steps.

If git is unavailable or the diff cannot be retrieved, skip this section and proceed with the original review mode. Note: "Could not generate trail — git unavailable."

NEXT

Read fully and follow ./step-02-walkthrough.md