Skip to content

ayoubben18/ab-method / .agents/skills/review-implementation

review-implementation

Unverified

Post-implementation review. Spins up three read-only critics on a completed task's diff — cleaner-architecture, slop-defender, reusability-inspector — that push back ONLY on real issues. Autonomous runs apply safe fixes (tests-green-gated) and write everything to review.md next to progress-tracker.md; interactive runs present findings to pick. Use after a task's missions are done (from start-task / start-roadmap / create-task) or standalone on a diff.

Review Implementation (post-implementation)

Review a completed task's diff through three lenses, each a read-only critic subagent. The counterpart to ../critique-plan/SKILL.md: that guards the plan before coding; this guards the result after.

Silence is the default output. A clean diff produces no findings — that is the normal case. A finding survives only if a senior engineer, looking at this diff, would actually make the change. State each as a concrete cost, not a preference. Never invent refactors to look thorough.

ALWAYS check .ab-method/structure/index.yaml FIRST for paths (task location, domain model, review.md). Review only what this task changed — the cohesive diff across its missions (git diff for the commit range). This is not a whole-codebase audit; that's /improve-codebase-architecture.

Look for it under the project root (the current working directory) first — a project's own copy is how it customises its paths, so it always wins. Only if the project has none (AB Method installed as a plugin rather than with npx ab-method), read the bundled default: ../../../.ab-method/structure/index.yaml relative to this SKILL.md. Either way, every path the index names is relative to the project root, never to the folder the bundled file lives in.

Process

1. Gather diff + context

The changed files and their git diff, plus (read only what exists): UBIQUITOUS_LANGUAGE.md / CONTEXT.md (canonical terms, spotting reinvented concepts), the pattern docs for the layers the diff touches (docs/architecture/<layer>/index.md, then only the relevant topic files), docs/adr/ (don't propose what an ADR settled), .ab-method/rules/code.md (the rules the code was written under), the task's progress-tracker.md sections ## Placement and ## Protected (## Test Plan in legacy trackers), and its unresolved-questions.md if it has one.

Black boxes are deliberate — seed every critic with the file. A TODO(UQ-n) seam whose entry is recorded there is a decision the user signed off on: ship a placeholder rather than guess. No lens may flag it as slop, a shallow module, a speculative abstraction, or dead code, and none may propose "just implement it properly" — the answer isn't theirs to pick. Two things are fair game and should be reported: a TODO(UQ-n) marker with no matching entry (an orphan black box nobody recorded), and a placeholder that leaked past its named seam into several call sites — the seam was supposed to contain it, and containing it again is a safe fix.

2. Spin up THREE read-only critics — in parallel

Spawn three subagents in one batch, named exactly:

AgentLensBrief
cleaner-architecturedepth / deepeningARCHITECTURE.md
slop-defenderAI code-slopSLOP.md
reusability-inspectorduplication / reuseREUSE.md

Each is read-only — analyses the diff, returns a findings list (often empty), edits nothing. Seed each with the diff + context + its lens file — including the task's unresolved-questions.md when it exists, since every lens would otherwise read its placeholders as defects (each lens file says so too). On Codex (spawn_agent is one level deep) spawn them at the orchestrator's own level — flat; on Claude they may nest. Flat works on both.

3. Collect + classify

Merge the lists. Drop anything that's a preference (not a concrete cost), an ADR already settled, or a design change bigger than this task (note it open, don't act). Classify each survivor:

  • safe-fix — confirmed, mechanical, covered by existing tests, no interface/behavior change (delete dead code, inline a pass-through, drop a redundant comment, call an existing util of identical semantics).
  • needs-judgment — real but design-level, risky, behavior/interface-affecting, or not test-covered.

4. Act — by mode

Interactive (manual create-task tail, or standalone): present findings grouped by lens, each marked safe-fix/needs-judgment; apply what the user approves; run tests; report.

Autonomous (start-task / start-roadmap — afk): the orchestrator (never the parallel critics) applies fixes, so there are no concurrent writes:

  1. For each safe-fix: apply it, re-run the focused tests for what it touched. Green → keep. Red → revert it, downgrade to needs-judgment with a note (attempted, reverted — broke <test>). If any fix was kept, run the full suite (command from tech-stack.md) once at the end; red → revert the fixes one by one until green, downgrading each reverted one.
  2. Commit kept fixes as one refactor(<task>): post-review cleanup (repo convention). Nothing kept → no commit.
  3. Write docs/tasks/<task>/review.md (below) — every finding, applied or open. Never prompt; anything uncertain stays open rather than being changed.

5. review.md format

Written next to progress-tracker.md. Always write it in autonomous mode — even when clean — so the afk user knows the review ran.

# Post-Implementation Review: <Task Name>
**Reviewed**: YYYY-MM-DD   **Scope**: missions <a–z> / commit <range>

## Applied — safe fixes ✅ (commit <hash>)
- [slop-defender] removed pass-through wrapper `fooProxy` — src/foo.ts
- [cleaner-architecture] inlined shallow `formatName` into its one caller — src/user.ts

## Open — need your judgment ⬜
### [reusability-inspector] duplicates `paymentService.calculateTax`
- **Files**: src/checkout/tax.ts
- **Why it matters**: two tax formulas will drift; a rate change must be made twice.
- **Suggested change**: call the existing `paymentService.calculateTax` instead.

## Clean lenses
- slop-defender: no further findings

## Checked, dropped
- [cleaner-architecture] `RefundRow` looks shallow, but it is the table's row adapter — two adapters exist

## Checked, dropped (optional) lists near-misses a critic examined and rejected, with the reason, so later reviews (review-pr) don't re-raise them. Each lens's evidence line (Checked: ...) goes under its heading or after its clean line.

If all three lenses are clean and nothing was applied, the whole body is one line: All three lenses clean — no findings.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall