Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/review-spec

review-spec

Verified

Review proposed specifications for feasibility, gaps, and testability; not plans or code conformance.

references/review-cost-examples.md

View on GitHub
# Specification review cost examples

| Request or condition | Before | After |
|---|---|---|
| Same proposal is sent to specification, plan, and architecture reviewers | All three assess general feasibility and derive the retry timing again | `review-spec` checks requirement coverage, consistency, explicit limits, and observable acceptance cases; only `plan-review` derives ordered worst-case timing; only `review-arch` compares structural alternatives |
| Retry guarantee has no units, deadline start, or acceptance case | Duplicate a full execution calculation before reporting a requirement gap | Cite the missing requirement/test condition and the consequence; name missing quantitative evidence without automatically starting another reviewer |
| Supplied calculation proves the promised retry exceeds the deadline | Re-derive the same arithmetic | Reuse the cited result, report the contradicted promise as P1 with `REVISE`, and preserve the existing finding fields |
| `shared_context=_coord/PROJ-123/code-facts.md` pins paths, excerpts, and table schemas to the reviewed revision | Read both repositories from scratch | Reuse the collected facts and identify them as supplied evidence; check only a doubtful schema claim or missing material fact, plus applicable repository instructions |
| Context excerpt belongs to an older revision and contradicts the spec | Accept all collected facts to save reads | Inspect the disputed current source narrowly; record the stale fact and remaining evidence limit |
| `light`: one-repository UI proposal with researched component facts, no storage/concurrency changes, seven discovered issues including one P1 | Re-read the research and emit seven detailed findings | Reuse research; show the five highest-priority findings, disclose two omitted, retain sources/limits and the P1-driven `REVISE` verdict |
| `light` requested for a proposal changing durable storage or concurrent ownership | Apply the small-plan shortcut because the document is short | Explain ineligibility and use the normal review; document length alone does not establish light eligibility |
| Caller selects a model for UI copy/spec prose versus a plan or storage design | Always use the most expensive model | Recommend a cheaper model for UI/text/docs changes and the top model for concurrency/storage designs; the caller chooses, the skill never switches |

Routing examples: a proposal asking whether all obligations have testable acceptance cases activates `review-spec`, including with `shared_context=...` or `light`. An ordered implementation plan activates `plan-review`; a component-ownership and alternatives question activates `review-arch`; a request to verify completed code against a spec activates `verify-impl`. Shared context changes evidence collection, not routing or readiness standards.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall