superplan-brainstorm

name	superplan-brainstorm
description	Use when routed repo work still has meaningful ambiguity about behavior, constraints, taste, or acceptance intent, and that ambiguity would make planning or execution unsafe.

Brainstorming

Overview

Turn real ambiguity into an approved design before planning or execution proceeds.

This skill is for expectation discovery, not decomposition theater.

In Superplan, superplan-brainstorm is a support discipline skill. It does not decide whether Superplan should engage, and it does not own the full shaping phase.

If this skill appears to be the first lane for a repo-work request, stop and hand control back to superplan-entry or the current owning workflow phase.

Hard Gate

Do not invoke implementation skills, shape broad work, or start execution until a design has been presented and approved.

This applies even when the work looks small.

If the right design is only three sentences, write three sentences. Do not skip the design because the work feels obvious.

Anti-Pattern: "This Is Too Simple To Need A Design"

That is rationalization.

Simple work often hides:

• unstated acceptance intent
• taste sensitivity
• hidden constraints
• wrong assumptions about what "done" means

Small work may need a short design. It does not get to skip design discipline.

Trigger

Use when:

• a workflow skill has already established that design clarification is the next blocker
• hidden expectations make direct shaping unsafe
• the user wants something built, changed, or clarified but key constraints are still implicit
• taste, product, or acceptance risk is high enough that the wrong early assumption would increase blast radius
• multiple materially different approaches exist and the trade-off needs approval before planning
• the next blocker is target clarity rather than execution sequencing

Stay Out

Do not use when:

• the request is a simple explanation or answer
• this is first-contact repo work and no workflow skill has routed into design clarification yet
• the work is already clear enough for proportional shaping
• the ambiguity is casual ideation with no durable artifact, visibility, or reusable-context benefit
• superplan-entry or superplan-route still needs to decide whether Superplan should engage
• the real problem is missing workspace context, which belongs to superplan-context
• the real problem is execution trajectory or artifact depth, which belongs to superplan-shape

Ordered Process

1. Confirm that a workflow skill has already routed here and that design clarification is the current blocker.
2. Explore repo context first.
3. Confirm the ambiguity is real and durable enough to justify superplan-brainstorm.
4. If the request is overscoped, decompose it before deeper refinement.
5. Ask one high-leverage question at a time.
6. Propose 2-3 approaches with trade-offs and a recommendation.
7. Present the design in sections scaled to complexity.
8. Get explicit approval before planning or execution.
9. Write the minimum durable design artifact.
10. If a substantial spec artifact was written, ask the user to review that artifact before moving on.
11. Hand control back to the owning workflow phase, usually superplan-shape.

Do not reorder this flow casually.

Context-First Rules

• inspect repo files, docs, nearby code, and existing Superplan artifacts before asking questions the workspace can already answer
• if this is clearly first-contact repo work, return to superplan-entry instead of continuing
• treat the user's raw narrative as signal, not noise
• prefer one high-leverage question at a time
• ask only questions whose answer materially changes the path
• if the repo already contains a strong pattern or constraint, incorporate it into the design instead of rediscovering it conversationally

Overscope Detection

Before asking detailed questions, check whether the request actually contains multiple independent systems, workstreams, or product surfaces.

If it does:

• say so explicitly
• decompose the request into smaller designable units
• identify the best first slice to design
• do not pretend one clean design can safely cover everything at once

Design Content Guidance

Scale the design to the work.

For small work, the design may be brief. For larger or riskier work, cover the parts that materially prevent wrong execution, such as:

• target behavior or user outcome
• meaningful constraints and non-goals
• major approach trade-offs
• interface, workflow, or contract shape when relevant
• error, edge-case, or risk handling when relevant
• what evidence will later prove the design was implemented correctly

Do not expand this into boilerplate for its own sake.

Public Reasoning Rules

Keep the thinking visible in a user-helpful way.

• This skill runs in planning mode.
• lead with your best read of the user's actual intention, not just the literal wording of the request
• be explicit about what signals, tensions, or hidden expectations are driving the design question
• when alternatives are real, always show the approaches and recommend one
• take positions; avoid bland summaries that only repeat uncertainty back to the user
• keep the conversation focused on product, UX, technical trade-offs, and acceptance intent rather than Superplan process
• do not hide behind control-plane terseness here; the user should be able to see the real alternatives, recommendation, and trade-off logic

The goal is not to expose raw chain-of-thought. The goal is to make the important reasoning legible: what you think the user wants, what options exist, and which direction you recommend.

Durable Output Rules

Conversation is not durable enough by itself when future shaping or execution depends on the result.

Write the minimum durable artifact that preserves the approved truth:

• use superplan change spec set <change-slug> --name <spec-slug> --stdin --json when target behavior, interface expectations, or acceptance intent need durable capture
• use superplan change plan set <change-slug> --stdin --json when the main clarified output is trajectory, sequencing, or execution path
• use superplan context log add --kind decision --content "..." --json when the durable fact is an approved trade-off, preference, or boundary choice

Do not force a spec file for tiny or obvious work. Do not skip the design-write step just because the conversation already contains the reasoning.

Artifact Review Gate

Approval of the design is always required before planning proceeds.

If the design produced a substantial spec artifact, ask the user to review that artifact before moving into planning.

Do not force a written-artifact review loop when no meaningful artifact was created.

Boundary With superplan-shape

superplan-brainstorm clarifies the target.

superplan-shape still owns:

• artifact depth
• graph structure
• autonomy class
• interruption points
• re-shape triggers
• verification-path shaping
• the decision to hand off to superplan-plan or superplan-execute

superplan-brainstorm may recommend that a spec is needed. It must not silently absorb the full shaping phase.

Forbidden Behavior

• jumping straight to tasks before the target is understood
• acting as the first lane for repo work that should still go through superplan-entry or superplan-route
• asking low-value questions the workspace can answer
• skipping the approval loop because the work seems obvious
• treating "I can code this" as proof that the design is understood
• forcing a universal spec -> plan -> tasks ritual
• writing a large spec when a decision log entry or short plan update would preserve the truth just as well
• slipping into superplan-shape, execution, or completion review responsibilities

Decision And Gotcha Rules

Use .superplan/decisions.md when:

• the user approves a meaningful design choice
• a trade-off changes the expected trajectory
• a clarified expectation will matter to later agents
• the boundary of scope or non-goals is explicitly set

Use .superplan/gotchas.md when:

• the same ambiguity trap is likely to recur
• the repo has a misleading pattern that causes repeated wrong assumptions
• a design misunderstanding would predictably waste future work

Do not log every clarifying answer. Do not record transient conversation detail as durable memory.

Handoff

The normal next step is to return control to the owning workflow phase, usually superplan-shape.

If approval is still missing, stop and get it. If the real blocker turns out to be stale workspace context, route back toward superplan-context. If the request collapses into already-clear tiny work, return control to the owning workflow phase rather than forcing more ceremony. If the owning workflow phase has already established that the next blocker is execution sequencing rather than artifact depth, that phase may invoke superplan-plan.

Validation Cases

Should trigger:

• ambiguous feature request with hidden taste risk
• bounded feature where multiple viable approaches differ materially
• brownfield change where repo context answers some questions but acceptance intent is still unclear
• request that sounds singular but actually hides multiple workstreams

Should stay out:

• direct explanation-only requests
• first-contact Superplan repo work where entry routing has not happened yet
• casual ideation with no durable workflow value
• tiny already-clear work where proportional shaping can proceed directly
• cases where the real missing prerequisite is context bootstrap rather than design clarification

Should fail if:

• it becomes the first lane for repo work that should still route through superplan-entry
• it skips context inspection and asks avoidable questions
• it asks multiple low-leverage questions in one burst
• it presents only one path when real alternatives exist
• it hides the useful reasoning behind a thin summary of the user's intentions
• it proceeds without approval
• it forces a spec file when a smaller durable artifact would do
• it turns into superplan-shape or execution