---
name: vibe-gap-analysis
description: Assesses production readiness or audits a codebase against its specs. Supports quick static mode, deep 17-dimension audit, or single-dimension focus. Use before a production launch, after a major refactor, when inheriting a codebase, or when someone asks how done the project is.
user-invocable: true
---

# 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

### Single Dimension (`--dim N`)

Deep-dive into specific dimensions. One agent per requested dimension.

After completion, update only the audited dimensions in the existing gap analysis doc.

## Dimension Reference

| # | Dimension | Type | What to Audit |
|---|-----------|------|---------------|
| 1 | Spec Compliance | Structural | Specs vs implementation |
| 2 | Backend Code Quality | Structural | Tests, errors, lint, races |
| 3 | Frontend Completeness | Structural | UI, routes, stores, tests |
| 4 | Deployment & Ops | Structural | Deploy, CI/CD, Docker, TLS |
| 5 | Architecture Integrity | Structural | Design patterns, boundaries |
| 6 | Database Concurrency | Runtime | Transactions, locks, backups |
| 7 | Failure Cascades | Runtime | Recovery, circuit breakers |
| 8 | E2E Data Flow | Runtime | API contracts, idempotency |
| 9 | Security | Runtime | Input validation, injection, secrets |
| 10 | Observability | Runtime | Logging, alerting, metrics |
| 11 | Data Durability | Runtime | RPO/RTO, backups, replication |
| 12 | Cost/Resource Control | Runtime | Budgets, limits, rate limiting |
| 13 | Performance & Load | Business | Timeouts, benchmarks, limits |
| 14 | Multi-Tenancy | Business | User isolation, data scoping |
| 15 | Privacy & Compliance | Business | GDPR, PII, consent, encryption |
| 16 | Supply Chain | Business | Dep pinning, vuln scanning, builds |
| 17 | Operational Readiness | Business | Runbooks, SLOs, incident response |

## Output Format

All modes produce:
- Executive summary with total findings count
- Audit dimensions table with scores
- CRITICAL findings (full detail)
- HIGH findings (full detail)
- MEDIUM findings (one-line each)
- LOW findings (one-line each)
- Findings by system area (cross-reference)
- Recommended action plan (phased)
- Production readiness scorecard