Skip to content
This repository was archived by the owner on Apr 11, 2026. It is now read-only.

Commit 0af3edd

Browse files
z23ccclaude
andcommitted
feat: expand brainstorm to 20 forcing questions across 5 dimensions
5 dimensions × 4-5 questions each = 20 questions (vs previous 7): - Dimension 1: Problem Reality (4Q) — demand evidence, status quo, specificity, cost - Dimension 2: Solution Space (5Q) — narrowest wedge, existing code, alternatives, non-goals, precedent - Dimension 3: Risk & Failure (4Q) — pre-mortem, blast radius, edge cases, security - Dimension 4: Implementation (4Q) — integration, temporal walk-through, testing, dependencies - Dimension 5: Long-term (3Q) — maintainability, scalability, future-fit (Large tier only) Adaptive tier sizing: - Trivial: Q1-6 only (6 questions) - Medium: Q1-17 (17 questions) - Large: Q1-20 all (20 questions) Every question has reject/accept criteria + mandatory pushback. Quality scoring /25 with re-exploration if <15. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent bc6ffad commit 0af3edd

1 file changed

Lines changed: 147 additions & 83 deletions

File tree

skills/flow-code-brainstorm/steps/step-03-self-interview.md

Lines changed: 147 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22

33
## Interactive Mode (AUTO_MODE=false)
44

5-
Ask questions **one at a time** via `AskUserQuestion`. Wait for each answer. Apply pushback rules below.
5+
Ask questions **one at a time** via `AskUserQuestion`. Wait for each answer. Apply pushback rules.
66

77
## Auto Mode (AUTO_MODE=true)
88

99
AI self-interview — no `AskUserQuestion`. All answers from codebase analysis + reasoning.
1010

1111
**Output contract (auto mode):**
12-
1. Print each Q&A pair to stdout (user sees the reasoning)
12+
1. Print each Q&A to stdout (user sees reasoning)
1313
2. Embed full trace in requirements doc under `## Self-Interview Trace`
1414

1515
---
@@ -18,134 +18,198 @@ AI self-interview — no `AskUserQuestion`. All answers from codebase analysis +
1818

1919
Before questioning, gather hard evidence:
2020

21-
1. **Affected surface**: `flowctl find "<key terms>" --json` → list all related files
22-
2. **Current patterns**: Read 3-5 key files. How does the codebase handle similar things?
23-
3. **Dependencies**: Check imports, configs, shared types
24-
4. **Test coverage**: Do tests exist? What kind? What's missing?
25-
5. **Recent history**: `git log --oneline -20` on affected files
26-
6. **Existing specs**: Check `.flow/specs/` and `.flow/epics/` for related work
27-
7. **Impact graph**: `flowctl graph impact <main-file> --json`what would break?
21+
1. `flowctl find "<key terms>" --json` → list all related files
22+
2. Read 3-5 key files — how does the codebase handle similar things?
23+
3. Check imports, configs, shared types for dependencies
24+
4. `git log --oneline -20` on affected files
25+
5. Check `.flow/specs/` and `.flow/epics/` for related prior work
26+
6. `flowctl graph impact <main-file> --json` → what would break?
27+
7. `flowctl graph map --json`project overview
2828

2929
---
3030

31-
## Phase A2: Forcing Questions (Sequential, with Pushback)
31+
## Phase A2: Forcing Questions (5 Dimensions × 4-5 Questions Each)
3232

33-
Each question has **rejection criteria** — answers that are too vague MUST be re-examined. In auto mode, if the first answer falls into a rejection category, the AI must challenge itself and provide a more specific answer.
34-
35-
Format each as:
33+
Each question has **rejection criteria**. In auto mode, if the first answer is vague, challenge and refine.
3634

35+
Format:
3736
```
38-
### Q1: [Question]
39-
**First answer:** [initial response]
40-
**Pushback:** [challenge the answer using rejection criteria]
41-
**Refined answer:** [specific, evidence-grounded response]
37+
### Q[N]: [Question]
38+
**Answer:** [response with evidence]
39+
**Pushback:** [challenge if answer hits rejection criteria]
40+
**Refined:** [specific, grounded answer]
4241
```
4342

44-
### Q1: Demand Reality
45-
> What's the strongest evidence this change is actually needed?
43+
---
4644

47-
- **Reject**: "It would be nice" / "best practice says" / "users might want" / "it's cleaner"
48-
- **Accept**: Specific failure observed, measured time waste, blocked workflow, real user complaint, production incident
49-
- **Pushback test**: Does the answer cite a SPECIFIC event/metric, or is it hypothetical?
45+
### Dimension 1: Problem Reality (4 questions)
46+
47+
**Q1: Demand Evidence**
48+
> What's the strongest evidence this change is actually needed?
49+
- Reject: "It would be nice" / "best practice" / "users might want" / "cleaner code"
50+
- Accept: Specific failure, measured waste, blocked workflow, production incident
51+
- Push: Does the answer cite a SPECIFIC event/metric, or is it hypothetical?
5052

51-
### Q2: Status Quo
53+
**Q2: Status Quo**
5254
> How is this being handled RIGHT NOW without this change?
55+
- Reject: "Nothing handles this" (no workaround = no urgency)
56+
- Accept: Specific workaround, manual steps, duct-tape solution
57+
- Push: Who is suffering and how often? If nobody, why build it?
5358

54-
- **Reject**: "Nothing handles this" (if nothing does, pain isn't real enough)
55-
- **Accept**: Specific workaround described, manual steps counted, duct-tape solution identified
56-
- **Pushback test**: If no workaround exists, WHO is suffering and HOW? If nobody, why build it?
59+
**Q3: Desperate Specificity**
60+
> Name the specific user/workflow/scenario that needs this MOST.
61+
- Reject: Categories ("developers", "users", "the team")
62+
- Accept: A specific role, a specific task, what fails for THEM
63+
- Push: Can you describe their current workflow step by step?
5764

58-
### Q3: Narrowest Wedge
59-
> What's the smallest version that delivers 80% of the value?
65+
**Q4: Cost of Inaction**
66+
> What happens in 3 months if we do NOTHING?
67+
- Reject: "Technical debt grows" (unmeasurable)
68+
- Accept: "Feature X becomes impossible" / "Latency exceeds SLA" / "Team spends N hours/week on workaround"
69+
70+
---
6071

61-
- **Reject**: "We need the full implementation" / "It won't work if incomplete"
62-
- **Accept**: One function, one file, one config change that unblocks the core use case
63-
- **Pushback test**: Can you ship this in < 1 day? If not, scope is too big.
72+
### Dimension 2: Solution Space (5 questions)
73+
74+
**Q5: Narrowest Wedge**
75+
> What's the smallest version that delivers 80% of the value?
76+
- Reject: "We need the full implementation"
77+
- Accept: One function/file/config that unblocks the core use case
78+
- Push: Can this ship in <1 day? If not, cut more.
6479

65-
### Q4: Existing Code Audit
80+
**Q6: Existing Code Audit**
6681
> What already exists in the codebase that solves part of this?
82+
- Reject: "Nothing relevant" (search harder — `flowctl find`, `graph refs`)
83+
- Accept: Specific functions, patterns, utilities to reuse or extend
84+
- Push: If >50% exists, is this an extension/refactor rather than new build?
85+
86+
**Q7: Alternative Approaches**
87+
> What are 2 completely different ways to solve this?
88+
- Reject: Variations of the same approach ("do it in module A vs module B")
89+
- Accept: Genuinely different architectures (e.g., polling vs webhooks, batch vs streaming)
90+
- Push: What would a developer who disagrees with your approach suggest?
91+
92+
**Q8: Non-Goals**
93+
> What should this explicitly NOT do?
94+
- Reject: "It should do everything the user needs" (scope creep)
95+
- Accept: Explicit boundaries ("no UI", "no migration", "read-only first")
96+
- Push: Check `.flow/project-context.md` Non-Goals — does this align?
97+
98+
**Q9: Precedent**
99+
> Has this been attempted before in this codebase? What happened?
100+
- Check: git log for reverted commits, closed PRs, abandoned specs
101+
- Accept: "Attempted in fn-X but abandoned because Y" → learn from it
67102

68-
- **Reject**: "Nothing relevant" (search harder — `flowctl find`, `graph refs`)
69-
- **Accept**: Specific functions, patterns, utilities that can be reused or extended
70-
- **Pushback test**: If >50% already exists, is this a refactor/extension rather than a new feature?
103+
---
71104

72-
### Q5: Integration & Contracts
73-
> What systems/modules will this touch? What contracts must be preserved?
105+
### Dimension 3: Risk & Failure (4 questions)
74106

75-
- **Reject**: "It's self-contained" (almost nothing is — check imports, callers, config)
76-
- **Accept**: Listed APIs, shared types, database schemas, config files affected
77-
- **Pushback test**: Run `flowctl graph impact <file>` — is the impact bigger than expected?
107+
**Q10: Pre-mortem**
108+
> Assume this shipped and FAILED. Top 3 most likely causes?
109+
- Reject: Vague categories ("security issues", "performance problems")
110+
- Accept: "Auth token not refreshed after 1hr", "N+1 query on list page"
111+
- Push: For each cause — is prevention cheaper than fix-later?
78112

79-
### Q6: Failure Pre-mortem
80-
> Assume this shipped and FAILED in production. Top 3 most likely causes?
113+
**Q11: Blast Radius**
114+
> If this goes wrong, what's the worst that happens?
115+
- Reject: "It breaks" (too vague)
116+
- Accept: "Data loss in X table" / "All API calls return 500" / "Users locked out"
117+
- Push: Is there a rollback plan? Feature flag? Database backup?
81118

82-
- **Reject**: Vague categories ("security issues", "performance problems")
83-
- **Accept**: Specific scenarios ("auth token not refreshed after 1hr", "N+1 query on user list page")
84-
- **Pushback test**: For each cause, is prevention cost < fix-later cost? If not, accept the risk explicitly.
119+
**Q12: Edge Cases**
120+
> What are the 3 trickiest edge cases?
121+
- Must be specific: empty inputs, concurrent access, large payloads, timezone issues, Unicode, null values
122+
- Push: Which edge case is the one that teams ALWAYS forget?
85123

86-
### Q7: Temporal Walk-Through
87-
> Walk through implementation step by step:
124+
**Q13: Security & Privacy**
125+
> Does this touch auth, user data, external APIs, or file system?
126+
- If yes: What's the attack surface? Input validation? Secrets management?
127+
- If no: Confirm by checking imports — really no auth/data handling?
88128

89-
```
90-
Hour 1 (foundations): What does the implementer need to know FIRST?
91-
Hour 2-3 (core): What ambiguities will they HIT?
92-
Hour 4-5 (integration): What will SURPRISE them?
93-
Hour 6+ (polish): What will they WISH they'd planned for?
94-
```
129+
---
95130

96-
Surface decisions that should be resolved NOW, not during implementation.
131+
### Dimension 4: Implementation (4 questions)
132+
133+
**Q14: Integration Points**
134+
> What systems/modules will this touch? What contracts must be preserved?
135+
- Reject: "It's self-contained" (check imports, callers, config)
136+
- Accept: Listed APIs, shared types, database schemas, config files
137+
- Push: `flowctl graph impact <file>` — is impact bigger than expected?
138+
139+
**Q15: Temporal Walk-Through**
140+
> Walk through implementation hour by hour:
141+
- Hour 1 (setup): What does the implementer need to know FIRST?
142+
- Hour 2-3 (core): What ambiguities will they HIT?
143+
- Hour 4-5 (integration): What will SURPRISE them?
144+
- Hour 6+ (polish): What will they WISH they'd planned for?
145+
146+
**Q16: Testing Strategy**
147+
> What test types are needed? What's the current coverage gap?
148+
- Reject: "We'll add tests" (what KIND?)
149+
- Accept: "Unit tests for parser, integration test for API endpoint, E2E for user flow"
150+
- Push: Is there an existing test pattern to follow? (`flowctl find "test" --json`)
151+
152+
**Q17: Dependencies & Ordering**
153+
> What must happen BEFORE this can start? What's blocked until this is done?
154+
- Check: Other in-progress epics, required migrations, API changes
155+
- Push: Can any dependency be parallelized?
97156

98157
---
99158

100-
## Extended Questions (Large tier only — skip for Trivial/Medium)
159+
### Dimension 5: Long-term (3 questions) — Large tier only
101160

102-
### Q8: Performance Impact
103-
> Will this change affect latency, memory, or throughput?
104-
- Check hot paths, data volume, caching layers in affected code.
161+
**Q18: Maintainability**
162+
> In 6 months, will a new developer understand this code without the author?
163+
- Push: What documentation/comments are needed? What's the non-obvious part?
105164

106-
### Q9: Security Surface
107-
> Does this introduce or modify auth, data handling, or external access?
108-
- Check auth middleware, input validation, sensitive data flows.
165+
**Q19: Scalability**
166+
> What breaks first at 10x load? 100x?
167+
- Accept: "Database becomes bottleneck at 10K concurrent users"
168+
- Push: What's the cheapest mitigation (caching, pagination, async)?
109169

110-
### Q10: Migration & Compatibility
111-
> Are there breaking changes? Data migration needed? Feature flags?
112-
- Check API contracts, database schemas, config formats.
170+
**Q20: Future-Fit**
171+
> If the project's direction changes in 1 year, does this become MORE or LESS useful?
172+
- Push: Is this a building block or a dead end?
113173

114174
---
115175

116176
## Phase A3: Structured Deepening
117177

118-
After all questions, apply ONE named reasoning method (auto-selected based on task type):
178+
After all questions, apply ONE named reasoning method (auto-selected):
119179

120180
| Task type | Method | Prompt |
121181
|-----------|--------|--------|
122-
| New feature / spec | **Pre-mortem** | "Assume this failed 6 months later. What are the 3 most likely causes?" |
123-
| Architecture / refactor | **First Principles** | "Strip all assumptions. What's the simplest solution from ground truth?" |
124-
| Bug fix / reliability | **Inversion** | "How would you guarantee this fails? Now avoid those things." |
182+
| New feature / spec | **Pre-mortem** | "Assume this failed 6 months later. 3 most likely causes?" |
183+
| Architecture / refactor | **First Principles** | "Strip all assumptions. Simplest solution from ground truth?" |
184+
| Bug fix / reliability | **Inversion** | "How would you guarantee this fails? Avoid those things." |
125185
| Security / API | **Red Team** | "You're an attacker. How do you break this?" |
126-
| Scope decision | **Constraint Removal** | "Remove all constraints (time, tech, team). What changes? What stays?" |
186+
| Scope decision | **Constraint Removal** | "Remove all constraints. What changes?" |
127187

128-
Append deepening insights to the self-interview trace.
188+
Append insights to self-interview trace.
129189

130190
---
131191

132-
## Pushback Scoring
192+
## Quality Scoring
133193

134-
After all Q&A, rate the exploration quality:
194+
Rate the exploration (1-5 per dimension):
135195

136-
| Dimension | Score (1-5) | Criteria |
137-
|-----------|-------------|----------|
138-
| **Specificity** | ? | Are answers citing specific files, lines, metrics? |
139-
| **Evidence** | ? | Are claims backed by code/git/data, not assumption? |
140-
| **Challenge depth** | ? | Did pushback reveal anything the first answer missed? |
141-
| **Completeness** | ? | Are all major risk areas covered? |
142-
| **Actionability** | ? | Can a developer start implementing from these answers? |
143-
144-
**Total: ?/25**
196+
| Dimension | Score | Criteria |
197+
|-----------|-------|----------|
198+
| **Problem Reality** (Q1-4) | /5 | Specific evidence, not hypothetical? |
199+
| **Solution Space** (Q5-9) | /5 | Alternatives explored, non-goals defined? |
200+
| **Risk & Failure** (Q10-13) | /5 | Concrete failure modes, not categories? |
201+
| **Implementation** (Q14-17) | /5 | Temporal walk-through done, deps mapped? |
202+
| **Long-term** (Q18-20) | /5 | Maintainability and scalability addressed? |
203+
| **Total** | /25 | |
145204

146205
- **20-25**: Excellent — proceed to approaches
147-
- **15-19**: Good — proceed but flag weak areas for plan phase
148-
- **<15**: Insufficient — add 2-3 follow-up Q&A pairs on the weakest dimensions
206+
- **15-19**: Good — proceed but flag weak dimensions
207+
- **<15**: Insufficient — add 2-3 follow-up Q&A on weakest dimension, re-score
208+
209+
**Adaptive tier sizing:**
210+
- **Trivial**: Q1-6 only (6 questions, ~3 min)
211+
- **Medium**: Q1-17 (17 questions, ~8 min)
212+
- **Large**: Q1-20 all (20 questions, ~12 min)
149213

150214
## Next Step
151215

0 commit comments

Comments
 (0)