brainstorming
The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation.
What it does
Section titled “What it does”This is where a feature starts before any code exists. /feature opens here, and /sprint’s
planning stage runs the same interview. Given a one-line idea, it drives a Socratic
back-and-forth — one question at a time — until the idea is concrete enough to build from: a
named problem, a named caller, an explicit boundary of what the feature does not do, and a set
of acceptance criteria specific enough that each one maps to a single test. Anything genuinely
unresolved becomes a numbered open question on record rather than a guess.
Phases
Section titled “Phases”- The problem, its caller, and the out-of-scope boundary are pinned down and checked against the project’s existing context for a contradiction.
- A question-at-a-time refinement loop closes every vague term, surfaces hidden complexity, and forces any real trade-off to a resolution or a recorded open question.
- The agreed spec — problem, scope, testable acceptance criteria, open questions — is written to disk.
- The spec is approved (by you directly, or by a logged automatic approval under an autonomous sprint) before anything moves on to test-first implementation.
Approval hands the spec to the test-first gate, where each acceptance criterion becomes one obligation to prove. A spec carrying an unresolved blocking question never reaches that handoff — it stops for your decision instead.
| Gate | When | Effect |
|---|---|---|
| frame the problem | at the start of a new feature idea | the one-line idea must resolve to a stated problem, caller, and out-of-scope boundary before questioning begins |
| spec approval | after the spec is drafted | hard stop until you (or, under an autonomous sprint, a logged auto-approval) sign off; no code and no handoff to test-first work happens before that |
Related
Section titled “Related”Source
Section titled “Source”Source — plugins/ca/skills/brainstorming/SKILL.md (v2.9.1)
---name: brainstormingdescription: The Socratic spec-refinement front of /feature, and the planning front of /sprint. Routed to BEFORE any code — it takes a one-line idea and drives it to an approved, concrete spec with testable acceptance criteria. Four gated phases — frame, refine, write, approve. No implementation and no handoff to tdd until the spec is on disk and approved; each acceptance criterion becomes one tdd Phase 1 obligation.---
# brainstorming
Refine the idea before it touches code. Routed to by `/feature` (before `tdd`) and by `/sprint` (the planning front).
## Pre-flight
Read these, or STOP and surface the gap — never guess scope or stack:
- `${CLAUDE_PROJECT_DIR}/.codearbiter/CONTEXT.md` — the `stage:` frontmatter (the maturity value), domain vocabulary, and what the project is NOT building.- `${CLAUDE_PROJECT_DIR}/.codearbiter/tech-stack.md` — the stack the feature must fit; rule out incompatible designs early.- `${CLAUDE_PROJECT_DIR}/.codearbiter/open-questions.md` — existing `[CONFIRM-NN]` items; new ones number sequentially from here.
Per-feature and light. NOT decompose's whole-project six-layer interview — one feature, four phases.
## Phase 1 — Frame the problem · gate: BLOCK
Take the one-line idea and pin its boundaries before asking anything else:
- State the problem in one sentence — the concrete pain, not the proposed solution.- Name the user or caller who feels it, and what "done" looks like to them.- Name what this feature explicitly does NOT do — the boundary that keeps scope honest.- Check the framing against `CONTEXT.md`: it never contradicts the NOT-building list or redefines domain vocabulary. A contradiction is a conflict — surface it, do not reconcile it silently.
Gate: problem, caller, and out-of-scope boundary stated and consistent with `CONTEXT.md`.
## Phase 2 — Socratic refinement loop · gate: BLOCK
One focused question at a time. Never advance on a hand-wavy answer. Run every answer through three lenses:
- **Vague language** — Force concrete nouns, numbers, and verbs. "Manage", "handle", "support" are not verbs. "Fast", "secure", "scalable" are not specifications. "We'll figure it out later" is not an answer — every "later" becomes a `[CONFIRM-NN]`.- **Hidden complexity** — Name what the user assumes is easy but is hard: state, concurrency, edge cases, failure modes, validation, idempotency, migration of existing data. Surface it now or it surfaces in `tdd`.- **Trade-off forcing** — When a real decision exists, frame it: "X gives you A but costs B; Y gives you C but costs D — choose." Do not pick for the user.
Record every genuinely-unresolved unknown as `[CONFIRM-NN]` in `${CLAUDE_PROJECT_DIR}/.codearbiter/open-questions.md`, numbered sequentially. A finding that belongs to a different feature or a future scope gets an inline `[NEEDS-TRIAGE]` marker in the notes — never route it to a ticket.
Gate: every vague term made concrete; every forced trade-off resolved or recorded as `[CONFIRM-NN]`; no unresolved "later" outside a `[CONFIRM-NN]`. A blocking `[CONFIRM-NN]` that gates the spec's core stops the loop — surface it and STOP.
## Phase 3 — Write the spec · gate: BLOCK
Write the agreed spec to `${CLAUDE_PROJECT_DIR}/.codearbiter/specs/<slug>.md`. The slug is derived from the feature. The spec holds:
- **Problem** — the Phase 1 framing in final form.- **Scope** — what is in, and the explicit out-of-scope boundary.- **Acceptance criteria** — a numbered list, each criterion concrete and testable: a specific input, the observable output, the boundary or failure behavior. Each criterion is verifiable by a single test. "It works well" is not a criterion. These become `tdd` Phase 1 obligations — one obligation per criterion, so an untestable criterion is a defect to fix here, not in `tdd`.- **Open questions** — every `[CONFIRM-NN]` raised, cross-referenced to `open-questions.md`.- **Governs** *(optional)* — a spec-header line `**Governs:** <comma-separated globs>` that enrolls the approved spec in file-scoped just-in-time context injection: on a Read of any file matching one of the listed globs, a pointer to this spec is surfaced to the agent (tier 3 of the file→knowledge map). Adding the line is sufficient to enroll; no other change required.
Gate: the spec file exists on disk under `specs/`, with at least one acceptance criterion and every criterion individually testable.
## Phase 4 — Approval & handoff · gate: STOP
The spec is approved before any code is written or any handoff to `tdd` occurs — no exceptions:
- **Under `/feature`** — present the spec and request explicit user approval. Iterate on the file in place until the user approves. A blocking `[CONFIRM-NN]` must be resolved by the user before approval — never auto-resolve it.- **Under `/sprint`** — approval may be granted automatically by SMARTS scoring, logged to the `.codearbiter/` audit trail. A blocking `[CONFIRM-NN]` is never auto-approvable; it escalates to the user and STOPs the sprint flow.
On approval, hand off to the `tdd` skill, which enters Phase 1 against the approved spec — one obligation per acceptance criterion.
Gate: the spec is approved (by the user under `/feature`, or by logged SMARTS auto-approval under `/sprint`) with no unresolved blocking `[CONFIRM-NN]`. Only then does control pass to `tdd`.
## Hard rules
- MUST NOT write implementation code or route to `tdd` before the spec is on disk under `specs/` AND approved.- MUST NOT write an acceptance criterion that cannot be verified by a single test.- MUST NOT resolve a `[CONFIRM-NN]` by guessing — surface it and record it in `open-questions.md`.- MUST NOT auto-approve a spec carrying a blocking `[CONFIRM-NN]`, even under `/sprint` — it escalates to the user.- MUST NOT contradict the NOT-building list or redefine domain vocabulary in `CONTEXT.md` — a contradiction is a conflict to surface, not reconcile.- MUST NOT run decompose's six-layer whole-project interview — this is one feature, four phases.- MUST log a `/sprint` auto-approval to the `.codearbiter/` audit trail.- MUST, at exit, run the follow-up harvest (`${CLAUDE_PLUGIN_ROOT}/includes/harvest.md`) over any `[NEEDS-TRIAGE]` notes raised this run — batch-confirm promoting them to `open-tasks.md` (work) or `open-questions.md` (decisions) so out-of-scope ideas don't vanish.