brainstorming

Files (1)

• SKILL.md

SKILL.md (first lines)

# Brainstorming

Turn a rough idea into a concrete design before implementation

This is a discussion and design skill, not an implementation skill

## Process

### 1. Understand the current state

Inspect the current state:
- relevant README/docs/instruction files
- nearby code and tests
- existing patterns and similar implementations
- current constraints

Use `scout` if the area is broad. Keep raw research in `.scratch/research/`

### 2. Clarify intent

Rules:
- Follow `AGENTS.md` for questions and parallel investigation
- If evidence does not settle user intent, defer to the user instead of choosing silently
- Ask about material intent, preferences, and trade-offs that evidence cannot settle
- Explain the problem, your recommendation, and why it matters before asking for a decision. If the user is still exploring or correcting the model, keep discussing
- Surface assumptions that would materially change the design instead of silently deciding them. When several candidate assumptions serve the same focused scope decision, one short checklist may be clearer than asking them separately
- Map the workflows, roles, states, failure paths, and consequences that can actually occur
  - Ask about unresolved behavior in those paths
  - Do not invent impossible cases
- When cost, time, downtime, rollout, production load, or resource tolerance could change the design, explain the consequence and ask whether it is acceptable. Do not silently optimize around it
- Do not start planning for the affected work while any of these remains unresolved:
  - a consequential user-owned assumption
  - a material requirement
  - a scope boundary
  - a design choice
- Use structured options only when the alternatives are clear, materially different, and the user is ready to choose
- Include a short context summary in `ask_user` so the user sees why the question matters

Clarify:
- user goal and non-goals
- success criteria
- materially reachable user/system workflows and states
- constraints, risks, and acceptable cost/time/downtime/rollout consequences
- compatibility expectations
- testability expectations
- human review triggers

### 3. Explore approaches

Present only credible approaches that would produce materially different outcomes. Do not force an arbitrary number of options. Lead with the recommendation and confidence level. Explain what changes for the user, the tradeoffs and risks, and why the preferred option is the simplest coherent solution. If one option is clearly wrong, say so and explain why

Use bullets or short labeled options in generated Markdown. Use a table in direct chat only when it makes the choice clearer

### 4. Validate design

#### Design sections

For larger work:
- Show the design in short sections so it is easy to inspect and comment on without stopping progress
- These sections are not an approval wait
- They do not replace the complete reviewed design for the scope being approved
- Cover:
  - architecture / placement
  - data/control flow
  - previous and proposed user-visible behavior
  - reachable failure behavior when relevant
  - proof strategy
  - rollout/cleanup when relevant

#### Approval wait

- The only default normal-mode wait is after:
  - the complete draft
  - asynchronous review
  - the complete revised design for the scope being approved
- Any additional milestone wait must be:
  - named in the decision-ready proposal
  - explicitly approved

### 5. Save a design when useful

Write `.scratch/plans/YYYY-MM-DD-<topic>-design.md` when the user explicitly requests it or helps continuity. Include the goal and non-goals, chosen and rejected approaches, marked assumptions, affected systems, risks, review triggers, and open questions

Do not edit project docs during brainstorming. The artifact preserves detail but never replaces a self-contained decision-ready proposal in chat

## Quality Bar

A brainstorm is not done until:
- the user's actual goal is clear,
- at least one simpler alternative was considered,
- risks are explicit,
- the proof strategy is plausible,
- the next step is either planning or a clearly bounded implementation

From OrestesK/pi, MIT.

More from OrestesK/pi