exploration-to-spec · diff

git:20260303.717bcda to git:20260911.22df896

2 added, 0 removed. Audit A to A.

---

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.

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.