Spec Review
Overview
A 6-phase workflow for reviewing specifications before implementation. Applies industry-standard quality criteria, identifies issues, and produces a Spec Review Report with a hard gate for authority approval.
When to Use
- A spec or design document has been provided for review
- Before implementation planning begins
- Leader agent needs quality validation of requirements
When NOT to Use
- Code is already implemented and you need to review it -- use code review
- You need to create the spec -- use [oneteam:skill]
brainstorming
Phase 1: Read & Understand
- Obtain the spec. Read from initialization context, authority message, or user prompt. If unavailable, ask before proceeding.
Template:
"Need the spec to begin review. Please provide it or point me to the design doc."
- Read end-to-end. Complete the full read before analyzing -- understand overall intent and scope first.
Phase 2: Analyze Target Codebase
- Map the scope. Use Glob and Grep to identify files and modules in the spec's scope.
- Understand current architecture. Read existing code to understand patterns, data flow, and dependencies. Note conflicts or dependencies with the spec.
- Identify test coverage. Check for existing tests; note covered and uncovered areas.
Phase 3: Quality Check
Apply to every requirement. Criteria drawn from IEEE 830, INVEST, and Wiegers.
| Criterion |
What to check |
Red-flag words |
| Unambiguous |
Each requirement has exactly one interpretation. No vague qualifiers. |
"usually", "sometimes", "may", "mostly", "etc.", "appropriate", "as needed" |
| Complete |
All functional, non-functional, and interface requirements are present. No placeholders. |
"TBD", "to be determined", "later", "TODO" |
| Consistent |
No requirements contradict each other or conflict with existing code behavior. |
-- |
| Testable |
Each requirement has definable acceptance criteria. Can be verified via test, analysis, or demonstration. |
"user-friendly", "fast", "intuitive", "robust", "efficient" (unmeasurable) |
| Feasible |
Achievable with available technology, dependencies, and codebase constraints. |
-- |
| Necessary |
Every requirement traces to a business need. No gold-plating or scope creep. |
-- |
| Independent |
Requirements are self-contained with minimal overlap. Can be implemented and tested separately. |
-- |
| Scoped correctly |
Specifies what, not how. Does not mix requirements with design decisions or implementation details. |
-- |
Mark Pass or Fail per criterion with specific issues noted.
Phase 4: Issue Identification
Beyond the quality TaskList, identify:
- Ambiguities -- statements interpretable multiple ways
- Missing edge cases -- empty input, errors, concurrency, boundaries, unexpected types
- Unstated assumptions -- assumed infrastructure, data formats, API contracts, environment
- Risks -- highest blast radius failures, unaddressed failure modes
- Contradictions -- conflicts within the spec or with existing code from Phase 2
Phase 5: Produce Spec Review Report
Format the findings into this exact template:
## Spec Review Report
### Quality Assessment
| Criterion | Pass/Fail | Notes |
|-----------|-----------|-------|
| Unambiguous | | |
| Complete | | |
| Consistent | | |
| Testable | | |
| Feasible | | |
| Necessary | | |
| Independent | | |
| Scoped correctly | | |
### Confirmed Requirements
- [R1] <requirement clearly stated in spec>
- [R2] ...
### Questions and Gaps
- [Q1] <ambiguity or missing detail> -- suggested resolution: <suggestion>
- [Q2] ...
### Risks
- [K1] <risk description> -- mitigation: <suggestion>
- [K2] ...
### Suggested Refinements
- [S1] <improvement to spec>
- [S2] ...
If a section has no items, write "None" rather than omitting the section.
Send to authority for approval. Via SendMessage if in a team, or display
to user if standalone. Include the full report.
Template: "Spec review complete. Blocked on answers to <Q1, Q2, ...>. Please confirm the spec to proceed."
Phase 6: Hard Gate — Wait for Approval
STOP. Do NOT proceed until the authority has reviewed the report, answered questions from the Questions and Gaps section, and explicitly confirmed the spec. If the authority provides an updated spec, return to Phase 1 and re-review; if they answer questions without changing the spec, incorporate answers into Confirmed Requirements and proceed.
Quick Reference
| Phase |
Key Action |
Output |
| 1. Read |
Read spec end-to-end |
Understanding of intent and scope |
| 2. Analyze |
Map scope in codebase |
File list, architecture understanding |
| 3. Quality Check |
Apply 8 criteria |
Pass/Fail per criterion |
| 4. Issues |
Identify ambiguities, gaps, risks |
Issue list |
| 5. Report |
Produce Spec Review Report |
Spec Review Report for authority |
| 6. Hard Gate |
STOP -- wait for approval |
Authority confirmation |
Common Mistakes
| Mistake |
Fix |
| Starting issue identification while still reading the spec |
Complete the full read first (Phase 1 before Phase 3) |
| Skipping codebase analysis |
Phase 2 is required -- feasibility/consistency needs code context |
| Proceeding without authority approval |
Phase 6 is a hard gate -- STOP until explicit confirmation |
Constraints
- ALWAYS complete all 6 phases in order. Do not skip any phase.
- ALWAYS read the full spec before identifying issues (Phase 1 before Phase 3).
- ALWAYS analyze the target codebase (Phase 2) before the quality check -- you need codebase context to assess feasibility and consistency.
- ALWAYS produce the full Spec Review Report template. Do not omit sections.
- NEVER proceed past the Phase 6 hard gate without explicit authority approval.
- NEVER begin implementation planning or coding during spec review.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: yotto3s-oneteam-agents-spec-review3description: Spec Review4---56# Spec Review78## Overview910A 6-phase workflow for reviewing specifications before implementation. Applies industry-standard quality criteria, identifies issues, and produces a Spec Review Report with a hard gate for authority approval.1112## When to Use1314- A spec or design document has been provided for review15- Before implementation planning begins16- Leader agent needs quality validation of requirements1718## When NOT to Use1920- Code is already implemented and you need to review it -- use code review21- You need to create the spec -- use [oneteam:skill] `brainstorming`2223## Phase 1: Read & Understand24251. **Obtain the spec.** Read from initialization context, authority message, or user prompt. If unavailable, ask before proceeding.26 Template: `"Need the spec to begin review. Please provide it or point me to the design doc."`272. **Read end-to-end.** Complete the full read before analyzing -- understand overall intent and scope first.2829## Phase 2: Analyze Target Codebase30311. **Map the scope.** Use Glob and Grep to identify files and modules in the spec's scope.322. **Understand current architecture.** Read existing code to understand patterns, data flow, and dependencies. Note conflicts or dependencies with the spec.333. **Identify test coverage.** Check for existing tests; note covered and uncovered areas.3435## Phase 3: Quality Check3637Apply to every requirement. Criteria drawn from IEEE 830, INVEST, and Wiegers.3839| Criterion | What to check | Red-flag words |40|-----------|--------------|----------------|41| **Unambiguous** | Each requirement has exactly one interpretation. No vague qualifiers. | "usually", "sometimes", "may", "mostly", "etc.", "appropriate", "as needed" |42| **Complete** | All functional, non-functional, and interface requirements are present. No placeholders. | "TBD", "to be determined", "later", "TODO" |43| **Consistent** | No requirements contradict each other or conflict with existing code behavior. | -- |44| **Testable** | Each requirement has definable acceptance criteria. Can be verified via test, analysis, or demonstration. | "user-friendly", "fast", "intuitive", "robust", "efficient" (unmeasurable) |45| **Feasible** | Achievable with available technology, dependencies, and codebase constraints. | -- |46| **Necessary** | Every requirement traces to a business need. No gold-plating or scope creep. | -- |47| **Independent** | Requirements are self-contained with minimal overlap. Can be implemented and tested separately. | -- |48| **Scoped correctly** | Specifies *what*, not *how*. Does not mix requirements with design decisions or implementation details. | -- |4950Mark Pass or Fail per criterion with specific issues noted.5152## Phase 4: Issue Identification5354Beyond the quality TaskList, identify:5556- **Ambiguities** -- statements interpretable multiple ways57- **Missing edge cases** -- empty input, errors, concurrency, boundaries, unexpected types58- **Unstated assumptions** -- assumed infrastructure, data formats, API contracts, environment59- **Risks** -- highest blast radius failures, unaddressed failure modes60- **Contradictions** -- conflicts within the spec or with existing code from Phase 26162## Phase 5: Produce Spec Review Report6364Format the findings into this exact template:6566```67## Spec Review Report6869### Quality Assessment70| Criterion | Pass/Fail | Notes |71|-----------|-----------|-------|72| Unambiguous | | |73| Complete | | |74| Consistent | | |75| Testable | | |76| Feasible | | |77| Necessary | | |78| Independent | | |79| Scoped correctly | | |8081### Confirmed Requirements82- [R1] <requirement clearly stated in spec>83- [R2] ...8485### Questions and Gaps86- [Q1] <ambiguity or missing detail> -- suggested resolution: <suggestion>87- [Q2] ...8889### Risks90- [K1] <risk description> -- mitigation: <suggestion>91- [K2] ...9293### Suggested Refinements94- [S1] <improvement to spec>95- [S2] ...96```9798If a section has no items, write "None" rather than omitting the section.99100**Send to authority for approval.** Via SendMessage if in a team, or display101to user if standalone. Include the full report.102Template: `"Spec review complete. Blocked on answers to <Q1, Q2, ...>. Please confirm the spec to proceed."`103104## Phase 6: Hard Gate — Wait for Approval105106**STOP.** Do NOT proceed until the authority has reviewed the report, answered questions from the Questions and Gaps section, and explicitly confirmed the spec. If the authority provides an updated spec, return to Phase 1 and re-review; if they answer questions without changing the spec, incorporate answers into Confirmed Requirements and proceed.107108## Quick Reference109110| Phase | Key Action | Output |111|-------|-----------|--------|112| 1. Read | Read spec end-to-end | Understanding of intent and scope |113| 2. Analyze | Map scope in codebase | File list, architecture understanding |114| 3. Quality Check | Apply 8 criteria | Pass/Fail per criterion |115| 4. Issues | Identify ambiguities, gaps, risks | Issue list |116| 5. Report | Produce Spec Review Report | Spec Review Report for authority |117| 6. Hard Gate | STOP -- wait for approval | Authority confirmation |118119## Common Mistakes120121| Mistake | Fix |122|---------|-----|123| Starting issue identification while still reading the spec | Complete the full read first (Phase 1 before Phase 3) |124| Skipping codebase analysis | Phase 2 is required -- feasibility/consistency needs code context |125| Proceeding without authority approval | Phase 6 is a hard gate -- STOP until explicit confirmation |126127## Constraints128129- ALWAYS complete all 6 phases in order. Do not skip any phase.130- ALWAYS read the full spec before identifying issues (Phase 1 before Phase 3).131- ALWAYS analyze the target codebase (Phase 2) before the quality check -- you need codebase context to assess feasibility and consistency.132- ALWAYS produce the full Spec Review Report template. Do not omit sections.133- NEVER proceed past the Phase 6 hard gate without explicit authority approval.134- NEVER begin implementation planning or coding during spec review.135136---137> Converted and distributed by [TomeVault](https://tomevault.io/claim/yotto3s) — claim your Tome and manage your conversions.138<!-- tomevault:4.0:skill_md:2026-04-15 -->
tomevault-io