brainstorm

Files (1)

• SKILL.md

SKILL.md (first lines)

# brainstorm

Turn an idea into a validated design through dialogue, then hand off to `plan`. No code is written here.

## HARD-GATE

Do NOT write code, scaffold a project, or invoke any implementation skill until you have presented a design and the user has approved it in writing.

This applies to every project regardless of perceived simplicity. A todo list, a one-function utility, a config change: all go through this gate. The design can be three sentences, but it must exist and be approved.

**Anti-pattern:** "this is too simple to need a design." Simple projects are where unexamined assumptions cause the most wasted work.

## Understand before you shorten

Before proposing anything, trace the whole thing first: every file the change touches, the actual flow. `lazy` governs how short the solution gets. It never shortens the reading.

## Procedure

1. **Invoke `lazy`, `terse` and `plain` before anything else.** `lazy` governs what you build, `terse` how you talk, `plain` how text is typed. All three stay on for the rest of the session. Their description lines are not their content. You have not read a skill until you have invoked it.
2. Explore context: **look before you ask**. List the directory, read what matters, check recent commits. "New project, nothing to explore" is a conclusion you may only reach *after* a tool call, never instead of one. Asking your first question before you have looked is skipping this step.
3. Clarifying questions, one at a time.
4. Scope check.
5. Pushback turn.
6. Two or three approaches with a recommendation.
7. Present the design in sections, approval after each.
8. Write the spec doc, commit.
9. Self-review.
10. User review gate.
11. Hand off to `plan`. Terminal.

## Clarifying questions

One at a time. Never batch. Multiple choice when the option space is small, open-ended when it is wide. Focus on purpose, constraints, success criteria.

**One question mark per turn.** Batching is what this rule actually fails at, so check the literal text before sending: if your turn contains a second `?`, or an "and" joining two asks, cut everything after the first question and hold it for the next turn. Two questions in one turn is a violation even when they are related, especially then, because the answer to the first often deletes the second.

Two rules that override the urge to proceed:

- **If multiple interpretations exist, present them. Do not pick silently.**
- **If something is unclear, stop. Name what is confusing. Ask.**

## Scope check

Before spending questions on detail: if the request spans multiple independent subsystems, say so immediately. Do not refine a project that must first be decomposed.

Decompose into sub-projects with an explicit build order, then brainstorm the first one. Each sub-project gets its own spec, plan and implementation cycle.

## Pushback turn

Exactly one, before approaches. Required. Challenge the framing if a simpler path exists. Silently accepting the user's framing is a failure mode.

Output verbatim, in this shape:

> **Pushback:** Before I sketch approaches, one challenge. `<one-sentence simpler framing or hidden assumption>`. Is the smaller version what you want, or do you need the larger framing? (If the larger framing is correct, say so and I'll proceed.)

If no simpler framing exists, say so explicitly:

> **Pushback:** No simpler framing: the requirement is already minimal. Proceeding to approaches.

Record the user's response in the spec's Approach section.

## Approaches

Two or three, always, even when one seems obvious. The user decides obviousness.

Full prose, with trade-offs and your recommendation. Lead with the recommendation and say why.

**At least one approach must sit at the laziest rung of `lazy`'s ladder that still meets the requirement**, so the user can choose it.

## Presenting the design

Scale each section to its complexity: a few sentences if straightforward, up to about 300 words if nuanced. Ask after each section whether it looks right so far.

Cover architecture, components, data flow, error handling, testing.

Break the system into units with one clear purpose each, communicating through well-defined interfaces. For each unit: what does it do, how do you use it, what does it depend on? If a unit cannot be understood without reading its internals, or its internals cannot change without breaking consumers, the boundaries need work.

In an existing codebase, follow existing patterns. Include targeted improvements where existing problems affect this work. Do not propose unrelated refactoring.

## Spec document

Write to `docs/specs/YYYY-MM-DD-<topic>-design.md`, then commit. Headings, in order:

```
---
title: <topic>
date: YYYY-MM-DD
status: draft
---

# <topic>: Design

## Problem
## Goals
## Non-goals
## Constraints
## Approach
## Alternatives considered
## Testing
## Open questions
```

**Each goal states an observable success criterion.** "Make it work" is not a goal. Strong criteria let downstream skills verify without asking the user.

If a section is genuinely not applicable, write `N/A: <one-line reason>`, never `TODO`.

## Self-review

Fresh eyes on what you just wrote:

1. **Placeholders.** Any TBD, TODO, or vague requirement? Fix it.
2. **Internal consistency.** Do sections contradict each other?
3. **Scope.** Focused enough for a single implementation plan?
4. **Ambiguity.** Could any requirement be read two ways? Pick one and make it explicit.

Fix inline. No re-review.

## User review gate

From rizukirr/vibekit, MIT.

More from rizukirr/vibekit