tier1-review

name

tier1-review

description

Run a Tier 1 same-model multi-lens review of a completed chunk of work: dispatch independent review subagents (code-reviewer, architect-reviewer, simplify, and — when the change involves tests or a no-test claim — test-signal) in parallel with a complete five-element context package, triage findings into Critical/Important/Minor with a disposition per finding, land fixes as a separate commit, file beads for deferred minors, and emit a close-evidence line. Use when the user says "tier 1 review", "run tier 1", "three-lens review", "multi-lens review", or when a feature/refactor bead reaches the self-review-done stage and the change meets the multi-agent-review trigger criteria.

Tier 1 Review

Dispatch the multi-lens same-model review that the multi-agent-review rule mandates, so every run is dispatch-complete (no lens forgotten, no context element dropped) and triage-consistent (every finding gets an explicit disposition). The rule states the law; this skill is the procedure.

When to Use This Skill

Run Tier 1 when the change meets the multi-agent-review trigger criteria. The criteria are owned by the always-on multi-agent-review rule; this skill restates them for standalone invocation — if they ever disagree, the rule wins:

• A component was decomposed (split into multiple production files)
• A shared component was created or significantly changed
• A structural change touches 3+ production files (excluding tests, docs, generated files, mechanical renames)
• The change affects a load-bearing boundary the project treats as high-risk (state management, auth, data integrity, public API surface)

Skip it (and say so) for: narrow bug fixes, config/chore/docs beads, mechanical migrations, test-only changes. Do not run Tier 1 as ceremony on work that doesn't meet the bar — a skipped review with a stated reason is correct behavior.

Sequencing: Tier 1 runs after the implementing agent's self-review against ACs and before the Tier 2 cross-model handoff. It supplements the self-review; it never replaces it.

Core Process

Phase 1 — Assemble the context package

Build the five-element package every lens receives. All five are mandatory; an incomplete package is the most common cause of shallow reviews.

1. Bead description + acceptance criteria — from bd show <id>
2. Full file contents of every changed/created file (not diffs alone — lenses need the surrounding code to judge boundaries and edge cases). Embed the contents in the prompt, or — when reviewers have file access — give exact paths with a read-completely instruction and a note pinning the state under review (branch/commit; confirm the working tree matches)
3. Bead type (feature/refactor/bug) — calibrates review depth
4. Shared components the change depends on — so reviewers can check integration, not just the new code in isolation
5. Change summary — what was done and why, 3-6 sentences, written fresh (do not paste the bead description as the summary)

Identify the changed-file set from the work's commits (`git diff

..HEAD --stat` on the feature branch), not from memory.

Phase 2 — Dispatch the lenses in parallel

Launch the subagents in a single message, one per lens, each with independent context — no lens sees another's findings until triage:

Lens	Focus	Catches
code-reviewer	Correctness, edge cases, race conditions, error paths	Logic bugs, state issues, missing guards
architect-reviewer	Pattern consistency, boundaries, reusability	Architectural drift, duplication, wrong abstractions
simplify	Over-engineering, unnecessary complexity	Gold-plating, dead code, YAGNI, stdlib replacements
test-signal	Test quality: would each test catch the defect it guards?	Zero-signal tests, ACs with no failing-capable test, helper-only bug tests, non-credible red-first claims

The first three lenses always run. Include test-signal for feature/bug/story/refactor beads whose change set includes test files, or whose close will claim a no-test exception (the lens judges whether that exception is legitimate for the bead type). Omit it for docs/chore/config-only changes.

Lens prompt templates live in lenses.md. Each prompt embeds the full five-element package — subagents do not share the parent's context, so nothing may be referenced by allusion.

Defaults: tool-native general-purpose subagents on the same model as the parent (same-model multi-lens is Tier 1's design — cross-model diversity is Tier 2's job). The overlay may override models per lens.

Fallback (no parallel subagents): run the passes sequentially, writing each pass's findings to a scratch file before starting the next, to prevent anchoring on your own prior findings.

Recovery: when collecting results, check each lens's final message before triage. If it contains a verdict line (or section headers) without the full findings, resume that subagent once with this fixed prompt — do not re-run the lens fresh (that discards its analysis):

Your final message did not contain the findings report — only your FINAL message is delivered; earlier messages are invisible. Repeat the COMPLETE findings report now, in full, in this message. Do not reference earlier messages. End with the verdict line.

In both observed failures to date, this prompt recovered the full report cleanly on the first resume.

Phase 3 — Triage

Collect all findings into one table. Every finding gets a severity and an explicit disposition — no finding is silently dropped:

#	Lens	Severity	Finding	Disposition

Severities: Critical (correctness/data-loss/security — must fix before close), Important (real defect or design problem — fix now), Minor (polish, diagnostics, style — fix cheaply or defer).

Dispositions (pick exactly one per finding):

• fixed — change made, name the commit
• accepted — the flagged behavior is intentional; record the rationale (and, where the ceiling is real, a defer: comment or tripwire test that pins the accepted limitation)
• deferred — valid but out of scope now; file a bead at triage time and name it (a deferral without a bead ID is a dropped finding)
• rejected — the finding is wrong; record why in one sentence

When two lenses flag the same thing, merge into one row and credit both. When lenses disagree, start from the more conservative position and document the tension rather than letting the findings cancel out.

Phase 4 — Fix, commit, file

1. Fix all Critical and Important findings immediately.
2. Commit fixes as a separate commit — never amend the original work. Commit message names the review: fix: tier-1 review — <themes> (<bead-id>).
3. Re-run the project's quality gate (tests, lint) after fixes.
4. File beads for every deferred finding, with description and acceptance criteria — a bare title is not a filed finding.

Phase 5 — Record and report

1. Append the triage table (or its summary) to the bead: bd note <id> "Tier 1: <lens results + dispositions>". If the table is large, commit it as a review doc in the project's reviews directory and note the path.
2. Pattern-level insight check: if any finding revealed a systemic pattern — hidden coupling, an undocumented convention, a recurring anti-pattern — capture it with bd remember --key <area>-<topic> after the finding is resolved. Localized bugs don't qualify; patterns do.
3. Emit the close-evidence line for later use in bd close --reason:

Tier 1 (N lenses: code-reviewer, architect-reviewer, simplify[, test-signal]):
N Critical / N Important / N Minor — C/I fixed in <commit>,
minors <fixed in <commit> | carried to <bead-ids> | accepted with rationale in notes>.

Project Overlay

Project-specific parameters live in .agents/overlay.md in the consuming repo, under a ## tier1-review section (shared overlay convention — one file, one section per skill). Keys this skill reads:

Key	Meaning	Default when absent
models	Per-lens model overrides, lens: model-slug lines	Parent model for all lenses
focus	Extra project-specific focus areas appended to every lens's context	None
reviews_dir	Where large triage tables are committed	docs/reviews/
quality_gate	Command(s) to re-run after fixes	Project's standard test/lint invocation

The skill behaves sensibly with no overlay file: same-model lenses, no extra focus areas, defaults above.

Anti-Patterns

• Shared-context dispatch. Giving lens 2 the findings of lens 1 anchors it. Independence until triage is the point of multi-lens.
• Diff-only packages. A lens that can't see the surrounding file judges edge cases blind. Full file contents, always.
• Findings without dispositions. A triage table with an empty disposition column is a list of complaints, not a review. Every row closes.
• Amending fixes into the original commit. Destroys the review trail — the separate fix commit is the evidence that review happened.
• Deferral IOUs. "We should fix this later" without a bead ID filed at triage time is how findings evaporate.
• Ceremony runs. Running three subagents on a two-line bug fix wastes cycles and dilutes the signal of real reviews. Honor the skip conditions.
• Simplify-lens suppression. The simplify lens's free-form structural observations (section 2 of its output) are often the highest-value findings. Never harvest only its tagged lines.