flow-pr-review

Files (23)

• SKILL.md
• evals.json · evals/
• agent-prompts.md · references/
• bug-detection.md · references/checklists/
• pattern-consistency.md · references/checklists/
• performance.md · references/checklists/
• product.md · references/checklists/
• security.md · references/checklists/
• supply-chain.md · references/checklists/
• test-coverage.md · references/checklists/
• conventional-comments.md · references/
• delegated-lenses.md · references/
• deployment-followup-checklist.md · references/
• escalation-recipes.md · references/
• fix-applier-spawn-prompt.md · references/
• gemini-lens-run.md · references/
• intent-mismatch-resolution.md · references/
• manual-test-rubric.md · references/
• report-template.md · references/
• result-artifact-write-protocol.md · references/
• review-scope.md · references/
• task-tool-exemption-preamble.md · references/
• ui-validation-evidence.md · references/

SKILL.md (first lines)

# Goal

Perform a thorough, multi-agent independent code review of a PR and (when present) address
all existing review comments — using conventional comment labels with confidence scoring,
running pre-commit checks, and producing a structured report. The skill improves over time
by learning from gaps between its findings and human reviewer feedback.

# When to Use

- User wants to address review comments on a PR (Copilot, human reviewers, etc.)
- User pastes a PR URL or number and asks for review or feedback
- User says "address PR feedback", "fix review comments", "review PR", "code review"
- User wants an independent code review before requesting human review
- User wants to verify a PR is ready to merge

# When NOT to Use

- For creating a new PR — use git commands directly
- For running pre-commit checks only — use the `verify` skill
- For code review not tied to a specific PR — just review the files directly

# Context

Helpers (installed globally by `flow install` and on PATH):

- `flow-fetch-pr-review` — fetches PR metadata, description, changed files, review
  summaries, and inline comments from GitHub
- `flow-pr-diff` — wraps `gh pr diff <number>`, per-file caps each block at 300 source lines. `capDiff` is reused by `flow-review-scope`; direct use is now only the Gemini-lens fallback (L682) — agents Read changed files in full, so the diff is a hint, not the source of truth.
- `flow-review-scope` — resolves Step 3's `full`/`delta` scope + per-lens gates, writes the capped diff and synthetic gated-lens artifacts.
- `flow-review-telemetry` — `collect`/`print`: per-lens counts feeding the Step 12 `### Lens telemetry` section.
- `flow-pr-static-analysis` — runs the consumer's installed static-analysis tools
  (semgrep, biome/eslint, tsc), parses each into a unified
  `{file, line, rule_id, confidence, severity, source}` shape filtered to PR-touched
  lines, and emits a combined JSON envelope keyed by lens (`{security, types, lint,
  meta}`, default `--min-confidence 80`). Used at Step 3 so each agent receives only
  its lens subset. Tool-presence detection is graceful: a missing tool produces
  `meta.<lens>.ran=false` + `skipped_reason` and the lens emits `[]`.
- `flow-pre-commit` — auto-detects scope, runs the checks (no formatting), reports pass/fail
- `flow-reply-pr-comments` — batch-posts replies to PR review comments

If `flow install` has not been run on this machine, fall back to `gh pr view`, `gh pr diff`,
and the project's npm scripts directly. The skill workflow is the value; the binaries are
just helpers.

Reference files (read on demand, not upfront):

- `references/checklists/<lens>.md` — one per-lens checklist file (`security.md`,
  `performance.md`, `bug-detection.md`, `pattern-consistency.md`, `test-coverage.md`,
  `supply-chain.md`), soft-capped at ~150 lines each. Read the lens-matching file at Step 3 when preparing
  that agent's context. `docs/consumer-review-patterns.md` is a portable seed for consumer
  repos' `.flow/review-checklist.md` — not loaded here.
- `references/conventional-comments.md` — labeling framework (praise/nitpick/suggestion/
  issue/todo/question) with decorations. Read at Step 3 when preparing agent context.
- `references/agent-prompts.md` — prompt templates for the 6 specialized review agents.
  Read at Step 3 when spawning agents.
- `references/manual-test-rubric.md` — depth rubric for the "Test Steps" criterion
  (happy/unhappy/edges + PR-type scenario menus). Read at Step 11 when evaluating
  description Testability.
- `references/report-template.md` — output format for the final report. Read at Step 12.

# Step 1.5 Metadata Triage

Between Step 1 (Parse the PR Identifier) and Step 2 (Fetch and
Pre-Flight), the reviewing session itself runs a cheap metadata triage
inline — no Task-tool spawn, no subagent, no isolated context — to
short-circuit "this PR isn't worth a full review" verdicts before the
six-agent Sonnet fan-out fires. The step fetches PR metadata via a
single `gh pr view --json state,isDraft,additions,deletions,commits,author,body`
call, applies deterministic skip rules, and writes a structured artifact
at `<worktree>/.flow-tmp/gatekeeper-result.json` — the artifact name and
shape are unchanged from the prior subagent-backed design so downstream
readers (Step 3's prompt-interpretation-tension read, `flow-pipeline`)
keep working unmodified. The triage branches on `.decision`: `"skip"`
writes a well-formed `pr-review-result.json` with `status: "clean"` and
`completed_steps: ["1", "1.5"]` so `/flow-pipeline` step 8 sees a clean
result and proceeds normally to the auto-merge gate; `"proceed"` falls
through to Step 2 unchanged. The triage never reads diff content, never
runs static-analysis — its job is the cost-routing call, not the review.

Because the triage runs in the same session as the rest of this skill,
there is no separate wrapper/subagent transcript split to document here
— see `## 1.5. Metadata triage` under `# Instructions` for the
procedure and skip-rule table.

The artifact additionally carries a `prompt_interpretation_tension:
boolean` always-emit field detected from the originating PR body's Why
section (see `## 1.5. Metadata triage` below for the heuristic). The
field is independent of the skip-decision branch and is consumed by
Step 2's Pattern & Consistency Agent — see `Step 3`'s multi-agent prep
below for how the wrapper reads the field from the artifact and passes
it as the `{{PROMPT_INTERPRETATION_TENSION}}` template variable. The
canonical detection heuristic lives in
`skills/pipeline/flow-product-planning/references/discovery-prompt-interpretation.md`
"Prompt interpretation (conditional)"; the AGENTS.md `## Output style`
rule **Treat user prompts as evidence of intent, not exhaustive
specifications.** documents the rationale, and PR #170 is the
canonical precedent.

# Independent Consolidator-Validator Subagent

This skill spawns one **Independent Consolidator-Validator Subagent**
via the Task tool at Step 3.5 — after the six-agent multi-agent review
at Step 3 and before Step 4's finding-consumption pass. The subagent
reads the six per-agent JSON outputs at
`$WORKTREE/.flow-tmp/agent-output-<lens>.json`, validates each via
`flow-agent-finding-schema --validate`, merges +
dedups + threshold-filters, runs a second-opinion validation pass on
>=80-confidence non-praise survivors, and writes a structured artifact
at `<worktree>/.flow-tmp/consolidator-result.json` with five REQUIRED top-level keys (`consolidated_findings`, `dropped_by_validation`, `rejected_alternatives`, `anti_patterns_found`, `summary`) plus three OPTIONAL per-lens pass-through keys (`lens_rejected_alternatives`, `lens_anti_patterns_found`, `lens_negatives_missing`), the three OPTIONAL keys produced by `flow-agent-finding-schema --collect-lens-negatives` rather than hand-copied. The full
prose, procedure, and prompt template live in
[flow-consolidator-instructions](../flow-consolidator-instructions/SKILL.md).

The fan-out is the **seventh** named Task-tool exemption; the bidirectional
contract lives in `.claude/rules/flow-supervisor-contracts.md` `## Don'ts` and
`skills/pipeline/flow-pipeline/SKILL.md`'s "Hard rules" exemption #7.
Context isolation is primary: the per-agent JSON reads, the
second-opinion validation prose, and the dedup reasoning all stay
inside the subagent rather than landing in the wrapper's transcript.
Step 4 reads the artifact body exactly once and reuses the parsed

From gavingolden/flow, MIT.

More from gavingolden/flow