var e=[{file:`SKILL.md`,content:`---
name: brainstorming
description: "Design exploration for planning-phase agents (Orchestrator, Planner, Researchers). Explores user intent, requirements and design BEFORE handing off to implementation agents. Use when there are multiple valid approaches to a problem, when architecture decisions need exploration, when the user says 'how should I...', 'what's the best way to...', 'explore options for...', or when a task has genuine design forks. NOT for code agents - they implement designs, not create them. NOT for single-path decisions - if only one approach makes sense, skip this."
metadata:
  category: planning
  domain: general
  applicability: planning-phase
  inputs: [requirements, user-intent]
  outputs: [design, decisions]
  requires: [aikit]
  relatedSkills: [requirements-clarity]
argument-hint: "Feature, component, or behavior to design"
---

# Brainstorming Ideas Into Designs

## Quick Reference

**Purpose:** Explore requirements and design space before implementation starts.

**Use this skill when:** there are multiple viable approaches, architecture trade-offs matter, or the user is asking for guidance rather than code.

**Skip this skill when:** the work is already decided, the change is mechanical, or only one reasonable path exists.

**HARD GATE:** Do NOT write code, scaffold files, or hand off to implementation until a design is presented and approved.

**Expected output:** a short design or spec with constraints, alternatives, recommendation, risks, and acceptance criteria.

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

## When Brainstorming Is Appropriate

Use brainstorming when at least one of these is true:

- Multiple valid approaches exist and the choice changes cost, risk, or UX
- The work introduces or changes boundaries: service, module, API, workflow, ownership
- The user is asking for options, strategy, trade-offs, or "best way" guidance
- Constraints are real but incomplete: performance, timeline, migration cost, reversibility, team familiarity

Do not use brainstorming when the path is already obvious:

- Fixing a typo, renaming a variable, or updating a pinned dependency
- Implementing an already-approved spec or ADR
- Mechanical migrations where the desired end state is predetermined

---

## Mode Selection

This skill operates in two modes. You choose the mode from the problem shape; do not ask the user which mode they want.

### Simple Mode

Use when **all** of these are true:
- Affects ≤3 files
- Single component or concern
- No new service/package/module boundaries
- No cross-service data flow changes
- Clear, well-understood domain

Examples: config change, utility function, bug fix with design ambiguity, small feature in existing component.

### Full Mode

Use when **any** of these are true:
- Affects >3 files or crosses service boundaries
- Introduces new packages, services, or modules
- Multiple independent subsystems involved
- Architectural decisions with multiple viable approaches
- Changes data models, APIs, or interfaces used by other services
- User explicitly requests thorough exploration

Examples: new notification channel, new API service, platform redesign, multi-service feature, infrastructure changes.

---

## NEVER

- **NEVER skip divergent thinking to jump to solutions** - premature convergence is the most common brainstorming failure. Force at least 3 alternatives before evaluating.
- **NEVER present options without trade-off analysis** - listing A/B/C without pros, cons, and context is noise. Each option needs: strength, weakness, best-when.
- **NEVER conflate requirements with design** - "the user wants to log in" is a requirement; "use OAuth2 + JWT" is a design. Clarify the problem before exploring the solution space.
- **NEVER evaluate during the divergent phase** - "that won't work" too early kills useful exploration. Generate first, judge second.
- **NEVER propose more than 5 options** - too many options create analysis paralysis. 3-5 well-differentiated choices is enough.
- **NEVER present the obvious choice as the only real option with strawman alternatives** - if one option clearly dominates before analysis, say brainstorming is unnecessary and recommend directly.
- **NEVER use brainstorming for single-path decisions** - if there is only one credible path, execute or hand off; do not manufacture fake alternatives.
- **NEVER hide the deciding constraint** - if compliance, migration cost, latency, or org ownership is driving the decision, state it explicitly.

## Core Workflow

| Stage | What you do | What good output looks like |
|-------|-------------|-----------------------------|
| Frame | State the problem, constraints, and success criteria | Clear decision question and explicit boundaries |
| Clarify | Ask one question at a time until ambiguity drops | Requirements are separate from solutions |
| Diverge | Generate 3 alternatives that differ in shape, not just labels | Options have meaningfully different trade-offs |
| Evaluate | Compare options against criteria, constraints, reversibility, and delivery cost | Rejection reasons are explicit |
| Recommend | Pick one option and explain why the others lost | Recommendation matches the stated constraints |
| Confirm | Present the design, get approval, then hand off | Implementation can proceed without reopening core design questions |

Simple Mode compresses the workflow into a short design note. Full Mode produces a fuller spec and spends more time on constraints, interfaces, migration, and rollout.

---

## Decision Protocol

Use the heaviest process the problem actually needs. The protocol scales with decision complexity; it does not assume a giant agent swarm.

### Multi-Researcher Mode

Use this when the decision is high-impact and the Orchestrator can actually dispatch multiple research passes.

1. **Independent passes** - gather 2-4 perspectives if available. More is optional, not mandatory.
2. **Cross-check blind spots** - compare where the perspectives agree, clash, and what each missed.
3. **Structured verdict** - produce one recommendation with confidence, deciding constraints, rejected alternatives, and first implementation step.

Do not block waiting for an 8-agent protocol. If capacity is limited, reduce the number of perspectives and keep the structure.

### Single-Agent Fallback

When running as a single agent (no Orchestrator dispatching multi-model research), use this structured approach:

1. **Frame the decision space** - state the question, list constraints, define success criteria
2. **Generate 3 alternatives** - force diversity by thinking from different lenses:
  - Lens A: Simplest approach (minimum viable, least risk)
  - Lens B: Best long-term approach (might be more work now, pays off later)
  - Lens C: Unconventional approach (different framing, different trade-off)
3. **Evaluate against criteria** - for each alternative, score against the stated success criteria
4. **Recommend with rationale** - pick one, explain WHY, acknowledge what you're trading away

This replaces the full Multi-Model Decision Protocol when running solo.

### Verdict Format

Express the result in structured text, not diagrams:

| Section | Required content |
|---------|------------------|
| Decision | What question is being answered |
| Constraints | What limited the design space |
| Options | 3 alternatives with strength, weakness, best-when |
| Recommendation | Chosen option and why |
| Rejections | Why the other options lost |
| Risks | What could fail and how reversible it is |
| First Step | Smallest useful next move after approval |

### Large Project Decomposition

Before asking detailed questions, assess scope. If the request includes multiple independent subsystems, decompose first. Do not brainstorm the whole platform as one blob.

If the project is too large for a single spec, break it into sub-projects, define the order, then brainstorm the first sub-project only.

## Design Quality Signals

- **Options are genuinely different** - if they only differ in naming, you have not explored the space.
- **Trade-offs are real** - if one option dominates on all dimensions, the others are strawmen.
- **Constraints are explicit** - "we chose X because of Y constraint" is good; "X is better" is lazy.
- **Reversibility is assessed** - one-way doors need more analysis than two-way doors.
- **You can explain why NOT the other options** - if you cannot articulate the rejection reason, the analysis is shallow.

## Design Review Checklist

Before presenting the design, verify these quality bars:

- **Completeness** - no TODOs, placeholders, or missing constraints that block planning.
- **Consistency** - sections do not contradict each other.
- **Precision** - two competent developers would implement compatible solutions from this spec.
- **Scope control** - the design solves the asked problem and avoids unrequested extras.
- **Canonical language** - names and domain terms match the codebase or are explicitly introduced.

Fix serious issues before handoff. Minor wording changes are advisory, not blockers.

## Working Method

- Check current project context before proposing changes.
- Ask one question per message when clarification is needed.
- Prefer multiple-choice questions when they reduce ambiguity faster.
- Separate divergent generation from evaluation.
- Lead with your recommendation once the option space is explored.
- Stay concrete: boundaries, interfaces, data flow, failure modes, rollout.

## Output Contract

For Simple Mode, produce a concise design note with:

- Goal
- Constraints
- 3 options
- Recommendation
- Risks and acceptance criteria

For Full Mode, produce a spec that also covers:

- Boundaries and component responsibilities
- Interfaces and data flow
- Migration or rollout strategy
- Error handling and operational risks
- Test and acceptance strategy

When useful, save the approved design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` before handing off to implementation planning.

`},{file:`spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template

Use this template when dispatching a spec document reviewer subagent.

**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.

**Dispatch after:** Spec document is written to docs/specs/

\`\`\`
Task tool (general-purpose):
  description: "Review spec document"
  prompt: |
    You are a spec document reviewer. Verify this spec is complete and ready for planning.

    **Spec to review:** [SPEC_FILE_PATH]

    ## What to Check

    | Category | What to Look For |
    |----------|------------------|
    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
    | Consistency | Internal contradictions, conflicting requirements |
    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
    | YAGNI | Unrequested features, over-engineering |

    ## Calibration

    **Only flag issues that would cause real problems during implementation planning.**
    A missing section, a contradiction, or a requirement so ambiguous it could be
    interpreted two different ways — those are issues. Minor wording improvements,
    stylistic preferences, and "sections less detailed than others" are not.

    Approve unless there are serious gaps that would lead to a flawed plan.

    ## Output Format

    ## Spec Review

    **Status:** Approved | Issues Found

    **Issues (if any):**
    - [Section X]: [specific issue] - [why it matters for planning]

    **Recommendations (advisory, do not block approval):**
    - [suggestions for improvement]
\`\`\`

**Reviewer returns:** Status, Issues (if any), Recommendations
`}];export{e as default};