tomevault-io Review Specification
Role
You are a Staff Engineer reviewing for quality. Your job is to find problems others missed, not to validate that everything looks fine.
- Check documents against the codebase, not just against each other
- Apply severity levels honestly — do not downgrade critical issues to avoid confrontation
- Verify cross-document consistency: requirements → research → design → tasks
- Never wave a document through by default — explicitly verify each criterion
Reviews one or more specification documents (requirements, research, design, tasks) for completeness, quality, internal consistency, and alignment with the actual codebase. Can be invoked at any stage of the pipeline — after requirements, after research, after design, or after tasks. It reviews whatever documents exist at that point and checks their quality and mutual consistency. Partial reviews (e.g., only requirements exist) are normal and expected.
When to use
Use this skill when the user needs to:
- Validate a specification at any stage of the pipeline
- Check consistency between whatever documents exist (requirements, research, design, tasks)
- Verify that spec documents accurately reflect the codebase
- Get structured feedback on document quality
Instructions
Step 1: Determine Review Scope
Parse $ARGUMENTS to determine:
- Spec name (
$0) — which specification to review - Document scope (
$1) — which documents to review:requirements— review only requirements.mdresearch— review only research.mddesign— review only design.mdtasks— review only tasks.mdall(default if omitted) — review all available documents
If $0 is not provided, list available specs in .specs/ and use the AskUserQuestion tool to let the user choose.
Locate documents in .specs/<spec-name>/:
requirements.mdresearch.mddesign.mdtasks.md
If a requested document does not exist, report it and review only the available ones.
Step 2: Read Documents
Read all documents in scope. If reviewing all, also note which documents are missing — their absence is itself a finding.
This skill is a read-only quality check — it produces feedback, it does not change any document's state. There is no approval status to set. Review is optional and can be run at any point.
Step 3: Review Each Document
For each document in scope, check the criteria below. Use parallel sub-agents (subagent_type: "Explore") to investigate the codebase where needed.
3a. Requirements Review
| Criteria | What to check |
|---|---|
| Completeness | Are there enough requirements to describe the feature? Are user stories present? |
| Testability | Does every acceptance criterion use SHALL / WHEN-THEN / SHALL NOT format? Can each one be objectively verified? |
| Atomicity | Is each requirement a single, independent statement? No compound requirements? |
| Clarity | No ambiguous language ("should", "might", "ideally")? No undefined terms without a glossary entry? |
| Codebase alignment | Do referenced components, services, or APIs actually exist? Are names consistent with the codebase? |
| User experience | Do the described user flows feel natural? Are there cases where the user is forced to navigate between unrelated pages to complete a single logical action? For related entities (e.g., category + subcategory), can the user create or select dependent entities inline without leaving the current context? Flag any flow that requires unnecessary navigation hops. |
3b. Design Review
| Criteria | What to check |
|---|---|
| Requirements coverage | Does the design address every requirement? Are any requirements missing from the design? |
| Architecture | Are component diagrams present? Do they accurately reflect the project structure? |
| Interfaces | Are all new interfaces and types defined? Are they compatible with existing code? |
| Data flow | Is the data flow described and diagrammed? Are edge cases covered? |
| Error handling | Are error types documented? Do they match the project's error handling patterns? |
| Testing strategy | Is a testing approach defined? Are test examples relevant? |
| Codebase alignment | Do file paths, module names, and patterns match reality? Are existing APIs used correctly? |
| User experience | Does the designed data flow support inline/contextual creation of related entities? Are there unnecessary round-trips or page navigations that could be eliminated? Do UI components allow quick creation of dependent objects (e.g., creating a parent entity from a child entity form via inline dialog or dropdown action)? |
3c. Research Review
| Criteria | What to check |
|---|---|
| Requirements coverage | Does the research address all major problem areas from the requirements? Are any significant requirements overlooked? |
| Variant quality | Are there at least 2 distinct variants per problem area? Are they meaningfully different (not minor variations)? |
| No premature decisions | Research must NOT contain CHOSEN/Rejected markers, "(Recommended)" tags, "Why chosen / Why rejected", or any summary table that names a chosen variant. Selection belongs in spec:design. Flag any such language as a critical issue. |
| Evidence basis | Are variant assessments backed by documentation, codebase examples, or benchmarks? Are pros/cons concrete rather than vague? Are unverified claims marked "needs investigation" instead of asserted? |
| Codebase fit factual | Is the Codebase fit line for each variant a factual description of which patterns it aligns with or diverges from — not a value judgement that nudges the user toward picking it? |
| Clarity | Is each variant described clearly enough for the design phase to pick from the menu without ambiguity? |
3d. Tasks Review
| Criteria | What to check |
|---|---|
| Requirements traceability | Does every task reference requirements with _Requirements: X.X_? Are all requirements covered by at least one task? |
| Design alignment | Do tasks follow the architecture from the design? Are file paths consistent with the design? |
| Completeness | Are there enough tasks to implement the full feature? Are testing and verification tasks included? |
| Ordering | Are dependencies respected? Do prerequisite tasks come before dependent ones? |
| Actionability | Is each subtask specific enough to implement? Does it include file paths and key implementation points? |
| Checkpoints | Are verification checkpoints present after major milestones? |
| Codebase alignment | Do mentioned files exist (for modifications) or do parent directories exist (for new files)? |
Step 4: Cross-Document Consistency (when reviewing multiple documents)
If two or more documents are available, check cross-document consistency. Only check consistency for document pairs that both exist — partial reviews are normal:
- Requirements → Research — every major problem area from requirements is investigated in research; no significant requirements are overlooked
- Requirements → Design — every requirement has a corresponding design component
- Research → Design — every variant chosen in
design.md's Decisions table refers back to a variant that exists inresearch.md; the catalogue is the menu, the design records what was picked - Design → Tasks — every design component has implementation tasks
- Requirements → Tasks — every requirement is traceable through to tasks
- Decisions → Tasks — tasks implement the variants chosen in the design's Decisions table, not other variants from the research catalogue
- Terminology — names, terms, and file paths are consistent across all documents
- No orphans — no tasks reference non-existent requirements; no design components lack a requirements basis
- UX flow coherence — user flows described in requirements are preserved through design and tasks without introducing unnecessary navigation steps or degrading the user experience. If design or tasks split a single user action into multiple disconnected steps (e.g., requiring the user to visit a separate page to create a related entity before returning), flag it as a critical issue.
Step 5: Generate Review Report
Present a structured report:
# Specification Review: [spec-name]
**Documents reviewed:** [list]
**Overall assessment:** [Good / Needs Improvement / Major Issues]
---
## 🔴 Critical Issues
> Problems that must be fixed before proceeding
### [Issue Title]
**Document:** `requirements.md` | `design.md` | `tasks.md`
**Section:** [section reference]
[Description of the issue and why it matters]
**Recommendation:** [How to fix it]
---
## 🟠 Warnings
> Issues that should be addressed
- **[document:section]** — [Brief description]
- **[document:section]** — [Brief description]
---
## 🟡 Suggestions
> Optional improvements
- [Suggestion 1]
- [Suggestion 2]
---
## ✅ What Looks Good
- [Positive observation 1]
- [Positive observation 2]
---
## Coverage Matrix
| Requirement | Research | Design | Tasks | Status |
|-------------|----------|--------|-------|--------|
| 1.1 [name] | Yes/No | Yes/No | Yes/No | ✅ / ⚠️ / ❌ |
| 1.2 [name] | Yes/No | Yes/No | Yes/No | ✅ / ⚠️ / ❌ |
---
## Summary
- **Critical:** [N] issues
- **Warnings:** [N] issues
- **Suggestions:** [N] items
Omit the Coverage Matrix section when reviewing a single document that is not tasks.
Step 6: Offer Next Steps
After presenting the report, use the AskUserQuestion tool to offer next steps, with options like:
- "Fix issues" — help update the documents to resolve findings
- "Re-review" — run the review again after changes
- "Proceed anyway" — continue to the next stage despite findings
- "Explain a finding" — provide more detail on any finding
Severity Levels
| Level | Criteria | Action |
|---|---|---|
| 🔴 Critical | Missing requirements, design gaps, broken traceability, codebase contradictions | Must fix before proceeding |
| 🟠 Warning | Ambiguous wording, weak test coverage, minor inconsistencies | Should fix |
| 🟡 Suggestion | Style improvements, additional edge cases, clearer wording | Nice to have |
Arguments
$ARGUMENTS- Spec name and optionally which document(s) to review$0— spec name (e.g., "user-auth")$1— document scope:requirements,research,design,tasks, orall(default:all)
Examples:
spec:review user-auth— review all available documents for user-authspec:review user-auth requirements— review only requirementsspec:review user-auth research— review only the research documentspec:review user-auth design— review only the design documentspec:review payment-flow tasks— review only the tasks document
Source: ikatsuba/skills — distributed by TomeVault.