# Brainstorming

> Use when starting any new feature, significant change, or when you have an idea that needs design

- Skill: `rutgerdijk/brainstorming` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rutgerdijk/brainstorming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rutgerdijk/brainstorming/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: RutgerDijk (https://skillmd.com/u/rutgerdijk)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/rutgerdijk/brainstorming

---


# Brainstorming Ideas Into Designs

## Overview

Turn ideas into fully formed designs with implementation plans through collaborative dialogue. Produces two artifacts:
1. **Spec Document** — Design + implementation plan in single `docs/plans/` file
2. **GitHub Issue** — Tracking with acceptance criteria

**Announce at start:** "I'm using brainstorming to design and plan this feature."

## Arguments

| Flag | Effect |
|------|--------|
| (none) | Full flow: design + plan in one doc → issue |
| `--design-only` | Stop after design section (no implementation tasks) |

## The Process

### Phase 1: Understanding the Idea

1. Check the current project state (files, docs, recent commits)
2. Ask questions **one at a time** to refine the idea
3. Prefer multiple choice questions when possible
4. Focus on: purpose, constraints, success criteria, affected areas

### Phase 2: Exploring Approaches

1. Propose 2-3 different approaches with trade-offs
2. Lead with your recommended option and explain why
3. Get user confirmation before proceeding

### Phase 3: Presenting the Design

1. Present design in sections of 200-300 words
2. Ask after each section: "Does this look right so far?"
3. Cover: architecture, components, data flow, error handling, testing
4. Be ready to revise based on feedback

### Phase 4: Creating Artifacts

**Create Spec Document:**

Save to `docs/plans/YYYY-MM-DD-<topic>.md` with both design AND implementation plan:

```markdown
# <Feature Name>

> Use executing-plans to implement this spec task-by-task.

## Overview

<2-3 sentence description of what this builds>

## Architecture

<Technical approach, key decisions, components involved>

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

---

## Implementation Plan

**Execution Strategy:** `parallel` | `batch` | `sequential`

<Rationale for chosen strategy>

### Task 1: <Component Name>

**Files:**
- Create: `exact/path/to/file.ext`
- Test: `tests/exact/path/to/test.ext`

**Steps:**
1. <Exact action with code>
2. <Verify step>
3. Commit: `git commit -m "feat(scope): description"`

### Task 2: <Next Component>

...

---

```

**Unless `--design-only` flag**, include the Implementation Plan section.

## Writing Implementation Tasks

### Task Granularity

**Each task = one logical unit (2-5 minutes):**

| Good Task | Bad Task |
|-----------|----------|
| "Add User entity with Id, Email, Name" | "Implement user management" |
| "Add CreateUserAsync to IUserService" | "Add service layer" |
| "Add POST /api/users endpoint" | "Build the API" |

### Task Structure Template

```markdown
### Task N: <Descriptive Name>

**Files:**
- Create: `src/Domain/Entities/User.cs`
- Create: `tests/Domain.Tests/Entities/UserTests.cs`
- Modify: `src/Infrastructure/Data/AppDbContext.cs:15-20`

**Step 1: Write failing test**

```csharp
[Fact]
public void User_WithValidData_CreatesSuccessfully()
{
    var user = new User("test@example.com", "Test User");

    user.Email.Should().Be("test@example.com");
    user.Name.Should().Be("Test User");
}
```

**Step 2: Run test (expect FAIL)**

```bash
dotnet test --filter "User_WithValidData"
```

Expected: Test fails (User class doesn't exist)

**Step 3: Implement minimal code**

```csharp
public class User
{
    public int Id { get; private set; }
    public string Email { get; private set; }
    public string Name { get; private set; }

    public User(string email, string name)
    {
        Email = email;
        Name = name;
    }
}
```

**Step 4: Run test (expect PASS)**

```bash
dotnet test --filter "User_WithValidData"
```

Expected: Test passes

**Step 5: Commit**

```bash
git add src/Domain/Entities/User.cs tests/Domain.Tests/Entities/UserTests.cs
git commit -m "feat(backend): add User entity with email and name"
```
```

### Execution Strategies

```yaml
# For independent tasks (different files, no dependencies)
execution:
  strategy: parallel

# For phased work (model → service → controller)
execution:
  strategy: batch
  batches:
    - name: "Data Model"
      tasks: [1, 2]
    - name: "Business Logic"
      tasks: [3, 4]
    - name: "API Layer"
      tasks: [5, 6]

# For tightly coupled changes
execution:
  strategy: sequential
```

### TDD Requirements

Every task MUST follow Red-Green-Refactor:

1. **Test file listed** — Every task has a test file in "Files:"
2. **Test written first** — Step 1 is always "Write failing test"
3. **Failure verified** — Step 2 runs test, expects failure
4. **Minimal implementation** — Step 3 writes just enough code
5. **Success verified** — Step 4 runs test, expects pass
6. **Commit includes both** — Test and implementation committed together

### Stack-Specific Patterns

**Detect stack and include relevant patterns:**

| Stack | Test Framework | Patterns |
|-------|---------------|----------|
| .NET | xUnit + FluentAssertions | `[Fact]`, `.Should().Be()` |
| React | Vitest + Testing Library | `test()`, `render()`, `screen.getByText()` |
| Node | Jest | `describe()`, `it()`, `expect()` |

Reference `.github/instructions/*.md` for detailed patterns.

### Phase 4b: Create Feature Branch and Push Spec

**After writing spec, before creating issue:**

```bash
# 1. Create topic name from feature title
TOPIC=$(echo "<feature-title>" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-')

# 2. Create feature branch from main
git checkout -b feature/$TOPIC

# 3. Commit the spec document
git add docs/plans/YYYY-MM-DD-<topic>.md
git commit -m "docs(plans): add spec for $TOPIC"

# 4. Push branch to remote
git push -u origin feature/$TOPIC

# 5. Return to main branch
git checkout main
```

**Why push before creating issue:**
- Spec link in issue points to actual file on the branch
- Anyone can fetch the branch to see the spec
- Spec stays on feature branch, not polluting main

### Phase 4c: Create GitHub Issue

```bash
# Get the branch name for the spec link
BRANCH="feature/$TOPIC"

gh issue create --title "<Feature Name>" --body "$(cat <<'EOF'
## Summary

<2-3 sentence description>

## Linked Spec

[View full spec](https://github.com/<owner>/<repo>/blob/feature/<topic>/docs/plans/YYYY-MM-DD-<topic>.md)

## Feature Branch

`feature/<topic>` — spec is committed here, ready for implementation

## Quick Start

```bash
pickup <issue-number>
```

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

---

EOF
)" --label "<labels>"
```

**After issue is created**, update the branch name to include issue number:

```bash
# Get the issue number from the created issue
ISSUE_NUMBER=<newly-created-issue-number>

# Rename local branch
git branch -m feature/$TOPIC feature/${ISSUE_NUMBER}-${TOPIC}

# Delete old remote branch and push renamed one
git push origin --delete feature/$TOPIC
git push -u origin feature/${ISSUE_NUMBER}-${TOPIC}

# Update issue with correct branch reference
gh issue edit $ISSUE_NUMBER --body "$(updated body with correct branch name)"
```

### Phase 5: Final Handoff

"**Ready for implementation!**

**Artifacts created:**
- Spec: `docs/plans/<date>-<topic>.md` (on feature branch)
- Branch: `feature/<issue-number>-<topic>` (pushed to remote)
- Issue: #<number>

**To start implementation:**

```bash
pickup <issue-number>
```

This will:
1. Fetch the feature branch
2. Create a worktree in `.worktrees/<issue-number>-<topic>`
3. Auto-continue to execution if spec has tasks

**IMPORTANT:** The spec lives on the feature branch, not main."

## Labels Reference

| Label | When to Use |
|-------|-------------|
| `backend` | Changes to .NET API, services, database |
| `frontend` | Changes to React UI, components, styling |
| `infrastructure` | Docker, Azure, Bicep, CI/CD |
| `security` | Authentication, authorization, security fixes |
| `feature` | New functionality |
| `refactor` | Code restructuring without behavior change |
| `bugfix` | Fixing broken functionality |
| `docs` | Documentation only |

## Key Principles

- **One question at a time** — Don't overwhelm
- **Multiple choice preferred** — Easier to answer
- **YAGNI ruthlessly** — Remove unnecessary features
- **Artifacts are durable** — Everything survives context loss
- **Commit the design doc** — Save to git before creating issue