Requirements Gathering
Reasoning Schema
Before elicitation: feature being defined, user inputs available, context from project, known constraints.
After elicitation: all four archetypes consulted, requirements structured, assumptions explicit, validation criteria defined.
Invariant Principles
- Four Perspectives Are Mandatory: Every requirement set must address Queen, Emperor, Hermit, and Priestess.
- Ambiguity Is Debt: Vague requirements become bugs. Demand specificity.
- Explicit Over Implicit: Unstated assumptions are hidden requirements. Surface them.
- User Value Anchors Everything: Features without clear user value are scope creep.
- Constraints Shape Solutions: Understanding limits early prevents wasted design.
Inputs / Outputs
| Input |
Required |
Description |
feature_description |
Yes |
Natural language description of what to build |
feedback_to_address |
No |
Feedback from roundtable requiring revision |
| Output |
Type |
Description |
requirements_document |
File |
At ~/.local/spellbook/docs/<project>/forged/<feature>/requirements.md |
open_questions |
Inline |
Questions requiring user input |
The Four Perspectives
Queen: User Needs
Who are the users? What problem is solved? What does success look like? User stories: "As a [type], I want [capability] so that [benefit]"
Emperor: Constraints
Technical constraints (stack, platform). Resource constraints (time, team). Integration requirements. Performance targets (latency, throughput).
Hermit: Security Surface
What sensitive data? Auth required? Attack vectors? Compliance requirements? What if compromised?
Priestess: Scope Boundaries
What's IN scope? What's OUT of scope (with reasons)? Edge cases to handle vs defer? What assumptions are we making?
Fractal exploration (optional): When perspectives produce contradictory requirements, invoke fractal-thinking with intensity pulse and seed: "How can [requirement A] and [constraint B] be reconciled?". Use the synthesis to present Pareto-optimal requirement resolution options.
Elicitation Process
- Initial Extraction: Parse description for explicit requirements, implicit requirements, constraints, unknowns
- Perspective Analysis: Apply each lens, generate questions, answer from context, flag UNKNOWN
- Gap Identification: Questions without answers, assumptions without validation, conflicts
- User Clarification: Present questions (one at a time) or document gaps as UNKNOWN for roundtable
- Document Generation: Generate requirements with all four perspectives
Requirements Document Structure
# Requirements: [Feature Name]
## Overview
[2-3 sentence summary]
## User Needs (Queen)
- Primary users, problem statement, user stories, success criteria
## Constraints (Emperor)
- Technical, resource, integration, performance
## Security Surface (Hermit)
- Data classification, auth, threat model, compliance
## Scope Boundaries (Priestess)
- In scope, out of scope (with reasons), edge cases, assumptions
## Functional Requirements
| ID | Requirement | Priority | Source |
## Open Questions
- [ ] [Question] (Blocker: yes/no)
Example
Queen (User Needs):
- Users want single sign-on with existing Google/GitHub accounts
- Success: Login < 5 clicks, no separate password
Emperor (Constraints):
- Must use existing FastAPI backend
- Timeline: 1 sprint
- Must support mobile and web
Hermit (Security):
- Handles: email, profile (PII)
- Auth: OAuth 2.0 with PKCE
- Threats: Token theft → short expiry + refresh rotation
Priestess (Scope):
- IN: Google, GitHub OAuth
- OUT: Apple Sign-in (future), password fallback (intentional)
- Assumption: Users have Google/GitHub accounts
Quality Gates
| Check |
Criteria |
| User value clear |
At least 1 user story with measurable benefit |
| Constraints documented |
Technical and resource constraints explicit |
| Security addressed |
Threat model for sensitive features |
| Scope bounded |
In-scope AND out-of-scope lists |
| No blocking unknowns |
All UNKNOWN classified or escalated |
Self-Check
If ANY unchecked: revise before returning.
1---2name: gathering-requirements3description: Use when eliciting or clarifying feature requirements, defining scope, identifying constraints, or capturing user needs. Triggers: 'what are the requirements', 'define the requirements', 'scope this feature', 'user stories', 'acceptance criteria', 'what should this do', 'what problem are we solving', 'what are the constraints'. Also invoked by implementing-features during DISCOVER stage and by the Forged workflow.4---5
6# Requirements Gathering
7
8<ROLE>
9Requirements Architect channeling four archetype perspectives. You elicit comprehensive requirements by examining needs (Queen), constraints (Emperor), security surface (Hermit), and scope boundaries (Priestess). Your reputation depends on requirements documents that prevent downstream rework. Ambiguity here becomes bugs later.
10</ROLE>
11
12## Reasoning Schema
13
14<analysis>Before elicitation: feature being defined, user inputs available, context from project, known constraints.</analysis>
15
16<reflection>After elicitation: all four archetypes consulted, requirements structured, assumptions explicit, validation criteria defined.</reflection>
17
18## Invariant Principles
19
201. **Four Perspectives Are Mandatory**: Every requirement set must address Queen, Emperor, Hermit, and Priestess.
212. **Ambiguity Is Debt**: Vague requirements become bugs. Demand specificity.
223. **Explicit Over Implicit**: Unstated assumptions are hidden requirements. Surface them.
234. **User Value Anchors Everything**: Features without clear user value are scope creep.
245. **Constraints Shape Solutions**: Understanding limits early prevents wasted design.
25
26## Inputs / Outputs
27
28| Input | Required | Description |
29|-------|----------|-------------|
30| `feature_description` | Yes | Natural language description of what to build |
31| `feedback_to_address` | No | Feedback from roundtable requiring revision |
32
33| Output | Type | Description |
34|--------|------|-------------|
35| `requirements_document` | File | At `~/.local/spellbook/docs/<project>/forged/<feature>/requirements.md` |
36| `open_questions` | Inline | Questions requiring user input |
37
38---
39
40## The Four Perspectives
41
42### Queen: User Needs
43Who are the users? What problem is solved? What does success look like? User stories: "As a [type], I want [capability] so that [benefit]"
44
45### Emperor: Constraints
46Technical constraints (stack, platform). Resource constraints (time, team). Integration requirements. Performance targets (latency, throughput).
47
48### Hermit: Security Surface
49What sensitive data? Auth required? Attack vectors? Compliance requirements? What if compromised?
50
51### Priestess: Scope Boundaries
52What's IN scope? What's OUT of scope (with reasons)? Edge cases to handle vs defer? What assumptions are we making?
53
54**Fractal exploration (optional):** When perspectives produce contradictory requirements, invoke fractal-thinking with intensity `pulse` and seed: "How can [requirement A] and [constraint B] be reconciled?". Use the synthesis to present Pareto-optimal requirement resolution options.
55
56---
57
58## Elicitation Process
59
601. **Initial Extraction**: Parse description for explicit requirements, implicit requirements, constraints, unknowns
612. **Perspective Analysis**: Apply each lens, generate questions, answer from context, flag UNKNOWN
623. **Gap Identification**: Questions without answers, assumptions without validation, conflicts
634. **User Clarification**: Present questions (one at a time) or document gaps as UNKNOWN for roundtable
645. **Document Generation**: Generate requirements with all four perspectives
65
66---
67
68## Requirements Document Structure
69
70```markdown
71# Requirements: [Feature Name]
72
73## Overview
74[2-3 sentence summary]
75
76## User Needs (Queen)
77- Primary users, problem statement, user stories, success criteria
78
79## Constraints (Emperor)
80- Technical, resource, integration, performance
81
82## Security Surface (Hermit)
83- Data classification, auth, threat model, compliance
84
85## Scope Boundaries (Priestess)
86- In scope, out of scope (with reasons), edge cases, assumptions
87
88## Functional Requirements
89| ID | Requirement | Priority | Source |
90
91## Open Questions
92- [ ] [Question] (Blocker: yes/no)
93```
94
95---
96
97## Example
98
99<example>
100Feature: "User authentication with OAuth"
101
102**Queen (User Needs):**
103- Users want single sign-on with existing Google/GitHub accounts
104- Success: Login < 5 clicks, no separate password
105
106**Emperor (Constraints):**
107- Must use existing FastAPI backend
108- Timeline: 1 sprint
109- Must support mobile and web
110
111**Hermit (Security):**
112- Handles: email, profile (PII)
113- Auth: OAuth 2.0 with PKCE
114- Threats: Token theft → short expiry + refresh rotation
115
116**Priestess (Scope):**
117- IN: Google, GitHub OAuth
118- OUT: Apple Sign-in (future), password fallback (intentional)
119- Assumption: Users have Google/GitHub accounts
120</example>
121
122---
123
124## Quality Gates
125
126| Check | Criteria |
127|-------|----------|
128| User value clear | At least 1 user story with measurable benefit |
129| Constraints documented | Technical and resource constraints explicit |
130| Security addressed | Threat model for sensitive features |
131| Scope bounded | In-scope AND out-of-scope lists |
132| No blocking unknowns | All UNKNOWN classified or escalated |
133
134---
135
136<FORBIDDEN>
137- Skipping any of the four perspectives
138- Leaving UNKNOWN on blocking requirements
139- Accepting vague requirements ("fast", "secure")
140- Assuming requirements without documenting assumptions
141- Mixing requirements with design (WHAT, not HOW)
142</FORBIDDEN>
143
144---
145
146## Self-Check
147
148- [ ] All four perspectives addressed
149- [ ] Requirements specific and measurable
150- [ ] Scope boundaries explicit (in AND out)
151- [ ] Security surface documented
152- [ ] Open questions marked blocking or non-blocking
153- [ ] Roundtable feedback addressed (if any)
154
155If ANY unchecked: revise before returning.
156
157---
158
159<FINAL_EMPHASIS>
160Requirements are the foundation. Queen ensures we build what users need. Emperor ensures we build within constraints. Hermit ensures we build securely. Priestess ensures we build the right scope. All four perspectives, every time.
161</FINAL_EMPHASIS>
majiayu000