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

Commit bc6ffad

Browse files
z23ccclaude
z23cc
and
claude
committed
feat: upgrade brainstorm to forcing-question depth (gstack pattern)
Step 3 (Self-Interview) rewritten: - 7 forcing questions with rejection criteria per question - Mandatory pushback: First answer → Challenge → Refined answer - Temporal walk-through: hour-by-hour implementation preview - Quality scoring (/25) — score <15 triggers follow-up questions Step 4 (Approaches) rewritten: - 3 mandatory distinct approaches: Narrow/Balanced/Ideal - Weighted scoring matrix (6 dimensions, /55 max) - Highest score wins (completeness as tiebreaker) Codex variant: 4 forcing questions with reject/accept criteria. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 591c242 commit bc6ffad

3 files changed

Lines changed: 213 additions & 107 deletions

File tree

‎codex/skills/flow-code-brainstorm/SKILL.md‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -75,24 +75,36 @@ Classify into one of three tiers:
7575

7676
Tell the user which tier you picked and why (one sentence).
7777

78-
## Phase 1: Pressure Test
79-
80-
Ask exactly 3 questions, **one at a time**, using `AskUserQuestion` for each.
81-
82-
**CRITICAL REQUIREMENT**: You MUST use the `AskUserQuestion` tool for every question. Do NOT output questions as plain text — they will be ignored.
83-
84-
Wait for each answer before asking the next question.
85-
86-
### Question 1: Who and why?
87-
> Who uses this? What's the specific pain point or motivation?
88-
89-
### Question 2: Cost of inaction?
90-
> What happens if we do nothing? What's the actual cost or risk?
91-
92-
### Question 3: Simpler framing?
93-
> Is there a simpler version that delivers 80% of the value? What's the minimum viable version?
94-
95-
After all 3 answers, summarize the key insights in 2-3 bullets before proceeding.
78+
## Phase 1: Forcing Questions (with Pushback)
79+
80+
Ask questions **one at a time** via `AskUserQuestion`. After each answer, apply pushback — challenge vague/hypothetical responses.
81+
82+
### Q1: Demand Reality
83+
> What's the strongest evidence this change is actually needed?
84+
- **Reject**: "It would be nice" / "best practice says" / "users might want"
85+
- **Accept**: Specific failure, measured waste, blocked workflow, production incident
86+
- If answer is vague, reframe: "Let me restate what I think the core need is: [restate]. Is that right?"
87+
88+
### Q2: Status Quo
89+
> How is this being handled RIGHT NOW without this change?
90+
- **Reject**: "Nothing handles this" (if nobody works around it, pain isn't real)
91+
- **Accept**: Specific workaround, manual steps, duct-tape solution
92+
- If no workaround: "Who is suffering and how? If nobody, should we build this?"
93+
94+
### Q3: Narrowest Wedge
95+
> What's the smallest version that delivers 80% of the value?
96+
- **Reject**: "We need the full implementation"
97+
- **Accept**: One function/file/config change that unblocks the core use case
98+
- Push: "Can this ship in < 1 day? If not, can we cut more?"
99+
100+
### Q4: Failure Pre-mortem
101+
> If this shipped and FAILED, what are the top 3 causes?
102+
- **Reject**: Vague categories ("security issues", "performance")
103+
- **Accept**: Specific scenarios ("token not refreshed after 1hr", "N+1 on list page")
104+
105+
After all 4 answers, summarize key insights in 2-3 bullets. Rate quality:
106+
- All answers specific + evidence-backed → proceed
107+
- Any answer still vague → flag as risk in requirements
96108

97109
## Structured Deepening
98110

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

Lines changed: 112 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,151 @@
1-
# Step 3: Interview (Interactive or Self-Interview)
1+
# Step 3: Deep Exploration (Interview or Self-Interview)
22

33
## Interactive Mode (AUTO_MODE=false)
44

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

7-
### Phase 1: Pressure Test
8-
9-
Ask exactly 3 questions, **one at a time**, using `AskUserQuestion` for each.
7+
## Auto Mode (AUTO_MODE=true)
108

11-
**CRITICAL REQUIREMENT**: You MUST use the `AskUserQuestion` tool for every question. Do NOT output questions as plain text — they will be ignored.
9+
AI self-interview — no `AskUserQuestion`. All answers from codebase analysis + reasoning.
1210

13-
Wait for each answer before asking the next question.
11+
**Output contract (auto mode):**
12+
1. Print each Q&A pair to stdout (user sees the reasoning)
13+
2. Embed full trace in requirements doc under `## Self-Interview Trace`
1414

15-
#### Question 1: Who and why?
16-
> Who uses this? What's the specific pain point or motivation?
15+
---
1716

18-
#### Question 2: Cost of inaction?
19-
> What happens if we do nothing? What's the actual cost or risk?
17+
## Phase A1: Evidence Gathering
2018

21-
#### Question 3: Simpler framing?
22-
> Is there a simpler version that delivers 80% of the value? What's the minimum viable version?
19+
Before questioning, gather hard evidence:
2320

24-
After all 3 answers, summarize the key insights in 2-3 bullets before proceeding.
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?
2528

2629
---
2730

28-
## Auto Mode (AUTO_MODE=true)
31+
## Phase A2: Forcing Questions (Sequential, with Pushback)
2932

30-
AI self-interview — no `AskUserQuestion` calls. All answers derived from codebase analysis, best practices, and reasoning.
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.
3134

32-
**Output contract (auto mode):**
33-
1. Print Q&A pairs to **stdout** so the user sees the reasoning in conversation
34-
2. Embed Q&A pairs in the requirements doc under a `## Self-Interview Trace` section
35-
3. Requirements doc written to `.flow/specs/${SLUG}-requirements.md` (same as interactive)
35+
Format each as:
36+
37+
```
38+
### Q1: [Question]
39+
**First answer:** [initial response]
40+
**Pushback:** [challenge the answer using rejection criteria]
41+
**Refined answer:** [specific, evidence-grounded response]
42+
```
43+
44+
### Q1: Demand Reality
45+
> What's the strongest evidence this change is actually needed?
46+
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?
50+
51+
### Q2: Status Quo
52+
> How is this being handled RIGHT NOW without this change?
3653
37-
### Phase A1: Deep Code Analysis
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?
3857

39-
Before self-interview, gather evidence:
58+
### Q3: Narrowest Wedge
59+
> What's the smallest version that delivers 80% of the value?
4060
41-
1. **Affected surface**: Grep/Glob for all files related to the request. List them.
42-
2. **Current patterns**: How does the codebase currently handle similar functionality? Read 3-5 key files.
43-
3. **Dependencies**: What modules/packages/APIs are involved? Check imports, configs.
44-
4. **Test coverage**: Do tests exist for the affected area? What kind?
45-
5. **Recent history**: `git log --oneline -20` on affected files — who changed what, why?
46-
6. **Existing specs**: Check `.flow/specs/` and `.flow/epics/` for related prior work.
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.
4764

48-
### Phase A2: Self-Interview
65+
### Q4: Existing Code Audit
66+
> What already exists in the codebase that solves part of this?
4967
50-
Ask and answer questions in structured Q&A format. Output each as a visible block:
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?
71+
72+
### Q5: Integration & Contracts
73+
> What systems/modules will this touch? What contracts must be preserved?
74+
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?
78+
79+
### Q6: Failure Pre-mortem
80+
> Assume this shipped and FAILED in production. Top 3 most likely causes?
81+
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.
85+
86+
### Q7: Temporal Walk-Through
87+
> Walk through implementation step by step:
5188
5289
```
53-
### Q: <question>
54-
**A:** <answer with code evidence>
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?
5594
```
5695

57-
**Core questions (always ask all):**
96+
Surface decisions that should be resolved NOW, not during implementation.
97+
98+
---
99+
100+
## Extended Questions (Large tier only — skip for Trivial/Medium)
101+
102+
### Q8: Performance Impact
103+
> Will this change affect latency, memory, or throughput?
104+
- Check hot paths, data volume, caching layers in affected code.
58105

59-
#### 1. Problem & Users
60-
> Q: Who uses this and what specific pain point does it solve?
61-
> A: Derive from codebase context — who calls the affected code, what user-facing behavior it impacts.
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.
62109

63-
#### 2. Cost of Inaction
64-
> Q: What happens if we do nothing? What breaks or degrades?
65-
> A: Check for open issues, error patterns, performance trends, tech debt signals in the code.
110+
### Q10: Migration & Compatibility
111+
> Are there breaking changes? Data migration needed? Feature flags?
112+
- Check API contracts, database schemas, config formats.
66113

67-
#### 3. Simpler Framing
68-
> Q: Is there a simpler version that delivers 80% of the value?
69-
> A: Analyze the request — what's the minimum change that solves the core problem? What can be deferred?
114+
---
115+
116+
## Phase A3: Structured Deepening
70117

71-
#### 4. Existing Patterns
72-
> Q: How does the codebase currently handle similar problems?
73-
> A: Cite specific files, functions, patterns found in Phase A1. Quote code if relevant.
118+
After all questions, apply ONE named reasoning method (auto-selected based on task type):
74119

75-
#### 5. Integration Points
76-
> Q: What other systems/modules will this touch? What contracts must be preserved?
77-
> A: List APIs, shared types, database schemas, config files that are affected.
120+
| Task type | Method | Prompt |
121+
|-----------|--------|--------|
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." |
125+
| 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?" |
78127

79-
#### 6. Edge Cases & Failure Modes
80-
> Q: What can go wrong? What are the boundary conditions?
81-
> A: Analyze error handling in current code, identify missing cases, concurrency risks.
128+
Append deepening insights to the self-interview trace.
82129

83-
**Extended questions (Large tier only):**
130+
---
84131

85-
#### 7. Performance Impact
86-
> Q: Will this change affect latency, memory, or throughput?
87-
> A: Analyze hot paths, data volume, caching layers in affected code.
132+
## Pushback Scoring
88133

89-
#### 8. Security Surface
90-
> Q: Does this introduce or modify authentication, authorization, or data handling?
91-
> A: Check for auth middleware, input validation, sensitive data flows.
134+
After all Q&A, rate the exploration quality:
92135

93-
#### 9. Migration & Compatibility
94-
> Q: Are there breaking changes? Do we need data migration or feature flags?
95-
> A: Check API contracts, database schemas, config formats for backwards compatibility.
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? |
96143

97-
#### 10. Testing Strategy
98-
> Q: What test types are needed and what's the current coverage gap?
99-
> A: Analyze existing test files for the affected area, identify missing test categories.
144+
**Total: ?/25**
100145

101-
**Adaptive follow-ups**: If any answer reveals unexpected complexity (e.g., a shared module with 10+ consumers, no test coverage, concurrency issues), add 1-2 follow-up Q&A pairs to drill into that specific area. Cap at 15 total Q&A pairs.
146+
- **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
102149

103150
## Next Step
104151

‎skills/flow-code-brainstorm/steps/step-04-approaches.md‎

Lines changed: 71 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,87 @@
1-
# Step 4: Approach Generation
1+
# Step 4: Approach Generation & Scoring
22

3-
## Interactive Mode (AUTO_MODE=false)
3+
## Generate 3 Distinct Approaches
44

5-
Generate 2-3 concrete approaches based on Phase 1 answers and codebase analysis.
5+
Each approach MUST be genuinely different — not just "same thing with more/less scope". One must be minimal, one must be ideal.
66

7-
For each approach:
7+
### Required Approaches:
88

9-
| Field | Format |
10-
|-------|--------|
11-
| **Name** | Short descriptive label |
12-
| **Summary** | One sentence — what this approach does |
13-
| **Effort** | S / M / L |
14-
| **Risk** | Low / Med / High |
15-
| **Pros** | 2-3 bullets |
16-
| **Cons** | 2-3 bullets |
9+
**Approach A: Narrowest Wedge** — The smallest change that unblocks the core use case.
10+
- Fewest files touched, smallest diff
11+
- Ships in hours, not days
12+
- Deliberately leaves things out
1713

18-
Ask (via `AskUserQuestion`):
19-
> Which approach do you prefer? (1/2/3, or "combine" to mix elements)
14+
**Approach B: Balanced** — Best tradeoff of completeness vs effort.
15+
- Covers main use cases + key edge cases
16+
- Reasonable timeline
17+
- Reuses existing patterns
18+
19+
**Approach C: Ideal Architecture** — Best long-term solution if time were unlimited.
20+
- Complete coverage
21+
- Proper abstractions
22+
- Full test coverage
23+
- May require larger refactoring
24+
25+
### Table Format (all 3 approaches):
26+
27+
| Field | Approach A (Narrow) | Approach B (Balanced) | Approach C (Ideal) |
28+
|-------|--------------------|-----------------------|-------------------|
29+
| **Summary** | One sentence | One sentence | One sentence |
30+
| **Files** | List affected files | List affected files | List affected files |
31+
| **Effort** | S / M / L | S / M / L | S / M / L |
32+
| **Risk** | Low / Med / High | Low / Med / High | Low / Med / High |
33+
| **Reuse** | What existing code used | What existing code used | What existing code used |
34+
| **Pros** | 2-3 bullets | 2-3 bullets | 2-3 bullets |
35+
| **Cons** | 2-3 bullets | 2-3 bullets | 2-3 bullets |
36+
37+
---
38+
39+
## Score Each Approach (1-5 per dimension)
40+
41+
| Dimension | A (Narrow) | B (Balanced) | C (Ideal) | Weight |
42+
|-----------|-----------|-------------|-----------|--------|
43+
| **Completeness** — solves the full problem? | ? | ? | ? | 3x |
44+
| **Code alignment** — fits existing patterns? | ? | ? | ? | 2x |
45+
| **Risk** — what can go wrong? (5=low risk) | ? | ? | ? | 2x |
46+
| **Effort** — how much work? (5=least effort) | ? | ? | ? | 1x |
47+
| **Maintainability** — easy to extend/change later? | ? | ? | ? | 2x |
48+
| **Testability** — can it be verified? | ? | ? | ? | 1x |
49+
| **Weighted Total** | ?/55 | ?/55 | ?/55 | |
2050

2151
---
2252

23-
## Auto Mode (AUTO_MODE=true)
53+
## Select Best Approach
2454

25-
Same table format as interactive (Name/Summary/Effort/Risk/Pros/Cons), but **AI picks the best approach** instead of asking user.
55+
### Auto Mode (AUTO_MODE=true)
2656

27-
Generate 2-3 approaches with the same table format.
57+
Pick the approach with the **highest weighted score**.
58+
59+
If scores are within 5 points:
60+
- Prefer higher **Completeness** score (most comprehensive wins)
61+
- If still tied, prefer higher **Maintainability** (long-term wins)
62+
63+
Output:
64+
```
65+
**Selected: Approach X — score Y/55**
66+
Reason: [one line citing the scoring advantage]
67+
Runner-up: Approach Z (score W/55) — [one line on what it trades off]
68+
```
69+
70+
### Interactive Mode (AUTO_MODE=false)
71+
72+
Show the scoring table, then ask via `AskUserQuestion`:
73+
> "Approach B scored highest (42/55). Do you want to go with B, or prefer a different approach? (A/B/C/combine)"
74+
75+
---
2876

29-
**Auto-select logic** — pick the approach that:
30-
1. Aligns best with existing codebase patterns (don't fight the codebase)
31-
2. Has lowest risk for the effort level
32-
3. Maximizes reuse of existing code
77+
## Validate Selection Against Self-Interview
3378

34-
Output: "**Selected: Approach N** — <one-line reason based on code evidence>"
79+
After selection, cross-check:
80+
1. Does the selected approach address ALL failure causes from Q6 (Pre-mortem)?
81+
2. Does it respect the Narrowest Wedge from Q3? (Or is there a reason to go bigger?)
82+
3. Does the Temporal Walk-Through (Q7) flag anything this approach doesn't handle?
3583

36-
If approaches are genuinely close (risk/effort within one level), flag it:
37-
> "Approaches N and M are close calls. Defaulting to N (<reason>). Override by re-running without --auto."
84+
If validation reveals gaps, add them as "## Known Gaps" in the requirements doc.
3885

3986
## Next Step
4087

0 commit comments

Comments
 (0)