review-rounds

systematic review using spawned subagents with iterative fix cycles.

prerequisite skills: spawn, coordinate, report

core rule: don't trust first clean

round 5 finding bugs after round 4 was clean is common. run 2-3 verification rounds minimum after issues stop appearing.

round lifecycle

round N:
  1. spawn review agents (parallel: code + docs)
  2. wait for reports
  3. if issues → spawn fix agents → wait → proceed to N+1
  4. if clean → proceed to N+1 anyway (verify the clean)
  5. repeat until 2+ consecutive rounds where BOTH code and docs are clean

skills review agents should load

instruct review agents to load these skills before reviewing:

• write — academish voice, precision without hyperbole, supported claims
• document — only document non-obvious why
• dig — load when investigating why code was written a certain way (git archaeology), tracing dependencies/impact, or verifying claims about intent

these define what "quality" means in this context. without them, reviews catch syntax but miss substance.

review agent focus areas

code review

• types tell the truth?
• naming honest?
• abstractions self-consistent?
• edge cases tested?
• claims supported?

docs review

• docs match implementation?
• examples compile?
• only documents non-obvious why?
• avoids hyperbole and absolutist language?

ambiguous decisions

when review finds issues requiring product decisions ("remove feature X or implement it?"), pause and ask user. don't make product decisions unilaterally.

summary format

after completion:

list all changes made across fix phases.