---
name: brainstorming
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

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

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

## Checklist

You MUST create a todo item for each of these and complete them in order:

1. **Explore project context** — check files, docs, recent commits
2. **Offer visual companion** (if topic will involve visual questions) — own message, not combined with a clarifying question
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Save spec to BookStack** — create a page in the Specs book (https://wiki.ctz.fyi) with the full design doc
7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope
8. **User reviews spec** — ask user to review the BookStack page before proceeding
9. **Transition to implementation** — invoke `writing-plans` skill

## BookStack Spec Page

After the design is approved (step 6), save it to BookStack at https://wiki.ctz.fyi:

1. The **Specs** book already exists (book ID 157) under the Superpowers shelf.
2. Create the spec page via `bookstack_pages_create`:
   - `book_id`: 157
   - `name`: `[Spec] YYYY-MM-DD: <topic>`
   - `markdown`: full design doc in markdown
3. Note the returned page URL for the user review gate: `https://wiki.ctz.fyi/books/specs-CdD/page/<slug>`

> If a project-specific chapter is appropriate (e.g., a named project has multiple specs), create or reuse a chapter inside the Specs book and use `chapter_id` instead of `book_id`.

## Vikunja Project Setup

Also create or identify the Vikunja project for implementation tracking:

1. Call `litellm_vikunja-vikunja_api` with operation `get_projects` to list all projects
2. Ask: "Which Vikunja project should tasks live in? Or I can create a new one cloned from the Template."
3. If creating a new project:
   - Ask the user what to name it
   - Call `put_projects_projectid_duplicate` with `projectID: 5`, body `{ "name": "<chosen name>" }`
4. Note the project ID for `writing-plans`

## The Process

**Understanding the idea:**
- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately
- If the project is too large for a single spec, help the user decompose into sub-projects
- For appropriately-scoped projects, ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible
- Only one question per message
- Focus on understanding: purpose, constraints, success criteria

**Exploring approaches:**
- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why

**Presenting the design:**
- Once you believe you understand what you're building, present the design
- Scale each section to its complexity
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing

**Design for isolation and clarity:**
- Break the system into smaller units that each have one clear purpose
- Can someone understand what a unit does without reading its internals?

**Working in existing codebases:**
- Explore the current structure before proposing changes. Follow existing patterns.
- Include targeted improvements but don't propose unrelated refactoring.

## Spec Self-Review (step 7)

Run this yourself — not a subagent:

1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. **Internal consistency:** Do any sections contradict each other?
3. **Scope check:** Is this focused enough for a single implementation plan?
4. **Ambiguity check:** Could any requirement be interpreted two different ways?

## User Review Gate (step 8)

After saving to BookStack and completing the self-review, ask the user:

> "Spec saved to BookStack: https://wiki.ctz.fyi/books/specs-CdD/page/<slug>. Please review it and let me know if you want any changes before we start writing the implementation plan."

Wait for the user's response. Only proceed once the user approves.

## Implementation (step 9)

- Invoke the `writing-plans` skill to create a detailed implementation plan
- Do NOT invoke any other skill. `writing-plans` is the next and only step.

## Key Principles
- One question at a time
- Multiple choice preferred
- YAGNI ruthlessly
- Explore alternatives — always propose 2-3 approaches
- Incremental validation — present design section by section, get approval before moving on
- Be flexible — go back and clarify when something doesn't make sense

## Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options. Offer it once for consent when visual questions are anticipated. This offer MUST be its own message — not combined with a clarifying question.

Per-question decision: use browser for layout/mockup/diagram content; use text for conceptual questions.