exploration-write-spec

/exploration-write-spec - Spec Document Generator

Transform brainstorm conversations into structured spec documents. This skill produces consistent spec.md files that the planning phase can reliably parse.

When to Use

Called at the end of /brainstorm when the user confirms they're ready to capture their exploration. Can also be invoked directly if you have a clear idea ready to document.

The Process

1. Gather context - Review the brainstorm conversation (or get user input if invoked directly)
2. Extract key elements - Problem, solution, requirements, constraints
3. Identify gaps - Note any open questions that would block planning
4. Write spec.md - Use the template below
5. Confirm output location - Show user the file path

Output

Location: .space-agents/exploration/ideas/YYYY-MM-DD-<topic>/spec.md

The spec file lives alongside any exploration notes in the same topic folder. This folder will later move to planned/ when /plan processes it.

spec.md Template

# Exploration: [Topic Title]

**Date:** YYYY-MM-DD
**Status:** [Ready for planning | Needs discussion | Blocked]

---

## Problem

What problem are we solving? Why does this matter?

[1-3 paragraphs describing the problem, its impact, and why it needs solving]

---

## Solution

High-level approach. The "what" not the "how".

[Describe the solution at a conceptual level. Include diagrams/tables if they clarify the approach.]

---

## Requirements

Must-have functionality. Use checklist format for tracking.

- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

---

## Non-Requirements

Explicitly out of scope. Prevents scope creep during planning.

- Not doing X
- Not changing Y
- Not supporting Z

---

## Architecture

Components, data flow, key technical decisions.

[Include diagrams, flow descriptions, component interactions. This section should give a developer enough context to understand how the pieces fit together.]

---

## Constraints

Technical limitations, patterns to follow, dependencies.

- [Constraint 1 - e.g., must work with existing API]
- [Constraint 2 - e.g., follow project naming conventions]
- [Constraint 3 - e.g., external dependency requirement]

---

## Success Criteria

How do we know it's done? Checklist format for verification.

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

---

## Open Questions

Things still to be decided. Unresolved questions may block planning.

1. [Question 1] - [Context/options if known]
2. [Question 2] - [Context/options if known]

---

## Next Steps

What happens after this exploration.

1. `/plan` to create implementation tasks
2. [Any specific preparatory work needed]
3. [Dependencies to resolve first]

Section Guidelines

Section	Purpose	Planning Impact
Problem	Why are we doing this?	Guides priority decisions
Solution	What approach?	Shapes feature structure
Requirements	What must it do?	Becomes task acceptance criteria
Non-Requirements	What's out of scope?	Prevents scope creep
Architecture	How do pieces fit?	Informs task breakdown
Constraints	What limits us?	Affects implementation choices
Success Criteria	How do we verify?	Defines "done" for feature
Open Questions	What's unresolved?	Blocks planning if critical
Next Steps	What's next?	Guides user action

Status Values

• Ready for planning - All critical questions resolved, can proceed to /plan
• Needs discussion - Some open questions remain, but not blocking
• Blocked - Critical questions must be resolved before planning

Tips

• Keep Problem and Solution sections concise - save details for Architecture
• Requirements should be testable - if you can't verify it, refine it
• Non-Requirements prevent future scope creep - be explicit
• Open Questions with no resolution path should set status to "Blocked"
• Success Criteria should map roughly to what the feature will deliver

Folder Lifecycle

/brainstorm conversation
    |
    v
/exploration-write-spec creates:
    exploration/ideas/YYYY-MM-DD-<topic>/spec.md
    |
    v
/plan reads spec.md, creates plan.md, moves to:
    exploration/planned/YYYY-MM-DD-<topic>/
    |
    v
/plan creates Beads, moves to:
    mission/staged/YYYY-MM-DD-<topic>/