Skill v1.0.0

version: "1.0.0" name: spec-review description: Specification Review Protocol

Purpose

Review technical specifications for inconsistencies, gaps, contradictions, and ambiguities. This skill is for finding specification issues, not proposing design changes.

Trigger

Use this skill when:

• User asks to review specs, documentation, or technical designs
• User asks to find inconsistencies or gaps in documentation

Inputs

The user should provide:

• Spec location: Directory or file paths containing specifications. Default to specs/ if it exists.
• Optional focus areas: Specific concerns to prioritize

If not provided, ask:

To review your specifications, I need:
1. Where are the spec files? (e.g., specs/, docs/)
2. Any specific concerns to focus on?

Protocol

Corpus Size

• Under 50 files: Process normally
• 50-100 files: Warn user that quality may degrade; suggest focusing on specific subsystems
• Over 100 files: Require user to specify focus areas or subdirectories; refuse to review entire corpus in single pass

If token limits force truncation mid-analysis, stop and report:

• What was fully reviewed
• What was partially reviewed
• What was not reviewed

Phase 1: Discovery

1. Map the specification corpus

• List all spec files in the provided location(s)
• Identify the document hierarchy and relationships
• Note any README or index files that describe reading order

1. Classify documents

• Primary specs: Markdown/text documents defining the system (review targets)
• Reference material: OpenAPI schemas, JSON schemas, ADRs, code comments (use for cross-validation, don't review independently)

1. Read all documents completely

• Read every spec file before beginning analysis
• Track key terms, states, field names, and identifiers as you read
• Note cross-references between documents

Phase 2: Analysis

Review against these categories. For each issue found, record:

• Location: file.md:123, file.md:50-55, file.md#section, or quoted snippet (≤15 words) if line numbers unavailable
• Type: One of the types below
• Severity: Critical | High | Medium | Low
• Description: What's wrong
• Suggestion: How to fix the spec (e.g., "define term", "align names", "add missing state"). Not system design changes.

Issue Types

Severity Levels

Phase 3: Systematic Checks

Apply these checks to the specification corpus:

1. Cross-Document Consistency

• [ ] Same term defined identically everywhere
• [ ] State/status names match across all documents
• [ ] Field names in examples match schema definitions
• [ ] File/script/component names consistent across documents
• [ ] Path formats consistent (relative vs absolute, directory conventions)

2. Completeness

• [ ] Every state has defined entry conditions and exit transitions
• [ ] Every role/actor has defined: purpose, capabilities, constraints
• [ ] Every operation has: trigger, steps, success/failure outcomes
• [ ] Every data type/field has: purpose, format, valid values
• [ ] Cross-references resolve (no broken links)
• [ ] Error conditions documented with recovery paths

3. Logical Consistency

• [ ] No circular dependencies in sequences or phases
• [ ] State transitions are deterministic (no ambiguous branches)
• [ ] Constraints don't contradict capabilities
• [ ] Numeric limits/thresholds align across documents
• [ ] Default values documented and consistent

4. Edge Cases

• [ ] What happens on component/process failure mid-operation?
• [ ] What happens on data corruption?
• [ ] What happens on race conditions (concurrent access)?
• [ ] What happens on resource exhaustion?
• [ ] What happens when humans don't respond?
• [ ] What happens when external dependencies fail?

5. Undefined or Ambiguous Terms

• [ ] All field/property names documented
• [ ] All states/statuses have clear definitions
• [ ] Functions/operations have precise semantics
• [ ] Format specifications are explicit (dates, IDs, paths)
• [ ] "Magic values" or special cases explained

6. Error Handling

• [ ] Each operation specifies possible errors
• [ ] Error propagation paths documented
• [ ] Partial failure handling specified
• [ ] Recovery procedures defined

7. Testability

• [ ] Success criteria are measurable
• [ ] Validation items can be objectively verified
• [ ] Timeouts/thresholds are specific numbers, not vague terms
• [ ] Examples are concrete and verifiable

Phase 4: Report

• If the same issue appears across multiple files, report once with all locations listed
• Prefer root-cause framing over symptom repetition

Generate report in this format:

# Specification Review: [Project/Component Name]
 
## Summary
 
-Critical: N
-High: N
-Medium: N
-Low: N
 
---
 
## Critical Issues
 
### [Issue Title]
 
-**Location:** file.md:123 or file.md#section
-**Type:** [Issue Type]
-**Description:** [What's wrong]
-**Suggestion:** [How to fix]
 
---
 
## High Issues
 
[Same format]
 
---
 
## Medium Issues
 
[Same format]
 
---
 
## Low Issues
 
[Same format]
 
---
 
## Recommendations
 
[Overall observations about spec quality and suggested improvements]

Constraints

• DO NOT modify any file - this skill is read-only, producing a report, not changes
• DO NOT suggest changes to the system design itself — only identify spec issues
• DO NOT skip files within the agreed review scope — read everything before concluding
• DO note when something is intentionally deferred (marked "v2", "future", "out of scope")
• DO check that deferred items aren't referenced as if they exist in the current version
• DO flag when deferral creates inconsistency in the planned version (e.g., v1 spec assumes a v2 feature, or deferral leaves a gap that breaks v1 completeness)
• DO distinguish between "spec doesn't say" (gap) and "spec is wrong" (contradiction)

Examples

Example Issue: Inconsistency

### Agent State Missing from State Machine
 
-**Location:** roles.md:330 vs state-machines.md:102-108
-**Type:** Inconsistency
-**Description:** roles.md shows agents register with `status: STARTING`, but state-machines.md only defines IDLE, WORKING, WAITING, HANDOFF. STARTING is not a valid state.
-**Suggestion:** Add STARTING to state machine with transition STARTING → IDLE, or change registration to use IDLE.

Example Issue: Gap

### Grace Period Duration Undefined
 
-**Location:** state-machines.md:263
-**Type:** Undefined Term
-**Description:** Validation rule references "grace period" but duration is never defined.
-**Suggestion:** Define explicitly (e.g., "60 seconds") or reference related timing constant.

Example Issue: Contradiction

### Backoff Timing Mismatch
 
-**Location:** design.md:50-55 vs implementation.md:120-125
-**Type:** Contradiction
-**Description:** design.md specifies exponential backoff (10s, 20s, 40s), but implementation.md shows fixed 5s delay.
-**Suggestion:** Align documents — update implementation to match design or document the simplification.

Notes

• For large spec corpuses, organize findings by document or subsystem
• Prioritize Critical and High issues in the summary
• If spec quality is generally good, say so in Recommendations