---
name: reverse-spec
description: >-
  Reverse-engineer a SaaS / web product's OBSERVABLE surface (screenshots, help-center
  docs/PDFs, instructional videos) into a deep reverse-engineered PRD + v2 redesign
  brief, with NO source-code access. Use when the user wants to spec out, document,
  reconstruct, or competitively analyze a product they can only see from the outside
  — "reverse engineer this app", "build a PRD from these screenshots/videos/help
  center", "spec out a competitor", "turn this product's docs into a redesign brief".
  Provenance-disciplined (OBSERVED / DOC / VIDEO / INFERRED). Runs as multi-agent
  Workflows; opt into orchestration. Bundles acquisition + assembly scripts.
---

# Reverse-Engineered Product Spec

Turn a product's **observable surface** into a depth **reverse-engineered PRD + v2 redesign brief** — without source code. This skill is the operating manual; the full playbook (every gotcha, exemplar pointers, cost math) is in `references/methodology.md` — **read it before starting a new site.**

## When this applies
The user can only observe a product from outside (a competitor, a legacy app, a SaaS to clone or replace) and wants a trustworthy spec: per-feature current-state docs + cross-cutting artifacts + a redesign backlog. Inputs are any mix of: product **screenshots**, a **help center / PDFs**, **instructional videos**. No DB, no repo.

## The non-negotiable: provenance discipline
Every non-trivial claim carries a tag. This is what separates a real spec from plausible fiction. **Never upgrade a weaker tag to a stronger one.**
- **OBSERVED** — visible in captured pixels; cite the exact screenshot (`S12`) or keyframe (`frame 0009.png @01:23 (video 07)`).
- **DOC «article»** — stated in a help article/PDF, not seen in pixels.
- **VIDEO @mm:ss** — stated in narration, not shown on screen.
- **INFERRED** — deduced from naming, arithmetic, route conventions, domain logic. Must be flagged.

Verify arithmetic against captured values wherever possible — a verified formula beats ten asserted ones.

## Deliverables (per site)
A self-contained `spec/` tree + two pasteable docs. See `references/methodology.md` §0 for the exact contents.
- `spec/README.md` — master PRD. `spec/features/README.md` — feature index.
- `spec/features/<module>/<slug>.md` — one spec per coherent feature (skeleton in `references/feature-spec-skeleton.md`).
- `spec/_meta/*` — taxonomy, glossary, business-rules, data-model, sitemap, media/screenshot-index, redesign-backlog, open-questions.
- `<Site>-Spec-Combined.md` — everything concatenated, **mermaid-free**, for Google Docs.
- `<Site>-Spec-Abridged.md` — a single ~20–30K-char shareable condensation (NOT a concatenation). Required deliverable.

## The 4-stage pipeline
Stages 1–3 run as **background multi-agent Workflows** (the user opts into orchestration); scout cheap text inline between them and verify each Workflow's output before launching the next. Assembly is inline.

```
Stage 0  Acquire        → corpus on disk (screenshots, pdfs/transcripts, frames)
Stage 1  Inventory+Classify (Workflow A) → per-source dossiers → taxonomy + routes + feature-manifest
Stage 2  Specs+Verify   (Workflow B) → 1 spec per feature, each adversarially verified (writer→verifier pipeline)
Stage 3  Synthesis      (Workflow C) → 7 cross-cutting artifacts + master PRD
Assembly                → single mermaid-free combined .md + abridged .md
```

When authoring the Workflow scripts, the bundled subagent roles are available as `agentType`: `reverse-spec-inventory` (Stage 1 vision cataloguing, sonnet), `reverse-spec-writer` (Stage 2 spec writing, opus), `reverse-spec-verifier` (Stage 2 adversarial verify, sonnet). Use `pipeline()` (writer→verifier per feature), not a barrier.

## Bundled scripts
All live in this skill's `scripts/` dir; reference them at `${CLAUDE_PLUGIN_ROOT}/skills/reverse-spec/scripts/`. (If that variable does not expand in your context, locate the installed plugin dir under `~/.claude/plugins/` and use the absolute path.) Run acquisition scripts from the site directory.

| Script | Stage | Purpose |
|---|---|---|
| `scrape_help.py` | 0 | Scrape a hosted HTML help center (Intercom/HelpDocs/InstantDocsBase) → clean markdown, records embedded image URLs. |
| `scrape_zendesk_api.py` | 0 | Scrape a Zendesk help center via its public REST API (bypasses Cloudflare challenge on article pages). |
| `download_help_images.py` | 0 | Download CDN images referenced by scraped help → `S###-<slug>` corpus + `_index.tsv` tying each shot to its article. |
| `build_transcripts.py` | 0 | Per-video transcripts: use native captions when present, else `mlx_whisper` (offline, Apple Silicon). |
| `extract_frames.sh` | 0 | ffmpeg keyframes on scene-change OR every N s (periodic floor) → `frames/<video>/NNNN.png` + `index.tsv`. |
| `assemble_combined.py` | Assembly | Manifest-driven concatenation into the combined Google-Docs markdown; prints `mermaid-blocks: N` (must be 0). |

## Quick start (next site)
1. `cd <site>`; read `NOTES.md` (app URL, video/help URL, access hints); sample 3 screenshots (first/middle/last) to ground the app + capture its route shape from address bars.
2. **Stage 0 — acquire.** Videos: probe → download → `build_transcripts.py` + `extract_frames.sh`. Help center: `scrape_help.py` or `scrape_zendesk_api.py` → `download_help_images.py`. PDFs: convert to text. Report a corpus summary.
3. Read transcripts/help inline. Launch **Workflow A** (inventory+classify). Verify the manifest/taxonomy yourself — cheapest place to fix scope.
4. Launch **Workflow B** (write+verify, one `pipeline()` per feature). Check verify verdicts (most come back `revised` — that's the verifier working).
5. Launch **Workflow C** (7 artifacts in parallel → master PRD). Confirm **mermaid-free** (author tables/nested-bullets, not Mermaid).
6. `assemble_combined.py` → `<Site>-Spec-Combined.md`; verify 0 mermaid; report deliverable + paste caveats (large file; paste in chunks).
7. Author `<Site>-Spec-Abridged.md` (one synthesis agent; mirror a prior site's abridged file). Don't skip — required deliverable.

## Read before you start
- `references/methodology.md` — the full playbook: deliverable contents (§0), repo layout (§1), per-corpus acquisition branches (§4), the exact Workflow A/B/C designs (§5–7), assembly (§8), cost/orchestration notes (§9), and lessons paid for in prior runs (§10).
- `references/feature-spec-skeleton.md` — the fixed per-feature spec skeleton + provenance tag reference.