cc-workflows:review-doc

What this skill does

# Review Spec, Plan, Requirements, or Other Documents
Thoroughly review specifications, implementation plans, PRDs, technical designs, requirement documents, or other documents to ensure they are complete, clear, unambiguous, and ready for implementation or distribution.


## Variables

_Path to specific document(s) to review, or additional focus areas (**required**):_
SPEC_PATH_OR_FOCUS: $ARGUMENTS


## Instructions

- **Make sure `SPEC_PATH_OR_FOCUS` is provided** - otherwise **STOP** immediately and ask user for input
- **Fully** read and understand the **Workflow Rules, Guardrails and Guidelines** section in CLAUDE.md (and/or system prompt) before starting work, including but not limited to:
  - **Foundational Rules and Guardrails**
  - **Foundational Development Guidelines and Standards** (e.g. Development, Architecture, UI/UX Guidelines etc.)
- **Read-only review** - No modifications to specs during analysis
- **Be thorough and critical** - Challenge assumptions, find edge cases, identify ambiguities
- **Favor simplicity** - Actively identify over-engineering; recommend simplest solution (KISS, YAGNI, DRY)
- **Proportional review** - Calibrate the depth and expectations of your review to the project's actual scale, stage, and goals. A simple CLI tool, a prototype, or an MVP does not need the same scrutiny as an enterprise SaaS platform. Never recommend patterns, processes, or infrastructure that are disproportionate to the project's scope and ambition. If the document doesn't mention something (e.g. i18n, monitoring, rollback), consider whether it's actually needed before flagging it as missing.
- **The words "spec" and "specification" in this command** refers to any specification, plan, requirement document, PRD, technical design, or other documentation that is the focus of the review


## Workflow

### Phase 1: Discovery and Context

1. **Locate specification documents**
   - If _`SPEC_PATH_OR_FOCUS`_ is provided, review those documents/areas
   - List all documents found and their relationships

2. **Build context**
   - Understand existing patterns, conventions, tech stack
   - Identify problem being solved, success criteria, scope boundaries
   - Note dependencies, constraints, and assumptions
   - **Read additional guidelines and documentation** - Read additional relevant guidelines and documentation (API, guides, reference, etc.) as needed

3. **Understand project scale and vision**
   - Determine the project's nature (CLI tool, library, web app, SaaS, internal tool, prototype, etc.)
   - Determine the project's stage (greenfield, MVP, early product, mature product, etc.)
   - Understand the overall vision and goals — what is the project trying to achieve?
   - Use this understanding to calibrate all subsequent review phases proportionally

**Gate**: All relevant specs identified, context understood, and project scale/vision established


### Phase 2: Completeness Review

Verify specification covers all necessary aspects _(only flag items as missing if they are actually relevant to the project's scale, stage, and goals)_:

1. **Functional requirements** - Features, workflows, use cases, success/error states
2. **Non-functional requirements** - Performance, security, accessibility, i18n, compatibility _(only those relevant to the project)_
3. **Technical specifications** - Data models, APIs, integrations, error handling, monitoring
4. **Edge cases and errors** - Validation rules, timeouts, retries, error messages, boundary conditions
5. **Testing strategy** - Acceptance criteria, test approach, test scenarios
6. **Operations** - Deployment, configuration, monitoring, rollback, maintenance _(only if applicable to the project's stage)_

Document all missing or incomplete areas.

**Gate**: Completeness assessment finished


### Phase 3: Clarity and Ambiguity Review

Identify unclear, ambiguous, or contradictory specifications:

1. **Language precision** - Check for vague terms ("fast", "user-friendly"), conflicting requirements, undefined terms
2. **Implementation clarity** - Verify developers can implement without guessing, acceptance criteria are testable
3. **Missing details** - Find TBD/TODO items, referenced missing documents, unvalidated assumptions
4. **Consistency** - Verify consistency across sections, examples match specs, naming is consistent
   - If the reviewed spec is a FIS (Feature Implementation Specification), ensure the spec follows the format and structure as defined in the `/cc-workflows:spec` command
5. **Conciseness and Brevity** - Ensure specs are as brief and concise as possible without losing meaning. Unnecessary prose should be avoided, and code listings should be minimized (prefer using pseudo code when possible)
6. **Maintain Important Details** - Ensure all important and essential details are preserved. Avoid removing or simplifying details that are critical to understanding the specification, such as diagrams, process flows, or complex requirements.


Document all ambiguities and clarity issues.

**Gate**: All ambiguities identified


### Phase 4: Technical Accuracy and Standards

Verify technical solutions use current best practices:

1. **Technology versions** - Check if libraries/frameworks use latest stable versions, identify deprecated APIs
2. **Best practices** - Verify industry standards, security (OWASP), accessibility (WCAG 2.1+), project patterns
3. **Technical feasibility** - Assess if solution is feasible, identify risks, verify performance expectations
4. **Documentation lookup** - Verify use of latest APIs, best practices, deprecations. Perform multiple web searches and use Context7 MCP as needed for different technologies/APIs/topics.


**Gate**: Technical accuracy verified


### Phase 5: Edge Cases and Risk Analysis

Identify missing edge cases and risks:

1. **Edge cases inventory**
   - Empty/maximum states, invalid input, concurrent access
   - Network failures, third-party failures, data migration
   - Browser/platform-specific issues

2. **User journey edge cases** - Unexpected action order, navigation away mid-process, multiple tabs/sessions

3. **Security edge cases** - Malicious input, privilege escalation, injection attacks, data leakage

4. **Risk assessment** - Identify highest risks, potential failures, invalid assumptions, dependency risks

**Gate**: Comprehensive edge case analysis complete


### Phase 6: Scope and Architecture Validation

Ensure scope is well-defined and architecture is sound:

1. **Scope validation**
   - Verify in-scope items are necessary and achievable
   - Confirm out-of-scope items are explicitly stated
   - Identify scope creep risks, phase boundaries
   - Challenge "nice-to-haves" masquerading as requirements

2. **Architecture review** _(calibrate to project scale — skip aspects that are irrelevant to the project's nature and stage)_
   - Use the `/cc-workflows:review-code` skill's architectural review guidance
   - Assess and evaluate **only aspects relevant to the project's scale and goals**, such as:
      - Architectural soundness, component separation, separation of concerns
      - Evaluate scalability, performance, maintainability
      - Review integration points, API contracts, data flows
      - Where applicable: CUPID principles, DDD patterns, clean architecture, service architecture
      - Anti-patterns, performance, resilience, security architecture
   - **Do not recommend patterns or architecture disproportionate to the project** — e.g., don't suggest DDD/bounded contexts for a simple library, or microservices for a tool that works fine as a monolith
   - Identify signs of over-engineering, such as:
      - **Unnecessary complexity**: Custom implementations when standard libraries/patterns exist, premature abstractions, overly generic solutions
      - **Premature optimization**: Performance optimizations without measured need, caching/pooling without proven bottlenecks
      - **Excessive layering**: Unnecessary indirection, wrapper clas