git:20260324.691be9c to git:20260519.40bb110

89 added, 97 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: brainstorming
- description: >-
- Activates before any code is written to refine rough ideas through Socratic
- questioning, explore alternatives, and produce an approved design document.
- Use this skill when the user describes a new feature, when requirements are
- unclear or ambiguous, when an architectural decision needs to be made, when
- the user says "I want to build," "let's make," or "new feature," or when
- re-designing after a failed approach.
+ description: Refines rough ideas into approved designs before code.
+ tier: practical
+ category: workflow
+ created_by: human
+ platforms: [windows, macos, linux]
+ tags: [design, socratic, discovery]
+ author: Andreas Wasita (@andreaswasita)
---
- # Brainstorming
+ # Brainstorming Skill
- Refine rough ideas into clear designs through Socratic questioning. No code until the design is approved.
+ Turns a vague request into an approved design through focused Socratic questioning and tradeoff-honest alternatives. Does NOT permit any code to be written until the user has explicitly approved the design.
## When to Use
- - User describes a new feature or project
- - Requirements are unclear or ambiguous
- - Architectural decisions need to be made
- - Re-designing after a failed or rejected approach
- - User says "I want to build...", "let's make...", or "new feature"
- - Any non-trivial work where jumping straight to code would be premature
+ - User describes a new feature or project.
+ - Requirements are unclear, conflicting, or ambiguous.
+ - An architectural decision needs to be made.
+ - Re-designing after a failed or rejected approach.
+ - User says "I want to build…", "let's make…", or "new feature".
+ - NOT when the user explicitly asks to skip design and prototype.
- ## How to Use
+ ## Prerequisites
- ### Step 1: Ask Socratic Questions
+ - The `edit` tool to save the approved design.
+ - The `ask_user` tool to gather clarifications without spamming prose.
+ - A target file for the design (typically `tasks/todo.md` or `docs/design.md`).
+ - The user is actually available to respond — no design loops with a phantom user.
- Don't assume you understand the full picture. Draw out the real requirements:
+ ## How to Run
- 1. **What problem are we solving?** — Not what to build, but *why*
- 2. **Who is this for?** — User persona, scale, constraints
- 3. **What does success look like?** — Measurable outcomes, not vague goals
- 4. **What are the constraints?** — Time, tech stack, existing systems, team size
- 5. **What have you already tried?** — Don't re-invent failed approaches
+ ```text
+ 1. Ask 3–5 Socratic questions to surface the real problem.
+ 2. Present 2–3 alternative approaches with honest tradeoffs.
+ 3. Recommend ONE with reasoning.
+ 4. Walk the design in chunks: overview → architecture → data → API → edges.
+ 5. Get explicit approval ("approved", "go", "ship it") before saving.
+ 6. Save the approved design. Hand off to `executing-plans`.
+ ```
- Ask 3–5 focused questions. Don't interrogate — guide the conversation toward clarity.
+ ## Quick Reference
- ### Step 2: Explore Alternatives
+ | Question shape | Why it matters |
+ |---|---|
+ | What problem are we solving? | Forces the "why", not just the "what" |
+ | Who is this for? | Persona, scale, constraints |
+ | What does success look like? | Measurable outcome, not vibes |
+ | What are the constraints? | Time, stack, existing systems, team |
+ | What have you already tried? | Avoid re-inventing failed approaches |
- Before committing to an approach:
- - Present 2–3 viable approaches with tradeoffs
- - Highlight which approach you'd recommend and why
- - Note what each approach sacrifices (complexity, performance, flexibility)
+ | Design chunk | Length |
+ |---|---|
+ | Overview | 1 paragraph |
+ | Architecture | 5–10 lines + diagram if useful |
+ | Data model | Table or list |
+ | API / interface | Endpoint or function signatures |
+ | Edge cases | Bullet list |
+ ## Procedure
+
+ ### Step 1: Socratic Questions (3–5 max)
+
+ Use the `ask_user` tool. Ask focused questions one at a time. Stop at five. More than five feels like interrogation.
+
+ ### Step 2: Present Alternatives
+
```markdown
## Approaches
- ### Option A: [Name]
- - **Pros:** Simple, fast to implement
- - **Cons:** Doesn't scale past X users
- - **Effort:** ~2 hours
+ ### Option A: <name>
+ - Pros: <…>
+ - Cons: <…>
+ - Effort: <rough estimate>
- ### Option B: [Name]
- - **Pros:** Scales well, maintainable
- - **Cons:** More complex upfront
- - **Effort:** ~4 hours
+ ### Option B: <name>
+ - Pros: <…>
+ - Cons: <…>
+ - Effort: <rough estimate>
- **Recommendation:** Option B — the extra upfront work pays off because [specific reason].
+ **Recommendation:** Option B — <specific reason>.
```
- ### Step 3: Present Design in Chunks
+ Be honest about tradeoffs. A fake "Option A" you do not believe in undermines trust.
- Don't dump a 500-line design document. Present in digestible sections:
+ ### Step 3: Walk the Design in Chunks
- 1. **Overview** — One paragraph, what we're building and why
- 2. **Architecture** — How the pieces fit together
- 3. **Data model** — What data flows where
- 4. **API / Interface** — How the outside world interacts
- 5. **Edge cases** — What could go wrong
+ Present overview → architecture → data → API → edges. Pause for feedback after each chunk. Do not dump a 500-line document in one message.
- Wait for approval on each section before moving to the next.
+ ### Step 4: Get Explicit Approval
- ### Step 4: Save the Approved Design
+ "Maybe" is not approval. "I'm not sure" is not approval. Ask what is bothering them and iterate. Only proceed when the user says "approved", "go ahead", "ship it", or equivalent.
- Once the user explicitly approves:
+ ### Step 5: Save the Approved Design
+ Use `edit` to write to `docs/design.md` or `tasks/todo.md`:
+
```markdown
- ## Approved Design: [Feature Name]
- Date: [date]
+ ## Approved Design: <feature>
+ Date: <YYYY-MM-DD>
Status: Approved
### Problem
- [What we're solving]
+ <what we're solving>
### Solution
- [What we're building]
+ <what we're building>
### Architecture
- [How it fits together]
+ <how it fits together>
### Acceptance Criteria
- - [ ] Criterion 1
- - [ ] Criterion 2
+ - [ ] <criterion 1>
+ - [ ] <criterion 2>
```
- Save to `docs/design.md` or `tasks/todo.md` depending on the project convention.
-
- ### Step 5: Get Explicit Approval
-
- **Never proceed to planning or code without the user saying "approved," "go ahead," "looks good," or equivalent explicit consent.**
-
- If the user says "maybe" or "I'm not sure" — that's not approval. Ask what's bothering them.
-
- ## Examples
-
- **Bad — Skipping Design:**
- > User: "I want to add notifications to the app"
- > Agent: *immediately starts writing a NotificationService class*
-
- **Good — Brainstorming First:**
- > User: "I want to add notifications to the app"
- > Agent: "Before we build, let me understand the scope:
- > 1. What types of notifications? (email, push, in-app, all three?)
- > 2. What triggers them? (user actions, system events, scheduled?)
- > 3. Do users need to configure preferences (opt-in/out)?
- > 4. What's the expected volume? (10/day vs 10,000/day changes the architecture)
- > 5. Any existing notification infrastructure we should integrate with?"
-
- **Bad — Design Dump:**
- > Agent: *sends a 300-line design document in one message*
-
- **Good — Chunked Presentation:**
- > Agent: "Here's the overview: We'll add an in-app notification system with push support.
- > Three components: a notification service, a preference store, and a delivery layer.
- > Does this direction make sense before I detail the architecture?"
+ Hand off to the `plan-before-code` or `executing-plans` skill.
- ## Guidelines
+ ## Pitfalls
- - Ask questions to clarify, not to stall — 3–5 questions max per round
- - Present alternatives with honest tradeoffs, not just the one you prefer
- - Keep design chunks short enough to actually read (5–10 lines each)
- - Save the approved design — it becomes the source of truth for planning
- - Never plan or code without an approved design document
+ - **DO NOT** start writing code while the design is still under discussion.
+ - **DO NOT** interrogate the user — five questions per round, maximum.
+ - **DO NOT** present a single "approach" with no alternatives. That is a decree, not a design discussion.
+ - **DO NOT** dump a 300-line design in one message. Chunk it.
+ - **DO NOT** treat "maybe" as consent. Get the word "approved".
- ## Anti-Patterns
+ ## Verification
- - **"I'll figure out the design as I code"** — This produces spaghetti, not architecture
- - **Asking too many questions** — 15 questions feels like an interrogation, not a conversation
- - **One-sided design** — Presenting only one approach without alternatives
- - **Proceeding without approval** — "I assumed you'd be fine with this" is not consent
- - **Design documents nobody reads** — If it's longer than 2 pages, it's a novel, not a design
+ - [ ] At least 3 Socratic questions were asked and answered.
+ - [ ] At least 2 alternatives were presented with honest tradeoffs.
+ - [ ] Design was walked in chunks with user feedback between them.
+ - [ ] Explicit approval ("approved" / "go ahead") is captured.
+ - [ ] Approved design is saved to `docs/design.md` or `tasks/todo.md`.