Brainstorm

Brainstorming Ideas Into Designs

Transform rough ideas into fully-formed designs through intelligent agent selection and structured exploration.

Core principle: Analyze the topic, select relevant agents dynamically, explore alternatives in parallel, present design incrementally.

Argument Resolution

TOPIC = "$ARGUMENTS"  # Full argument string, e.g., "API design for payments"
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

---

STEP -1: MCP Probe + Resume Check

Probe MCP servers once at skill start, store capabilities, and resume from any prior crashed session. Each phase emits a JSON handoff file consumed by the next.

Full procedure + handoff-file table: Read("${CLAUDE_SKILL_DIR}/references/mcp-probe-resume.md")

---

STEP 0: Project Context Discovery

BEFORE creating tasks or selecting agents, detect the project tier. This becomes the complexity ceiling for all downstream decisions.

Auto-Detection (scan codebase)

# PARALLEL — quick signals (launch all in ONE message)
Grep(pattern="take-home|assignment|interview|hackathon", glob="README*", output_mode="content")
Grep(pattern="take-home|assignment|interview|hackathon", glob="*.md", output_mode="content")
Glob(pattern=".github/workflows/*")
Glob(pattern="**/Dockerfile")
Glob(pattern="**/terraform/**")
Glob(pattern="**/k8s/**")
Glob(pattern="CONTRIBUTING.md")

Tier Classification

If confidence is low, ask the user:

AskUserQuestion(questions=[{
  "question": "What kind of project is this?",
  "header": "Project tier",
  "options": [
    {"label": "Interview / take-home", "description": "8-15 files, 200-600 LOC, simple architecture"},
    {"label": "Startup / MVP", "description": "MVC monolith, managed services, ship fast"},
    {"label": "Growth / enterprise", "description": "Modular monolith or DDD, full observability"},
    {"label": "Open source library", "description": "Minimal API surface, exhaustive tests"}
  ],
  "multiSelect": false
}])

Pass the detected tier as context to ALL downstream agents and phases. The tier constrains which patterns are appropriate — see scope-appropriate-architecture skill for the full matrix.

Override: User can always override the detected tier. Warn them of trade-offs if they choose a higher tier than detected.

---

STEP 0a: Verify User Intent with AskUserQuestion

Clarify brainstorming constraints:

# NOTE: AskUserQuestion caps each question at 4 options (CC schema: minItems 2,
# maxItems 4). Use plain `label` + `description` only — the schema permits a
# `preview` field, but on current CC it forces a side-by-side picker layout with
# dead up/down keyboard nav (confirmed 2026-05-28), so skills no longer use it
# (`markdown` was never valid). The 6 legacy
# modes are split across 3 valid questions: Q1 = exploration flow, Q2 folds the
# old "Constrained design" mode into constraints, Q3 carries the orthogonal
# "Plan first" preamble (it composes with any Q1 mode — it was never mutually
# exclusive). "Quick ideation" + STEP 0c /effort=low overlap; both downscale.
AskUserQuestion(
  questions=[
    {
      "question": "What type of design exploration?",
      "header": "Mode",
      "options": [
        {"label": "Open exploration (Recommended)", "description": "Generate 10+ ideas, evaluate all, synthesize top 3"},
        {"label": "Comparison", "description": "Compare 2-3 specific approaches I have in mind"},
        {"label": "Quick ideation", "description": "Generate ideas fast, skip deep evaluation"},
        {"label": "Iterative optimization", "description": "Try, measure, keep/discard, repeat (autoresearch-style)"}
      ],
      "multiSelect": false
    },
    {
      "question": "Any preferences or constraints?",
      "header": "Constraints",
      "options": [
        {"label": "None", "description": "Explore all possibilities"},
        {"label": "Use existing patterns", "description": "Prefer patterns already in codebase"},
        {"label": "Minimize complexity", "description": "Favor simpler solutions"},
        {"label": "Fixed requirements (constrained)", "description": "Hard requirements to work within — skip divergent phase, focus on feasibility (old 'Constrained design' mode)"}
      ],
      "multiSelect": false
    },
    {
      "question": "Research before ideating?",
      "header": "Plan-first",
      "options": [
        {"label": "No — dive straight in (Recommended)", "description": "Go directly to ideation"},
        {"label": "Yes — plan first", "description": "Read-only research (EnterPlanMode): scan codebase, map the solution space, then ExitPlanMode for approval before Phase 1 (old 'Plan first' mode)"}
      ],
      "multiSelect": false
    }
  ]
)

If Q3 = 'Yes — plan first' (composes with any Q1 mode):

# 1. Enter read-only plan mode
EnterPlanMode("Brainstorm exploration: $TOPIC")

# 2. Research phase — Read/Grep/Glob ONLY, no Write/Edit
#    - Scan existing codebase for related patterns
#    - Search for prior decisions on this topic (memory graph)
#    - Identify constraints, dependencies, and trade-offs

# 3. Produce structured exploration plan:
#    - Key questions to answer
#    - Dimensions to explore
#    - Agents to spawn and their focus areas
#    - Evaluation criteria

# 4. Exit plan mode — returns plan for user approval
ExitPlanMode()

# 5. User reviews. If approved → continue to Phase 1 with plan as input.

Based on answers, adjust workflow:

• Open exploration (Q1): Full 7-phase process with all agents
• Comparison (Q1): Skip ideation, jump to evaluation phase
• Quick ideation (Q1): Generate ideas, skip deep evaluation
• Iterative optimization (Q1): Skip phases 2-6, enter autoresearch-style loop (see below)
• Constrained design (Q2 = "Fixed requirements"): Skip divergent phase, focus on feasibility within the stated requirements — composes with any Q1 mode

If 'Iterative optimization' selected: skip Phases 2-6 and enter the autoresearch-style metric-driven loop.

Full sub-flow (metric question, baseline, loop body): Read("${CLAUDE_SKILL_DIR}/references/iterative-optimization-mode.md")

---

STEP 0b: Select Orchestration Mode (skip for Tier 1-2)

Choose Agent Teams (mesh — agents debate and challenge ideas) or Task tool (star — all report to lead):

1. Agent Teams mode (GA since CC 2.1.33) → recommended for 3+ agents (real-time debate produces better ideas) 2. Task tool mode → for quick ideation 3. ORCHESTKIT_FORCE_TASK_TOOL=1 → Task tool (override)

Fallback: If Agent Teams encounters issues, fall back to Task tool for remaining phases.

---

STEP 0c: Effort-Aware Phase Scaling (CC 2.1.76; xhigh added in 2.1.111)

Read the /effort setting and scale brainstorm depth — low runs phases 0/2/5 only, high (default) runs all 7, xhigh adds extra devil's-advocate and synthesis rounds. Explicit user choice in STEP 0a always overrides downscaling.

Full level table + detection rules: Read("${CLAUDE_SKILL_DIR}/references/effort-scaling.md")

---

🚨 CRITICAL: Task Management is MANDATORY (CC 2.1.16)

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Brainstorm: {topic}",
  description="Design exploration with parallel agent research",
  activeForm="Brainstorming {topic}"
)

# 2. Create subtasks for each phase
TaskCreate(subject="Analyze topic and select agents", activeForm="Analyzing topic")          # id=2
TaskCreate(subject="Search memory for past decisions", activeForm="Searching knowledge graph") # id=3
TaskCreate(subject="Generate divergent ideas (10+)", activeForm="Generating ideas")          # id=4
TaskCreate(subject="Feasibility fast-check", activeForm="Checking feasibility")              # id=5
TaskCreate(subject="Evaluate with devil's advocate", activeForm="Evaluating ideas")          # id=6
TaskCreate(subject="Synthesize top approaches", activeForm="Synthesizing approaches")        # id=7
TaskCreate(subject="Present design options", activeForm="Presenting options")                # id=8

# 3. Set dependencies (sequential chain: 2→3→4→5→6→7→8)
for i in range(3, 9):
    TaskUpdate(taskId=str(i), addBlockedBy=[str(i-1)])

# 4. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty
# 5. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

🔄 The Seven-Phase Process

Phase 6.5 — Post-synthesis audio podcast (signal-fired, optional)

After Phase 6 lands, optionally invoke scripts/post_synth_podcast.py <session-dir> to auto-emit an audio podcast summarizing the top approaches + trade-offs. Self-skips on every non-happy-path so it never breaks the brainstorm:

python3 ${CLAUDE_SKILL_DIR}/scripts/post_synth_podcast.py "$CLAUDE_JOB_DIR"

Auto-skip conditions (all exit 0, all WARN-logged):

Session dir must contain brainstorm-output.json (with recommended, composite, approaches) + design-doc.md. Handoff JSON at <session-dir>/brainstorm-podcast.json records status (fired / skipped) and m4a_path on success.

Mirrors Yonatan-HQ/hq-ext-plugin#194 (audio_podcast handler for /hq-ext:decide).

Progressive Output (CC 2.1.76)

Output results incrementally after each phase — don't batch everything until the end:

For Phase 2 parallel agents, output each agent's ideas as soon as it returns — don't wait for all agents. This lets users see early ideas and redirect the exploration if needed. Showing ideas incrementally also helps users build a mental model of the solution space faster than a final dump.

Load the phase workflow for detailed instructions:

Read("${CLAUDE_SKILL_DIR}/references/phase-workflow.md")

---

⚠️ When NOT to Use

Skip brainstorming when:

• Requirements are crystal clear and specific
• Only one obvious approach exists
• User has already designed the solution
• Time-sensitive bug fix or urgent issue

---

Quick Reference: Agent Selection

Always include: workflow-architect for system design perspective, test-generator for testability assessment.

---

Agent Teams Alternative: Brainstorming Team

In Agent Teams mode, form a brainstorming team where agents debate ideas in real-time. Dynamically select teammates based on topic analysis (Phase 0):

# CC 2.1.178+: one implicit team per session — no TeamCreate.
# Spawn teammates directly via Agent(name=...). Requires
# CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in ork.settings.json).

# Always include the system design lead
Agent(subagent_type="ork:workflow-architect", name="system-designer",
     team_name="brainstorm-{topic-slug}",
     prompt="""You are the system design lead for brainstorming: {topic}
     DIVERGENT MODE: Generate 3-4 architectural approaches.
     When other teammates share ideas, build on them or propose alternatives.
     Challenge ideas that seem over-engineered — advocate for simplicity.
     After divergent phase, help synthesize the top approaches.""")

# Domain-specific teammates (select 2-3 based on topic keywords)
Agent(subagent_type="ork:backend-system-architect", name="backend-thinker",
     team_name="brainstorm-{topic-slug}",
     prompt="""Brainstorm backend approaches for: {topic}
     DIVERGENT MODE: Generate 3-4 backend-specific ideas.
     When system-designer shares architectural ideas, propose concrete API designs.
     Challenge ideas from other teammates with implementation reality checks.
     Play devil's advocate on complexity vs simplicity trade-offs.""")

Agent(subagent_type="ork:frontend-ui-developer", name="frontend-thinker",
     team_name="brainstorm-{topic-slug}",
     prompt="""Brainstorm frontend approaches for: {topic}
     DIVERGENT MODE: Generate 3-4 UI/UX ideas.
     When backend-thinker proposes APIs, suggest frontend patterns that match.
     Challenge backend proposals that create poor user experiences.
     Advocate for progressive disclosure and accessibility.""")

# Always include: testability assessor
Agent(subagent_type="ork:test-generator", name="testability-assessor",
     team_name="brainstorm-{topic-slug}",
     prompt="""Assess testability for each brainstormed approach: {topic}
     For every idea shared by teammates, evaluate:
     - Can core logic be unit tested without external services?
     - What's the mock/stub surface area?
     - Can it be integration-tested with docker-compose/testcontainers?
     Score testability 0-10 per the evaluation rubric.
     Challenge designs that score below 5 on testability.
     Propose test strategies for the top approaches in synthesis phase.""")

# Optional: Add security-auditor, llm-integrator based on topic

Key advantage: Agents riff on each other's ideas and play devil's advocate in real-time, rather than generating ideas in isolation.

Fork pattern (CC 2.1.89 — #1227): All brainstorm agents are fork-eligible: prompts are <500 words, no custom model, no worktree. CC shares the parent's cached API prefix across forks, reducing cost by ~60%. Do NOT add model= to agent calls. See chain-patterns/references/fork-pattern.md.

Nested delegation (CC 2.1.172+): Teammates MAY be instructed to delegate a bounded sub-question to their declared sub-agents (e.g. backend-thinker → database-engineer to sanity-check a schema idea) instead of guessing inline. Keep chains ≤ 3 levels deep; divergent ideation itself stays flat — the parallel teammates above ARE the fan-out for independent ideas. See chain-patterns Pattern 9 (CC 2.1.172+).

Team teardown after synthesis:

# After Phase 5 synthesis and design presentation
# CC 2.1.178+: no TeamDelete — teammates wind down at turn end
# (press Ctrl+F twice to stop lingering background teammates).

# Worktree cleanup (CC 2.1.72) — for Tier 3+ projects that entered a worktree
# If EnterWorktree was called during brainstorm (e.g., Plan first → worktree), exit it
ExitWorktree(action="keep")  # Keep branch for follow-up /ork:implement

Fallback: If team formation fails, load Read("${CLAUDE_SKILL_DIR}/references/phase-workflow.md") and use standard Phase 2 Task spawns.

Partial results (CC 2.1.76): Background agents that are killed (timeout, context limit) return responses tagged with [PARTIAL RESULT]. When collecting Phase 2 divergent ideas, check each agent's output for this tag. If present, include the partial ideas but note them as incomplete in Phase 3 feasibility. Prefer synthesizing partial results over re-spawning agents.

PostCompact recovery: Long brainstorm sessions may trigger context compaction. The PostCompact hook re-injects branch and task state. If compaction occurs mid-brainstorm, check .claude/chain/state.json for the last completed phase and resume from the next handoff file (see Phase Handoffs table). Reactive compaction (CC 2.1.142+) now sizes the first summarize to the actual overflow, so mid-turn stalls are rare — no need to expect a second pass.

When context fills (CC 2.1.141+): Instead of ending the session, use the rewind menu's "Summarize up to here" to compress earlier turns while keeping recent context intact — a deliberate compaction point that pairs with the improved reactive compaction above.

Session recap (CC 2.1.108+): After idle periods, use /recap to restore conversational context alongside checkpoint-resume. Enabled by default since CC 2.1.110 (even with telemetry disabled).

Push notifications (CC 2.1.110+): For long brainstorm sessions, use PushNotification to alert when synthesis is complete (requires Remote Control with "Push when Claude decides").

>

Lighter alternative (CC 2.1.141+): Hooks can emit desktop notifications, window titles, and bells natively via the terminalSequence field in hook JSON output — no Remote Control required, no Anthropic round-trip. See #1847 for the migration of ork's existing notification hooks.

Manual cleanup: To stop lingering background teammates, press Ctrl+F twice (foreground/Stop). Note: /clear (CC 2.1.72+) preserves background agents — only foreground tasks are cleared.

Teammate background tasks survive turn-end (CC 2.1.183): A background task started by a teammate is no longer killed when that teammate finishes its turn. Phase-2 teammates may safely kick off a long run_in_background task (e.g. a feasibility build) and let it outlive their own turn — the result is still collectable at synthesis. Pre-2.1.183 this required the lead to own the background task.

---

Key Principles

---

Running unattended with /goal

Set a completion condition with /goal (CC 2.1.139+, 2.1.143+ recommended for this skill) and this skill will keep working across turns until the condition is met. Works in interactive, -p, and Remote Control. The overlay panel shows live elapsed / turns / tokens.

Why 2.1.143+: Pre-2.1.143 /goal evaluator could fire while background shells or delegated subagents were still running — racing the parallel agents this skill spawns in Phase 2. Fixed in CC 2.1.143 (changelog: "/goal evaluator firing while background shells or delegated subagents are still running").

Example completion condition for this skill:

/goal until design.options_count >= 2 AND user_chose_option

Stops when: 2+ ranked design options presented and the user selects one (or after Phase 6 if running unattended via -p). Compatible with claude.ai Remote Control runs.

---

📜 Related Skills

• ork:architecture-decision-record - Document key decisions made during brainstorming
• ork:implement - Execute the implementation plan after brainstorming completes
• ork:explore - Deep codebase exploration to understand existing patterns
• ork:assess - Rate quality 0-10 with dimension breakdown
• ork:design-to-code - Convert brainstormed UI designs into components
• ork:component-search - Find existing components before building new ones
• ork:competitive-analysis - Porter's Five Forces, SWOT for product brainstorms

Picker fallback (#1795)

The picker stall reported in orchestkit#1795 was a schema break, not a CC input bug: questions with >4 options or a markdown field (the markdown key is not valid — the schema field is preview) fail AskUserQuestion validation, so the picker never renders. All skill questions conform to the schema (2–4 options, no preview on multiSelect), enforced by tests/skills/structure/test-askuserquestion-schema.sh. Separately, although the schema permits a preview field, current CC renders any question that uses one in a side-by-side picker layout where ↑/↓ keyboard navigation is dead (confirmed 2026-05-28). So skills now standardize on plain label + description only and no longer set preview. If you still hit a stall on a future CC build, ORK_ASK_FALLBACK=text remains as a defensive opt-in: the lifecycle/ask-fallback-injector hook then tells the assistant to pose options inline as a numbered list. Hook propagates globally — no per-skill edit needed.

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

Idea Evaluation Template

Copy this table to score brainstorm ideas.

Scoring Table

Formula

Raw = Impact*0.25 + (10-Effort)*0.20 + (10-Risk)*0.20 + Align*0.20 + Innov*0.15
Final = Raw * (0.70 if critical concerns, 0.85 if 3+ high concerns, else 1.0)

Devil's Advocate Summary

Brainstorm Completion Checklist

Verify brainstorm quality before concluding.

Divergent Phase

• [ ] Generated 10+ distinct ideas (quantity over quality)
• [ ] Used at least one divergent technique (SCAMPER, Mind Map, Reverse, Round-Robin)
• [ ] Included unconventional "crazy" ideas
• [ ] Did NOT filter during generation

Feasibility Check

• [ ] Quick viability assessed for all ideas (30s per idea)
• [ ] Infeasible ideas (score 0-2) dropped
• [ ] Risks flagged for challenging ideas (score 3-5)

Evaluation Phase

• [ ] Scored all five dimensions (Impact, Effort, Risk, Alignment, Innovation)
• [ ] Applied weighted composite formula
• [ ] Ran devil's advocate challenge on top 3-5 ideas
• [ ] Adjusted scores for critical/high concerns

Synthesis

• [ ] Filtered to top 2-3 approaches
• [ ] Trade-off table complete
• [ ] Presented options with scores to user

Documentation

• [ ] Decision stored in knowledge graph
• [ ] Tasks marked complete
• [ ] ADR created if architectural decision

Brainstorming Session Checklist

Use this checklist to facilitate effective brainstorming sessions that transform rough ideas into actionable implementation plans.

---

Pre-Session Preparation

Context Gathering

• [ ] Read the initial idea/request - What is the user actually asking for?
• [ ] Identify the problem domain - Backend, frontend, infrastructure, process, UX?
• [ ] Check existing system constraints - Review architecture docs, tech stack, current capabilities
• [ ] Review similar features - Has this been attempted before? What can we learn?
• [ ] Estimate time available - Sprint timeline, team capacity, dependencies

Stakeholder Identification

• [ ] Primary user - Who will use this feature?
• [ ] Secondary users - Who else is impacted?
• [ ] Decision makers - Who approves this?
• [ ] Implementation team - Who will build this?

---

Phase 1: Exploration (Socratic Questioning)

Foundational Questions

• [ ] Who is this for?
• Primary user persona
• User skill level (beginner, intermediate, expert)
• Team size (solo, small team, enterprise)

• [ ] What problem does this solve?
• Current pain point
• Workarounds users are doing today
• Impact if not solved (low, medium, high, critical)

• [ ] When does this problem occur?
• User workflow stage
• Frequency (daily, weekly, rare)
• Time-sensitive vs. async

• [ ] Where in the system does this fit?
• Existing feature enhancement vs. net-new
• Integration points with other features
• User journey touchpoints

• [ ] Why now?
• Strategic priority
• Market pressure
• Technical debt reduction

• [ ] How is this currently done?
• Manual workarounds
• External tools
• Cost of current solution

Depth Questions (Ask 2-3 levels deep)

• [ ] "Can you give me an example of when this happened?"
• [ ] "What did you try that didn't work?"
• [ ] "What would success look like in 6 months?"
• [ ] "If we could only solve one part, which part matters most?"
• [ ] "What assumptions are we making?"

---

Phase 2: Constraint Analysis

Technical Constraints

• [ ] Technology stack - What tools/libraries are available?
• [ ] Performance requirements - Latency, throughput, scale
• [ ] Data constraints - Volume, retention, privacy/security
• [ ] Integration points - APIs, webhooks, third-party services
• [ ] Browser/platform support - Desktop, mobile, accessibility

Resource Constraints

• [ ] Time - Sprint duration, deadline, phased rollout?
• [ ] Team - Available developers, skill levels, concurrent work
• [ ] Budget - Infrastructure costs, third-party services
• [ ] Dependencies - Blocked by other features? Auth, payments, etc.

User Experience Constraints

• [ ] Learning curve - Matches user skill level?
• [ ] Accessibility - WCAG compliance, keyboard navigation
• [ ] Mobile-first vs. desktop-first - Primary usage context
• [ ] Offline support - Required or nice-to-have?
• [ ] Internationalization - Multiple languages needed?

---

Phase 3: Solution Generation

Create Multiple Variants (Aim for 3 options)

For each option, document:

Option Name (e.g., "MVP", "Standard", "Advanced")

• [ ] What: 2-3 sentence description of the solution
• [ ] Scope: List of included features (bullet points)
• [ ] Excluded: What's explicitly NOT included
• [ ] Time estimate: Days/weeks for implementation
• [ ] Pros: 3-5 advantages
• [ ] Cons: 3-5 disadvantages or risks
• [ ] Example user flow: Step-by-step scenario (5-7 steps)
• [ ] Technical approach: Key technologies/patterns

---

Phase 4: Evaluation & Decision

Create Decision Matrix

Criteria to evaluate (customize per project):

• [ ] Time to value - How quickly can users benefit?
• [ ] Solves core problem - Fully, partially, or tangentially?
• [ ] Technical risk - Low, medium, high complexity
• [ ] User experience - Intuitive, learnable, complex
• [ ] Scalability - Handles growth (users, data, features)
• [ ] Maintainability - Easy to debug, extend, document
• [ ] Enables future work - Unlocks other features vs. dead-end
• [ ] Cost - Infrastructure, development, ongoing maintenance

Scoring

• [ ] Rate each option (1-5 scale or Low/Med/High)
• [ ] Identify deal-breakers (e.g., "Exceeds sprint timeline")
• [ ] Calculate weighted scores if needed

Recommendation

• [ ] Chosen option: Which variant and why?
• [ ] Rationale: 2-3 sentences explaining decision
• [ ] Tradeoffs acknowledged: What are we giving up?
• [ ] Risks to monitor: What could go wrong?

---

Phase 5: Implementation Planning

Break Down Work

For the chosen option:

Backend Tasks

• [ ] List 5-10 concrete tasks
• [ ] Estimate effort (hours/days per task)
• [ ] Identify dependencies (what must happen first?)
• [ ] Tag technical risks

Frontend Tasks

• [ ] List 5-10 concrete tasks
• [ ] Estimate effort (hours/days per task)
• [ ] Identify shared components/utilities needed
• [ ] Tag UX decision points

Testing Tasks

• [ ] Unit tests for new logic
• [ ] Integration tests for API interactions
• [ ] E2E tests for critical user flows
• [ ] Performance/load testing if needed

Documentation Tasks

• [ ] API documentation
• [ ] User-facing docs
• [ ] Internal architecture notes
• [ ] Migration guides (if applicable)

Create Timeline

• [ ] Day 1-2: [Tasks]
• [ ] Day 3-4: [Tasks]
• [ ] Day 5+: [Tasks]
• [ ] Buffer: Reserve 20-30% time for unknowns

---

Phase 6: Success Metrics

Define Success

Quantitative Metrics

• [ ] Adoption: What % of users will use this?
• [ ] Engagement: How often (daily, weekly)?
• [ ] Performance: Latency, uptime, error rate targets
• [ ] Business impact: Revenue, retention, cost savings

Qualitative Metrics

• [ ] User satisfaction: Survey ratings, NPS
• [ ] User feedback: Common praise/complaints
• [ ] Observation: Behavior changes noted

Rollback Criteria

• [ ] Performance degradation: What's unacceptable?
• [ ] Error rates: Threshold for disabling feature
• [ ] User complaints: Volume/severity trigger
• [ ] Business impact: Negative outcomes to watch

---

Post-Session Documentation

Create RFC or Design Doc

• [ ] Title: Clear, descriptive name
• [ ] Summary: 2-3 sentences
• [ ] Problem statement: From exploration phase
• [ ] Proposed solution: Chosen option
• [ ] Alternatives considered: Other options + why rejected
• [ ] Implementation plan: Timeline and tasks
• [ ] Success metrics: How we'll measure
• [ ] Risks: What could go wrong
• [ ] Open questions: What's still TBD

Share with Team

• [ ] Post RFC in team channel (Slack, Discord, etc.)
• [ ] Tag relevant stakeholders for review
• [ ] Set feedback deadline (24-48 hours)
• [ ] Schedule sync meeting if needed (complex changes)

Create Actionable Issues

• [ ] Create GitHub/Jira issue with implementation plan
• [ ] Tag with appropriate labels (feature, backend, frontend, etc.)
• [ ] Assign to sprint/milestone
• [ ] Link to RFC/design doc

---

Session Anti-Patterns to Avoid

Common Pitfalls

• [ ] ❌ Jumping to solutions - Explore the problem first (5W1H)
• [ ] ❌ Analysis paralysis - Aim for 3 options, not 10
• [ ] ❌ Ignoring constraints - Be realistic about time/resources
• [ ] ❌ Missing user voice - Ground in real user needs
• [ ] ❌ Vague estimates - "A few days" → "3-5 days"
• [ ] ❌ Skipping tradeoffs - Every solution has pros AND cons
• [ ] ❌ No decision - End with clear recommendation
• [ ] ❌ No next steps - Create issues/tasks immediately

---

Example Session Flow (30-45 minutes)

Minute 0-10: Exploration

• Ask 5W1H questions
• Dig 2-3 levels deep
• Document user context

Minute 10-15: Constraints

• List technical limitations
• Check time/resource budget
• Identify dependencies

Minute 15-30: Solution Generation

• Create 3 options (MVP, Standard, Advanced)
• Document pros/cons for each
• Write example user flows

Minute 30-40: Evaluation

• Score options against criteria
• Make recommendation
• Acknowledge tradeoffs

Minute 40-45: Next Steps

• Create implementation task list
• Define success metrics
• Assign follow-up actions

---

Template Prompts

Starting a Session

"I have an idea: [rough idea]. Can you help me refine this into an actionable plan?"

When Stuck

"We've explored [option A] and [option B]. What other approaches should we consider?"

When Overcomplicating

"This feels complex. What's the simplest version that solves the core problem?"

When Missing Context

"What assumptions are we making? What don't we know yet?"

Ending the Session

"Based on our discussion, what should we build first?"

---

Remember: Great brainstorming is 70% asking questions, 20% generating options, 10% deciding. Resist the urge to code immediately—clarity saves days of rework.

Example: OrchestKit Feature Brainstorming Session

Feature Idea: Real-Time Collaborative Analysis Review

Initial Request: "We should let multiple users review analysis results together, maybe like Google Docs but for technical content analysis."

---

Phase 1: Clarifying Questions (Socratic Exploration)

Agent: Let's explore this idea through some foundational questions:

1. Who is the primary user?

• Solo developers reviewing their own analyses?
• Teams reviewing analyses before implementation?
• Educational settings (instructor + students)?

2. What problem does this solve?

• Is asynchronous commenting insufficient?
• Do users need to see changes in real-time?
• Is this about reducing review cycles or improving quality?

3. When would users collaborate?

• During initial analysis (watching agents work)?
• After completion (reviewing artifacts)?
• During implementation (referencing analysis)?

4. How does this fit OrchestKit's core value?

• OrchestKit generates implementation guides from technical content
• Is collaboration about improving analysis inputs or outputs?
• Does this enhance learning or just convenience?

---

Phase 2: User Responses & Refinement

User: "Mainly teams reviewing analyses after completion. Current workflow has devs analyzing content separately, then discussing in Slack. We lose context switching between OrchestKit and Slack."

Agent: Excellent context! This narrows scope significantly. Let's refine:

Refined Problem Statement: Teams using OrchestKit lose context when discussing analyses outside the platform, leading to fragmented feedback and slower implementation decisions.

Next-Level Questions:

1. What specific actions do teams take during review?

• Highlighting relevant chunks?
• Questioning agent findings?
• Proposing implementation changes?
• Voting on next steps?

2. What information needs to be synchronized?

• Cursor positions? (high complexity)
• Comments/annotations? (medium complexity)
• Presence indicators (who's viewing)? (low complexity)

3. What's the minimum viable collaboration?

• Asynchronous comments with @mentions?
• Shared cursors and highlights?
• Video chat integration?

---

Phase 3: Constraint Analysis

Agent: Let's check this against OrchestKit's architecture:

Technical Constraints:

• ✅ Backend: FastAPI supports WebSockets (for real-time)
• ✅ Frontend: React 19 supports Suspense (for optimistic UI)
• ⚠️ Database: PostgreSQL needs LISTEN/NOTIFY for pub/sub
• ❌ No existing auth system for multi-user (planned but not built)

Resource Constraints:

• Current sprint: 2 weeks remaining
• Team: 2 developers (backend + frontend)
• Dependencies: Auth system (3-5 days), WebSocket infrastructure (2-3 days)

User Experience Constraints:

• Can't require all reviewers to be online simultaneously
• Must work for distributed teams (async-first)
• Mobile support not critical (desktop-focused workflow)

---

Phase 4: Solution Variants

Agent: Based on constraints, here are 3 implementation levels:

Option A: Async Comments (MVP - 3 days)

What:

• Thread-based comments on analysis sections
• @mentions for notifications
• Email digest of new comments

Pros:

• Builds on existing artifact display
• No WebSocket complexity
• Works async (global teams)

Cons:

• Not "real-time" (user's original ask)
• Still requires context switching to email

Example User Flow: 1. Alice completes analysis of "RAG Pipeline Best Practices" 2. Shares link with team in Slack 3. Bob adds comment: "Security analysis missing OWASP checks @alice" 4. Alice gets email notification with context snippet 5. Replies inline, updates analysis

---

Option B: Presence + Live Comments (Standard - 7 days)

What:

• All of Option A, plus:
• Show who's viewing the analysis (presence indicators)
• Live comment updates via WebSockets
• Typing indicators

Pros:

• Feels collaborative (see teammates' activity)
• Reduces duplicate comments (see others typing)
• Better for synchronous review sessions

Cons:

• Requires WebSocket infrastructure
• More complex state management
• Needs connection health monitoring

Example User Flow: 1. Alice shares analysis link in Slack: "Reviewing RAG pipeline analysis now" 2. Bob clicks link, sees "Alice is viewing" badge 3. Bob starts typing comment on Security section 4. Alice sees "Bob is typing in Security Analysis..." 5. Alice waits for Bob's comment before adding her own

---

Option C: Full Collaborative Editing (Advanced - 14 days)

What:

• All of Option B, plus:
• Collaborative editing of artifact summaries
• Shared cursors and highlights
• Conflict resolution (CRDT or OT)

Pros:

• True Google Docs experience
• Can refine analyses together
• Reduces "review → edit → re-review" cycles

Cons:

• High complexity (CRDT libraries)
• Requires authentication/authorization
• May confuse "agent-generated" vs "human-edited" content

Example User Flow: 1. Alice and Bob review analysis in real-time 2. Both see shared cursors as they scroll 3. Bob highlights "Missing: error handling patterns" 4. Alice immediately edits artifact to add error handling section 5. Both approve finalized artifact

---

Phase 5: Decision Framework

Agent: Let's evaluate against OrchestKit's goals:

Recommendation: Option B (Presence + Live Comments)

Rationale: 1. Addresses core problem: Eliminates context switching while maintaining async-first design 2. Balances complexity: WebSockets are proven tech, no CRDT complexity 3. Fits sprint: 7 days leaves buffer for testing 4. Enables future: Presence infrastructure unlocks Option C later

---

Phase 6: Implementation Plan

Agent: Here's the breakdown:

Backend (3 days)

Day 1: WebSocket Infrastructure

• [ ] Add fastapi-websockets dependency
• [ ] Create ConnectionManager for presence tracking
• [ ] Add /ws/analysis/{id}/presence endpoint
• [ ] Redis pub/sub for multi-server scaling

Day 2: Comment System

• [ ] Database schema: comments table (analysis_id, user_id, section_id, content, created_at)
• [ ] REST endpoints: POST/GET/PATCH/DELETE /api/v1/analyses/{id}/comments
• [ ] WebSocket events: comment.created, comment.updated, comment.deleted

Day 3: Presence Logic

• [ ] Track active connections per analysis
• [ ] Broadcast join/leave events
• [ ] Typing indicators (debounced 1s)
• [ ] Heartbeat ping/pong for connection health

Frontend (3 days)

Day 1: WebSocket Client

• [ ] Create useAnalysisPresence hook
• [ ] Handle reconnection logic (exponential backoff)
• [ ] Show connection status indicator

Day 2: Comments UI

• [ ] Comment thread component (nested replies)
• [ ] Markdown support for code snippets
• [ ] @mention autocomplete
• [ ] Optimistic updates (show immediately, sync later)

Day 3: Presence UI

• [ ] Avatar badges for active viewers
• [ ] Typing indicators in comment sections
• [ ] Toast notifications for new comments

Testing (1 day)

• [ ] Unit tests: Comment CRUD operations
• [ ] Integration tests: WebSocket message flow
• [ ] E2E tests: Multi-user collaboration scenario
• [ ] Load test: 50 concurrent users on one analysis

---

Phase 7: Success Metrics

Agent: How will we know this succeeded?

Quantitative Metrics:

• Adoption: 40%+ of team analyses have comments within 1 week
• Engagement: Average 3+ comments per analysis
• Speed: 30% reduction in time from analysis → implementation decision
• Reliability: 99.9% WebSocket uptime, <100ms message latency

Qualitative Metrics:

• Survey: "Collaboration features improved our review process" (4/5 rating)
• Observation: Teams stop using Slack for analysis discussions
• Feedback: "Presence indicators helped us avoid duplicate comments"

Rollback Criteria:

• WebSocket connection failures >5%
• User complaints about "too many notifications"
• Performance degradation (page load >2s with active presence)

---

Key Takeaways

Brainstorming Process Applied: 1. ✅ Socratic questioning transformed vague idea into specific problem 2. ✅ Constraint analysis eliminated unrealistic options early 3. ✅ Multiple variants provided choice with clear tradeoffs 4. ✅ Decision framework aligned with project values 5. ✅ Implementation plan made idea actionable

Outcome: Went from "Google Docs for technical analysis" → "Async-first collaborative comments with real-time presence" in ~20 minutes of structured exploration.

Next Steps:

• [ ] Share this RFC with team for feedback
• [ ] Create GitHub issue with Option B implementation plan
• [ ] Spike: Test Redis pub/sub with FastAPI WebSockets (2 hours)

Common Brainstorming Pitfalls

Avoid these mistakes during brainstorming sessions.

Pitfall 1: Information Overload

❌ BAD:
"Before we start, I need to know:
1. What's your tech stack?
2. How many users?
3. What's the budget?
..."

✅ GOOD:
"What problem does this solve for your users?"
[Wait for answer, then ask next question]

Why: Asking many questions at once prevents conversation flow.

Pitfall 2: Single Approach

❌ BAD:
"Here's the solution: Use Redis for caching..."

✅ GOOD:
"I see three approaches:
1. Redis (fast, but adds infrastructure)
2. In-memory (simple, but doesn't scale)
3. Database cache (integrated, but slower)
Which trade-offs matter most?"

Why: Single approach suggests you haven't explored alternatives.

Pitfall 3: Over-Engineering

❌ BAD:
"Let's use microservices, Kubernetes, Redis, Kafka..."

✅ GOOD:
"For 100 users/day, a monolith with PostgreSQL is sufficient.
We can split services later if needed."

Why: YAGNI. Start simple, scale when necessary.

Pitfall 4: Ignoring Existing Code

❌ BAD:
"Let's rebuild with completely different architecture..."

✅ GOOD:
[Read existing code first]
"I see you're using Express + PostgreSQL.
Let's extend that pattern..."

Why: Consistency > novelty. Use existing patterns unless compelling reason to change.

Pitfall 5: Premature Convergence

❌ BAD:
[After generating 3 ideas]
"Option B is clearly best, let's go with that."

✅ GOOD:
[Generate 10+ ideas first]
[Fast-check feasibility]
[Rate systematically]
"After evaluating all options, Option B scores highest because..."

Why: Filtering too early misses potentially better alternatives.

Pitfall 6: Designing Without Considering Testability

❌ BAD:
"Beautiful hexagonal architecture with 12 ports and adapters!"
[Requires 50 mocks to test a single use case]

✅ GOOD:
"Each module has clear boundaries.
Unit tests need 0-2 mocks. Integration tests run against
docker-compose services. E2E covers the 3 critical paths."

Why: A design that scores 10/10 on architecture but 2/10 on testability will slow down every future change. Score testability during evaluation (see evaluation-rubric.md) and prefer designs with clear testing boundaries.

Pitfall 7: Skipping Devil's Advocate

❌ BAD:
"This approach looks great, let's implement it!"

✅ GOOD:
"Let me challenge this approach:
- What assumptions are we making?
- How could this fail?
- What's the maintenance burden?"

Why: Unchallenged ideas often have hidden flaws.

Devil's Advocate Prompts

Challenge templates for assumption testing. Find hidden flaws before implementation.

Hidden Assumptions

• "What if the core assumption that [X] is wrong?"
• "This assumes [dependency] will always be available. What if it fails?"
• "We're assuming users will [behavior]. What evidence supports this?"

Failure Modes

• "What if this fails because the data volume exceeds expectations?"
• "The hidden flaw in this approach is [single point of failure]."
• "At 10x scale, what breaks first?"
• "What's the worst-case recovery scenario?"

Simpler Alternatives

• "Could we solve 80% of this with a much simpler solution?"
• "What if we just used [existing tool] instead of building this?"
• "Is this complexity justified by the requirements?"

Maintenance Burden

• "In 2 years, will anyone understand why this was built this way?"
• "What technical debt does this create?"
• "How many dependencies are we adding?"

Scaling Concerns

• "What happens when [resource] becomes the bottleneck?"
• "This works for 100 users. Does it work for 100,000?"
• "What's the migration path when this outgrows itself?"

Security Holes

• "What's the attack surface we're introducing?"
• "If an attacker had access to [component], what could they do?"
• "Are we trusting user input anywhere we shouldn't?"

Testability Challenges

• "How would you test the critical path without mocking everything?"
• "What happens when the external dependency is unavailable during testing?"
• "Show me the integration test — can it run in CI without special infrastructure?"
• "How many mocks/stubs does a single test need? If more than 3, the design has coupling issues."
• "Can a new developer write a test for this without reading the entire codebase?"

Challenge Template

DEVIL'S ADVOCATE for: [idea name]

1. ASSUMPTIONS: What must be true for this to work?
2. FAILURE: How could this fail catastrophically?
3. SIMPLER: What's the 10x simpler alternative?
4. SCALE: What breaks at 10x load?
5. TESTABILITY: How do you test this? What's the mock surface?
6. MAINTENANCE: What's the 2-year cost?

Severity: [Critical|High|Medium|Low] per concern

Divergent Techniques

Generate 10+ ideas without filtering. Quantity over quality in early phases prevents premature convergence.

Techniques

SCAMPER

Modify existing solutions systematically:

• Substitute: What can replace a component?
• Combine: Merge two approaches?
• Adapt: Borrow from another domain?
• Modify: Change scale, shape, or form?
• Put to other use: Repurpose existing code?
• Eliminate: Remove complexity?
• Rearrange: Change sequence or flow?

Use when: Improving existing features or patterns.

Mind Mapping

Radiate from central topic, no filtering: 1. Write topic in center 2. Branch primary themes (tech, UX, data, security) 3. Sub-branch specific ideas per theme 4. Connect related branches

Use when: Exploring unfamiliar problem spaces.

Reverse Brainstorming

Ask "How could we make this fail?" then invert: 1. List ways to guarantee failure 2. Flip each into success criteria 3. Generate ideas that achieve those criteria

Use when: Risk-heavy decisions, security features.

Round-Robin

Each agent contributes sequentially: 1. Agent A proposes approach 2. Agent B builds on or pivots from A 3. Agent C adds new dimension 4. Repeat until 10+ ideas

Use when: Multi-domain topics needing diverse expertise.

Selection Guide

Effort-Aware Phase Scaling

CC 2.1.76 introduced /effort levels; xhigh was added in CC 2.1.111 (Opus 4.7); since CC 2.1.154 Opus 4.8 defaults to high and reserves xhigh for the hardest tasks. The effort-aware context budgeting hook (global) detects effort level automatically — adapt the phase plan accordingly.

# Effort detection — the global hook injects effort level, but also check:
# If user said "quick brainstorm" or "just ideas" → treat as low effort
# If user selected "Quick ideation" in Step 0a → treat as low effort regardless of /effort

Override: Explicit user selection in STEP 0a (e.g., "Open exploration") overrides /effort downscaling.

Evaluation Rubric

Rate each idea 0-10 across seven dimensions with weighted scoring.

Dimensions

Scoring Scale

Testability Scoring Guide

Simplicity Scoring Guide

"A small improvement that adds ugly complexity is not worth it. Removing something and getting equal or better results is a great outcome — that's a simplification win." — autoresearch design principle

Composite Formula

composite = impact * 0.15 + (10 - effort) * 0.20 + (10 - risk) * 0.15 + alignment * 0.20 + testability * 0.15 + simplicity * 0.10 + innovation * 0.05

Devil's Advocate Adjustment

Example

Note: Session-only now wins over JWT+Redis because its high Simplicity score (9) rewards removing complexity. This encodes the autoresearch principle: simpler solutions that achieve similar results are preferred.

Example Session: Authentication Storage Design

This complete example demonstrates the brainstorming workflow for designing an authentication storage solution.

Context

User request: "I need to add authentication to my web app but I'm not sure how to store the auth data."

Phase 1: Understanding

Question 1 (Clarification)

Using AskUserQuestion tool:

Question: "Where should the authentication data be stored?"
Header: "Storage Location"
Options:
  - "Session storage"
    Description: Clears on tab close, more secure, no cross-tab access
  - "Local storage"
    Description: Persists across sessions, more convenient, cross-tab access
  - "Cookies"
    Description: Works with SSR, compatible with older browsers, sent with requests
  - "Server-side session"
    Description: Most secure, requires backend session store, scales with infrastructure

User selects: "Cookies" (needs SSR compatibility)

Question 2 (Constraints)

Using AskUserQuestion tool:

Question: "What's the primary security concern for this application?"
Header: "Security Level"
Options:
  - "Basic protection"
    Description: Standard security, public-facing app, low-risk data
  - "Enhanced security"
    Description: Financial data, user PII, requires CSRF protection
  - "Maximum security"
    Description: Healthcare/banking, requires encryption, audit logs

User selects: "Enhanced security" (handling user PII)

Question 3 (Success Criteria)

Open-ended: "What would successful authentication look like for your users?"

User response: "Users stay logged in for 7 days, can log out from any device, get notified of new logins"

Phase 1 Summary

• Storage: Cookies (for SSR compatibility)
• Security: Enhanced (CSRF protection, PII handling)
• Requirements: 7-day sessions, multi-device logout, login notifications

Phase 2: Exploration

Proposed Approaches

Using AskUserQuestion tool:

Question: "Which authentication architecture should we use?"
Header: "Auth Architecture"
Options:
  - "JWT in httpOnly cookie"
    Description: Stateless, scales easily, can't revoke tokens early, 7-day expiry matches requirement
  - "Session ID with Redis"
    Description: Stateful, instant revocation, requires Redis infrastructure, supports multi-device logout
  - "JWT + Refresh Token"
    Description: Balanced, short-lived JWT (15min) + long refresh token, instant revocation of refresh, more complex

Trade-off Discussion:

User selects: "Session ID with Redis" (needs instant revocation for multi-device logout)

Phase 3: Design Presentation

Section 1: Architecture Overview

Present:

Authentication Flow:
1. User logs in → Backend validates credentials
2. Backend creates session in Redis (7-day TTL)
3. Backend returns httpOnly cookie with session ID
4. Client sends cookie with each request
5. Backend validates session ID against Redis
6. On logout → Delete session from Redis

Session Structure in Redis:
{
  "user_id": "123",
  "created_at": "2024-01-15T10:30:00Z",
  "device_info": "Chrome/Mac",
  "last_active": "2024-01-15T10:35:00Z"
}

Validate: "Does this architecture handle your multi-device logout requirement?"

User feedback: "Yes, but how do we notify about new logins?"

Section 2: Multi-Device Management

Present:

Session Management:
- Store all active sessions per user in Redis set: `user:123:sessions`
- Each login creates new session, adds to set
- On login, check if >3 sessions → send email notification
- Logout from one device → remove that session ID
- "Logout all devices" → delete entire session set

Notification Logic:
- On new session creation:
  1. Check if user has existing sessions
  2. If yes → trigger notification email/push
  3. Include: device info, IP, timestamp, "Not you?" link

Validate: "Does this notification approach work for your use case?"

User feedback: "Perfect, let's proceed"

Section 3: Security Implementation

Present:

Security Measures:
1. httpOnly cookies (prevent XSS theft)
2. Secure flag (HTTPS only)
3. SameSite=Lax (CSRF protection)
4. 7-day max age, sliding window on activity
5. CSRF token in separate header for mutations
6. Rate limiting on login endpoint (5 attempts/15min)

Cookie Setup:
Set-Cookie: session_id=abc123;
  HttpOnly;
  Secure;
  SameSite=Lax;
  Max-Age=604800;
  Path=/

Validate: "Does this meet your enhanced security requirement?"

User feedback: "Yes, looks good"

Final Design Summary

Storage: Session ID in httpOnly cookie Backend: Redis for session storage (7-day TTL) Multi-device: Session set per user, email notifications Security: httpOnly + Secure + SameSite + CSRF tokens Logout: Single-device and all-devices support

Implementation Notes

• Use Redis with persistence (AOF or RDB)
• Consider session cleanup job for expired entries
• Monitor Redis memory usage
• Log all authentication events for audit

Key Takeaways

1. Cookie choice was validated early (Phase 1) → No rework needed 2. Trade-offs were explicit (Phase 2) → User made informed choice 3. Design was validated incrementally (Phase 3) → Caught notification requirement early 4. Security was specific → Actual cookie configuration provided

This prevented a common pitfall: building JWT auth and realizing multi-device logout is impossible without a backend state store.

Example Session: Real-Time Dashboard Design

This complete example demonstrates brainstorming workflow for a real-time analytics dashboard.

Context

User request: "Build me a real-time dashboard to track user activity on my SaaS app."

Phase 1: Understanding

Question 1 (Purpose)

Open-ended: "What specific user activities do you want to track on this dashboard?"

User response: "Logins, API calls, errors, active users right now."

Question 2 (Constraints)

Using AskUserQuestion tool:

Question: "What's your data volume and update frequency?"
Header: "Scale Requirements"
Options:
  - "Low volume"
    Description: <1000 users, updates every 5-10 seconds acceptable
  - "Medium volume"
    Description: 1k-50k users, need 1-2 second updates
  - "High volume"
    Description: >50k users, need sub-second updates, streaming data

User selects: "Medium volume" (10k users, 2-second updates okay)

Question 3 (Success Criteria)

Open-ended: "What decisions will you make based on this dashboard?"

User response: "Spot issues quickly (error spikes), see if marketing campaigns are working (login spikes), monitor API health."

Phase 1 Summary

• Metrics: Logins, API calls, errors, active users
• Scale: 10k users, 2-second update frequency
• Goal: Issue detection, campaign tracking, API health monitoring

Phase 2: Exploration

Proposed Approaches

Using AskUserQuestion tool:

Question: "Which data pipeline architecture should we use?"
Header: "Pipeline Design"
Options:
  - "Database polling"
    Description: Query DB every 2 seconds, simple setup, may strain DB at scale
  - "Server-Sent Events (SSE)"
    Description: Push updates from server, real-time, keeps connections open
  - "WebSockets with aggregation"
    Description: Bidirectional real-time, more complex, supports filters

Trade-off Analysis:

Additional consideration: "For 10k users with 2-second updates, SSE is optimal. WebSockets are overkill since you don't need bidirectional communication."

User selects: "Server-Sent Events" (fits requirements, reasonable complexity)

Phase 3: Design Presentation

Section 1: Data Flow Architecture

Present:

Data Pipeline:
1. Application events → Message queue (Redis Streams)
2. Aggregation worker → Process events every 1 second
3. Aggregate results → Store in Redis cache (2-second TTL)
4. SSE endpoint → Push aggregated data to dashboard
5. Dashboard → Render charts with new data

Components:
- Event Producer: Application server (logs events to Redis Stream)
- Aggregation Worker: Node.js worker (consumes stream, calculates metrics)
- Cache Layer: Redis (stores last 60 seconds of aggregated data)
- SSE Server: Express.js endpoint (/api/dashboard/stream)
- Frontend: React + Chart.js (renders real-time updates)

Validate: "Does this flow make sense for tracking your user activities?"

User feedback: "Yes, but what happens if dashboard disconnects?"

Section 2: Connection Handling

Present:

SSE Connection Management:
1. On disconnect → Client auto-reconnects with exponential backoff
2. On reconnect → Server sends last 60s of cached data (catch-up)
3. Heartbeat every 30s → Keep connection alive
4. If aggregation worker fails → Fallback to DB polling (degraded mode)

Reconnection Logic:
- 1st attempt: Immediate
- 2nd attempt: 1 second delay
- 3rd attempt: 2 second delay
- Max delay: 30 seconds
- Give up after: 5 minutes (show "Reconnecting..." UI)

Catch-up Strategy:
- Server tracks last event ID per client
- On reconnect, client sends: Last-Event-ID header
- Server replays events since that ID (max 60s buffer)

Validate: "Does this handle disconnections appropriately?"

User feedback: "Great, what about the actual metrics?"

Section 3: Metrics & Visualization

Present:

Dashboard Metrics (auto-updating every 2s):

1. Active Users (right now)
   - Metric: Count of unique user_ids in last 5 minutes
   - Visualization: Large number with sparkline
   - Alert: Red if drops >50% from baseline

2. Logins (per minute)
   - Metric: Count of login events in rolling 1-minute window
   - Visualization: Line chart (last 30 minutes)
   - Alert: Green spike if >2x baseline (campaign success)

3. API Calls (per second)
   - Metric: Count of API events per second
   - Visualization: Area chart (last 10 minutes)
   - Alert: Yellow if >80% of rate limit

4. Error Rate (percentage)
   - Metric: (Error count / Total requests) * 100
   - Visualization: Line chart with threshold markers
   - Alert: Red if >5%

Data Retention:
- Real-time view: Last 60 minutes (Redis)
- Historical: Last 30 days (TimescaleDB)
- Switch view: Toggle between "Last hour" and "Today"

Validate: "Do these metrics and visualizations match what you need?"

User feedback: "Perfect, this covers everything"

Final Design Summary

Architecture: Redis Streams → Aggregation Worker → Redis Cache → SSE → React Dashboard

Metrics:

• Active users (5-min window)
• Logins per minute (30-min chart)
• API calls per second (10-min chart)
• Error rate percentage (with alerts)

Resilience:

• Auto-reconnect with backoff
• 60-second event replay on reconnect
• Fallback to polling if worker fails
• Heartbeat keep-alive

Data Storage:

• Real-time: Redis (60 minutes)
• Historical: TimescaleDB (30 days)

Implementation Priorities

1. Phase 1: Basic SSE endpoint + 4 metrics (2-3 days) 2. Phase 2: Reconnection logic + error handling (1 day) 3. Phase 3: Historical view + TimescaleDB (2 days) 4. Phase 4: Alerting system (optional, 1 day)

Key Takeaways

1. Chose SSE over WebSockets → Simpler, fits requirements (no bidirectional needed) 2. Redis Streams for events → Natural fit for streaming data 3. 60-second replay buffer → Handles disconnections gracefully 4. Degraded mode fallback → System stays functional even if worker fails 5. Clear alert thresholds → Makes dashboard actionable, not just informational

What Was Avoided

• Mistake 1: Starting with WebSockets → Would be overengineered
• Mistake 2: Polling database directly → Would strain DB at 10k users
• Mistake 3: No reconnection strategy → Poor user experience on network issues
• Mistake 4: Storing everything in memory → Would lose data on restart

This design validates requirements early and makes explicit trade-offs before implementation.

Iterative Optimization Mode (autoresearch-style)

Selected when the user picks "Iterative optimization" in STEP 0a. Skips Phases 2-6 of the standard brainstorm flow and enters a metric-driven optimization loop that runs until the user interrupts.

Required: one command that produces a metric, plus an extraction rule for that metric.

1. Ask for metric definition

AskUserQuestion(questions=[
  {"question": "What command produces the metric?",
   "header": "Metric command",
   "options": [
     {"label": "npm run benchmark", "description": "Node.js benchmark suite"},
     {"label": "pytest --tb=short", "description": "Python test suite"},
     {"label": "lighthouse --output=json", "description": "Web performance score"},
     {"label": "I'll type my own", "description": "Custom command"}
   ]},
  {"question": "How to extract the metric number?",
   "header": "Metric extraction",
   "options": [
     {"label": "grep from stdout", "description": "e.g. grep 'score:' output.log"},
     {"label": "JSON field", "description": "e.g. jq '.score' result.json"},
     {"label": "Exit code", "description": "0 = pass, non-zero = fail"},
     {"label": "I'll specify", "description": "Custom extraction"}
   ]},
  {"question": "Direction?",
   "header": "Optimization direction",
   "options": [
     {"label": "Lower is better", "description": "Latency, bundle size, error rate"},
     {"label": "Higher is better", "description": "Score, throughput, coverage"}
   ]}
])

2. Establish baseline

Bash(command="{metric_command} > .claude/experiments/baseline.log 2>&1")
baseline = extract_metric(".claude/experiments/baseline.log")
append_to_journal(baseline, "keep", "-", current_commit, "baseline")

3. Optimization loop

See ${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/experiment-journal.md for journal format.

# LOOP (until user interrupts or trajectory == "stuck" for 5+ iterations):
#   a. Generate ONE idea (quick ideation, single agent)
#   b. Implement in worktree: Agent(isolation="worktree", ...)
#   c. Run metric command in worktree
#   d. Compare to previous best
#   e. If improved: merge worktree back, log "keep"
#   f. If not: discard worktree, log "discard"
#   g. Check trajectory — if "stuck" for 5+, try radical changes
#   h. NEVER STOP — continue until user interrupts

MCP Probe + Resume Check

Run this once at skill start to detect available MCP servers and resume any prior session that crashed mid-phase.

Probe MCP servers

ToolSearch(query="select:mcp__memory__search_nodes")  # CC < 2.1.121 fallback (alwaysLoad in .mcp.json otherwise)
ToolSearch(query="select:mcp__sequential-thinking__sequentialthinking")

Detailed detection patterns: Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/mcp-detection.md").

Store capabilities

Write(".claude/chain/capabilities.json", {
  "memory": probe_memory.found,
  "sequential_thinking": probe_st.found,
  "skill": "brainstorm",
  "timestamp": now()
})

Resume from prior crash

state = Read(".claude/chain/state.json")  # may not exist
if state.skill == "brainstorm" and state.status == "in_progress":
    # Skip completed phases, resume from state.current_phase
    last_handoff = Read(f".claude/chain/{state.last_handoff}")

Phase Handoff Files

Each phase writes a handoff file consumed by the next phase:

Brainstorming Phase Workflow

Detailed instructions for the 7-phase brainstorming process.

Phase 0: Project Context Discovery & Agent Selection

Goal: Detect project tier, then identify topic domain and select relevant agents.

Step 0: Detect Project Tier

Before analyzing the topic, classify the project into one of 6 tiers (see scope-appropriate-architecture skill). This tier becomes the complexity ceiling for all ideas generated in later phases.

Tier impacts on brainstorming:

• Tier 1-2 (Interview/Hackathon): Skip complex patterns entirely. Ideas should focus on simplicity and directness. Limit to 5 ideas max.
• Tier 3 (MVP): Prefer managed services and monolith patterns. Flag any microservice or event-driven idea as OVERKILL.
• Tier 4-5 (Growth/Enterprise): Full brainstorming with all patterns available.
• Tier 6 (Open Source): Focus on API design, extensibility, and backwards compatibility.

Include tier context in EVERY agent prompt:

PROJECT TIER: {tier_name} (Tier {N})
COMPLEXITY CEILING: {ceiling_description}
Do NOT suggest patterns marked OVERKILL for this tier in the scope-appropriate-architecture matrix.

Step 1: Classify Topic Keywords

Step 2: Select Agents

Always include: workflow-architect (system design perspective) + test-generator (testability assessment)

---

Phase 1: Memory + Codebase Context

# Check knowledge graph for past decisions
mcp__memory__search_nodes(query="{topic}")

# Quick codebase scan (PARALLEL)
Grep(pattern="{keywords}", output_mode="files_with_matches")
Glob(pattern="**/*{topic}*")

---

Phase 2: Divergent Exploration

CRITICAL: Generate 10+ ideas WITHOUT filtering. Quantity over quality.

# Launch ALL agents in ONE message
Agent(subagent_type="ork:workflow-architect", prompt="...", run_in_background=True)
Agent(subagent_type="ork:security-auditor", prompt="...", run_in_background=True)
Agent(subagent_type="ork:backend-system-architect", prompt="...", run_in_background=True)

Collecting results (CC 2.1.76): When background agents complete, check for [PARTIAL RESULT] tag in the response. Partial results contain usable ideas but may be incomplete — include them in the idea pool but flag them for extra scrutiny in Phase 3.

Divergent mindset instruction for agents:

PROJECT TIER: {tier_name} (Tier {N})
COMPLEXITY CEILING: {ceiling_description}

DIVERGENT MODE: Generate as many approaches as possible.
- Do NOT filter or critique ideas in this phase
- Include unconventional, "crazy" approaches
- Target: At least 3-4 distinct approaches
- CONSTRAINT: Do NOT suggest patterns marked OVERKILL for Tier {N}

---

Phase 3: Keep / Discard / Crash Gate

Binary viability gate inspired by autoresearch. No scoring — just a fast yes/no/unknown per idea. Save detailed scoring for Phase 4.

Time budget: 10 seconds per idea. For each idea from Phase 2, answer ONE question: "If we built this, would it work?"

Discard reasons (tag each discard for experiment journal):

• overkill — exceeds project tier complexity ceiling
• infeasible — requires technology/resources not available
• duplicate — too similar to a previously discarded approach
• untestable — no seam for testing core logic without real services

Experiment journal check (if .claude/experiments/brainstorm-{topic}.tsv exists):

# Pre-filter: skip ideas similar to previous 'discard' entries
prior = Read(f".claude/experiments/brainstorm-{topic_slug}.tsv")
# If a similar idea was discarded before, auto-discard with reason 'duplicate'

Output format:

Phase 3 Gate Results (N ideas → M survivors)
  ✓ keep    — JWT + Redis sessions
  ✓ keep    — Session-only with signed cookies
  ✗ discard — Custom token protocol (infeasible: reinvents OAuth)
  ? crash   — Blockchain auth (can't assess without more context)

---

Phase 4: Evaluation & Rating

See evaluation-rubric.md for scoring criteria (7 dimensions including testability and simplicity). See devils-advocate-prompts.md for challenge templates (including testing challenges).

Composite Score Formula

composite = (
    impact * 0.15 +
    (10 - effort) * 0.20 +
    (10 - risk) * 0.15 +
    alignment * 0.20 +
    testability * 0.15 +
    simplicity * 0.10 +
    innovation * 0.05
)

# Devil's advocate adjustment
if critical_concerns > 0:
    composite *= 0.7  # 30% penalty

See evaluation-rubric.md for the Simplicity scoring guide — scores net complexity change, not implementation difficulty. Removing code for equal results scores 9-10.

---

Phase 5: Synthesis

1. Filter to top 2-3 approaches 2. Merge perspectives from all agents 3. Build comprehensive trade-off table 4. Add test strategy per approach (see below) 5. Present to user with scores

Test Strategy Per Approach

For each top approach, include:

This ensures the chosen design comes with a concrete testing plan, not just architecture.

AskUserQuestion(questions=[{
  "question": "Which approach fits your needs?",
  "header": "Design Options",
  "options": [
    {"label": "Option A (7.8/10)", "description": "..."},
    {"label": "Option B (7.5/10)", "description": "..."}
  ]
}])

---

Phase 6: Design Presentation

Present in 200-300 word sections: 1. Architecture Overview 2. Component Details 3. Data Flow 4. Error Handling 5. Security Considerations 6. Test Plan (test types, mock boundaries, infrastructure requirements) 7. Implementation Priorities

After each section: "Does this look right so far?"

# Store decision in memory
mcp__memory__create_entities(entities=[{
  "name": "{topic}-design-decision",
  "entityType": "Decision",
  "observations": ["Chose {approach} because {rationale}"]
}])

Socratic Questioning Templates

Use these templates to guide requirements discovery through structured questioning.

Purpose Discovery

Goal: Understand the "why" behind the feature.

• "What problem does this solve for your users?"
• "What happens if we don't build this?"
• "How will success be measured?"
• "Who is the primary user of this feature?"
• "What's the most important outcome?"

Constraint Identification

Goal: Uncover limitations and requirements.

• "Are there performance requirements? (e.g., must load in < 2s)"
• "What's the expected scale? (users, data volume, requests/sec)"
• "Are there compliance requirements? (GDPR, HIPAA, SOC2)"
• "What's the timeline/budget constraint?"
• "What existing systems must this integrate with?"

Trade-Off Exploration

Goal: Make implicit preferences explicit.

• "Would you prefer faster development or better performance?"
• "Is flexibility more important than simplicity?"
• "Should this be user-friendly or developer-friendly?"
• "Optimize for: build speed, maintainability, or scalability?"
• "What's more critical: feature completeness or time-to-market?"

Alternative Exploration

Goal: Ensure consideration of all viable approaches.

• "What if we didn't build this at all? What's the workaround?"
• "How would [competitor] solve this?"
• "Could we start with a simpler version? What's the MVP?"
• "What if we had unlimited time/budget? What would we add?"
• "What approaches have you already rejected? Why?"

Questioning Best Practices

1. One question at a time - Don't overwhelm with multiple questions 2. Wait for answers - Let conversation flow naturally 3. Follow threads - Ask follow-up questions based on answers 4. Summarize understanding - "So you need X because of Y?"

Rule Categories

1. Idea Quality (quality-gates) — HIGH — 2 rules

Filters out unfeasible or over-complex ideas before synthesis so the evaluation phase only spends tokens on actionable options.

• feasibility-filter.md — Score every idea 1-5 for feasibility during Phase 3; explicitly flag low-feasibility ideas before synthesis
• complexity-ceiling.md — Check every idea against the project's detected tier; flag ideas that exceed team or infra capacity

2. Agent Orchestration (orchestration) — MEDIUM — 1 rule

Caps the number of parallel brainstorm agents to avoid context overload and diminishing returns in the synthesis phase.

• agent-count-limit.md — Never spawn more than 5 parallel brainstorm agents; beyond 5 produces diminishing returns at high token cost

3. Convergence (synthesis) — HIGH — 1 rule

Ensures every brainstorm session ends with ranked, actionable recommendations rather than an unfiltered list of ideas.

• convergence-requirement.md — Brainstorm must converge to ranked options, a trade-off table, and explicit next steps before completing

Agent Count Limit

Never spawn more than 5 parallel brainstorm agents (Task tool or Agent Teams). Beyond 5, each additional agent produces diminishing returns while consuming significant tokens, and the synthesis phase struggles to meaningfully integrate outputs from too many sources.

Problem

The brainstorm skill dynamically selects agents based on topic keywords (Step 0). Without a hard cap, broad topics like "brainstorm full-stack architecture" can trigger 7-8 agents (workflow-architect, backend, frontend, security, data, devops, test-generator, performance). Each agent consumes 40-80K tokens. The synthesis phase then receives 400K+ tokens of input, leading to shallow integration, missed contradictions, and context exhaustion before the design presentation completes.

Token Budget by Agent Count

Rules

• Maximum 5 agents in any brainstorm session (including the mandatory workflow-architect and test-generator)
• This leaves 3 slots for domain-specific agents selected by topic analysis
• If topic analysis suggests more than 5 agents, prioritize by relevance and merge overlapping roles
• Document which agents were excluded and why in 00-topic-analysis.json

Incorrect -- spawning too many agents for a broad topic:

# Topic: "brainstorm e-commerce platform architecture"
# 8 agents spawned -- exceeds limit
TaskCreate(subject="workflow-architect: system design")
TaskCreate(subject="backend-system-architect: API design")
TaskCreate(subject="frontend-ui-developer: UI patterns")
TaskCreate(subject="security-auditor: auth + payments")
TaskCreate(subject="data-pipeline-engineer: analytics")
TaskCreate(subject="devops-engineer: deployment")
TaskCreate(subject="test-generator: test strategy")
TaskCreate(subject="performance-engineer: load testing")
# Synthesis receives 8 agent outputs (~400K tokens)
# Context exhaustion before design presentation completes

Correct -- capping at 5, merging overlapping roles:

# Topic: "brainstorm e-commerce platform architecture"
# 8 candidates identified, capped to 5 by priority
selected = [
    "workflow-architect",          # Always included (system design lead)
    "backend-system-architect",    # Core: API + data model
    "security-auditor",            # Critical: payments require security focus
    "frontend-ui-developer",       # User-facing: checkout + catalog UX
    "test-generator",              # Always included (testability)
]
excluded = [
    {"agent": "data-pipeline-engineer", "reason": "Merged into backend scope"},
    {"agent": "devops-engineer", "reason": "Deferred to implementation phase"},
    {"agent": "performance-engineer", "reason": "Merged into backend scope"},
]

Write(".claude/chain/00-topic-analysis.json", {
    "agents_selected": selected,
    "agents_excluded": excluded,
    "agent_count": len(selected),
    "cap_applied": True
})

for agent in selected:
    TaskCreate(subject=f"{agent}: brainstorm e-commerce architecture")

Exceptions

• If the user explicitly requests more agents ("use all available agents"), allow up to 7 with a warning about token cost and synthesis quality
• Agent Teams mode has a stricter effective limit of 4-5 due to higher per-agent token cost from cross-agent communication

Complexity Ceiling

Every brainstorm idea must be checked against the project's detected tier (Step 0) to ensure it does not exceed the team's capacity. Ideas that exceed the complexity ceiling must be flagged before reaching synthesis.

Problem

Brainstorm agents optimize for technical elegance, not team reality. Without a complexity ceiling, a Tier 2 hackathon project receives recommendations for event-driven microservices, and a Tier 3 MVP gets suggestions requiring dedicated SRE. The user implements the recommendation, then fails because they lack the operational capacity.

Tier Complexity Ceilings

These ceilings align with the scope-appropriate-architecture skill and assess skill complexity scoring (Level 1-5).

Rules

• Detect project tier in Step 0 before generating ideas
• During Phase 3 feasibility check, compare each idea's complexity level against the tier ceiling
• Ideas exceeding the ceiling get "exceeds_ceiling": true with a "ceiling_reason" field
• If ALL generated ideas exceed the ceiling, generate simpler alternatives before proceeding
• Never present a ceiling-exceeding idea as the top recommendation

Incorrect -- recommending enterprise patterns for a hackathon:

# Tier 2 hackathon, but agents suggest enterprise architecture
TaskCreate(
    subject="Brainstorm: API for todo app",
    description="Explore CQRS + event sourcing + saga pattern for todo CRUD"
)
# Agent recommends:
# - Event-driven microservices (Level 5)
# - Saga orchestration (Level 5)
# - Custom API gateway (Level 4)
# User cannot implement any of these in a hackathon

Correct -- constraining recommendations to tier ceiling:

# Tier 2 hackathon detected, ceiling = Level 2
ideas_with_ceiling = []
for idea in raw_ideas:
    complexity = assess_complexity(idea)  # Uses assess skill scoring
    exceeds = complexity.level > TIER_CEILINGS[detected_tier]
    ideas_with_ceiling.append({
        **idea,
        "complexity_level": complexity.level,
        "exceeds_ceiling": exceeds,
        "ceiling_reason": f"Level {complexity.level} exceeds Tier {detected_tier} "
                          f"ceiling of Level {TIER_CEILINGS[detected_tier]}"
                          if exceeds else None
    })

# Filter for synthesis: only ideas within ceiling
viable = [i for i in ideas_with_ceiling if not i["exceeds_ceiling"]]
if not viable:
    # Generate simpler alternatives before proceeding
    TaskCreate(subject="Generate simpler alternatives within Level 2 ceiling")

When to Override

The user can explicitly override the ceiling by saying things like "I want enterprise-grade" or "ignore the project tier." When overriding: 1. Acknowledge the override in the handoff file 2. Warn about operational requirements the higher complexity demands 3. Include a "Simplified alternative" alongside each ceiling-exceeding recommendation

Convergence Requirement

Every brainstorm session must converge from divergent idea generation to a concrete set of actionable recommendations. The final output must include ranked options, a trade-off table, and explicit next steps. A brainstorm that ends with just a list of ideas is a failed brainstorm.

Problem

The divergent phase (Phase 2) is designed to generate 10+ ideas without filtering. Without a strict convergence requirement, the skill can exhaust its context budget during ideation and never reach synthesis. The user receives a wall of possibilities with no guidance on which to pursue, how they compare, or what to do next.

Convergence Checkpoints

Required Final Output Structure

The Phase 6 design presentation must include all of these sections:

1. Recommended approach -- single top pick with justification 2. Runner-up(s) -- 1-2 alternatives with trade-off comparison 3. Trade-off table -- dimensions (cost, complexity, testability, time-to-ship, scalability, maintainability) 4. Next steps -- concrete actions to begin implementation 5. Considered but excluded -- ideas that were explored and why they were dropped

Rules

• Phase 2 has a hard cap: stop after 15 ideas regardless of agent output
• Each phase transition must produce a handoff file before proceeding
• If context is running low (> 70% consumed), skip remaining phases and synthesize from available data
• The final output must ALWAYS include a "Next steps" section with actionable items
• Never end a brainstorm with "Here are some ideas to consider" without ranking and recommending

Incorrect -- ending with an unranked idea list:

# Phase 6 output: just a list, no convergence
TaskUpdate(subject="Brainstorm: caching strategy", status="completed")
# Output to user:
"""
## Ideas Generated
1. Redis caching with TTL
2. CDN edge caching
3. Application-level memoization
4. Database query caching
5. GraphQL persisted queries
6. Service worker caching
7. Varnish reverse proxy

Let me know which approach interests you!
"""
# User has 7 options, no ranking, no trade-offs, no next steps

Correct -- converged to actionable recommendations:

# Phase 6 output: ranked, compared, actionable
Write(".claude/chain/05-synthesis.json", {
    "recommended": "Redis caching with TTL",
    "runner_ups": ["Application-level memoization"],
    "excluded": ["Varnish reverse proxy", "CDN edge caching",
                 "Service worker caching", "GraphQL persisted queries",
                 "Database query caching"],
    "next_steps": [
        "Add redis dependency to docker-compose.yml",
        "Implement cache-aside pattern in UserService",
        "Add cache invalidation on write paths",
        "Write integration test with testcontainers Redis"
    ]
})
# Output includes: Recommendation + trade-off table + Next Steps + Excluded
# User gets a single recommended approach, a runner-up with dimension
# comparison, concrete implementation steps, and rationale for exclusions

Feasibility Filter

Every idea generated in Phase 2 (Divergent Exploration) must receive a feasibility score (1-5) during Phase 3 (Feasibility Fast-Check) before advancing to synthesis. Ideas scoring 1-2 must be explicitly flagged as low-feasibility rather than silently dropped or presented alongside viable options.

Problem

When brainstorm agents generate 10+ ideas but skip feasibility scoring, the evaluation phase (Phase 4) wastes context rating ideas that were never buildable. Worse, unfeasible ideas can survive to the final presentation, undermining trust in the brainstorm output.

Feasibility Scale

Rules

• Every idea in 03-feasibility.json must include a feasibility_score field (1-5)
• Ideas scoring 1-2 are kept in the output but marked "flagged": true with a reason field
• Flagged ideas must NOT appear in the top recommendations unless the user explicitly asks for moonshots
• The feasibility check must consider the detected project tier from Step 0

Incorrect -- presenting ideas without feasibility scores:

# Phase 3 output: no scoring, all ideas pass through
Write(".claude/chain/03-feasibility.json", {
    "ideas": [
        {"title": "Build custom ML pipeline", "description": "..."},
        {"title": "Add caching layer", "description": "..."},
        {"title": "Rewrite in Rust", "description": "..."}
    ]
})
# Phase 5 wastes tokens evaluating "Rewrite in Rust" for a Tier 2 hackathon

Correct -- every idea scored, unfeasible ones flagged:

# Phase 3 output: each idea scored, low-feasibility flagged with reason
Write(".claude/chain/03-feasibility.json", {
    "tier": 2,
    "ideas": [
        {"title": "Add caching layer", "feasibility_score": 5,
         "flagged": False},
        {"title": "Build custom ML pipeline", "feasibility_score": 2,
         "flagged": True, "reason": "Requires GPU infra not available at Tier 2"},
        {"title": "Rewrite in Rust", "feasibility_score": 1,
         "flagged": True, "reason": "Complete rewrite exceeds project scope and timeline"}
    ],
    "viable_count": 1,
    "flagged_count": 2
})
# Phase 4 focuses evaluation on viable ideas; flagged ideas shown separately

Integration with Phase Workflow

• Phase 2 generates ideas freely (no filtering)
• Phase 3 applies this feasibility filter -- every idea gets a score
• Phase 4 evaluates only ideas with feasibility_score >= 3 in detail
• Phase 5 synthesis references flagged ideas in a "Considered but excluded" section

Create design document for: $ARGUMENTS

Auto-Filled Context

• Date: !date +%Y-%m-%d
• Author: !git config user.name || echo "[Your Name]"
• Project: !basename $(git rev-parse --show-toplevel 2>/dev/null) || echo "Project"
• Current Branch: !git branch --show-current || echo "main"
• Recent Commits: !git log --oneline -5 2>/dev/null | head -3 || echo "No recent commits"

Your Task

Create a design document for: $ARGUMENTS

Use the auto-filled context above and customize the template below with your feature's requirements, architecture, and implementation plan.

$ARGUMENTS Design Document

Date: !date +%Y-%m-%d Author: !git config user.name || echo "[Your Name]" Status: Draft | In Review | Approved

---

Overview

Brief description of what is being designed and why.

Goal: What problem does this solve?

Non-Goals: What is explicitly out of scope?

---

Requirements

Functional Requirements

• Requirement 1
• Requirement 2
• Requirement 3

Non-Functional Requirements

• Performance: Target metrics
• Security: Security considerations
• Scalability: Scale requirements

Success Criteria

• How will we measure success?
• What does "done" look like?

---

Approach Comparison

Decision: Why this approach was chosen.

---

Architecture

System Overview

[Component A] → [Component B] → [Component C]
     ↓              ↓              ↓
  [Detail]       [Detail]      [Detail]

Components

Component 1

• Purpose: What it does
• Technology: Implementation details
• Interface: How it communicates

Component 2

• Purpose: What it does
• Technology: Implementation details
• Interface: How it communicates

---

Data Flow

1. Step 1: User action triggers... 2. Step 2: System processes... 3. Step 3: Response is...

Data Models

interface DataModel {
  field1: string;
  field2: number;
  field3: Date;
}

---

Security & Privacy

• Authentication: How users are authenticated
• Authorization: Access control rules
• Data Protection: Encryption, PII handling
• Compliance: GDPR, SOC2, etc.

---

Error Handling

---

Testing Strategy

Unit Tests

• Component A tests
• Component B tests

Integration Tests

• End-to-end flow
• Error scenarios

Performance Tests

• Load testing
• Stress testing

---

Deployment Plan

Rollout Strategy

• Phase 1: Feature flag, 5% users
• Phase 2: 25% users
• Phase 3: 100% rollout

Rollback Plan

• How to disable feature quickly
• Data migration reversal (if applicable)

Monitoring

• Metrics to track: List key metrics
• Alerts: When to page on-call

---

Implementation Timeline

Total estimated time: X weeks

---

Open Questions

1. Question about implementation detail? 2. Question about requirements? 3. Question about dependencies?

---

Appendix

References

• Link to related documents
• API documentation
• Design inspiration

Revision History

Your Task

Use this decision matrix template to systematically compare options and make a data-driven decision. Fill in the criteria, score each option, and document the rationale.

Decision Matrix: [Decision Name]

Date: YYYY-MM-DD Decision Maker: [Name/Team]

---

Options Being Considered

1. Option 1: [Brief description] 2. Option 2: [Brief description] 3. Option 3: [Brief description]

---

Evaluation Criteria

Define the criteria that matter most for this decision.

---

Detailed Comparison

Option 1: [Name]

Pros:

• Advantage 1
• Advantage 2
• Advantage 3

Cons:

• Disadvantage 1
• Disadvantage 2
• Disadvantage 3

Score:

---

Option 2: [Name]

Pros:

• Advantage 1
• Advantage 2
• Advantage 3

Cons:

• Disadvantage 1
• Disadvantage 2
• Disadvantage 3

Score:

---

Option 3: [Name]

Pros:

• Advantage 1
• Advantage 2
• Advantage 3

Cons:

• Disadvantage 1
• Disadvantage 2
• Disadvantage 3

Score:

---

Weighted Score Comparison

Applying the criteria weights:

---

Decision

Chosen Option: Option 2

Rationale:

• Why this option was selected
• Which trade-offs were accepted
• What risks are being taken
• How to mitigate the cons

Alternatives Considered:

• Why Option 1 was rejected: [Reason]
• Why Option 3 was rejected: [Reason]

---

Implementation Notes

• Key considerations for implementation
• Dependencies to address
• Timeline implications

---

Revisit Criteria

This decision should be revisited if:

• Condition 1 changes (e.g., user count grows >10x)
• Condition 2 occurs (e.g., new technology becomes available)
• Condition 3 happens (e.g., cost becomes prohibitive)

Review date: YYYY-MM-DD

---

Stakeholder Sign-off

Your Task

Use this design document template to plan a new feature or system. Fill in each section with the specifics of your design, including requirements, architecture, and deployment plan.

[Feature Name] Design Document

Date: YYYY-MM-DD Author: [Your Name] Status: Draft | In Review | Approved

---

Overview

Brief description of what is being designed and why.

Goal: What problem does this solve?

Non-Goals: What is explicitly out of scope?

---

Requirements

Functional Requirements

• Requirement 1
• Requirement 2
• Requirement 3

Non-Functional Requirements

• Performance: Target metrics
• Security: Security considerations
• Scalability: Scale requirements

Success Criteria

• How will we measure success?
• What does "done" look like?

---

Approach Comparison

Decision: Why this approach was chosen.

---

Architecture

System Overview

[Component A] → [Component B] → [Component C]
     ↓              ↓              ↓
  [Detail]       [Detail]      [Detail]

Components

Component 1

• Purpose: What it does
• Technology: Implementation details
• Interface: How it communicates

Component 2

• Purpose: What it does
• Technology: Implementation details
• Interface: How it communicates

---

Data Flow

1. Step 1: User action triggers... 2. Step 2: System processes... 3. Step 3: Response is...

Data Models

interface DataModel {
  field1: string;
  field2: number;
  field3: Date;
}

---

Security & Privacy

• Authentication: How users are authenticated
• Authorization: Access control rules
• Data Protection: Encryption, PII handling
• Compliance: GDPR, SOC2, etc.

---

Error Handling

---

Testing Strategy

Unit Tests

• Component A tests
• Component B tests

Integration Tests

• End-to-end flow
• Error scenarios

Performance Tests

• Load testing
• Stress testing

---

Deployment Plan

Rollout Strategy

• Phase 1: Feature flag, 5% users
• Phase 2: 25% users
• Phase 3: 100% rollout

Rollback Plan

• How to disable feature quickly
• Data migration reversal (if applicable)

Monitoring

• Metrics to track: List key metrics
• Alerts: When to page on-call

---

Implementation Timeline

Total estimated time: X weeks

---

Open Questions

1. Question about implementation detail? 2. Question about requirements? 3. Question about dependencies?

---

Appendix

References

• Link to related documents
• API documentation
• Design inspiration

Revision History