Brainstorming

---
name: brainstorming
description: Use before planning or implementation for one bounded feature, roadmap outcome, behavior, app, site, tool, component, UI, API, workflow, or architecture change
---

# Brainstorming

Brainstorming turns one bounded goal into one architecture-aware Design Spec.
It owns feature-level design and any prospective Foundation change caused by
that design. It does not implement code.

Read `using-superpowers`, applicable instructions, the workflow policy,
artifact lifecycle, Foundation lifecycle when present, and Architecture
Conformance before writing.

## Entry

1. Resolve **Approval Policy** from the applicable version-2 owner. Autonomous
   is the default for new and existing work; Review-gated requires a new
   explicit opt-in. Migrate active legacy gate clauses through `workflow
   migrate` before they block this phase.
2. Resolve the durable **Phase Mode** independently. Preserve an existing
   choice. Ask only if none exists and the choice materially matters.
3. Determine whether this is:
   - a Foundation-backed ready `OUT-NNN` outcome received through a valid v2
     handoff or same-session reread; or
   - one generic bounded design unit with no Foundation.
4. Validate the exact source input once with explicit policy. For a handoff,
   require the full v2 envelope and receiver checks. A v1 receiver rejects Ready.
5. Read relevant code, tests, docs, and instructions from disk. For a
   Foundation-backed outcome, read Root Router, manifest-selected owners,
   Blueprint requirements, prior decisions, roadmap section, and canonical
   prompt.
6. If discovery reveals project-wide reorientation, release-boundary change, or
   several affected outcomes, return to `wayfinder`.

## Understand the Design

Ask one concise question at a time only when the answer is not available on disk
and materially affects the outcome. Put the question first, then provide one
concrete recommendation and a short reason.

Resolve:

- observable goal and acceptance criteria;
- non-goals and scope boundary;
- user-facing behavior and failure behavior;
- preferred language and rejected synonyms;
- modules, interfaces, seams, adapters, data flow, depth, locality, leverage,
  and public test surface;
- business, safety, privacy, security, data, and external-action constraints;
- migration and compatibility needs;
- relevant prior decisions and Blueprint requirement identities; and
- durable documentation impact.

When several materially different designs remain, compare two or three concise
options and recommend one. Ask the user only when the choice changes the
authorized goal, product behavior, risk boundary, or another consequential
constraint. Under Autonomous, ordinary architecture and technical choices
within the bounded goal are agent-owned and recorded in the spec.

Do not offer a visual companion. Do not create ADR, PRD, issue, or triage flows.

## Write the Design Spec

Save the local artifact under
`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`. Keep it ignored and
unstaged.

Use this shape:

```markdown
# <Title> Design Spec

**Source:** <request, roadmap outcome, and authoritative constraint source>
**Date:** YYYY-MM-DD
**Artifact Type:** Design Spec
**Status:** Draft
**Revision:** none
**Approved Revision:** none
**Approved At:** none
**Approval Policy:** Autonomous | Review-gated
**Workflow Policy Version:** 2
**Phase Mode:** Automated fresh-session mode | Same-session mode

## Problem
## Goal
## Non-Goals
## Design Understanding
### Language
### Architecture
### Key Decisions
### Open Risks
## Foundation Traceability
**Foundation Manifest:** <absolute WAYFINDING.md path or none>
**Base Agentic Foundation:** <exact revision or none>
**Roadmap Outcome:** <OUT-NNN or none>
**Blueprint Requirements:** <identities or none>
**Prior Decisions:** <identities or none>
## Durable Documentation Impact
## Foundation Candidate Declaration
## User-Facing Behavior
## Implementation Shape
## Testing Strategy
## Acceptance Criteria
```

Every design decision receives a stable `DDI-NNN` row and exactly one
classification:

- **Task-local:** authoritative in this Design Spec;
- **Project-durable:** updates a focused Foundation current-truth owner and
  appends immutable Decision Ledger evidence;
- **Operating-contract:** updates the exact AGENTS.md owner and affected parent
  Child DOX indexes;
- **No impact:** requires no durable change.

Each row gives a concrete classification reason, owner, and candidate action
identity or `none`. Task-local and No impact rows use `none`.

The fenced declaration is exact JSON:

```json
{
  "schema": "superpowers-architecture-foundation-declaration-v1",
  "actions": []
}
```

For durable changes, use unique sorted `FCA-NNN` actions with normalized paths,
`upsert|delete`, and sorted nonempty decision references. Project-durable
decisions include both their current-truth owner and a
`docs/agentic/DECISIONS.md` upsert. Operating-contract changes include their
exact AGENTS.md owner and affected indexes. Managed-file or reading-order
changes include the manifest/router consequence. Empty declarations include
the exact unfenced sentence `No durable documentation changes`.

## Lifecycle and Foundation Candidate

Run `artifact draft` before changing an existing generic spec and
`artifact refresh` after writing. Never type a revision manually.

For a generic spec:

1. refresh the exact Draft revision;
2. review the spec through the advisory reviewer or deterministic equivalent;
3. resolve issues through Draft and refresh;
4. under Autonomous, run `artifact ready`;
5. under Review-gated, present one readable package and after clear approval run
   `artifact approve`.

For a Foundation-backed spec:

1. keep the Design Spec Draft while preparing complete ignored candidate files
   under `docs/superpowers/foundation-candidates/`;
2. include exact current-truth, immutable ledger, AGENTS.md, manifest, and Root
   Router consequences declared by the spec;
3. run policy-aware `foundation preview` against the exact policy-accepted base
   and exact Draft spec;
4. inspect operation-owned `candidate.json` and
   `DESIGN-CHANGE-SET.md`; require declaration/candidate equality and no
   missing, extra, duplicate, conflicting, unreferenced, or no-op action;
5. run one combined advisory review against the spec, prospective Foundation,
   readable change set, and Architecture Conformance;
6. repair all issues, re-refresh, and re-preview whenever bound bytes change;
7. under Autonomous, apply the exact reviewed change set with explicit policy;
   apply records the spec/result as Ready and emits the v2 receipt;
8. under Review-gated, present the combined readable package once. After a clear
   approval of that displayed package, bind the response internally and apply
   with Review-gated; apply records real Approved provenance.

Reviewers return `Ready for progression` under Autonomous,
`Ready for user review` under Review-gated, or `Issues found`. They never
approve or mutate artifacts.

An empty Foundation action set must preserve all Foundation bytes and lifecycle
timestamps while still producing valid policy-bound application evidence when
the operation requires it.

## Progress to Planning

Before Planning, validate:

- the exact Design Spec with explicit Approval Policy;
- for Foundation-backed work, the exact base, v2 Application Receipt, resulting
  Foundation, declaration/actions, and lifecycle states;
- every acceptance criterion, constraint, architecture binding, and Foundation
  traceability field; and
- ignored local state and exact checkout affinity.

For automated fresh-session mode, prepare the v2 Planning envelope. The Design
Spec is the phase artifact; the source-spec pair is `none`. Carry Foundation
manifest/result and receipt outside the record when applicable. The bounded goal
and authoritative constraint source remain in the envelope. Launch only through
a runtime that proves genuine fresh user-owned same-checkout identity, then
inspect acknowledgement and `handoff receive`.

For same-session mode, re-read the policy-accepted spec, applicable Foundation
and receipt, instructions, and relevant code from disk, then invoke
`writing-plans`. Reuse unchanged entry evidence; revalidate mutations.