@vpxa/aikit 0.1.185 → 0.1.187

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  var e=[{file:`SKILL.md`,content:`---
2
2
  name: brainstorming
3
- description: "Design exploration for planning-phase agents (Orchestrator, Planner, Researchers). Explores user intent, requirements and design BEFORE handing off to implementation agents. NOT for code agents they implement designs, not create them."
3
+ description: "Design exploration for planning-phase agents (Orchestrator, Planner, Researchers). Explores user intent, requirements and design BEFORE handing off to implementation agents. Use when there are multiple valid approaches to a problem, when architecture decisions need exploration, when the user says 'how should I...', 'what's the best way to...', 'explore options for...', or when a task has genuine design forks. NOT for code agents - they implement designs, not create them. NOT for single-path decisions - if only one approach makes sense, skip this."
4
4
  metadata:
5
5
  category: planning
6
6
  domain: general
@@ -16,35 +16,40 @@ argument-hint: "Feature, component, or behavior to design"
16
16
 
17
17
  ## Quick Reference
18
18
 
19
- **Purpose:** Explore user intent, requirements, and design BEFORE any implementation. Mandatory for creative work.
19
+ **Purpose:** Explore requirements and design space before implementation starts.
20
20
 
21
- **HARD GATE:** Do NOT write any code until design is presented and user approves. No exceptions, even for "simple" tasks.
21
+ **Use this skill when:** there are multiple viable approaches, architecture trade-offs matter, or the user is asking for guidance rather than code.
22
22
 
23
- **Two modes** (you decide, don't ask user):
24
- - **Simple Mode** - <=3 files, single concern, no new boundaries -> brief context + 3-5 targeted questions + short design summary
25
- - **Full Mode** - multi-file, new services, cross-cutting concerns -> deep context gathering + structured design document + explicit approval
23
+ **Skip this skill when:** the work is already decided, the change is mechanical, or only one reasonable path exists.
26
24
 
27
- **Process:** Understand context -> Ask questions (one at a time) -> Present design -> Get user approval -> Hand off to implementation
25
+ **HARD GATE:** Do NOT write code, scaffold files, or hand off to implementation until a design is presented and approved.
28
26
 
29
- **Output:** Design document with: goal, scope, approach, file changes, edge cases, and acceptance criteria.
30
-
31
- Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
32
-
33
- Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
27
+ **Expected output:** a short design or spec with constraints, alternatives, recommendation, risks, and acceptance criteria.
34
28
 
35
29
  <HARD-GATE>
36
30
  Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
37
31
  </HARD-GATE>
38
32
 
39
- ## Anti-Pattern: "This Is Too Simple To Need A Design"
33
+ ## When Brainstorming Is Appropriate
34
+
35
+ Use brainstorming when at least one of these is true:
40
36
 
41
- Every project goes through this process. A todo list, a single-function utility, a config change all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
37
+ - Multiple valid approaches exist and the choice changes cost, risk, or UX
38
+ - The work introduces or changes boundaries: service, module, API, workflow, ownership
39
+ - The user is asking for options, strategy, trade-offs, or "best way" guidance
40
+ - Constraints are real but incomplete: performance, timeline, migration cost, reversibility, team familiarity
41
+
42
+ Do not use brainstorming when the path is already obvious:
43
+
44
+ - Fixing a typo, renaming a variable, or updating a pinned dependency
45
+ - Implementing an already-approved spec or ADR
46
+ - Mechanical migrations where the desired end state is predetermined
42
47
 
43
48
  ---
44
49
 
45
50
  ## Mode Selection
46
51
 
47
- This skill operates in two modes. **You decide which mode to use** based on the task characteristics do NOT ask the user which mode.
52
+ This skill operates in two modes. You choose the mode from the problem shape; do not ask the user which mode they want.
48
53
 
49
54
  ### Simple Mode
50
55
 
@@ -57,7 +62,7 @@ Use when **all** of these are true:
57
62
 
58
63
  Examples: config change, utility function, bug fix with design ambiguity, small feature in existing component.
59
64
 
60
- ### Advanced Mode
65
+ ### Full Mode
61
66
 
62
67
  Use when **any** of these are true:
63
68
  - Affects >3 files or crosses service boundaries
@@ -71,269 +76,129 @@ Examples: new notification channel, new API service, platform redesign, multi-se
71
76
 
72
77
  ---
73
78
 
74
- ## Simple Mode Process
75
-
76
- ### Checklist
77
-
78
- 1. **Explore project context** — check files, docs, recent commits
79
- 2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
80
- 3. **Propose 2-3 approaches** — with trade-offs and your recommendation
81
- 4. **Present design** — in sections scaled to their complexity, get user approval after each section
82
- 5. **Write design doc** — save to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` and commit
83
- 6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
84
-
85
- ### Process Flow
86
-
87
- \`\`\`dot
88
- digraph brainstorming_simple {
89
- "Explore project context" [shape=box];
90
- "Ask clarifying questions" [shape=box];
91
- "Propose 2-3 approaches" [shape=box];
92
- "Present design sections" [shape=box];
93
- "User approves design?" [shape=diamond];
94
- "Write design doc" [shape=box];
95
- "Invoke writing-plans skill" [shape=doublecircle];
96
-
97
- "Explore project context" -> "Ask clarifying questions";
98
- "Ask clarifying questions" -> "Propose 2-3 approaches";
99
- "Propose 2-3 approaches" -> "Present design sections";
100
- "Present design sections" -> "User approves design?";
101
- "User approves design?" -> "Present design sections" [label="no, revise"];
102
- "User approves design?" -> "Write design doc" [label="yes"];
103
- "Write design doc" -> "Invoke writing-plans skill";
104
- }
105
- \`\`\`
106
-
107
- ---
108
-
109
- ## Advanced Mode Process
110
-
111
- ### Checklist
112
-
113
- 1. **Explore project context** — check files, docs, recent commits
114
- 2. **Assess scope** — if multiple independent subsystems, decompose before detailing (see below)
115
- 3. **Offer visual presentation support** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. Use \`present({ schemaVersion: 1, title: "Brainstorming", blocks: [...] })\` to display brainstorming results. Use \`list\` for idea sets, \`table\` for evaluation matrices, \`kv\` for the selected approach, and \`metrics\` for requirement scores. NEVER \`code\` blocks for structured data.
116
- 4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
117
- 5. **Propose 2-3 approaches via Decision Protocol** — run the full 3-phase multi-model decision protocol: Phase 1 (4 Researchers in parallel), Phase 2 (peer review with anonymized outputs), Phase 3 (structured verdict). Present the verdict visually using \`present({ schemaVersion: 1, title: "Approach Verdict", blocks: [...] })\` with \`table\` for approach comparisons, \`list\` for recommendations, and \`kv\` for verdict metadata. NEVER \`code\` blocks for structured data. *(See "Decision Protocol Integration" below.)*
118
- 6. **Present design** — in sections scaled to their complexity, get user approval after each section
119
- 7. **Write design doc** — save to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` and commit
120
- 8. **Spec review loop** — review the spec for completeness, consistency, clarity, scope, and YAGNI. Fix issues. Max 3 iterations, then surface to user.
121
- 9. **User reviews written spec** — ask user to review the spec file before proceeding
122
- 10. **Transition to implementation** — invoke writing-plans skill to create implementation plan
123
-
124
- ### Decision Protocol Integration (Advanced Mode Only)
125
-
126
- When Advanced Mode reaches step 5 ("Propose approaches"), invoke the **full 3-phase multi-model decision protocol**:
127
-
128
- **Phase 1 — Independent Research:**
129
- 1. Frame the design question with full context gathered from steps 1-4
130
- 2. Launch ALL 4 Researcher variants **in parallel** with identical framing — each applies its thinking style:
131
- - **Alpha (Contrarian)**: Actively seeks flaws and fatal assumptions
132
- - **Beta (First Principles)**: Strips assumptions, rebuilds from ground truth
133
- - **Gamma (Expansionist)**: Finds undervalued opportunities, cross-domain patterns
134
- - **Delta (Executor)**: Focuses on fastest path, implementation cost, feasibility
135
-
136
- **Phase 2 — Peer Review:**
137
- 3. **Anonymize** Phase 1 outputs as Perspective A / B / C / D (strip agent names)
138
- 4. Launch a **second parallel batch** of 4 reviewers, each evaluating ALL perspectives:
139
- - Strongest argument — which perspective and why?
140
- - Critical blind spot — what did the strongest miss?
141
- - Consensus gap — what did ALL overlook?
142
- - Verdict — which approach to adopt?
143
-
144
- **Phase 3 — Structured Verdict:**
145
- 5. Synthesize BOTH layers into the structured verdict format:
146
- - **Where Agrees** / **Where Clashes** / **Blind Spots Caught** / **Recommendation** (with confidence) / **First Step**
147
- 6. Present verdict visually using \`present({ schemaVersion: 1, title: "Approach Verdict", blocks: [...] })\` with \`table\` for approach comparisons, \`list\` for recommendations, and \`kv\` for verdict metadata. NEVER \`code\` blocks for structured data.
148
- 7. If a decision produces an ADR, write it to \`docs/decisions/\`
149
-
150
- **Floor-tier shortcut**: Skip Phase 2 (peer review), synthesize directly from Phase 1.
151
-
152
- This replaces the single-agent "propose approaches" step with 8 independent evaluations (4 research + 4 review), producing significantly higher-quality decisions.
153
-
154
- ### Process Flow
155
-
156
- \`\`\`dot
157
- digraph brainstorming_advanced {
158
- "Explore project context" [shape=box];
159
- "Assess scope" [shape=diamond];
160
- "Decompose into sub-projects" [shape=box];
161
- "Visual questions ahead?" [shape=diamond];
162
- "Offer Visual Presentation\\n(own message)" [shape=box];
163
- "Ask clarifying questions" [shape=box];
164
- "Phase 1: 4 Researchers\\nin parallel" [shape=box, style=bold];
165
- "Phase 2: Peer Review\\n(anonymized, 4 reviewers)" [shape=box, style=bold];
166
- "Phase 3: Structured Verdict" [shape=box];
167
- "Present design sections" [shape=box];
168
- "User approves design?" [shape=diamond];
169
- "Write design doc" [shape=box];
170
- "Spec review loop" [shape=box];
171
- "Spec review passed?" [shape=diamond];
172
- "User reviews spec?" [shape=diamond];
173
- "Invoke writing-plans skill" [shape=doublecircle];
174
-
175
- "Explore project context" -> "Assess scope";
176
- "Assess scope" -> "Decompose into sub-projects" [label="too large"];
177
- "Assess scope" -> "Visual questions ahead?" [label="right-sized"];
178
- "Decompose into sub-projects" -> "Visual questions ahead?" [label="first sub-project"];
179
- "Visual questions ahead?" -> "Offer Visual Presentation\\n(own message)" [label="yes"];
180
- "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
181
- "Offer Visual Presentation\\n(own message)" -> "Ask clarifying questions";
182
- "Ask clarifying questions" -> "Phase 1: 4 Researchers\\nin parallel";
183
- "Phase 1: 4 Researchers\\nin parallel" -> "Phase 2: Peer Review\\n(anonymized, 4 reviewers)";
184
- "Phase 2: Peer Review\\n(anonymized, 4 reviewers)" -> "Phase 3: Structured Verdict";
185
- "Phase 3: Structured Verdict" -> "Present design sections";
186
- "Present design sections" -> "User approves design?";
187
- "User approves design?" -> "Present design sections" [label="no, revise"];
188
- "User approves design?" -> "Write design doc" [label="yes"];
189
- "Write design doc" -> "Spec review loop";
190
- "Spec review loop" -> "Spec review passed?";
191
- "Spec review passed?" -> "Spec review loop" [label="issues found, fix"];
192
- "Spec review passed?" -> "User reviews spec?" [label="approved"];
193
- "User reviews spec?" -> "Write design doc" [label="changes requested"];
194
- "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
195
- }
196
- \`\`\`
197
-
198
- ### Large Project Decomposition
199
-
200
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
201
-
202
- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
203
-
204
- ### Spec Review Loop
205
-
206
- After writing the spec document, review it yourself for:
207
-
208
- | Category | What to Look For |
209
- |----------|------------------|
210
- | Completeness | TODOs, placeholders, "TBD", incomplete sections |
211
- | Consistency | Internal contradictions, conflicting requirements |
212
- | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
213
- | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
214
- | YAGNI | Unrequested features, over-engineering |
79
+ ## NEVER
215
80
 
216
- **Only flag issues that would cause real problems during implementation planning.** A missing section, a contradiction, or a requirement so ambiguous it could be interpreted two different ways — those are issues. Minor wording improvements and stylistic preferences are not.
81
+ - **NEVER skip divergent thinking to jump to solutions** - premature convergence is the most common brainstorming failure. Force at least 3 alternatives before evaluating.
82
+ - **NEVER present options without trade-off analysis** - listing A/B/C without pros, cons, and context is noise. Each option needs: strength, weakness, best-when.
83
+ - **NEVER conflate requirements with design** - "the user wants to log in" is a requirement; "use OAuth2 + JWT" is a design. Clarify the problem before exploring the solution space.
84
+ - **NEVER evaluate during the divergent phase** - "that won't work" too early kills useful exploration. Generate first, judge second.
85
+ - **NEVER propose more than 5 options** - too many options create analysis paralysis. 3-5 well-differentiated choices is enough.
86
+ - **NEVER present the obvious choice as the only real option with strawman alternatives** - if one option clearly dominates before analysis, say brainstorming is unnecessary and recommend directly.
87
+ - **NEVER use brainstorming for single-path decisions** - if there is only one credible path, execute or hand off; do not manufacture fake alternatives.
88
+ - **NEVER hide the deciding constraint** - if compliance, migration cost, latency, or org ownership is driving the decision, state it explicitly.
217
89
 
218
- Fix issues and re-review. Max 3 iterations, then surface remaining concerns to the user.
90
+ ## Core Workflow
219
91
 
220
- ### User Review Gate
92
+ | Stage | What you do | What good output looks like |
93
+ |-------|-------------|-----------------------------|
94
+ | Frame | State the problem, constraints, and success criteria | Clear decision question and explicit boundaries |
95
+ | Clarify | Ask one question at a time until ambiguity drops | Requirements are separate from solutions |
96
+ | Diverge | Generate 3 alternatives that differ in shape, not just labels | Options have meaningfully different trade-offs |
97
+ | Evaluate | Compare options against criteria, constraints, reversibility, and delivery cost | Rejection reasons are explicit |
98
+ | Recommend | Pick one option and explain why the others lost | Recommendation matches the stated constraints |
99
+ | Confirm | Present the design, get approval, then hand off | Implementation can proceed without reopening core design questions |
221
100
 
222
- After the spec review passes, ask the user to review:
223
-
224
- > "Spec written and committed to \`<path>\`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
225
-
226
- Wait for the user's response. If they request changes, make them and re-run the spec review. Only proceed once the user approves.
101
+ Simple Mode compresses the workflow into a short design note. Full Mode produces a fuller spec and spends more time on constraints, interfaces, migration, and rollout.
227
102
 
228
103
  ---
229
104
 
230
- ## The Process (Both Modes)
231
-
232
- **Understanding the idea:**
233
- - Check out the current project state first (files, docs, recent commits)
234
- - Ask questions one at a time to refine the idea
235
- - Prefer multiple choice questions when possible, but open-ended is fine too
236
- - Only one question per message — if a topic needs more exploration, break it into multiple questions
237
- - Focus on understanding: purpose, constraints, success criteria
105
+ ## Decision Protocol
238
106
 
239
- **Exploring approaches:**
240
- - Propose 2-3 different approaches with trade-offs
241
- - Present options conversationally with your recommendation and reasoning
242
- - Lead with your recommended option and explain why
107
+ Use the heaviest process the problem actually needs. The protocol scales with decision complexity; it does not assume a giant agent swarm.
243
108
 
244
- **Presenting the design:**
245
- - Once you believe you understand what you're building, present the design
246
- - Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
247
- - Ask after each section whether it looks right so far
248
- - Cover: architecture, components, data flow, error handling, testing
249
- - Be ready to go back and clarify if something doesn't make sense
109
+ ### Multi-Researcher Mode
250
110
 
251
- **Design for isolation and clarity** (Advanced mode emphasis, but good practice always):
252
- - Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
253
- - For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
254
- - Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
111
+ Use this when the decision is high-impact and the Orchestrator can actually dispatch multiple research passes.
255
112
 
256
- **Working in existing codebases:**
257
- - Explore the current structure before proposing changes. Follow existing patterns.
258
- - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design — the way a good developer improves code they're working in.
259
- - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
113
+ 1. **Independent passes** - gather 2-4 perspectives if available. More is optional, not mandatory.
114
+ 2. **Cross-check blind spots** - compare where the perspectives agree, clash, and what each missed.
115
+ 3. **Structured verdict** - produce one recommendation with confidence, deciding constraints, rejected alternatives, and first implementation step.
260
116
 
261
- ## After the Design
117
+ Do not block waiting for an 8-agent protocol. If capacity is limited, reduce the number of perspectives and keep the structure.
262
118
 
263
- **Documentation:**
264
- - Write the validated design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\`
265
- - (User preferences for spec location override this default)
266
- - Use elements-of-style:writing-clearly-and-concisely skill if available
267
- - Commit the design document to git
119
+ ### Single-Agent Fallback
268
120
 
269
- **Implementation:**
270
- - Invoke the writing-plans skill to create a detailed implementation plan
271
- - Do NOT invoke any other skill. writing-plans is the next step.
121
+ When running as a single agent (no Orchestrator dispatching multi-model research), use this structured approach:
272
122
 
273
- **The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
123
+ 1. **Frame the decision space** - state the question, list constraints, define success criteria
124
+ 2. **Generate 3 alternatives** - force diversity by thinking from different lenses:
125
+ - Lens A: Simplest approach (minimum viable, least risk)
126
+ - Lens B: Best long-term approach (might be more work now, pays off later)
127
+ - Lens C: Unconventional approach (different framing, different trade-off)
128
+ 3. **Evaluate against criteria** - for each alternative, score against the stated success criteria
129
+ 4. **Recommend with rationale** - pick one, explain WHY, acknowledge what you're trading away
274
130
 
275
- ## Key Principles
131
+ This replaces the full Multi-Model Decision Protocol when running solo.
276
132
 
277
- - **One question at a time** — Don't overwhelm with multiple questions
278
- - **Multiple choice preferred** — Easier to answer than open-ended when possible
279
- - **YAGNI ruthlessly** — Remove unnecessary features from all designs
280
- - **Explore alternatives** — Always propose 2-3 approaches before settling
281
- - **Incremental validation** — Present design, get approval before moving on
282
- - **Be flexible** — Go back and clarify when something doesn't make sense
133
+ ### Verdict Format
283
134
 
284
- ## Challenge Discipline
135
+ Express the result in structured text, not diagrams:
285
136
 
286
- Every design MUST be stress-tested before presentation. Apply these checks:
137
+ | Section | Required content |
138
+ |---------|------------------|
139
+ | Decision | What question is being answered |
140
+ | Constraints | What limited the design space |
141
+ | Options | 3 alternatives with strength, weakness, best-when |
142
+ | Recommendation | Chosen option and why |
143
+ | Rejections | Why the other options lost |
144
+ | Risks | What could fail and how reversible it is |
145
+ | First Step | Smallest useful next move after approval |
287
146
 
288
- ### 1. Domain Model Cross-Reference
289
-
290
- Before presenting any design, \`search\` curated knowledge for existing glossary, domain models, and naming conventions. The design must use **canonical terms** from the codebase — not synonyms, not approximations.
147
+ ### Large Project Decomposition
291
148
 
292
- - If the design introduces a new term, justify why no existing term works
293
- - If fuzzy language exists ("handle the thing", "process the data"), sharpen it to precise domain terms
294
- - Cross-reference proposed interfaces against existing code: do the names, shapes, and flows match what's already there?
149
+ Before asking detailed questions, assess scope. If the request includes multiple independent subsystems, decompose first. Do not brainstorm the whole platform as one blob.
295
150
 
296
- ### 2. Contradiction Detection
151
+ If the project is too large for a single spec, break it into sub-projects, define the order, then brainstorm the first sub-project only.
297
152
 
298
- Search the codebase for existing implementations that touch the same domain:
153
+ ## Design Quality Signals
299
154
 
300
- - Does the proposed data flow contradict existing patterns?
301
- - Do proposed error handling strategies conflict with established conventions?
302
- - Are there implicit assumptions that contradict documented decisions?
155
+ - **Options are genuinely different** - if they only differ in naming, you have not explored the space.
156
+ - **Trade-offs are real** - if one option dominates on all dimensions, the others are strawmen.
157
+ - **Constraints are explicit** - "we chose X because of Y constraint" is good; "X is better" is lazy.
158
+ - **Reversibility is assessed** - one-way doors need more analysis than two-way doors.
159
+ - **You can explain why NOT the other options** - if you cannot articulate the rejection reason, the analysis is shallow.
303
160
 
304
- If contradictions exist, surface them explicitly: "This design proposes X, but the existing code does Y in [file]. Which should win?"
161
+ ## Design Review Checklist
305
162
 
306
- ### 3. Specification Precision
163
+ Before presenting the design, verify these quality bars:
307
164
 
308
- Before finalizing each design section, apply this test:
165
+ - **Completeness** - no TODOs, placeholders, or missing constraints that block planning.
166
+ - **Consistency** - sections do not contradict each other.
167
+ - **Precision** - two competent developers would implement compatible solutions from this spec.
168
+ - **Scope control** - the design solves the asked problem and avoids unrequested extras.
169
+ - **Canonical language** - names and domain terms match the codebase or are explicitly introduced.
309
170
 
310
- > "Could two competent developers independently implement this section and produce compatible results?"
171
+ Fix serious issues before handoff. Minor wording changes are advisory, not blockers.
311
172
 
312
- If no — the spec is too vague. Add:
313
- - Concrete examples (input → output)
314
- - Boundary conditions (what happens at 0, 1, MAX?)
315
- - Error cases (what fails, what's the recovery?)
173
+ ## Working Method
316
174
 
317
- ### 4. Living Documentation
175
+ - Check current project context before proposing changes.
176
+ - Ask one question per message when clarification is needed.
177
+ - Prefer multiple-choice questions when they reduce ambiguity faster.
178
+ - Separate divergent generation from evaluation.
179
+ - Lead with your recommendation once the option space is explored.
180
+ - Stay concrete: boundaries, interfaces, data flow, failure modes, rollout.
318
181
 
319
- During the brainstorming session, when design decisions clarify existing ambiguity:
320
- - Note which existing docs/comments are now outdated
321
- - Include documentation updates as part of the design output (not a separate "docs task")
322
- - The design doc itself becomes the canonical reference — don't create knowledge that lives only in chat
182
+ ## Output Contract
323
183
 
324
- ## Visual Presentation Support (Advanced Mode Only)
184
+ For Simple Mode, produce a concise design note with:
325
185
 
326
- Use the \`present\` MCP tool for showing mockups, diagrams, and visual options during brainstorming. It is available as a tool, not a separate mode. Choosing this means you can present rich visual output when it helps; it does NOT mean every question should become visual.
186
+ - Goal
187
+ - Constraints
188
+ - 3 options
189
+ - Recommendation
190
+ - Risks and acceptance criteria
327
191
 
328
- **Offering visual presentation:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
329
- > "Some of what we're working on might be easier to explain visually. I can use \`present({ schemaVersion: 1, title: \\"Working Session Visuals\\", blocks: [...] })\` to show mockups, diagrams, comparisons, and other visuals as we go, using \`list\`, \`table\`, \`kv\`, and \`metrics\` blocks as appropriate. I never use \`code\` blocks for structured data. Want me to use that when helpful?"
192
+ For Full Mode, produce a spec that also covers:
330
193
 
331
- **This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
194
+ - Boundaries and component responsibilities
195
+ - Interfaces and data flow
196
+ - Migration or rollout strategy
197
+ - Error handling and operational risks
198
+ - Test and acceptance strategy
332
199
 
333
- **Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use visual output or plain chat. The test: **would the user understand this better by seeing it than reading it?**
200
+ When useful, save the approved design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` before handing off to implementation planning.
334
201
 
335
- - **Use \`present({ schemaVersion: 1, title: "Visual Option", blocks: [...] })\`** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs. Use \`list\` for idea options, \`table\` for side-by-side evaluations, \`kv\` for selected approach metadata, and \`metrics\` for numeric scoring. NEVER \`code\` blocks for structured data.
336
- - **Use regular chat** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
337
202
  `},{file:`spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template
338
203
 
339
204
  Use this template when dispatching a spec document reviewer subagent.