mostafa-drz/exploration-to-spec

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.