spec

Interactive requirements discovery through Socratic dialogue and systematic exploration

/brainstorm - Interactive Requirements Discovery

Triggers

  • Ambiguous project ideas requiring structured exploration
  • Requirements discovery and specification development needs
  • Concept validation and feasibility assessment requests
  • Cross-session brainstorming and iterative refinement scenarios

Behavioral Flow

  1. Explore: Transform ambiguous ideas through Socratic dialogue and systematic questioning
  2. Analyze: Coordinate multiple personas for domain expertise and comprehensive analysis
  3. Validate: Apply feasibility assessment and requirement validation across domains
  4. Specify: Generate concrete specifications with cross-session persistence capabilities
  5. Handoff: Create actionable briefs ready for implementation or further development

Key behaviors:

  • Multi-persona orchestration across architecture, analysis, frontend, backend, security domains
  • Systematic execution with progressive dialogue enhancement and parallel exploration
  • Cross-session persistence with comprehensive requirements discovery documentation

Tool Coordination

  • Read/Write/Edit: Requirements documentation and specification generation
  • WebSearch: Market research, competitive analysis, and technology validation
  • sequentialthinking: Structured reasoning for complex requirements analysis
  • AskUserQuestion: Clarify specification via interactive dialog

Key Patterns

  • Socratic Dialogue: Question-driven exploration → systematic requirements discovery
  • Multi-Domain Analysis: Cross-functional expertise → comprehensive feasibility assessment
  • Progressive Coordination: Systematic exploration → iterative refinement and validation
  • Specification Generation: Concrete requirements → actionable implementation briefs

Boundaries

Will:

  • Transform ambiguous ideas into concrete specifications through systematic exploration
  • Coordinate multiple personas and MCP servers for comprehensive analysis
  • Provide cross-session persistence and progressive dialogue enhancement

Will Not:

  • Make implementation decisions without proper requirements discovery
  • Override user vision with prescriptive solutions during exploration phase
  • Bypass systematic exploration for complex multi-domain projects

CRITICAL BOUNDARIES

STOP AFTER REQUIREMENTS DISCOVERY

This command produces a REQUIREMENTS SPECIFICATION ONLY.

Explicitly Will NOT:

  • Create architecture diagrams or system designs
  • Generate implementation code
  • Make architectural decisions
  • Design database schemas or API contracts
  • Create technical specifications beyond requirements

Output: Requirements document with:

  • Clarified user goals
  • Functional requirements
  • Non-functional requirements
  • User stories / acceptance criteria
  • Open questions for user

Spec format

File name: {YYY}-{feature_slug}.md.

# Specification: [Feature Name]

**Epic:** XXX — Epic name
**User Story:** YYY — User story description
**Related specs:** [name](file.md) (if any)

---

## 1. User Goal

One paragraph: who is the user, what they want to do, why they need it.

Example:
> A patient wants to quickly capture their thoughts in a diary so they can
> discuss them with their doctor at the next appointment. The entry should
> save automatically, without extra steps.

---

## 2. Context

_(Optional)_ Background, dependencies, relation to other features.

---

## 3. User Scenarios

Every scenario listed here MUST be implemented. If a scenario can be deferred,
move it to "Out of Scope" with a TG reference to a separate story.

### Scenario 1 — [Name]

[Description: what the user does and why]

**How to test independently**: [How to verify this scenario in isolation]

**Acceptance criteria**:

1. **Given**: [initial state].
   **When**: [user action].
   **Then**: [expected result].

2. **Given**: [another initial state].
   **When**: [action].
   **Then**: [result].

### Scenario 2 — [Name]

...

---

## 4. Functional Requirements

Everything listed here MUST be implemented. No priority column — if it's here,
it's required. Defer anything non-essential to "Out of Scope".

| #      | Requirement                         |
|--------|-------------------------------------|
| REQ-01 | [What the system must do]           |
| REQ-02 | [Another requirement]               |
| REQ-03 | [Yet another requirement]           |

---

## 5. Non-functional Requirements

_(Optional)_

| #      | Requirement                                       | Category       |
|--------|---------------------------------------------------|----------------|
| NFR-01 | [Response time, size limits, etc.]                | Performance    |
| NFR-02 | [Security requirement]                            | Security       |

---

## 6. Success Criteria

_(Optional)_

| #     | Criterion                                | How to measure           |
|-------|------------------------------------------|--------------------------|
| SC-01 | [Metric showing feature success]         | [Measurement method]     |

---

## 7. Data Model

_(Optional — only if the feature introduces new entities)_

Key entities and their fields. No storage details.

**Entity: [Name]**

| Field        | Type     | Constraints              | Description                 |
|--------------|----------|--------------------------|-----------------------------|
| id           | UUID     | PK                       | Unique identifier           |
| [field]      | [type]   | [constraints]            | [description]               |

**Typical constraints to consider for each field:**
- **Required / Optional** — can the field be null or omitted?
- **Uniqueness** — must the value be unique across the entity?
- **Length / Size limits** — min/max length for strings, max size for files or collections
- **Value range** — min/max for numbers, dates; allowed values for enums
- **Format / Pattern** — email, URL, phone, date format, regex pattern
- **Default value** — what value is used if not provided?
- **Referential integrity** — FK to another entity
- **Immutability** — can the field be updated after creation?

---

## 8. Screens

_(Optional — only if there is UI)_

### Screen: [Name]

**Purpose**: [What the user sees and does on this screen]

**Elements**:
- [Element 1] — [behavior]
- [Element 2] — [behavior]

**States**:
- Loading: [what the user sees]
- Empty state: [what the user sees]
- Error: [what the user sees]

**Navigation**: Where user comes from -> Where user goes next

---

## 9. API Endpoints

_(Optional — only if there is server interaction)_

Contract only: method, path, request/response bodies, error codes.

### [Action]

[METHOD] /api/v1/[resource]


**Request**:
```json
{
  "field": "value"
}

Response 200:

{
  "id": "uuid",
  "field": "value"
}

Errors:

CodeSituationResponse body
400[Description]{"error": "bad_request", "message": "..."}
404[Description]{"error": "not_found", "message": "..."}
409[Conflict description]{"error": "conflict", "message": "...", "current": {...}}

10. Edge Cases

(Optional — if behavior at boundaries is non-obvious)

  • [Case 1] — [expected behavior]
  • [Case 2] — [expected behavior]
  • [Offline scenario] — [expected behavior]

11. Out of Scope

What is NOT included in this specification and why:

  • [Feature X] — separate story ZZZ
  • [Feature Y] — deferred until [reason/phase]

## Checklist Before Completion

- [ ] User goal is clear without additional context
- [ ] Every scenario has acceptance criteria in Given/When/Then
- [ ] All functional requirements are mandatory (no priorities — defer the rest to Out of Scope)
- [ ] Scope boundary is explicit (what is NOT included and why)
- [ ] API describes contract, not implementation
- [ ] No implementation details (architecture, DB schemas, code)

Next Step: After specification completes, use /architect for architecture or /planner for implementation planning