oc-reverse-spec

# Reverse Spec

**On first invocation, read `references/orchestrator.md` and follow its welcome protocol.**

Read an existing codebase and generate the structured spec documents that oc-app-architect
expects as inputs. This is the reverse of the normal pipeline: instead of idea → spec →
code, it goes code → spec → pipeline-ready.

## Why This Exists

The build pipeline (oc-app-architect Phase 2 stack decision → Phase 6 build loop) assumes
spec documents exist. But most real projects were built before the pipeline existed, or
grew organically without formal specs. Reverse-spec bridges that gap — it reads what's
actually built and produces the documentation that makes the project legible to the rest
of the toolchain.

This matters because without specs:
- **oc-app-architect** can't generate a roadmap for new features (no baseline to build from)
- **oc-stack-forge** can't run a gap analysis (no documented architecture to compare against)
- **oc-app-architect Phase 6** can't decompose features into sprints (no spec.md or sprint-plan.md to reference)

## /oc-reverse-spec — Command Reference

When the user types `/oc-reverse-spec`, display this menu:

```
REVERSE SPEC COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  MODES
  /oc-rev-scan       Quick scan — inventory what exists, recommend spec priority
  /oc-rev-full       Full spec generation — produce all oc-app-architect spec docs
  /oc-rev-design     Design system extraction — colors, typography, components
  /oc-rev-stack      Stack-forge gap analysis — typed pipeline audit
  /oc-rev-sprint     Tri-dev onramp — generate spec.md + sprint-plan.md for a feature

  UTILITIES
  /oc-rev-status     Show progress from checkpoint — what's done, what's next
  /oc-rev-diff       Compare generated specs against actual code (drift check)

  SESSION
  /checkpoint         Show checkpoint status
  /checkpoint show    Display full checkpoint JSON
  /checkpoint reset   Archive and clear checkpoint

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-reverse-spec to see this again.
```

### Command Behavior

**`/oc-rev-scan`**: Run Phase 0 only (orientation). Quick inventory, no deep analysis. Produces
the orientation summary and recommends which spec docs to prioritize.

**`/oc-rev-full`**: Run the complete pipeline — Phase 0 through Phase 2, generating all applicable
spec docs. This is the default when the user says "reverse spec this codebase." Uses the
checkpoint system to span sessions if needed.

**`/oc-rev-design`**: Can run standalone (without `/oc-rev-full`). Reads only the frontend layer
(components, styles, config) and produces `design/design-system.md` + `design/component-inventory.md`.
If Phase 1 analysis already exists in checkpoint, reuses it; otherwise runs a targeted frontend-only scan.

**`/oc-rev-stack`**: Can run standalone. Reads only the type pipeline artifacts (schema, ORM, API types,
OpenAPI, codegen, CI). Produces `stack-forge-audit.md`. If no prior analysis exists, runs a
targeted scan of just the typed pipeline layers.

**`/oc-rev-sprint`**: Requires either prior `/oc-rev-full` analysis or enough context from conversation/memory
to understand the project. Generates `app-architect-ready/spec.md` and optionally `sprint-plan.md` for a
specified feature.

**`/oc-rev-status`**: Reads checkpoint (JSON, or legacy markdown). If no checkpoint exists,
says so and suggests `/oc-rev-scan` to start.

**`/oc-rev-diff`**: Re-reads the codebase and compares against previously generated specs. Flags
drift (code changed since specs were generated). Requires prior spec generation.

---

## How This Skill Fits the Pipeline

```
EXISTING CODEBASE
       │
       ▼
┌──────────────┐
│ REVERSE-SPEC │  Reads code → produces spec docs
│              │  Outputs: spec/*.md, design/, gap-analysis.md
└──────┬───────┘
       │
       ├──► APP-ARCHITECT  (Phase 2+: has baseline specs, can roadmap new features)
       ├──► STACK-FORGE    (has architecture doc, can run typed pipeline audit)
       └──► TRI-DEV        (has spec.md + sprint-plan.md, can build features)
```

Reverse-spec is a **read-only analyzer** — it never modifies the codebase. It produces
documents that describe what exists, flags what's missing, and makes the project ready
for the build pipeline to take over.

---

## Phase 0: Scope & Orientation

Before reading any code, establish what we're working with. The scope determines how
deep the analysis goes and which output docs are relevant.

### Determine Input Scope

Ask the user (or infer from context) which scope applies:

| Scope | Input | Analysis Depth | Typical Output |
|---|---|---|---|
| **Monorepo** | Root path of a multi-app repo | Inventory all apps, shared libs, infra config. Generate top-level overview + per-app specs. | All spec docs + per-app summaries |
| **Single App** | Path to one application | Full analysis: schema, API, UI, auth, integrations, config | All spec docs (00-10) |
| **Feature/Module** | Path to a specific directory or set of files | Focused analysis: what this module does, its interfaces, dependencies | Targeted spec sections + oc-app-architect sprint docs |
| **Uploaded/Pasted** | Files in /mnt/user-data/uploads or pasted code | Best-effort analysis from available code | Whatever can be inferred; flag gaps prominently |

### Orientation Scan

Run a quick structural scan before deep analysis. This takes 60 seconds and saves hours
of wrong assumptions.

```
1. Directory tree (2 levels deep, ignore node_modules/.git/dist/build)
2. Package manifests (package.json, requirements.txt, pyproject.toml, wrangler.toml, Cargo.toml)
3. Config files (tsconfig, vite.config, tailwind.config, .env.example, docker-compose)
4. Database artifacts (migrations/, schema files, seed files, ORM config)
5. Entry points (index.ts, main.py, app.tsx, worker.ts)
6. Test infrastructure (test dirs, vitest/jest/pytest config, playwright config)
7. CI/CD (.github/workflows/, wrangler.toml deploy config, Dockerfile)
8.