dev-brainstorming

Files (8)

• SKILL.md
• frame-template.html · scripts/
• helper.js · scripts/
• server.cjs · scripts/
• start-server.sh · scripts/
• stop-server.sh · scripts/
• spec-reviewer-prompt.md
• visual-companion.md

SKILL.md (first lines)

# dev-brainstorming: Idea -> Design -> Spec

Turn ideas into fully formed designs and specs through natural collaborative dialogue. Classify how much process the request needs, then work your path: understand context, refine the idea, present a design, get your human partner's approval.

**Output style.** Everything you present to your human partner (findings, a design, the options box, the executive summary) goes in their active output style. If none is set, default to: lead with the answer, short sentences, plain words, no idiom. This shapes wording only, never the approval gate or the option set.

> **Credit.** The spike/bounded/architectural tiering, the hard approval gate, the
> red-flags table, the anti-pattern section, and the visual-companion concept below
> are adapted, in places near-verbatim, from **`superpowers:brainstorming`** by
> **Jesse Vincent** (https://github.com/obra/superpowers), which is MIT-licensed.
> See [`../../THIRD_PARTY_NOTICES.md`](../../THIRD_PARTY_NOTICES.md) for the full
> license text and attribution. The divergent-options research flow, the spec
> template, and the executive-summary review gate are original to this repository.
> Upstream is a reference only; this file is the source of truth for how the skill
> behaves here.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have told your human partner what you intend and they have approved it. This applies to EVERY path below - the ceremony scales with the task; the approval gate never does.
</HARD-GATE>

## Classify first: three paths

Before your first question, classify the request and say the classification out loud - "this looks bounded, so I'll present a short design here rather than write a spec" - so your human partner can override it.

- **Spike** - a feasibility question ("can we...", "is it possible...", "quick and dirty is fine") whose output is an answer, not code you keep. Present the question and what you'll try in 2-3 sentences, get a nod, then find out as cheaply as correctness allows. No spec, no plan. Report findings as a recommendation; anything you built stays labelled throwaway.
- **Bounded** - a well-scoped change to code that already exists in this repo: a new flag, a small endpoint, a one-file fix. Bounded means the flow you are changing is already here to read; if there is no existing flow to change, the task is not bounded. Ask the clarifying questions that matter, present a short design IN CHAT (a few sentences to a few short paragraphs), and STOP. Implementation starts only after your human partner says yes - a bounded task's approval is as hard a gate as an architectural one. No spec file, no plan document; build via `dev-quick-build` (or whatever small-scope build flow you use).
- **Architectural** - new projects, new subsystems, changes that restructure how components fit together or alter interfaces others depend on. Follow the full process below: research, divergent options, design, written spec, spec review, then `dev-writing-plans`.

**A new skill? Check for a mode first.** When the request is a new skill or plugin feature, first ask whether it is a mode of an existing skill (the same job at a different moment, the same delivery). If so, design it as a mode with its steps in that skill's `references/<mode>.md`, not as a new skill. (A skill built on its own that is later folded into an existing one as a mode is wasted work.)

When in doubt between two paths, take the heavier one. The ratchet is one-way: hidden complexity discovered mid-task upgrades the path - stop, say so, and step up. Nothing downgrades mid-task.

## Anti-pattern: "too simple to need approval"

Every path ends with your human partner approving your intent before implementation. A todo list, a single-function utility, a config change - the design may be two sentences in chat, but you MUST present it and get approval. "Simple" tasks are where unexamined assumptions cause the most wasted work. What scales with simplicity is the artifact, never the approval.

### Red flags (STOP - you are rationalizing)

| Thought | Reality |
|---|---|
| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt - take the heavier path. |
| "It's bounded and the design is obvious - I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow - it is architectural. |
| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request - classify it. |
| "It grew, but I'm almost done - no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |

## Spike path

1. **Explore context** - enough to frame the probe.
2. **Present the question + probe plan** - 2-3 sentences.
3. **Get approval** - a nod is enough.
4. **Investigate** - as cheaply as correctness allows.
5. **Report findings** - a recommendation; label anything built as throwaway. Record any decision the human makes on the findings in a dated note when you wrap up.

## Bounded path

1. **Explore context** - read the files, docs, recent commits for the flow you are changing.
2. **Ask clarifying questions** - one at a time, only the ones that matter. If the change touches who runs a tool or its safety controls, ask the "who runs it" question from Architectural Phase 1, step 1, and size the controls the same way.
3. **Present a short design in chat** - approach, files touched, how it is tested.
4. **Get approval** - STOP and wait for an explicit yes. Presenting the design and starting in the same breath is skipping the gate. The bounded path writes no spec, so pass the approval and each approved design decision to `dev-quick-build`, which records them in its runbook.
5. **Implement** - hand to `dev-quick-build` (or your own project's small-scope build flow); TDD applies; no plan document.

## Architectural path

The full flow. Create a task per step and work them in order.

### Phase 1: Diverge (research + options)

Goal: find the real options, then lead with a recommendation. Diverge in your own thinking; present a short, ranked shortlist, not the raw breadth.

1. **Clarify the problem space** - purpose (outcome, not solution), who benefits, constraints, and the trigger (why now). If the request describes several independent subsystems, flag it and help decompose into sub-projects before refining any one - each gets its own spec -> plan -> build cycle.
   - **Ask who runs it: a person who reviews the result and says go, or an unattended agent?** Size the controls to that answer. A tool a person runs gets checks shown to that person (with evidence for each), and it stops where the action would certainly be wrong, or where a safety precondition cannot be checked at all (a required read failed, or the system returned a state the tool does not know). Everything else is a warning for the person to judge. Keep a control that binds an approval to what runs (a plan id that rejects an edited or stale plan) wherever a plan is approved now and applied later or by someone else. Do not add controls whose only job is to guard against agent misuse (policy stores, confirm hooks, audit forensics) when a person reviews and runs each step. Write the answer into the spec, and hold reviewers to it, because review rounds add controls each cycle. (A human-run tool designed against agent misuse can grow to more than double its task count over a few review rounds, then get cut back to a robust tool with lots of checks and no machinery.)
2. **Research context** BEFORE ideating - by default, delegate the reading:
   - **Dispatch parallel reader subagents** (a cheaper model - a mid-tier model for judgment-light reading, your smallest model for bulk - via model override) to read the relevant code, docs, and prior decisions, each returning a condensed summary, not raw file dumps. Design from those summaries so the lead turn stays uncluttered. This is on by default; skip it only for a change whose context you can already see, and keep the design synthesis itself a single pass (coding/design does not parallelize the way reading does).
   - Search the codebase for existing patterns that apply, check whatever task tracker you use (Jira, Linear, GitHub Issues, or similar) for related work or prior art, and check any long-lived notes or past-conversation history you keep for earlier decisions on this topic.
   Do not brainstorm in a vacuum - ground every option in the real code and project context.
3. **Offer the visual companion just-in-time** - NOT upfront. The first time a question would be genuinely clearer shown than described (a real mockup / layout / diagram question), offer it then, as its own message. See the Visual Companion section.
4. **Settle on the distinct approaches the space genuinely has - usually 2-4.** Strip anything that is a minor variant of another; only exceed four when the design space is truly wide, and say so. For each, know its one-line what-it-does, its key tradeoff, and a rough effort (S/M/L/XL). YAGNI ruthlessly.
5. **Resolve any orthogonal decisions first.** If the design has cross-cutting axes (e.g. a behaviour choice AND a source-of-truth choice), settle those first, each as its own question - it collapses the option space. Never present the full option set and the axes in the same turn.
6. **Present recommend-led, through the question box.** Summarise each approach in a sentence with its key tradeoff, then **recommend ONE** with a one-line why. Surface the choice through `AskUserQuestion`: the recommended option **listed first and marked "(Recommended)"** as the default path, then the alternatives, plus a "Something else / combine" row. Invite combinations only when the approaches actually compose; otherwise it is a single pick. Do NOT post a dense lettered comparison table. **Names are the exception:** never offer a name, slug, or naming convention as a question-box option. The short option labels make the agent shorten or rewrite names, so the exact spelling is lost. Ask about names in chat instead, each candidate as exact text in a code span.
7. **Ask only genuine ambiguity.** Skip questions the code or an obvious convention already settles; ask one at a time, each with a recommended default. At any point offer "accept all remaining recommendations" so a long interview can end in one step.

### Phase 2: Converge (design)

Goal: narrow to one approach and flesh it out.

1. **Lock the direction** - confirm the chosen approach (or hybrid) and state it back in one sentence.
2. **Design the solution**, in sections scaled to their complexity (a few sentences if straightforward, up to ~200-300 words if nuanced): architecture / components / data flow, user experience, integration points, data model, edge cases and out-of-scope, dependencies. Ask after each section whether it looks right.
3. **Design for isolation and clarity** - break the system into units with one clear purpose and well-defined interfaces, each understandable and testable on its own. When a file or unit is doing too much, say so.
4. **Identify unknowns** - list what needs investigation or a decision before building; flag blockers vs nice-to-knows.

### Phase 3: Specify (spec document)

Goal: a concrete spec `dev-writing-plans` can consume.

1. **Write the spec** to `docs/plans/YYYY-MM-DD-<topic>-spec.md`. **Confirm today's date from your environment first** (an assistant's own "current date" context, or `date +%F`); never infer it from training priors; use ISO `YYYY-MM-DD`. (This date discipline does not travel to subagents - restate it in any delegating prompt.) Use this template:

```markdown
# <Project/Feature Name> - Spec

## Problem
{What problem this solves and why it matters}

## Solution
{Chosen approach - 2-3 paragraph summary}

## Architecture
{Components, services, data flow in text}

## Scope
### In Scope
- {what's included}
### Out of Scope
- {what's explicitly excluded}

## Data Model
{Key entities, fields, relationships}

From itgenius-au/skills-library, MIT.

More from itgenius-au/skills-library