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
99AI 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)
13132 . 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
1919Before 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