# Operationalizing Ideas Into Self-Documenting Beads

> The fourth and fifth steps of the generate-winnow methodology
> (`ideation-mode.md`): turn a ranked portfolio of ideas into a comprehensive,
> granular, self-documenting set of `bd` beads, then refine them 4-5x in "plan
> space" before any implementation begins.
>
> This is primarily a `/discovery` responsibility on the open-ended path, but it
> consumes ideation-mode output and uses the same `bd`-only discipline.
>
> **Tracking is `bd` (beads).** This is AgentOps — do NOT use `br`/`bv`.

## Step 4 — Comprehensive bead creation

Take ALL of the ranked ideas (top 5 + next 10 = 15) and elaborate them into a
comprehensive, granular set of beads with tasks, subtasks, and a dependency
structure overlaid. The beads must be **self-documenting**: so detailed that the
original markdown plan never needs to be consulted again.

Each bead's description should answer, for our "future self":

1. **What** — What specifically needs to be done?
2. **Why** — Why it matters; how it serves the project's overarching goals.
3. **How** — Key implementation approach.
4. **Risks** — What could go wrong (carry the red-team findings forward).
5. **Success criteria** — How we know it's done.

Include relevant background, reasoning/justification, and considerations — the
goals, intentions, and thought process that produced the idea.

### Bead structure

```bash
bd create "Epic: <Feature Name>" -p 1 -t epic --description "
## Background
[Why this feature matters; which ideation idea(s) it came from]

## Goals
- [Goal 1]
- [Goal 2]

## Non-Goals
- [What we are explicitly NOT doing]

## Considerations
[Technical constraints, user expectations, rubric scores, red-team findings]
"
```

### Subtask + dependency pattern

```bash
# Create the epic, then tasks under it
bd create "Design <component> interface" -p 1 -t task --description "..."
bd create "Implement <component> logic"  -p 2 -t task --description "..."
bd create "Tests for <component>"         -p 2 -t task --description "..."

# Wire dependencies (child depends on parent)
bd dep add <impl-id> <epic-id>      # impl depends on epic
bd dep add <test-id> <impl-id>      # tests depend on implementation
```

### Explicit test tasks (mandatory, with detailed logging)

Every feature gets companion test beads — unit AND e2e — with detailed logging
so we can confirm everything works after implementation:

```bash
bd create "Unit tests for <component>" -p 2 -t task --description "
## Coverage Requirements
- Core behavior
- Error handling for invalid input
- Edge cases (empty, unicode, concurrent)

## Logging
- Log inputs and outputs
- Log timing for performance tracking
"

bd create "E2E tests for <component>" -p 2 -t task --description "
## Scenarios
- Happy path
- Error path
- Integration with existing surfaces

## Logging
- Full command and response capture
- Timing and resource usage
"
```

### Overlap check before creating

Compare against existing beads so ideas enhance rather than duplicate:

```bash
bd list --json | jq '.issues[]?.title'
```

| Overlap type | Action |
|--------------|--------|
| Direct duplicate | Skip; reference the existing bead |
| Complementary | Merge into the existing bead |
| Conflicts | Note explicitly; flag an architectural decision (`bd human`) |

## Step 5 — Refine in plan space (4-5 passes)

It is far easier and faster to operate in **plan space** before implementing.
Run **4-5 refinement passes** over the bead set. Each pass:

1. **Re-read AGENTS.md / CLAUDE.md** so the project's rules are fresh (especially
   after any context compaction).
2. Check every bead carefully: Does it make sense? Is it optimal? Could anything
   change to make the system work better for users? Revise in place.
3. **DO NOT OVERSIMPLIFY.** Resist the urge to collapse complexity — complexity
   usually exists for a reason.
4. **DO NOT LOSE FEATURES OR FUNCTIONALITY.** Every capability in the portfolio
   must survive the refinement.
5. Ensure comprehensive unit tests AND e2e test scripts with detailed logging are
   part of the bead set.

Suggested per-pass focus:

| Pass | Focus |
|------|-------|
| 1 | Structural issues, missing tasks |
| 2 | Dependency sanity, cycle detection |
| 3 | Test coverage gaps |
| 4 | Comment quality, self-documentation completeness |
| 5 | Final optimization |

### Validation between passes

```bash
bd dep cycles --json     # dependency cycles MUST be empty
bd ready --json | jq 'length'   # confirm actionable work exists
bd lint                  # hygiene: orphans, missing fields
```

> If `bd` lacks a direct cycle-detection subcommand in your install, inspect the
> dependency graph with `bd dep tree <id>` and `bd blocked --json`. The
> invariant is the same: no cycles, every leaf actionable.

## Anti-patterns

| Don't | Do |
|-------|-----|
| Single-pass beads | 4-5 passes — the first draft is never optimal |
| Beads that need the markdown plan | Self-documenting beads — what/why/how/risks/success |
| Omit tests | Explicit unit + e2e test beads with detailed logging |
| Oversimplify on refinement | Preserve complexity that exists for a reason |
| Lose features when refining | Every portfolio capability survives |
| `br`/`bv` | `bd` — this is AgentOps |

# Executable spec for the /brainstorm skill — goal clarification (domain role).
# /brainstorm separates WHAT from HOW: it explores the problem space and captures testable
# Gherkin acceptance examples BEFORE planning commits to a solution. It runs upstream of loop
# move 1 (shape intent as BDD). Hexagon: domain; consumes standards; produces result.json +
# verdict.json; shared-kernel with standards. (soc-qk4b)

Feature: Brainstorm separates goals from implementation before planning
  As the pre-planning goal-clarification step
  I want a free-text goal explored as a problem space, then captured as Gherkin
  So that planning starts from clear, testable intent rather than a premature solution

  Scenario: a goal is clarified through the four phases
    When /brainstorm runs on a free-text goal
    Then it works through assess-clarity → understand-idea → explore-approaches → capture-design

  Scenario: approaches are explored as options, not a single solution
    When the explore phase runs
    Then it generates multiple options, compares tradeoffs, and applies adversarial critique
    And it separates the problem (WHAT) from any one solution (HOW)

  Scenario: capture writes testable Gherkin examples
    When the capture phase completes
    Then it produces Given/When/Then acceptance examples for /plan and /discovery
    And capture is not complete until at least one happy path and one critical edge are written

  # Ideation mode — open-ended generate-winnow methodology (ag-yw0). Additive to
  # the goal-clarification flow above; documentation-only spec (this file is
  # allowlisted in scripts/.scenario-linkage-allow). Wiring is asserted by the
  # bats regression test tests/scripts/brainstorm-discovery-ideation.bats.

  Scenario: an open-ended goal triggers ideation mode
    Given a goal like "improve the project" or the --ideate flag or an exploring clarity path with no single goal
    When /brainstorm runs
    Then it enters ideation mode instead of the single-goal four-phase flow
    And the goal-clarification four-phase flow remains available for specific goals

  Scenario: ideation mode generates many and winnows ruthlessly to a ranked five
    When ideation mode runs
    Then it grounds in reality by reading AGENTS.md and open and closed bd beads
    And it generates 30 candidate ideas thought through for how-it-works, user-perception, and implementation
    And it winnows to the very best 5 ranked best-to-worst with full rationale
    And it scores survivors against the ten-dimension rubric

  Scenario: ideation mode expands the portfolio to fifteen
    When the top 5 are selected
    Then it generates the next best 10 with rationale for a ranked portfolio of 15
    And it carries how-it-works, user-perception, implementation notes, and rubric scores forward to operationalize

# Idea Evaluation Rubric

> The ten-dimension rubric for scoring and winnowing ideas in ideation mode
> (`ideation-mode.md`). Adapted for AgentOps — tracking is `bd`, not `br`/`bv`.

Ideas are evaluated on: **robust, reliable, performant, intuitive, user-friendly,
ergonomic, useful, compelling, accretive, pragmatic.** A good idea makes the
project obviously better while staying obviously accretive and pragmatic.

## Quick Score Card

Rate each idea 1-5 on each criterion:

| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|-----------|----------|----------------|---------------|
| **Robust** | Breaks on edge cases | Handles common cases | Handles all cases gracefully |
| **Reliable** | Intermittent failures | Usually works | Always works |
| **Performant** | Noticeably slow | Acceptable speed | Imperceptibly fast |
| **Intuitive** | Confusing UX | Learnable | Obvious immediately |
| **User-friendly** | Frustrating | Neutral | Delightful |
| **Ergonomic** | Adds friction | No change | Reduces friction |
| **Useful** | Solves nothing | Solves minor pain | Solves major pain |
| **Compelling** | Nobody wants | Nice to have | Must have |
| **Accretive** | Negative value | Marginal value | Clear value |
| **Pragmatic** | Impossible | Difficult | Straightforward |

**Threshold:** Ideas scoring <3 average should be cut.

## Detailed Criteria

### Robust
Does it handle empty input, malformed input, unicode, concurrent access? Does it
fail gracefully?

### Reliable
Does it work the first time and the 1000th time? Under load? Offline? Does it
recover from errors?

### Performant
Is latency acceptable (<100ms for interactive)? Is throughput sufficient? Does it
scale with data size and use resources efficiently?

### Intuitive
Can users predict behavior? Are defaults sensible? Is naming clear? Do errors
explain themselves?

### User-friendly
Is the happy path smooth? Are error messages helpful? Is recovery easy? Is help
accessible?

### Ergonomic
How many steps to accomplish the goal? How much typing? Are shortcuts available?
Does it reduce cognitive load?

### Useful
What problem does it solve? How often does the problem occur and how painful is
it? Does it create new problems?

### Compelling
Would users request it, switch for it, recommend it, miss it?

### Accretive
Does it add capability, reduce complexity, improve existing features, open new
possibilities? Is the value measurable?

### Pragmatic
Is the technology mature? Is the scope clear? Are dependencies manageable? Is the
timeline reasonable?

## Winnowing Process (30 → 5)

### Round 1: Hard Cuts
Remove any idea that scores 1 on ANY criterion.

### Round 2: Threshold
Remove any idea scoring <3 average.

### Round 3: Ranking
Sort remaining by weighted average:

- Useful: 2x weight
- Pragmatic: 2x weight
- Accretive: 1.5x weight
- Others: 1x weight

### Round 4: Synergy
Consider which ideas complement each other. A weaker idea that enables a stronger
idea may be worth keeping in the expanded 15.

## Red Flags (immediate disqualification)

- "Users will figure it out"
- "We'll document it later"
- "It's technically correct"
- "Nobody does it differently"
- "We've always done it this way"

## Relationship to the red-team checklist

The rubric scores how GOOD an idea is. The `red-team-checklist.md` stress-tests
how an idea BREAKS. Run both: rubric for ranking, red team for risk
classification. An idea that scores high on the rubric but fails 2+ red-team
questions is HIGH RISK and needs a mitigation plan before it survives the winnow.

# Ideation Mode — Generate-Winnow Methodology

> Open-ended idea generation for "improve the project"-style goals.
> Distinct from the four-phase goal-clarification flow, which sharpens ONE
> specific goal. Ideation mode generates MANY candidate improvements, winnows
> ruthlessly, and operationalizes the survivors.

## When to use which mode

| Signal | Mode | Why |
|--------|------|-----|
| Goal names ONE specific capability ("add JWT auth", "fix the login bug") | Goal-clarification (Phases 1-4) | The WHAT is known; explore HOW. |
| Goal is open-ended ("improve the project", "what should we build next", "make X more robust") | **Ideation mode** | The WHAT is unknown; generate a portfolio and select. |
| `--ideate` flag is passed | **Ideation mode** | Explicit operator override. |
| Phase 1 clarity assessment returns `exploring` AND no single goal emerges after follow-up | **Ideation mode** | The user has a direction, not a target. |

The two modes share the same evaluation rubric (`idea-rubric.md`) and the same
adversarial discipline (`red-team-checklist.md`). Ideation mode is **additive**:
it does not replace the goal-clarification flow. A session may start in ideation
mode, select one idea, and hand that single idea to the goal-clarification flow
for HOW-exploration.

## The methodology: generate → winnow → expand → operationalize → refine

Five steps, each with an explicit artifact. The discipline is "generate many,
keep few, document everything."

### Step 1 — Ground in reality (research context)

Before generating, read the project's current state so ideas align with reality
and don't duplicate existing work.

```bash
cat AGENTS.md                # or CLAUDE.md — project rules + constraints
bd list --json              # open work — avoid duplicating
bd list --status closed --json   # closed work — lessons learned, don't re-propose
bd ready --json             # what is actionable right now
```

Checklist before generating:

- [ ] Read AGENTS.md / CLAUDE.md completely (constraints, non-goals, conventions)
- [ ] Reviewed open beads (don't propose what's already tracked)
- [ ] Reviewed closed beads (don't re-propose what was tried and cut)
- [ ] Understand the current architecture and where the project is headed

### Step 2 — Generate 30, winnow to 5 (ranked, with rationale)

Generate **30** candidate ideas for improving the project. The criteria are the
rubric dimensions: more robust, reliable, performant, intuitive, user-friendly,
ergonomic, useful, compelling — while staying **obviously accretive and
pragmatic**.

For each of the 30, think it through carefully:

1. **How it would work** — the mechanism, concretely.
2. **How users would perceive it** — first impression, learning curve, delight.
3. **How we would implement it** — rough approach, surfaces touched, scope.

Then **winnow ruthlessly to the VERY best 5**. Apply the winnowing rounds in
`idea-rubric.md` (hard cuts → threshold → weighted ranking → synergy).

Present the 5 **ranked best-to-worst**, each with full, detailed rationale: how
and why it makes the project obviously better, and why you are confident in that
assessment. Score each survivor against the rubric (see `idea-rubric.md`).

> The 30→5 funnel is the core discipline. Generating many before filtering
> prevents premature commitment to a mediocre first idea; the ruthless cut
> forces quality. Do NOT stop at the first 5 you think of — generate the full 30.

### Step 3 — Expand with the next 10 (→ 15 total)

The #6-15 ideas frequently have unique strengths that complement the top 5.
Generate the **next best 10**, each with its rationale, for a ranked portfolio
of **15**. Together the 15 form a more complete improvement package than the top
5 alone.

### Step 4 — Operationalize into self-documenting beads

This step belongs to `/discovery` on the open-ended path (see
`bead-operationalization.md`), but ideation mode produces its input: a ranked,
rationale-bearing list of 15 ideas with how/perceive/implement notes and rubric
scores. Hand that forward — do not lose the rationale.

### Step 5 — Refine in plan space (4-5 passes)

Also a `/discovery` responsibility (see `bead-operationalization.md`): re-read
AGENTS.md each pass, check every bead for sense and optimality, and resist
oversimplification. "It's a lot easier and faster to operate in plan space
before we start implementing."

## Output of ideation mode

When run standalone (`/brainstorm --ideate`), ideation mode writes its portfolio
to `.agents/brainstorm/YYYY-MM-DD-<slug>-ideation.md` with:

```markdown
---
id: brainstorm-YYYY-MM-DD-<slug>-ideation
type: brainstorm-ideation
date: YYYY-MM-DD
---
# Ideation: <Open-Ended Goal>
## Grounding (AGENTS.md + open/closed beads reviewed)
## Top 5 (ranked best-to-worst, with rationale + rubric scores)
## Next 10 (ranked, with rationale) — portfolio of 15
## Synergies and dependencies
## Next Step: /discovery --ideate (operationalize into beads)
```

When invoked BY `/discovery` on the open-ended path, ideation mode returns the
ranked portfolio inline for the operationalize step rather than writing a
standalone file.

## Anti-patterns

| Don't | Do |
|-------|-----|
| Skip grounding | Read AGENTS.md + beads first — prevents duplicates |
| Generate 5 and stop | Generate the full 30, then winnow |
| Keep all 30 | Winnow ruthlessly to 5; quality over quantity |
| Stop at 5 | Expand to 15 — #6-15 are often complementary |
| Present unranked | Rank best-to-worst with full rationale |
| Drop rationale on handoff | Carry how/perceive/implement + rubric scores into operationalize |
| Use `br`/`bv` | This is AgentOps — use `bd` for all tracking |

# Red Team Checklist for Ideation

Use these questions to stress-test approaches during brainstorm Phase 3b.

## Structural Questions

1. **What breaks first?** — Identify the weakest link under stress (load, concurrency, edge cases, adversarial input). If you can't name a specific failure mode, the approach is under-specified.

2. **What's the hidden cost?** — Every approach has costs beyond implementation time: maintenance burden, cognitive load for new contributors, infrastructure requirements, monitoring needs, migration complexity.

3. **What assumption is wrong?** — List the unstated assumptions. Which one, if false, invalidates the approach? Common false assumptions: "the API won't change", "data fits in memory", "users will read the docs", "this library is maintained".

4. **Who disagrees?** — Steel-man the opposing view. A performance engineer and a UX designer will critique the same approach differently. What does the most skeptical qualified person say?

## Scoring

| Red Team Failures | Classification |
|-------------------|---------------|
| 0 | Strong approach |
| 1 | Viable with mitigation |
| 2+ | HIGH RISK — needs rethinking or mitigation plan |

## When All Approaches Are HIGH RISK

If every approach fails 2+ questions, the problem statement may be wrong. Consider:
- Is the goal too broad? Split it.
- Is there a constraint you haven't stated? Surface it.
- Generate a hybrid approach that addresses the specific red team failures.

## Common False Assumptions

| Assumption | Why It Fails |
|-----------|-------------|
| "The API won't change" | External APIs change without notice; pin versions and add contract tests |
| "Data fits in memory" | Works in dev, breaks in prod when dataset grows 10x |
| "Users will read the docs" | They won't; make the happy path obvious and errors informative |
| "This library is maintained" | Check commit history; many popular libraries are effectively abandoned |
| "We can refactor later" | Technical debt compounds; later never comes without explicit scheduling |
| "Performance doesn't matter yet" | Architecture decisions that ignore performance are expensive to fix |
| "The team will adopt it" | New tools need champions, training, and visible wins to gain traction |

#!/usr/bin/env bash
set -euo pipefail
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0; FAIL=0

check() { if bash -c "$2"; then echo "PASS: $1"; PASS=$((PASS + 1)); else echo "FAIL: $1"; FAIL=$((FAIL + 1)); fi; }

check "SKILL.md exists" "[ -f '$SKILL_DIR/SKILL.md' ]"
check "SKILL.md has YAML frontmatter" "head -1 '$SKILL_DIR/SKILL.md' | grep -q '^---$'"

echo ""; echo "Results: $PASS passed, $FAIL failed"
[ $FAIL -eq 0 ] && exit 0 || exit 1

{
  "name": "brainstorm",
  "form": "A",
  "summary": "Separate WHAT from HOW before planning. Runs goal-clarification (4 phases: assess clarity → understand → explore approaches + adversarial critique → capture) or open-ended ideation (generate-30 → winnow-5 → expand-15) and emits Gherkin-shaped acceptance examples for /plan.",
  "sections": [
    { "id": "title", "title": "/brainstorm — Clarify Goals Before Planning", "type": "header", "priority": "high" },
    { "id": "loop-position", "title": "Loop position", "type": "overview", "priority": "medium" },
    { "id": "two-modes", "title": "Two modes", "type": "overview", "priority": "high" },
    { "id": "quick-start", "title": "Quick Start", "type": "overview", "priority": "high" },
    { "id": "execution-steps", "title": "Execution Steps", "type": "methodology", "priority": "high" },
    { "id": "ideation-mode", "title": "Ideation Mode (open-ended generate-winnow)", "type": "methodology", "priority": "medium" },
    { "id": "termination", "title": "Termination", "type": "constraints", "priority": "medium" },
    { "id": "validation", "title": "Validation", "type": "output_contract", "priority": "medium" },
    { "id": "examples", "title": "Examples", "type": "examples", "priority": "medium" },
    { "id": "troubleshooting", "title": "Troubleshooting", "type": "troubleshooting", "priority": "medium" },
    { "id": "see-also", "title": "See Also", "type": "routing", "priority": "low" },
    { "id": "reference-documents", "title": "Reference Documents", "type": "routing", "priority": "low" }
  ],
  "references": [
    { "path": "references/ideation-mode.md", "intent": "read", "description": "Open-ended generate-winnow methodology, mode-selection table, output template." },
    { "path": "references/idea-rubric.md", "intent": "read", "description": "Ten-dimension evaluation rubric + winnowing rounds." },
    { "path": "references/red-team-checklist.md", "intent": "read", "description": "Adversarial critique template for Phase 3b." },
    { "path": "references/bead-operationalization.md", "intent": "read", "description": "Operationalize the ranked portfolio into self-documenting bd beads." },
    { "path": "references/brainstorm.feature", "intent": "read", "description": "Executable spec: WHAT-not-HOW 4-phase clarification, capture Gherkin for /plan." }
  ],
  "scripts": [],
  "metadata": {
    "tier": "execution",
    "stability": "stable",
    "hexagonal_role": "domain",
    "dependencies": ["standards", "plan", "discovery"],
    "triggers": [
      "/brainstorm",
      "clarify the goal",
      "separate goals from implementation",
      "what should we build next",
      "improve the project",
      "explore approaches before planning",
      "/brainstorm --ideate"
    ],
    "token_estimate": {
      "minimal": 130,
      "overview": 400,
      "standard": 1300,
      "full": 2100
    }
  },
  "produces": [".agents/brainstorm/<date>-<slug>.md", "result.json", "verdict.json"],
  "consumes": ["standards"],
  "context_rel": [
    { "kind": "shared-kernel", "with": "standards" }
  ],
  "quality_score": 0.93,
  "evidence": {
    "sources": [
      "skills/brainstorm/SKILL.md",
      "skills/brainstorm/references/ideation-mode.md",
      "skills/brainstorm/references/idea-rubric.md"
    ]
  }
}