brainstorming

Files (7)

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

SKILL.md (first lines)

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by classifying how much process the request needs, then work
through your path: understand the context, refine the idea, choose a
design, self-review it, and proceed.

## Establish Shared Understanding

The outcome of brainstorming is an understanding your human partner can
recognize and correct, grounded in what they want to accomplish.

1. **Discover intent.** Use the request and available context to identify
   the intended outcome, who it is for, and what success looks like.
   Knowing the app genre does not tell you why your partner wants it. When
   the purpose is missing and the answer would materially change the
   design, ask one focused question about purpose or intended use before
   proposing features or an approach. Otherwise infer it and mark it as an
   assumption.
2. **Write back your understanding.** Summarize the intended outcome,
   relevant constraints, and success criteria in a short note your partner
   can assess. Separate what they said from assumptions so they can correct
   it. The note is for visibility, not a permission request: continue
   unless a correction arrives.
3. **Carry intent into the design.** Preserve the understanding in the
   selected path's design artifact: the written spec for architectural
   work, or the in-chat design/probe for bounded work and spikes. Check
   proposed features and technical choices against that understanding.

When the request already supplies the purpose and constraints, reflect
that understanding instead of asking the same questions again. Keep the
note concise; its accuracy and the opportunity to correct it matter.

<AUTONOMY-GATE>
Do NOT begin implementation until you understand the context, have selected
an approach, and have checked it against the request. Present the decision for
visibility, then continue without waiting for routine approval. Stop only when
the design requires missing information, expands scope materially, or needs
new authority for an irreversible or external action.

Implementation includes invoking an implementation skill, writing product
code, scaffolding, installing product dependencies, or creating an external
project. Complete the selected path's artifact first: the probe for a spike,
the short in-chat design for bounded work, and for architectural work the
written, self-reviewed spec followed by baspowers:writing-plans. Read-only
project exploration is allowed before that.
</AUTONOMY-GATE>

## Three Paths

Before your first question, classify the request. State the classification
briefly when it helps your human partner follow the work:

- **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, then
  find out as cheaply as correctness allows. No design
  doc, no spec file. Report findings as a recommendation; anything you
  built stays labeled throwaway.
- **Bounded** — a well-scoped change to code that already exists in
  this repo: a new flag, a small endpoint, a one-file fix.
  Understanding the kind of app is not enough — 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. Resolve material ambiguity,
  present a short design IN CHAT (a few sentences to a few short
  paragraphs), self-review it, then implement. No spec file, no
  implementation plan document.
- **Architectural** — new projects, new subsystems, changes that
  restructure how components fit together or alter interfaces others
  depend on. Follow the full process: questions, approaches, sectioned
  design, written spec, then the writing-plans skill.

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

## Anti-Pattern: Routine Approval Requests

Every path requires enough design to make implementation intentional. A
bounded change may need only two sentences in chat. A new todo-list project
is architectural and gets the written spec and plan. Scale the artifact to
the selected path. Presenting decisions is a status update, not a permission
gate. Continue unless one of the authority boundaries above applies.

## Red Flags

| Thought | Reality |
|---------|---------|
| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and plan. Then proceed. |
| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
| "I should ask whether this obvious reversible choice is okay" | Routine choices belong to the agent. Decide, state the decision, and proceed. |
| "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. Re-classify and apply the heavier workflow. |
| "Autonomy means I can expand scope" | Autonomy applies inside the request. Material scope expansion still needs authority. |

## Checklist

Classify first (state the path when it helps, as above), then create a task
for each item on your path and complete them in order.

**Spike:**
1. **Explore project context** — enough to frame the probe
2. **Present question + probe plan** — 2-3 sentences
3. **Investigate** — as cheaply as correctness allows
4. **Report findings** — a recommendation; label anything built as throwaway

**Bounded:**
1. **Explore project context** — check files, docs, recent commits
2. **Resolve ambiguity** — inspect first; ask only for missing decisions that materially change the result
3. **Present short design in chat** — approach, files touched, testing
4. **Self-review** — check scope, assumptions, and test strategy
5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document

**Architectural:**
1. **Explore project context** — check files, docs, recent commits
2. **Use the visual companion just-in-time** — only when a real visual question would be clearer shown than described. See the Visual Companion section below.
3. **Resolve ambiguity** — inspect first; ask one question only when the answer cannot be inferred safely

From basnijholt/baspowers, MIT.

More from basnijholt/baspowers