brainstorming

name	brainstorming
description	Turns a rough idea into an approved epic contract with immutable requirements, anti-patterns, and a first wave of executable tasks.
when_to_use	Use when user has a new feature idea, rough concept, or unexplored approach. Include when planning before code, breaking a design into tasks, creating an implementation plan, laying out tasks and dependencies, exploring architectural options, or requirements are vague. User phrases like "I want to build X", "should we do this", "let's think through Y", "explore approaches", "break this into tasks", "make an implementation plan". Do NOT use for executing existing plans, fixing bugs, refactoring, or when requirements and an epic already exist.
user_invokable	true

Brainstorming Ideas Into Designs

Freedom: HIGH — adapt the questioning to context. Fixed: design approved before code, first wave only, questions in prose.

Overview

Turn rough ideas into validated designs stored as epic Tasks with immutable requirements. Tasks are created iteratively as you learn, not upfront.

Turn rough ideas into validated designs captured as immutable epic contracts in the root transcript. Complete worker briefs are authored iteratively as you learn, not upfront.

Core principle: Ask questions to understand, research before proposing, document decisions for future reference.

Announce at start: "I'm using gambit:brainstorming to refine your idea into a design."

Quick Reference

Step	Action	Deliverable
1	Scope-check, then ask clarifying questions	Right granularity + understanding
2	Research codebase and patterns	Existing approaches
3	Propose 2-3 approaches	Recommended option
4	Present design, then Steelman agreement	Validated architecture + frozen Design Ledger

| 5 | Create epic Task | Immutable requirements + anti-patterns | | 6 | Create first wave (pluckable tasks only) | Ready for execution |

| 5 | Present draft epic contract | Immutable requirements + anti-patterns | | 6 | Author complete first-wave worker briefs | Ready for self-review |

| 7 | Apply task refinement | Corner cases covered | | 8 | Confirm immutable requirements with user | Contract locked | | 9 | Ask next step, invoke skill | Chain continues automatically |

Key: Epic = contract (immutable), Tasks = adaptive (created as you learn)

Key: Epic = root-transcript contract (immutable), wave plan = adaptive (replaced as you learn)

Do NOT write any code, invoke any implementation skill, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY idea regardless of perceived simplicity. No exceptions.

When to Use

• User describes a new feature to implement
• User has a rough idea that needs refinement
• About to write code without clear requirements
• Need to explore approaches before committing

Don't use for:

• Executing existing plans (use gambit:executing-plans)
• Starting a bug with no root cause yet (investigate with gambit:debugging first — it hands the root cause back here to design the fix)
• Refactoring (use gambit:refactoring)
• Requirements already crystal clear and epic exists

The Process

1. Understand the Idea

Research existing context first:

Resolve the absolute path to contracts/scout.md. Resolve the scout role through contracts/models.md — its entry rung, or a higher rung on the scout ladder when the question is about code flow or exhaustiveness rather than a single fact. Dispatch that rung: a model rung uses the read-only Explore class below; an agent rung uses the rung's readonly_agent and passes no model: at all. The prompt is identical either way.

Agent
  subagent_type: "Explore"          # model rung: the read-only scout class
  model: "<scout rung alias — contracts/models.md>"   # resolve <abs> via Glob **/contracts/scout.md
  prompt: "Read <abs>/contracts/scout.md first (your binding scout contract), then: Find existing [relevant] implementation patterns in this codebase. Report with file:line evidence; say NOT FOUND if absent."

Resolve the absolute path to contracts/scout.md, then dispatch the contracted scout class:

Agent
  subagent_type: "Explore"
  model: "<scout tier — default cheap; contracts/models.md>"
  prompt: "Read <abs>/contracts/scout.md first (your binding scout contract), then: Find existing [relevant] implementation patterns in this codebase. Report with file:line evidence; say NOT FOUND if absent."

Check scope before refining. If the request spans multiple independent subsystems (e.g., "a platform with chat, billing, and analytics"), STOP and decompose before asking detail questions — don't refine something that should be several epics. Identify the independent pieces, how they relate, and what order to build them. Then brainstorm the FIRST piece through the normal flow; each piece gets its own epic → tasks cycle. Refining an over-large project wastes questions and produces a brittle epic.

Then ask clarifying questions in prose. Never use the AskUserQuestion tool — in this step or anywhere else in this skill.

Aim for 2-4 questions per round, 2-4 rounds total. Every question carries its own context: why you're asking, what the realistic options are, and which one you recommend and why. A bare question with no setup arrives confusing — the reader shouldn't have to reconstruct what prompted it. Stop when you understand scope, constraints, existing patterns, and scale.

Two things before I propose an approach:

**Token storage.** The OAuth tokens have to live somewhere the browser sends
them from. httpOnly cookies block XSS token theft and are the industry default;
sessionStorage clears on tab close but any injected script can read it. I'd go
httpOnly cookies unless you need the token client-side. Which fits?

**Scale.** [context → options → recommendation → question]

Why prose, not the question widget. The widget strips the context that makes a question answerable: compressed option labels can't carry the trade-off, and the question lands without the reasoning that prompted it. Prose keeps the question, its context, and your recommendation together — and it works in every environment. This applies to every question in this skill, closed or open, including the handoff menu.

---

2. Explore Approaches

Research before proposing:

• Existing pattern in codebase → Explore agent
• New integration → WebSearch or WebFetch
• No results → Ask user for direction

Propose 2-3 approaches:

• Lead with your recommendation and why
• Include pros/cons for each
• Reference codebase consistency as a factor

Based on [research findings], I recommend:

1. **[Approach A]** (recommended)
   - Pros: [benefits, especially "matches existing pattern"]
   - Cons: [drawbacks]

2. **[Approach B]**
   - Pros: [benefits]
   - Cons: [drawbacks]

I recommend option 1 because [specific reason].

---

3. Present the Design

Once approach is chosen, present in digestible sections. Ask "Does this look right?" after each. Cover: architecture, components, data flow, error handling, testing.

Design the validation ladder, not just the tests. Identify the fastest focused worker command, the integrated wave/component gate, and any expensive release acceptance or blackbox suite. Record the freshness setup and an explicit acceptance budget. A slow system suite is a release claim, not a reflexive per-task check.

Decompose for isolation. Break the system into units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently. For each unit, you should be able to say what it does, how to use it, and what it depends on — without reading its internals. If you can't change a unit's internals without breaking its consumers, the boundaries are wrong; rework them before locking the epic.

Apply YAGNI ruthlessly. Cut every feature, abstraction, and "we might want this later" the stated requirements don't demand. Unbuilt scope is the cheapest scope to remove — if the user wants it, they'll say so when you present.

---

3a. Steelman the Agreed Design

After the user and root agree on one coherent candidate design, run one mandatory discovery pass before drafting an epic contract or authoring first-wave work.

Do not create or mutate task state during Steelman discovery, dialogue, or closure.

Do not initialize or mutate native plan state during Steelman discovery, dialogue, or closure.

No epic or first-wave work begins before Steelman resolution. The Steelman is read-only and advisory; the root owns all decisions and every ledger disposition.

Build the Design Packet

Supply a self-contained Design Packet containing exactly these contracted fields:

1. User goal
2. Agreed constraints and scope
3. Chosen approach
4. Architecture and data flow
5. Rejected alternatives and reasons
6. Validation strategy
7. Delivery constraints
8. Unresolved decisions

Do not omit an empty field; write None when there is genuinely nothing unresolved. The packet must stand alone without inherited conversation.

Resolve and dispatch the Steelman

Resolve the absolute path to contracts/steelman.md. Resolve the steelman role through contracts/models.md to its rung. Steelman is read-only and advisory, so an agent rung dispatches the rung's readonly_agent with no model: at all; a model rung dispatches general-purpose with the rung's alias. The dispatch is fresh and contracted either way, and its prompt carries only the absolute contract path plus the mode inputs:

Agent
  subagent_type: "general-purpose"          # model rung; an agent rung uses the rung's readonly_agent
  model: "<steelman rung alias — contracts/models.md>"   # omit entirely on an agent rung
  prompt: |
    Read <abs>/contracts/steelman.md first and follow it exactly.

    Mode: Discovery

    Design Packet:
    [complete self-contained packet]

Discovery receives the Design Packet and no previous Steelman output; closure receives the revised Design Packet, the frozen Design Ledger, and a concise design delta. Never inherit prior turns into a Steelman dispatch, and never dispatch a Steelman without its contract path.

Resolve the absolute path to contracts/steelman.md. Native Codex does not read the external executor registry. Dispatch the contracted steelman class, preferring an installed steelman profile and otherwise default, always with fork_turns: "none". The dispatch is fresh and its message contains only the contract path plus the mode inputs.

SpawnAgent
  role: "steelman"
  description: "Steelman the agreed design"
  prompt: |
    Read <abs>/contracts/steelman.md first and follow it exactly.

    Mode: Discovery

    Design Packet:
    [complete self-contained packet]

Discovery receives the Design Packet and no previous Steelman output. Require one of the contract statuses — READY, REVISE, NEEDS_DECISION, or BLOCKED — and all contracted sections: Status, Strongest case for the chosen design, Strongest credible alternative and when it wins, Numbered findings, Actual user decisions, and Evidence and coverage. A missing status or section is a failed call, not permission for the root to invent the result.

If the selected discovery dispatch or tool call fails, or its output is malformed or missing any contracted section, stop and report the failure. Do not create a Design Ledger, draft an epic contract, fall back to another dispatch path, or automatically redispatch.

Route each valid discovery result exactly once:

• BLOCKED: stop and show the exact missing material named by the result. Do not draft an epic or dispatch another call.
• NEEDS_DECISION: follow the ledger/yield path and yield on every named user decision. The root cannot advance while any named decision remains unresolved.
• REVISE: follow the ledger/yield path but do not advance directly. It requires finding dispositions and a material Design Packet revision. If no material revision is adopted, stop.
• READY: follow the ledger/yield path. It may skip closure only when no material design change follows.

No non-READY discovery result can fall through to epic drafting. No discovery branch automatically spends a second discovery call. Any adopted or open material revision requires the single closure pass.

Freeze the ledger and yield

For every result routed to the ledger/yield path, reflect every discovery finding visibly to the user in a transcript-local frozen Design Ledger. Keep every returned ID and assign it exactly one root-owned disposition: ADOPTED, REJECTED with a reason, OPEN, or DEFERRED with a scope boundary. Record user decisions and packet revisions against the affected IDs. Never put the ledger in task or plan state.

Then yield to the user for discussion. The root cannot silently revise the packet and dispatch closure in the same turn. The user must be able to see every discovery finding, every disposition, and the resulting design change before deciding what comes next.

Run bounded closure when required

After user/root discussion, run exactly one closure pass if an ADOPTED or OPEN finding materially changes the design. Skip closure only when discovery returned READY and no material design change occurred. Use the revised self-contained Design Packet, the frozen Design Ledger verbatim, and a concise design delta as the only closure inputs. Repeat the same backend dispatch rules above.

Under those rules, closure is another fresh contracted dispatch on the steelman role's rung.

Under those rules, native Codex uses another fresh contracted dispatch with fork_turns: "none".

Require one closure status — READY, STILL_OPEN, CHANGE_INDUCED_CONCERN, or BLOCKED — plus Status, Ledger dispositions, Change-induced concerns, Required caller action, and Evidence and coverage. Closure cannot restart discovery, cannot reopen REJECTED or DEFERRED items, and cannot add unrelated improvements. A READY result, or the permitted discovery skip, allows epic drafting to begin.

No automatic third call is allowed. For any non-READY closure, stop and offer exactly these user choices in prose:

1. revise without another Steelman pass;
2. lock the contract with the residual risk recorded; or
3. explicitly authorize another discovery cycle.

The third choice is the only choice that resets the budget, and it is valid only for a fundamental architecture reset with explicit user authorization. Never infer that authorization from a finding, a revision, or user silence.

Finalize the packet for contract drafting

Before epic drafting, the root must produce a finalized Design Packet from the agreed design, user decisions, and ledger dispositions. Incorporate every ADOPTED conclusion into the applicable packet field and carry it into the epic's Requirements (IMMUTABLE), Anti-Patterns (FORBIDDEN), Approach, Validation Strategy, or Delivery Constraints. A READY status permits drafting but is not the contract source.

Draft the epic contract from that finalized Design Packet. Do not copy the Design Ledger itself into the epic, and do not convert ledger IDs into task or plan state; the ledger remains transcript-local.

---

4. Create the Epic Task

After design is validated, create epic as immutable contract. See TEMPLATES.md for the full template with all sections.

4. Present the Epic Contract

After design is validated, author the immutable contract and present it in full in the root transcript. See TEMPLATES.md for the complete template. The epic is not a native plan step.

Required epic sections:

Section	Purpose
Requirements (IMMUTABLE)	Specific, testable conditions that must be true
Success Criteria	Objective, checkable items including "all tests passing"
Anti-Patterns (FORBIDDEN)	Explicitly forbidden patterns with reasoning
Quality Bar	gambit's fixed maximal standard for "good code" — the highest professional quality, written verbatim into every epic and judged against each diff by reviewers and the orchestrator at every checkpoint, beyond the objective Success Criteria
Approach	2-3 paragraph summary of chosen approach
Approaches Considered	Rejected alternatives with DO NOT REVISIT conditions
Delivery Constraints	Circuit breakers for non-convergence, repeated repairs, and scope growth
Validation Strategy	Focused worker command, wave/component gate, release acceptance, freshness, and acceptance budget
Scope Boundaries	What this epic does and does not cover — read by executing-plans at the release architecture/scope preflight

TEMPLATES.md is canonical for both templates. The skeletons below are abbreviated for reading; emit from TEMPLATES.md so no required section is dropped.

The Quality Bar is fixed — write it verbatim, don't elicit it. Every epic carries the same bar: the highest professional standard, the code a master engineer would ship — elegant, complete, built on a superb foundation. It is not a per-project preference and is never negotiated down. Copy it verbatim from TEMPLATES.md into the epic so the checkpoint gate and reviewers have it locally. It governs craftsmanship, not scope — how well the required work is built, never how much of it; project-specific prohibitions go in Anti-Patterns. It sits on top of the mechanical floor the worker contract enforces (no suppression, no weakened tests, no dead code).

<!-- gambit-backend:claude -->
TaskCreate
  subject: "Epic: [Feature Name]"
  description: |
<!-- /gambit-backend -->
<!-- gambit-backend:codex -->
Present in the root transcript as "Epic: [Feature Name]":
<!-- /gambit-backend -->
    ## Requirements (IMMUTABLE)
    - Requirement 1: [concrete, testable]

    ## Success Criteria (MUST ALL BE TRUE)
    - [ ] [objective criterion]
    - [ ] All tests passing

    ## Anti-Patterns (FORBIDDEN)
    - NO [pattern] (reason: [why])

    ## Quality Bar
    The highest professional standard — code a master engineer would ship: elegant, complete,
    built on a superb foundation. Fixed for every epic; copy it verbatim from TEMPLATES.md.

    ## Approach
    [2-3 paragraph summary]

    ## Approaches Considered
    ### [Rejected Approach] - REJECTED
    REJECTED BECAUSE: [reason]
    DO NOT REVISIT UNLESS: [condition]

    ## Delivery Constraints
    - Stop after two consecutive non-converging checkpoints; require explicit user approval
      before expanding scope, architecture, or budget. Repairs ladder up to terminal
      escalation attempts repeated with updated evidence until the defect clears.

    ## Validation Strategy
    - Focused worker command: [fast exact command]
    - Wave/component gate: [integrated exact command]
    - Release acceptance: [fresh expensive exact command]
    - Acceptance budget: [normally one final run]