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

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:

# <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):

Task Structure Template

### 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)

dotnet test --filter "User_WithValidData"

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

Step 3: Implement minimal code

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)

dotnet test --filter "User_WithValidData"

Expected: Test passes

Step 5: Commit

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:

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

Phase 4b: Create Feature Branch and Push Spec

After writing spec, before creating issue:

# 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

# 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 ""

**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: #

To start implementation:

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

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