Exploration To Spec

---
name: exploration-to-spec
description: >-
  Converts an exploration conversation (architecture discussions, codebase
  analysis, design decisions) into a structured technical specification document.
  Generates a comprehensive but concise product-engineering doc suitable for PMs,
  tech leads, designers, frontend/backend engineers, and QA. Use when you've
  finished exploring and want to formalize decisions into a shareable deliverable.
argument-hint: "[output-path] [--format roadmap|design-doc|adr|rfc] [--audience pm|engineering|all]"
disable-model-invocation: true
allowed-tools:
  - AskUserQuestion
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
metadata:
  trigger: "Use when you've finished exploring and want to formalize decisions into a shareable deliverable."
---

# Exploration to Spec

Convert exploration conversations into structured, professional technical documents that satisfy the needs of an entire startup product team — from PM to QA.

## Preferences

_On startup, use the Read tool to load `~/.claude/skills/exploration-to-spec/preferences.md`. If it doesn't exist, use defaults._

## Context

_On startup, use Bash to detect: current git branch, repo name, and working directory. Check if `~/.claude/skills/exploration-to-spec/reference/` exists for templates._

## Command routing

Check `$ARGUMENTS`:

- **`help`** → display help then stop
- **`config`** → interactive setup then stop
- **`reset`** → delete `~/.claude/skills/exploration-to-spec/preferences.md`, confirm, stop
- **output path provided** → use as the file destination
- **empty** → ask where to save

### Help

```
Exploration to Spec — Convert conversations into technical specifications

Usage:
  /exploration-to-spec                                    Interactive (asks for output path)
  /exploration-to-spec ./docs/design.md                   Write to specific path
  /exploration-to-spec --format roadmap                   Use roadmap template
  /exploration-to-spec --format design-doc                Use design document template
  /exploration-to-spec --format adr                       Architecture Decision Record
  /exploration-to-spec --format rfc                       Request for Comments
  /exploration-to-spec --audience pm                      Optimize for product managers
  /exploration-to-spec --audience engineering             Optimize for engineers
  /exploration-to-spec --audience all                     Full cross-functional doc (default)
  /exploration-to-spec config                             Set preferences
  /exploration-to-spec reset                              Clear preferences
  /exploration-to-spec help                               This help

Examples:
  /exploration-to-spec ./technical-docs/insight-engine.md
  /exploration-to-spec --format roadmap --audience all ./docs/roadmap.md
  /exploration-to-spec --format adr                       (asks for output path)

Current preferences:
  (read from preferences.md)
```

### Config

Use `AskUserQuestion`:

**Q1** — "Default document format?" (Roadmap, Design Doc, ADR, RFC)

**Q2** — "Default audience?" (Product — executive summary focus, Engineering — schema/API focus, All — cross-functional)

**Q3** — "Default output directory?" (text input, e.g., `./technical-docs/`)

**Q4** — "Include diagrams style?" (ASCII art — works everywhere, Mermaid — rendered in GitHub/Notion, Both)

Save to `~/.claude/skills/exploration-to-spec/preferences.md`.

### Reset

Delete `~/.claude/skills/exploration-to-spec/preferences.md` and confirm: "Preferences cleared. Using defaults."

## First-time detection

If no preferences file exists, show:
"First time using /exploration-to-spec? Run `/exploration-to-spec config` to set defaults, or continue — I'll use sensible defaults."

Then proceed.

## Steps

### 1. Analyze conversation context

Scan the current conversation to extract:

- **Decisions made** — architecture choices, tech stack, patterns chosen
- **Systems explored** — repos, services, APIs, databases analyzed
- **Schemas defined** — data models, table structures, field mappings
- **Diagrams drawn** — system overviews, data flows, component maps
- **Components identified** — what's new vs reuse vs extend
- **Open questions** — unresolved items, decisions deferred
- **Phases/sequencing** — if implementation phases were discussed

Build an internal outline of the key content areas.

### 2. Determine format and audience

If not specified via flags, use preferences. If no preferences, ask via **AskUserQuestion**:

**Q1: Document format**
- Roadmap — phased delivery plan with architecture, schemas, API contracts, UI specs
- Design Doc — deep technical design for a single system/feature
- ADR — Architecture Decision Record (problem, options, decision, consequences)
- RFC — Request for Comments (proposal with alternatives and trade-offs)

**Q2: Primary audience**
- All (cross-functional) — sections for PM, engineering, design, QA
- Product — executive summary, business value, phases, open questions
- Engineering — architecture, schemas, APIs, implementation details

### 3. Determine output path

If provided in `$ARGUMENTS`, use it. Otherwise ask:

> Where should I save this document? (e.g., `./technical-docs/my-spec.md`)

### 4. Generate the document

Apply the selected template structure. Every document must follow these rules:

**Principles:**
- ASCII diagrams (work everywhere — terminals, GitHub, Slack, Notion)
- Tables over prose (scannable, concise)
- Each section works standalone (PM reads 1-2, engineer reads 3-5, designer reads 6)
- No fluff — every line earns its place
- Cross-reference schemas end-to-end (source → storage → API → UI)
- Include component inventory (new vs reuse vs extend)

**Template structures by format:**

#### Roadmap
```
1. Executive Summary          ← PM: what & why in one paragraph
2. Current State              ← Context for anyone new
   2.1 What exists today
   2.2 What was explored/prototyped
   2.3 Gap analysis (table)
3. Architecture               ← Tech leads, engineers
   3.1 System overview (diagram)
   3.2 Data flow (step-by-step)
   3.3 Component inventory (new/reuse/extend table)
   3.4 Storage strategy
4. Schema Design              ← Backend, QA
   4.1 Source → target mappings
   4.2 Table definitions (SQL)
   4.3 Cross-reference table (source → storage → API → UI)
5. API Contracts              ← Backend + frontend
   5.1 Ingest APIs
   5.2 Query APIs
   5.3 Events
6. UI Requirements            ← Design, frontend
   6.1 Component specs with ASCII mockups
   6.2 Field mapping tables
   6.3 Pages & routes
7. Implementation Phases      ← PM, project managers
   Phase N: Goal, tasks table, acceptance criteria
8. Testing Strategy           ← QA
   Per-phase test matrix (type, test, owner)
9. Open Questions             ← Everyone
   Numbered table with impact and status
```

#### Design Doc
```
1. Overview                   ← Problem, goals, non-goals
2. Background                 ← Current state, prior art
3. Architecture               ← System design with diagrams
4. Detailed Design            ← Schemas, APIs, algorithms
5. Alternatives Considered    ← What else was evaluated and why not
6. Cross-cutting Concerns     ← Security, observability, migration
7. Implementation Plan        ← Sequencing, dependencies
8. Open Questions
```

#### ADR
```
# ADR-NNN: [Title]
Status: [Proposed | Accepted | Deprecated]
Date: YYYY-MM-DD

## Context                    ← What situation led to this decision
## Decision                   ← What was decided and why
## Options Considered         ← Alternatives with trade-offs
## Consequences               ← What follows from this decision
## References                 ← Related docs, tickets, conversations
```

#### RFC
```
# RFC: [Title]
Author: [name] | Date: YYYY-MM-DD | Status: Draft

## Summary                    ← One paragraph
## Motivation                 ← Why this change is needed
## Proposal                   ← Detailed design
## Alternatives               ← What else was considered
## Risks & Mitigations        ← What could go wrong
## Rollout Plan               ← How to ship it
## Open Questions             ← What needs resolving
```

### 5. Review and refine

After generating, do a self-review pass:

- Remove any section that's empty or has only placeholder text
- Verify all diagrams are valid ASCII (no broken boxes)
- Ensure cross-reference tables are complete (no "TBD" unless genuinely unresolved)
- Check that every schema field in the UI mockup has a data source
- Verify component inventory covers everything discussed

### 6. Write the file

Write the document to the specified path.

Report:
```
Document written to: [path]
Format: [format]
Audience: [audience]
Sections: [count]
Lines: [count]
```

### 7. Offer follow-ups

Via **AskUserQuestion**:

- "Open in editor" — suggest the user opens the file
- "Generate a summary slide" — create a 5-bullet executive summary
- "Create Linear tickets from phases" — extract tasks into ticket format
- "Done" — finish

### 8. Learn

If the user made corrections:
- Changed the format or structure
- Added/removed sections
- Preferred different diagram style
- Chose a different output path pattern

Save patterns to preferences.

## Principles

- **Conversation is the source of truth** — extract decisions from the discussion, don't invent new ones. If something wasn't discussed, flag it as an open question.
- **Every audience in one doc** — PMs read the summary, engineers read the schemas, designers read the UI specs. One document, multiple entry points.
- **Tables beat paragraphs** — a well-structured table communicates more than three paragraphs. Use tables for mappings, inventories, comparisons, and test matrices.
- **Diagrams are ASCII** — they must render correctly in terminals, GitHub markdown, Slack, and Notion. No external image dependencies.
- **Pragmatic over perfect** — this is a working document, not a thesis. Include enough detail to start implementation, flag gaps as open questions, and move on.