opsmachine/spec-review

Spec Review

Reviews a specification document for completeness and quality before approval. This is a read-only skill that analyzes without modifying.

When to Use

Use this skill when:

• After an interview, before approving a spec
• User asks "is this spec ready?" or "review the spec"
• User invokes /spec-review path/to/spec.md
• Before starting implementation to verify spec quality

Instructions

Step 1: Read the Spec

Read the spec document at the path provided by the user.

See shared/spec-io.md for spec file location and section structure.

If no path provided, look for recent specs in Documents/specs/ and ask which one to review.

Gate check: Verify **Status:** is Draft. If already Approved, the spec has been reviewed — nothing to do here.

Step 2: Check Completeness

Evaluate each section against these criteria:

Problem Statement

• [ ] Clearly states what problem is being solved
• [ ] Explains why it matters (impact/urgency)
• [ ] Identifies who benefits (user/persona)

Red flags:

• Vague statements like "improve the system"
• No clear user or beneficiary
• Missing "why"

Acceptance Criteria

• [ ] At least 3 testable criteria
• [ ] Each criterion is specific and observable
• [ ] Edge cases are covered
• [ ] Criteria use checkbox format
• [ ] Each criterion is assessable — an implementer can objectively determine ✅ satisfied / ⚠️ unsure / ❌ not satisfied

Red flags:

• Fewer than 3 criteria
• Vague criteria like "works well" or "is fast"
• No error/edge case handling
• Criteria that can't be tested
• Criteria that are ambiguous about what "done" looks like (e.g. "handles errors appropriately" — what does that mean?)

Non-Goals (Scope Fence)

• [ ] At least 1 explicit exclusion
• [ ] Exclusions are specific, not vague
• [ ] Related features explicitly deferred

Red flags:

• Empty or missing section
• Vague exclusions like "out of scope stuff"
• No mention of related work being deferred

Assumptions & Constraints

• [ ] Key assumptions documented
• [ ] Technical constraints noted
• [ ] Dependencies identified

Red flags:

• Empty section (every feature has assumptions)
• Implicit assumptions not made explicit

Falsification Analysis

• [ ] Strongest failure case identified ("What's the strongest case this fails?")
• [ ] Critical assumptions made explicit ("What am I assuming that, if wrong, breaks everything?")
• [ ] Edge cases for manual testing documented ("What needs manual testing before showing client?")

Red flags:

• Section missing entirely
• Generic answers like "usual edge cases"
• No consideration of failure modes
• Implementer won't know what to stress-test

Note: This section helps activate falsification (testing if you're wrong BEFORE implementing). It prevents discovering issues through iteration that could be caught upfront.

Technical Notes

• [ ] Implementation hints provided (if known)
• [ ] Existing patterns to follow mentioned
• [ ] Files/components likely affected

Acceptable if empty - not all specs need technical notes

Security Considerations

• [ ] All five prompts filled in (Data flow, Trust boundaries, Auth model, Failure modes, RLS)
• [ ] Answers are specific to this feature, not generic boilerplate
• [ ] "N/A" entries include a reason (e.g., "N/A — UI-only, no data mutation")
• [ ] If new tables: RLS mentioned explicitly
• [ ] If edge functions: auth verification approach stated

Red flags:

• Empty section or all "N/A" without reasons
• Generic answers like "standard auth" or "normal validation"
• New database tables with no mention of RLS
• Edge functions with no mention of JWT verification

See shared/security-lens.md for what good answers look like.

Open Questions Resolved

• [ ] All questions from interview addressed
• [ ] Decisions documented with reasoning

Acceptable if empty - not all interviews surface questions

Step 3: Assess Readiness

Rate the spec on this scale:

Ready for Implementation

• All required sections complete
• Acceptance criteria are testable
• Scope is clearly bounded
• No major gaps

Needs Minor Revision

• Most sections complete
• 1-2 small gaps that can be addressed quickly
• Spec is usable but could be improved

Needs Major Revision

• Multiple incomplete sections
• Acceptance criteria are vague or missing
• Scope is unclear
• Return to interview phase recommended

Step 4: Report Findings

Format your response as:

## Spec Review: {spec name}

### Readiness: {Ready | Needs Minor Revision | Needs Major Revision}

### Completeness Checklist

**Problem Statement:** {Complete | Incomplete}
- {specific feedback}

**Acceptance Criteria:** {Complete | Incomplete}
- {specific feedback}
- {count} criteria found

**Non-Goals:** {Complete | Incomplete}
- {specific feedback}

**Assumptions:** {Complete | Incomplete}
- {specific feedback}

**Falsification Analysis:** {Complete | Incomplete}
- {specific feedback}
- Failure modes considered: {yes/no}

**Security Considerations:** {Complete | Incomplete}
- {specific feedback}

### Gaps Found
{List specific gaps if any}

### Suggested Questions
{Questions that might have been missed during interview}

### Recommendation
{Clear next step - approve and proceed, or revise specific sections}

Step 5: Do Not Modify

This skill is read-only. Do not:

• Edit the spec document
• Create new files
• Make changes to the codebase

If revisions are needed, tell the user what to change and let them (or the interview skill) make the updates.

Example

User: /spec-review Documents/specs/42-dark-mode-spec.md

Claude:

## Spec Review: Dark Mode Toggle

### Readiness: Needs Minor Revision

### Completeness Checklist

**Problem Statement:** Complete
- Clear problem: users want dark mode for eye strain
- Impact: affects all users, especially night-time use
- Beneficiary: all application users

**Acceptance Criteria:** Complete
- 4 testable criteria found
- Edge cases covered (persistence, browser support)

**Non-Goals:** Incomplete
- Only says "not doing system-wide theme"
- Should clarify: custom color themes? Per-page themes?

**Assumptions:** Complete
- Assumes CSS variables already in place
- Assumes local storage is acceptable for persistence

### Gaps Found
1. Non-Goals could be more specific about what theme features are deferred

### Suggested Questions
- Should dark mode sync across devices (if user is logged in)?
- What's the default for new users - light or dark?

### Recommendation
Minor revision needed. Add specifics to Non-Goals section and consider the syncing question. Otherwise ready to proceed.

Best Practices

1. Be specific - "Acceptance criteria are vague" is not helpful. Say which criterion and why.
2. Suggest improvements - Don't just flag problems, suggest how to fix them.
3. Be proportionate - A minor gap shouldn't block implementation if the spec is otherwise solid.
4. Stay read-only - This skill analyzes, it doesn't modify.