brainstorming

What this skill does

# Brainstorming Skill

## Overview

Collaborative design exploration for new features, architecture decisions, and complex problem-solving.

## Triggers

Activate this skill when:
- User says "let's brainstorm", "let's ideate", or "let's explore"
- User runs `/exarchos:ideate` command
- User wants to discuss design options before implementation
- A problem has multiple valid solutions needing evaluation

For a complete worked example, see `references/worked-example.md`.

## Four-Phase Process

### Phase 0: Constraint anchoring (first turn, before Phase 1)

**Goal:** Surface the architectural invariants relevant to the proposal *before* the clarifying questions, so the design is anchored to load-bearing constraints from the first turn.

Load the **core** invariants catalog at `.exarchos/invariants.md` (entries marked `cost-of-load: always-load`) and surface a **Constraints** section naming the relevant invariants — e.g. a CLI / agent-first surface proposal anchors on `INV-5a` (input ergonomics) and `INV-5c` (Aspire verbs). The full selection rules — `always-load` baseline vs `reference-only` on-demand vs `archivable` not-surfaced, the proposal-shape → anchor-invariant table, the emit format, and the `invariants.devCatalog` gating — are the **single shared source of truth** for the design-time Constraints step used by `/ideate`, `/refactor`, and `/debug`. See `@skills/brainstorming/references/constraint-anchoring.md`.

Emit the **Constraints** section (per that reference) *before* Phase 1 so the clarifying questions can probe the proposal against the load-bearing invariants instead of re-discovering them mid-design.

### Phase 1: Understanding

**Goal:** Deeply understand the problem before proposing solutions.

**Rules:**
- Ask ONE question at a time
- Wait for response before asking next question
- Focus on: goals, constraints, existing patterns, user preferences
- Maximum 5 questions before moving to exploration

**Question Types:**
1. "What problem are we solving?" (core need)
2. "What constraints exist?" (time, tech, compatibility)
3. "What patterns already exist in the codebase?" (consistency)
4. "Who/what will consume this?" (users, APIs, other systems)
5. "What does success look like?" (acceptance criteria)

### Phase 2: Exploration

**Goal:** Present 2-3 distinct approaches with trade-offs.

Use the approach format from `references/design-template.md`. Present genuinely different approaches with honest trade-offs. Recommend one option with rationale.

### Phase 3: Design Presentation

**Goal:** Document the chosen approach in detail with numbered requirements.

Document the chosen approach using the structure in `references/design-template.md`. Sections of 200-300 words max. Use diagrams for complex flows.

**Requirements format (MANDATORY):**
- Use numbered requirement identifiers: `DR-1`, `DR-2`, ..., `DR-N`
- Each requirement MUST have an `**Acceptance criteria:**` block with concrete, testable criteria
- At least one requirement MUST address error handling, failure modes, or edge cases
- These DR-N identifiers are provenance anchors — implementation plans trace tasks to them

**Save Location:** `docs/designs/YYYY-MM-DD-<feature>.md`

## Iteration Limits

**Design iterations: max 3.** If Phase 2 (Exploration) cycles through 3 rounds of presenting approaches without the user converging on a choice, pause and summarize the trade-offs for the user to make a final decision.

The user can override: `/exarchos:ideate --max-iterations 5`

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| Jump to solution immediately | Ask clarifying questions first |
| Present only one option | Always show 2-3 alternatives |
| Hide drawbacks of preferred option | Be transparent about trade-offs |
| Write walls of text | Use 200-300 word sections max |
| Ignore existing patterns | Reference codebase conventions |
| Skip documentation | Save design to docs/designs/ |

## State Management

This skill manages workflow state for context persistence.

### On Start (before Phase 1)

Initialize workflow state using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "init"`, `workflowType: "feature"`, and the featureId.

This creates a state file tracked by the MCP server.

### On Design Save (after Phase 3)

```
action: "update", featureId: "<id>", updates: { "artifacts": { "design": "<path>" } }, phase: "plan"
```

### Phase Transitions and Guards

This skill is the entry point for the **feature workflow** (`workflowType: "feature"`). The full lifecycle is:

```
ideate → plan → plan-review → delegate ⇄ review → synthesize → completed
```

For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.

### Schema Discovery

Use `exarchos_workflow({ action: "describe", actions: ["update", "init"] })` for
parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
for phase transitions, guards, and playbook guidance.

## Completion Verification

Run the ideation artifact verification:

```typescript
mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
  action: "check_design_completeness",
  featureId: "<featureId>",
  designPath: "docs/designs/YYYY-MM-DD-<feature>.md"
})
```

**On `passed: true`:** All completion criteria met — proceed to gate check.
**On `passed: false`:** Missing artifacts — review output and complete before continuing. If the check is advisory (`advisory: true`), emit a warning but do not block auto-chain.

## Adversarial Gate Check (ideate → plan)

After artifact verification passes, run the design completeness gate check. This is the D1 (spec fidelity) lightweight adversarial check at the ideate → plan boundary.

```typescript
mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
  action: "check_design_completeness",
  featureId: "<id>",
  designPath: "<path>"
})
```

The handler returns a structured result: `{ passed, advisory, findings[], checkCount, passCount, failCount }`.

- **`passed=true`:** Design complete — all requirements have acceptance criteria and error coverage.
- **`passed=false, advisory=true`:** Findings detected. These are advisory — they do NOT block the auto-chain to `/exarchos:plan`. Present `result.data.findings` to the user alongside the transition message.

Gate events (`gate.executed`) are emitted automatically by the handler — no manual event emission is needed.

## Transition

After brainstorming completes, **auto-continue to planning** (no user confirmation):

### Pre-Chain Validation (MANDATORY)

Before invoking `/exarchos:plan`:
1. Verify `artifacts.design` exists in workflow state
2. Verify the design file exists on disk: `test -f "$DESIGN_PATH"`
3. Run `mcp__plugin_exarchos_exarchos__exarchos_orchestrate({ action: "check_design_completeness", featureId: "<id>", designPath: "<path>" })` (advisory — record findings but don't block)
4. If steps 1 or 2 fail: "Design artifact not found, cannot auto-chain to /exarchos:plan"

### Chain Steps

1. Update state: `action: "update", featureId: "<id>", updates: { "artifacts": { "design": "<path>" } }, phase: "plan"`

2. If `result.data.passed === false` and `result.data.advisory === true`: Output `result.data.findings` summary, then: "Advisory findings noted. Auto-continuing to implementation planning..."
   If `result.data.passed === true`: Output: "Design complete. Auto-continuing to implementation planning..."

3. Invoke immediately:
   ```typescript
   Skill({ skill: "exarchos:plan", args: "<design-path>" })
   ```

This is NOT a human checkpoint. The human checkpoint occurs at plan-review (plan approval) and synthesize (merge confirmation).

**Workflow continues:** `/exarchos:ideate` -> `/exarchos:plan` -> plan-review -> [HUMAN CHECKPOINT] -> `/exarchos:delegate` -> `/exarchos:review` -> `/exarchos:synthesize` -> [HUMAN CHECKPOINT]

## Exarchos Integration

When Exarchos MCP tools are available:

1. **At workflow start:** Auto-emitted by `exarchos_workflow` `action: "init"` — do NOT