/analyze-project

---

🚨 EXECUTION NOTICE FOR CLAUDE

When you invoke this command via SlashCommand, the system returns THESE INSTRUCTIONS below.

YOU are the executor. This is NOT an autonomous subprocess.

• ✅ The phases below are YOUR execution checklist
• ✅ YOU must run each phase immediately using tools (Bash, Read, Write, Edit, TodoWrite)
• ✅ Complete ALL phases before considering this command done
• ❌ DON't wait for "the command to complete" - YOU complete it by executing the phases
• ❌ DON't treat this as status output - it IS your instruction set

Immediately after SlashCommand returns, start executing Phase 0, then Phase 1, etc.

See @CLAUDE.md section "SlashCommand Execution - YOU Are The Executor" for detailed explanation.

---

Available Skills

This commands has access to the following skills from the planning plugin:

• architecture-patterns: Architecture design templates, mermaid diagrams, documentation patterns, and validation tools. Use when designing system architecture, creating architecture documentation, generating mermaid diagrams, documenting component relationships, designing data flows, planning deployments, creating API architectures, or when user mentions architecture diagrams, system design, mermaid, architecture documentation, or component design.
• decision-tracking: Architecture Decision Records (ADR) templates, sequential numbering, decision documentation patterns, and decision history management. Use when creating ADRs, documenting architectural decisions, tracking decision rationale, managing decision lifecycle, superseding decisions, searching decision history, or when user mentions ADR, architecture decision, decision record, decision tracking, or decision documentation.
• spec-management: Templates, scripts, and examples for managing feature specifications in specs/ directory. Use when creating feature specs, listing specifications, validating spec completeness, updating spec status, searching spec content, organizing project requirements, tracking feature development, managing technical documentation, or when user mentions spec management, feature specifications, requirements docs, spec validation, or specification organization.

To use a skill:

!{skill skill-name}

Use skills when you need:

• Domain-specific templates and examples
• Validation scripts and automation
• Best practices and patterns
• Configuration generators

Skills provide pre-built resources to accelerate your work.

---

Security Requirements

CRITICAL: All generated files must follow security rules:

@docs/security/SECURITY-RULES.md

Key requirements:

• Never hardcode API keys or secrets
• Use placeholders: your_service_key_here
• Protect .env files with .gitignore
• Create .env.example with placeholders only
• Document key acquisition for users

Arguments: $ARGUMENTS

Goal: Comprehensively analyze all existing project specification files to identify gaps, incomplete sections, missing features, and provide actionable recommendations for improvement.

Core Principles:

• Discover all specs systematically
• Analyze each spec independently in parallel
• Consolidate findings into actionable gaps
• Provide clear recommendations

Phase 1: Discovery Goal: Identify all existing specification files

Actions:

• Create todo list for tracking analysis progress
• Search for all specification files following naming convention
• Count total specs found
• Validate specs directory exists

!{bash if [ -d "specs" ]; then echo "Specs directory found"; else echo "ERROR: specs directory not found"; exit 1; fi}

!{bash find specs -type f -name '[0-9][0-9][0-9]-*.md' 2>/dev/null | sort}

Parse discovered specs and prepare for parallel analysis.

If no specs found, report that project has no specs to analyze.

Phase 2: Parallel Analysis Goal: Launch spec-analyzer agent for each discovered spec file

Actions:

For EACH spec file discovered in Phase 1, launch a spec-analyzer agent in PARALLEL.

Task(description="Analyze spec completeness", subagent_type="planning:spec-analyzer", prompt="You are the spec-analyzer agent. Analyze the specification file for completeness and quality.

Target: $ARGUMENTS

Your analysis should evaluate:

• Completeness: Are all sections filled out? Any TODO or placeholder text?
• Clarity: Is the spec clear and unambiguous?
• Technical detail: Sufficient implementation guidance?
• Requirements coverage: Are acceptance criteria defined?
• Dependencies: Are dependencies on other specs documented?
• Testability: Can this spec be validated/tested?

Deliverable: Return JSON analysis: { "spec_file": "filename", "completeness_score": 0-100, "missing_sections": [list], "incomplete_sections": [list with details], "clarity_issues": [list], "technical_gaps": [list], "recommendations": [list] }")

Wait for ALL spec-analyzer agents to complete before proceeding.

Update todos as each analysis completes.

Phase 3: Consolidation Goal: Aggregate all analysis results and identify patterns

Actions:

• Collect all JSON results from spec-analyzer agents
• Calculate aggregate metrics:
  • Average completeness score across all specs
  • Total missing sections
  • Total incomplete sections
  • Common clarity issues
  • Common technical gaps
• Identify specs requiring immediate attention (score < 60)
• Identify specs that are well-documented (score >= 80)
• Cross-reference dependencies between specs
• Prioritize gaps by impact

Phase 4: Gap Analysis Report Goal: Generate comprehensive gap analysis document

Actions:

• Create gaps-analysis.json with structure: { "analysis_date": "YYYY-MM-DD", "total_specs": N, "avg_completeness": X, "critical_gaps": [], "incomplete_specs": [], "well_documented_specs": [], "missing_features": [], "recommendations": [] }
• Write report to project root or specs directory
• Include severity levels: CRITICAL, HIGH, MEDIUM, LOW

!{bash echo "Gap analysis saved to gaps-analysis.json"}

Phase 5: Summary and Recommendations Goal: Present actionable findings to user

Actions:

• Mark all todos complete
• Display comprehensive summary:

Analysis Complete

Total Specs Analyzed: [N] Average Completeness: [X%]

Critical Issues (requires immediate attention):

• [List specs with score < 60]
• [Key missing sections]

Incomplete Specs (needs work):

• [List specs with score 60-79]

Well-Documented Specs (reference examples):

• [List specs with score >= 80]

Top Missing Features/Gaps:

1. [Gap 1 with affected specs]
2. [Gap 2 with affected specs]
3. [Gap 3 with affected specs]

Recommendations:

1. [Priority 1 action]
2. [Priority 2 action]
3. [Priority 3 action]

Next Steps:

• Review gaps-analysis.json for detailed breakdown
• Prioritize specs needing completion
• Consider creating new specs for missing features
• Update incomplete sections following well-documented examples