review-path
Plans a human-friendly reading order for a diff — comprehension, not bug-finding.
Given a change — unstaged/staged work, a commit or range, or a GitHub PR number — this skill produces a review path: the order a human should read the changed files, how the files group, and how much attention each deserves. It explicitly does not hunt for bugs; that is xiv-review-core's job. The two are complementary halves of "review": one finds the problems, this one helps a person understand the change.
Invoke it when someone asks for a review order, a guided review, file criticality, an attention budget, or help understanding a PR before reading it line by line.
How it works
It is a single SKILL.md with an eight-step workflow:
- Resolve the diff source —
git diff/git diff --cachedfor worktree changes, range diffs for commits,gh pr view/gh pr difffor a PR number. Ambiguous input defaults to the safest local option: current staged plus unstaged changes. - Inventory every changed file, including renames, deletions, lockfiles, generated output, docs, and tests — reading surrounding source when the diff alone doesn't reveal a file's role.
- Infer one dominant review angle and state it in one sentence.
- Cluster related files by subsystem or concern (for anything beyond a handful).
- Order for comprehension — cause before effect, coupled files adjacent, so the reviewer traces one shape through the change instead of hopping.
- Assign criticality per file:
low,med,high, orcrit. - Set the attention budget — where the bulk of attention goes, and what can be skimmed.
- Return only the review path — no bug lists, no line comments, no merge advice.
Review angles
The angle is the organizing principle for the whole path. The skill ships six and allows inventing others:
| Angle | Sequence |
|---|---|
| Data flow | entrypoint → validation → core logic → persistence/side effects → tests |
| Contract first | API/schema/types/migrations → producers → consumers → tests |
| Core first | domain logic → adapters/wrappers → UI/CLI/workflows → tests |
| Risk first | security/auth/data-loss/migration files → dependents → cleanup |
| Surface first | user-facing view/command → state/data hooks → implementation → tests |
| Mechanical last | behavior files first, then renames, barrels, formatting, generated output |
Criticality comes from signals, not diff size
Attention is raised toward high/crit by blast radius (high fan-in, public contracts, shared
utilities), risk domain (auth, money, data writes, migrations, concurrency, untrusted input),
change shape (deletions, new dependencies, config/secret changes), contract seams, and
uncertainty — a file whose role couldn't be determined is flagged for human eyes, never hidden.
Attention drops toward low for formatting, generated output, lockfiles, barrels, and mechanical
renames.
Two calibration rules stand out: a one-line change to a widely-imported module outranks a large isolated one, and tests written in the same diff don't count as existing coverage — they may assert the new behavior rather than the intended one.
Output
A fixed markdown structure: the review angle in one sentence, a one-line attention budget, then per-cluster tables with columns for order, file, criticality, "why here", and "focus". Small diffs collapse to a single table. Every changed file appears exactly once, with mechanical/low files grouped near the end.
Guardrails
Strictly read-only — never commits, pushes, posts comments, or submits reviews — and strictly a map for reading the diff: no bug findings, no approval or merge recommendations, no architecture essay. It has no CLI hook; it's a standalone skill any agent can apply to any diff, including the PRs that xiv stack push opens.