Vibe Gap Analysis

vibe-gap-analysis

Cynical gap analysis comparing specs/architecture to actual implementation. Three modes from fast to exhaustive. Works with any project that has architecture docs and implementation code.

When to Use This Skill

• Before launching to production
• After a major refactor to verify nothing was lost
• When inheriting a codebase and need to assess completeness
• Periodic production readiness audits
• When stakeholders ask "how done are we?"

When NOT to Use This Skill

• Greenfield projects with no specs yet (write specs first)
• Simple bug fixes or feature additions
• Frontend-only or design-only reviews

Usage

/vibe-gap-analysis              # Quick static (5 structural dimensions)
/vibe-gap-analysis --deep       # Full 17-dimension audit with parallel agents
/vibe-gap-analysis --dim N      # Single dimension deep-dive (1-17)
/vibe-gap-analysis --dim 1,4,9  # Multiple specific dimensions

Modes

Quick Static (default)

Fast, single-agent structural audit. No subagents dispatched.

1. Read architecture/design docs in docs/ or similar
2. Read implementation code in src/, internal/, lib/ etc.
3. Compare implementation against architecture doc section by section
4. Cover dimensions 1-5 (structural):
   • Dim 1: Spec Compliance — check specs against implementation
   • Dim 2: Backend Code Quality — test coverage, error handling, lint issues
   • Dim 3: Frontend Completeness — UI components, routes, test coverage
   • Dim 4: Deployment & Ops — deploy scripts, CI/CD, Docker, TLS
   • Dim 5: Architecture Integrity — design pattern compliance, component boundaries
5. Produce structured gap report: component, expected status, actual status, % complete, action items
6. Save to docs/plans/gap-analysis-$(date +%Y%m%d).md
7. Commit with docs: gap analysis $(date +%Y%m%d)

Deep (--deep)

Full 17-dimension audit using parallel subagents where the harness supports them (Claude Code, Codex, and Gemini CLI all can). Without subagents, run the dimensions sequentially. Exhaustive production readiness assessment.

Dispatch parallel agents in 3 rounds. Subagents inherit the session's model by default; if the harness lets you choose, a faster or cheaper tier is fine for the scanning rounds, but keep the most capable model for merging and scoring.

Round 1 — Structural (5 agents):

• Dim 1: Spec Compliance
• Dim 2: Backend Code Quality
• Dim 3: Frontend Completeness
• Dim 4: Deployment & Ops
• Dim 5: Architecture Integrity

Round 2 — Runtime Execution (7 agents):

• Dim 6: Database Concurrency & Integrity
• Dim 7: Failure Cascades & Recovery
• Dim 8: E2E Data Flow
• Dim 9: Security & Input Validation
• Dim 10: Observability & Alerting
• Dim 11: Data Durability & Backup
• Dim 12: Cost/Resource Explosion Safeguards

Round 3 — Business & Product Maturity (5 agents):

• Dim 13: Performance & Load Testing
• Dim 14: Multi-Tenancy / User Isolation
• Dim 15: Privacy & Compliance (GDPR/CCPA)
• Dim 16: Supply Chain Security
• Dim 17: Operational Readiness

Each agent gets this prompt template:

You are auditing [project] for production readiness.

**Your dimension:** [Dimension N — Name]
**Scope:** [Description]
**Previous gap analysis:** [path, if exists]

Instructions:
1. Read all relevant source files for your dimension
2. For each finding: severity (CRITICAL/HIGH/MEDIUM/LOW), location (file:line), issue, fix, effort
3. Score your dimension 0-100
4. Return findings as structured markdown

Be pedantic and skeptical, and calibrate severity to this project's actual stakes.
Report only findings you can point to with file:line evidence; mark anything inferred as "unverified".

After all rounds:

1. Merge findings, deduplicate across dimensions
2. Build production readiness scorecard (17 dimensions)
3. Build findings-by-system-area cross-reference
4. Build recommended action plan (phased)
5. Save and commit