majiayu000 /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
- Gather context - Review the brainstorm conversation (or get user input if invoked directly)
- Extract key elements - Problem, solution, requirements, constraints
- Identify gaps - Note any open questions that would block planning
- Write spec.md - Use the template below
- 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>/