---
description: Reconstruct a project's VISION.md from what the user actually typed into Claude Code prompt boxes over the project's life — real user messages + AskUserQuestion answers, separated from subagent/headless/harness noise, SYNTHESIZED into a coherent vision document. Use on /extract-vision <project-path>, "what did I say I wanted for X", "rebuild the vision from my prompts", or before writing GOLIVE/roadmap docs for a project whose intent lives only in chat history.
allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
---


# extract-vision

Audience: AI coding agents first.

Goal: `<project>/VISION.md` — the owner's words REWRITTEN into what the project is: structured, synthesized prose. NOT a quote collection. Three stages: deterministic extraction+slice (scripts), REASONING-agent distillation, quality verification.

**Executor law (learned 2026-07-12, owner rebuke):** stage 2 synthesis goes to a REASONING-tier subagent (fable/opus). NEVER a cheap executor (cursor/composer/haiku) — measured failure: composer-2.5 over a 4MB corpus produced quote-salad with bug reports presented as "vision". Cheap tiers may only do mechanical prep, never the writing.

## Stage 1 — extract + slice (scripts, by path)

```bash
node /home/user/.claude/skills/extract-vision/extract_prompts.mjs <project-path> <scratch>/corpus-<name>.md --include-worktrees
node /home/user/.claude/skills/extract-vision/slice_corpus.mjs <scratch>/corpus-<name>.md <scratch>/slice-<name>.md
```

- `extract_prompts.mjs`: user-vs-agent separation (sdk entrypoints dropped, sidechains dropped, harness artifacts dropped), AskUserQuestion pairing (`[Q]` tags), resume-replay dedup, chronological. entries=0 → STOP, report.
- `slice_corpus.mjs`: keeps genesis block + ALL `[Q]` + substantive prompts; truncates >8k entries, never drops them. Slice is what the distiller reads.
- **Provenance check (MANDATORY):** compare slice `firstTs` to the repo's first commit (`git log --reverse`). Corpus starts materially later → the genesis era is MISSING from transcripts (retention cleanup); the distiller MUST be told and MUST write a 2-line Provenance note — never fake a genesis narrative.

## Stage 2 — distill (reasoning subagent, foreground)

Spawn Agent (claude type, inherits session model). Dispatch prompt — adapt paths/provenance, keep rules verbatim:

```
Rewrite <project>/VISION.md from scratch as a SYNTHESIZED vision document.
SOURCE: <slice-path> — ONLY owner-typed messages + [Q] owner decision-answers (read every [Q]). Read fully in chunks.
PROVENANCE: corpus starts <firstTs>; project's first commit <date>. <If gap: genesis era missing — state in a 2-line Provenance note, never fake it.>
WHAT VISION.md IS: the owner's words REWRITTEN into what the project is — insight for agents and people about the project's actual vision. NOT a quote collection.
STRUCTURE (each section = flowing synthesized prose; quotes ONLY as short seasoning where the owner's phrasing itself carries intent):
1. Provenance (2 lines)
2. What <project> is and the problem it solves — product one-pager, plain words, zero feature minutiae, zero test/ops chatter
3. Who uses it, who pays, how it makes money
4. Non-negotiables the OWNER stated (must/always/never — only if owner said it)
5. Product decisions log — dated, from [Q] + explicit decisions; PRODUCT/architecture only — EXCLUDE harness/tooling/model/testing-mechanics decisions
6. Scope boundaries — IN vs OUT/later, per owner
7. Quality bar and taste — synthesized recurring preferences
8. Open contradictions — real product-intent conflicts only, both sides dated
HARD EXCLUSIONS: bug reports, continue/resume traffic, harness/orchestration/model instructions, test-fixture mechanics, agent praise/complaints, task-spec-shaped text. Test per sentence: would it help a NEW agent understand what the project is trying to BE? No → out.
RULES: never invent/embellish — unclear → omit; dated claims traceable to corpus; 120–220 lines; Write (overwrite); do NOT commit; touch no other file.
Final reply: 5-line report — sections, coverage, top 3 contradictions, honest omissions.
```

## Stage 3 — verify + deliver

1. **Quality gate (the one that catches quote-salad — authenticity alone does NOT):** read section 2's first paragraph — MUST read as a product one-pager. Any bug-report/ops quote inside sections 2–4, or a decisions-log entry about models/harness/seeding → REJECT, redo stage 2 naming the failure.
2. Authenticity spot-check: grep 5 quoted phrases + all cited dates against the FULL corpus (nested quotes — search inner fragment).
3. Do NOT commit unless asked. Report: path, coverage stats, top contradictions, provenance gaps.

$ARGUMENTS

Bundled assets for this command live in `/home/user/.claude/command-assets/extract-vision/`. Reference them BY ABSOLUTE PATH — any relative path in the text above resolves there.