spec-vs-reality

What this skill does

# Spec vs Reality

Systematic audit comparing what's actually implemented in code against what's described in spec and planning documents. Produces a color-coded status report classifying every component as GREEN, YELLOW, or RED.

## When to Use

- Before planning next phase of work — understand where things actually stand
- When the user asks "what's built?", "how far along are we?", "what's real vs. stub?"
- After a development sprint — verify what was actually delivered
- When onboarding to an unfamiliar codebase with existing documentation

## Classification System

| Status | Meaning | Evidence Required |
|--------|---------|-------------------|
| GREEN | Built and working | Real code with logic, approximate line count, tested |
| YELLOW | Exists but not wired | Code exists but isn't called, integrated, or functional end-to-end |
| RED | Stub or missing | Docstring-only, placeholder, TODO, or entirely absent |

## Workflow

### Phase 1 — Identify Spec Documents

Locate all planning and specification documents in the project:

- Product requirements (PRD)
- Architecture/system design docs
- Implementation plans
- Phase task breakdowns
- Test framework definitions
- README with feature descriptions

Search common locations: `docs/`, `doc/`, `specs/`, `design/`, root-level `.md` files. Use Glob patterns like `**/*prd*`, `**/*spec*`, `**/*architecture*`, `**/*design*`, `**/*plan*`.

### Phase 2 — Deep Codebase Exploration

Delegate to a sub-agent (subagent_type: Explore) with a thorough prompt. The sub-agent must **read actual source files**, not just list them. For each component area:

1. **Read the source** — What classes, functions, and methods actually exist?
2. **Check for real logic** — Is there actual business logic, or just a pass/TODO/placeholder?
3. **Check wiring** — Is the component called from anywhere? Is it imported and used?
4. **Check tests** — Do tests exist? Do they test real behavior or just stubs?
5. **Measure scope** — Approximate line count of real code (excluding comments/blanks)

The sub-agent prompt should enumerate every architectural area from the spec documents, so nothing is missed. Provide file paths and directory names where applicable.

Critical instruction for the sub-agent: **"Read the actual source files, not just list them. I need to know what code is REAL and what is placeholder/stub. For each file, report: what's implemented, what's stubbed, and what's missing."**

### Phase 3 — Classification

For each component described in the spec, classify using evidence:

**GREEN criteria:**
- Real working code with business logic (not just boilerplate)
- Approximate line count noted (e.g., "~240 lines of real code")
- Key file paths listed
- Tests exist and test real behavior

**YELLOW criteria:**
- Code exists but one of:
  - Not called from any other component
  - Returns hardcoded/dummy values
  - Has TODO markers for critical integration points
  - Methods exist but skip key steps (e.g., writes to 2 of 3 tiers)

**RED criteria:**
- File contains only a docstring or module-level comment
- Directory exists but all files are `__init__.py` with no logic
- Component referenced in spec but no corresponding code found
- Placeholder that returns static strings

### Phase 4 — Report Generation

Produce a structured report with:

1. **Layer/component table** — Component name, spec description, status (GREEN/YELLOW/RED), key files, and gaps
2. **Supporting infrastructure** — Config, Docker, CI/CD, monitoring, logging, tests
3. **Overall assessment** — One-line summary (e.g., "Phase 1 is ~60-70% infrastructure, <10% integration")
4. **Critical gaps** — What's blocking end-to-end functionality?

Format the table for readability:

```
| Component | Status | Key Files | Notes |
|-----------|--------|-----------|-------|
| Redis Hot | GREEN  | src/memory/redis-client.ts (~240 lines) | Full CRUD, TTL, LRU |
| Agent Loop | YELLOW | core/agent.py (~281 lines) | Structure exists, process_message() stubbed |
| WhatsApp | RED | api/__init__.py (9 lines) | Docstring only |
```

### Phase 5 — Actionable Insights (Optional)

If requested, follow the report with:

- **What to wire next** — YELLOW items closest to GREEN
- **Quick wins** — RED items that are small and self-contained
- **Blockers** — Dependencies that prevent progress on other items
- **Phase completion estimate** — Percentage based on GREEN/YELLOW/RED distribution

## Sub-Agent Prompt Template

When delegating exploration, use a prompt structured like:

```
I need a thorough analysis of what has ACTUALLY been implemented in this codebase.
Not what's planned in docs, but what exists as working code right now.

For each area, report: what files exist, what classes/functions are implemented,
what's wired up vs. stubbed, and what's missing.

Check these areas:
1. [Area 1 from spec] — expected files: [paths], expected functionality: [description]
2. [Area 2 from spec] — expected files: [paths], expected functionality: [description]
...

Read the actual source files, not just list them. I need to know what code is REAL
and what is placeholder/stub.
```

## Additional Resources

### Reference Files

- **`references/classification-examples.md`** — Detailed examples of GREEN, YELLOW, and RED classifications with real code snippets showing what qualifies for each status level