Review Synthesis

$skill-capture

Workflow

1. Confirm scope and mode: read-only review, implementation follow-up, or both.
2. Inspect repo instructions, relevant docs,

   git status --short

   , and target files enough to avoid blind delegation.
3. If reviewing an agent skill, skill proposal, or skill collection change, read

   references/skill-reviews.md

   and use its lenses to select reviewers and structure findings.
4. Select relevant perspectives. Use user-named roles first; otherwise choose only roles that fit the target.
5. Brief each reviewer with:
   • exact target files, directories, or question
   • its assigned perspective and boundaries
   • read-only instruction unless implementation was explicitly requested
   • expected output: findings first, severity, file/line references when available, and open questions
6. Continue a lightweight parent review while reviewers run; do not duplicate their assigned work.
7. Integrate the results:
   • deduplicate overlapping findings
   • resolve contradictions or mark them as tradeoffs
   • verify important claims against files when practical
   • separate confirmed issues from suggestions and taste calls
   • connect findings to likely user impact
8. Present one synthesized review, not a paste-up of agent reports, with the smallest useful action path.

Common Perspectives

• Architecture: boundaries, coupling, domain model, maintainability.
• Expert coder: correctness, idioms, tests, edge cases, best practices.
• DevOps: deployment, CI, config, observability, reliability.
• Security/privacy: secrets, auth, data exposure, unsafe defaults.
• UI: implementation polish, responsiveness, accessibility mechanics.
• UX/design: flows, clarity, hierarchy, task fit.
• Docs/product: accuracy, reader fit, terminology, missing context.
• Skill authoring: trigger clarity, instruction coherence, cognitive load, progressive disclosure, agent ergonomics, portability, bundled assets, and validation.

references/skill-reviews.md

Output Shape

Findings
- [severity] [perspective] File/line: issue, impact, recommendation.

Cross-Perspective Synthesis
- Consensus, tensions/tradeoffs, and parent assessment.

Open Questions
- Questions blocking a confident recommendation.

Recommended Next Actions
- Smallest useful fixes and validation.

Subagent Notes
- Brief role-by-role summary when useful.

Guardrails

• Keep role briefs narrow; vague reviewers produce fog with bullet points.
• Prefer independent lenses over several agents reading the same thing.
• Do not treat subagent output as truth. Review, merge, and challenge it.
• Do not bury severe findings under perspective summaries.
• Do not make changes after a review unless the user explicitly asks for implementation.
• Avoid decorative roles; more reviewers can mean more noise, not more insight.
• Tie subjective design feedback to user goals, accessibility, or task fit.