---
name: arc-brainstorming
description: Use when exploring ideas before implementation or when user wants to design a new feature or iterate on an existing spec
argument-hint: "[topic or feature to explore]"
---

# arc-brainstorming

## Iron Law

**NO DESIGN WITHOUT EXPLORATION FIRST**

Never skip to design just because "requirements seem clear" or time is tight. Exploration validates assumptions and uncovers edge cases.

**REQUIRED BACKGROUND:** Read `${ARCFORGE_ROOT}/scripts/lib/sdd-schemas/design.md` before producing any design doc — it carries the canonical schema (required/forbidden sections, heading regexes, enforcement authority), auto-generated from `${ARCFORGE_ROOT}/scripts/lib/sdd-utils.js`'s rule constants. The CLI alternative `node "${ARCFORGE_ROOT}/scripts/lib/print-schema.js" design` produces equivalent content. The same schema covers both branches (prose when no prior spec; Context + Change Intent when prior spec exists); filesystem state decides which conditional fields apply — this is not a "mode" switch.

## When NOT to Use

- Requirements are already clear and documented
- Scope is a single function or small fix
- User says "just do it" or equivalent

## Phase 0: Scan and Route

**Before any elicitation, scan `specs/` for existing spec_ids.**

### Step 0a: Pending-Conflict Detection (fr-bs-008)

**Check for `specs/<spec-id>/_pending-conflict.md` FIRST, before the new-vs-iterate confirmation gate.**

If `specs/<spec-id>/_pending-conflict.md` exists at the start of Phase 0, brainstorming MUST automatically enter the iterate branch — DO NOT ask "new spec or iteration?". This is the explicit exception carved out in `fr-bs-002-ac3`: the iterate-branch target is determined by filesystem state per `fr-bs-008-ac1`, and the user-consent gate is satisfied by the resolution-pick prompt in `fr-bs-008-ac2` — no separate "new spec or iteration?" confirmation is asked.

**Loading the conflict (fr-bs-008-ac1):**

Use `parseConflictMarker(filePath)` to load the file. It returns `{ axis_fired, conflict_description, candidate_resolutions, user_action_prompt }`. Treat the conflict body (`conflict_description` + cited design line ranges / Q&A `q_ids`) as the Change Intent seed. The canonical file path is `specs/<spec-id>/_pending-conflict.md` (from `PENDING_CONFLICT_RULES.canonical_path`).

**Presenting resolutions (fr-bs-008-ac2):**

Present `candidate_resolutions` to the user VERBATIM from the pending file — do not paraphrase. Prompt:

> "pick (a), (b), (c), or describe your own"

The user does not retell the conflict; brainstorming does not re-derive the conflict from scratch.

**Read-only constraint (fr-bs-008-ac4):**

Phase 0's conflict-detection branch MUST NOT modify or rewrite `_pending-conflict.md` content — the file is read-only from brainstorming's perspective. Any framing changes happen in the new `design.md`, not by editing the handoff file.

**Deletion on success (fr-bs-008-ac3):**

After the user picks (or describes) a resolution AND brainstorming successfully writes the new `design.md` to `docs/plans/<spec-id>/<NEW-DATE>/design.md`, brainstorming MUST delete `specs/<spec-id>/_pending-conflict.md`. Cleanup is gated on successful write — if the design write fails, the pending file persists for retry and MUST NOT be deleted.

---

### Step 0b: Standard New-vs-Iterate Confirmation

If no `_pending-conflict.md` exists, proceed with the standard confirmation gate:

1. List all directories under `specs/` that contain a `spec.xml`
2. If any exist, present them to the user: `Found existing specs: auth, payments, ...`
3. Ask the user to confirm the target — do NOT auto-detect:
   - If an existing spec matches: `"Iterating on <spec-id> (v<N> active)?"`
   - If this is a new topic: `"New topic — proposed spec-id: <suggestion>. OK?"`

**The user's explicit confirmation determines whether the design doc carries new-topic prose or iteration-context content. Never infer it.**

The downstream refiner detects context from the filesystem (presence or absence of `specs/<spec-id>/spec.xml`). Brainstorming has one behavior with context-sensitive output — it does not invoke a separate code path or "mode".

---

## When No Prior Spec Exists — New Spec

This branch fires when the user confirms a new topic and no `specs/<spec-id>/spec.xml` exists for the chosen spec-id.

### Phase 1: Understanding

**Start with context:**

- Check current project state (files, docs, recent commits)
- If `product/vision.md` exists, read it as context (read-only) — it states the product's long-horizon intent and `P-n` principles, so a new spec aligns with stated direction
- Understand the domain and constraints

**Ask questions one at a time:**

- Only one question per message — if a topic needs exploration, break it into multiple questions
- Prefer multiple choice when possible, but open-ended is fine
- Focus on: purpose, constraints, success criteria
- **Begin buffering the decision-log from your first question here** — these Phase 1 answers are authorization-bearing Q&A the refiner traces against. Assign stable q_ids and hold the rows in session memory; the spec-id is not yet known, so you cannot write to disk yet (see [Decision-Log Output (fr-bs-009)](#decision-log-output-fr-bs-009) for the spec-id-not-yet-determined ordering).

### Phase 2: Exploring

**Propose 2-3 approaches with trade-offs:**

- Present options conversationally with your recommendation
- Lead with recommended option and explain why
- Use 2-Action Rule: Save findings to `docs/research/<topic>.md` after every 2 search operations

**Apply YAGNI ruthlessly:**

- Build only what user explicitly requested
- Remove features beyond stated requirements
- Say no to "nice to have" additions

**Derive spec-id at end of Phase 2** (when scope is clear — not before):

- Propose a kebab-case spec-id based on the topic
- Ask user to confirm or modify: `"Proposed spec-id: <suggestion>. OK?"`
- The spec-id MUST NOT be finalized before Phase 2 completes

**Flush the buffered decision-log once the spec-id is confirmed.** Keep buffering Phase 2 Q&A into the same in-memory rows you started in Phase 1 (stable q_ids continue sequentially). The moment the user confirms the spec-id above, write the buffered rows to `decision-log.yml`, then append incrementally for any later exchanges — see [Decision-Log Output (fr-bs-009)](#decision-log-output-fr-bs-009) for the full ordering. The decision-log is required on this branch too — the refiner's mechanical authorization check runs on new-spec Q&A, not just iterations.

### Phase 2 Decision-Ledger Output (D6)

After the proposed approaches and trade-offs are clear, append a `status: proposed` entry to `specs/<spec-id>/decisions.yml` for each significant design decision. Follow the `DECISION_LEDGER_RULES` field shape (same as the "When Prior Spec Exists" branch above). If `specs/<spec-id>/decisions.yml` does not yet exist, create it as a YAML sequence. The B2 immutability hook enforces append-only on all writes to `decisions.yml`.

### Phase 3: Presenting

**Present design in 200-300 word sections:**

- Ask after each section whether it looks right
- Cover: problem, solution, requirements, scope, architecture, error handling
- Be ready to go back and clarify

**The design doc must contain all four elements:**

1. **Problem description / motivation** — what problem this solves and why
2. **Proposed solution / architecture** — key design decisions
3. **Identifiable requirements** — things the system must do, in prose (not stubs)
4. **Scope declaration** — what is included and what is explicitly excluded

### Phase 3 Output

Validate before writing to disk:

- File path follows `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md`
- Design doc has substantive content (not empty or stub)
- Identifiable requirements present in prose
- Scope declared (includes and excludes)

**ERROR on any missing element — do not write until resolved.**

**If the `docs/plans/<spec-id>/<YYYY-MM-DD>/` folder already exists**, offer the user a suffix to disambiguate (see Same-Day Iteration UX below).

Write to: `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md`

---

## When Prior Spec Exists — Iterating on a Spec

This branch fires when the user confirms iteration on an existing spec-id and `specs/<spec-id>/spec.xml` already exists.

### Phase 1: Load Existing State

Before asking the user anything:

1. Read `specs/<spec-id>/spec.xml` — understand the current spec version and scope
2. Read all previous design iterations under `docs/plans/<spec-id>/*/design.md` — understand the evolution history
3. If `specs/<spec-id>/vision.md` exists, read it as context (read-only). Vision P-n describes the product's long-horizon intent and informs which change directions align with the stated vision. Do NOT write to or modify `vision.md` — it is an input artifact only.
4. If `specs/<spec-id>/decisions.yml` exists, read it as context (read-only). The existing ledger entries show which decisions are already recorded, their rationale, and their current status.
5. Summarize the current state briefly to the user so they have shared context

### Phase 2: Elicit the Change Intent

Ask the user what is changing and why — one question at a time.

Use 2-Action Rule: Save research findings to `docs/research/<topic>.md` after every 2 search operations.

Apply YAGNI ruthlessly: only capture what the user explicitly states is changing.

**Emit the structured decision-log for every Q&A exchange** — see [Decision-Log Output (fr-bs-009)](#decision-log-output-fr-bs-009) below. The spec-id is already known on this branch (confirmed in Phase 0), so the output path resolves immediately; write the decision-log incrementally from the first exchange.

#### Phase 2 Decision-Ledger Output (D6)

After the user's change intent is clear and the key rationale is established, append a `status: proposed` entry to `specs/<spec-id>/decisions.yml` for each significant design decision made during this brainstorming session. Follow the `DECISION_LEDGER_RULES` field shape exported from `${ARCFORGE_ROOT}/scripts/lib/sdd-utils.js`:

```yaml
- D-id: D-NNN          # monotonically increasing, e.g. D-001, D-002
  date: YYYY-MM-DD
  spec_version: N      # current spec version number
  status: proposed
  decision: "<one-sentence statement of the decision>"
  why: "<rationale — what problem it solves and why this choice>"
  authorized_values: "<the specific value or range authorized, or 'any'>"
```

**Append-only:** never edit existing entries — `decisions.yml` is an append-only ledger. The B2 immutability hook will deny any write that modifies a frozen entry's `decision` or `why` text. If a decision changes, record a new superseding entry (`supersedes: D-NNN`) instead of editing in-place.

**Mode-agnostic:** recording `status: proposed` decisions applies to both new-spec and iteration brainstorming sessions.

If `specs/<spec-id>/decisions.yml` does not yet exist, create it as a YAML sequence.

### Phase 3 Output

The design doc carries a Context summary plus a natural-language Change Intent. The downstream refiner reads this alongside `specs/<spec-id>/spec.xml` and **derives the structured `<delta>` itself** — the design doc carries human-authored narrative, never a pre-authored ADDED/MODIFIED/REMOVED list.

**Get the current schema (required reading before writing):**

Read `${ARCFORGE_ROOT}/scripts/lib/sdd-schemas/design.md` directly (primary form), or invoke the equivalent CLI:

```bash
node "${ARCFORGE_ROOT}/scripts/lib/print-schema.js" design
```

Either form yields the canonical design-doc schema — required sections, forbidden sections, heading regexes, and enforcement authority. This is the single source of truth; do NOT reconstruct the schema from memory, and do NOT copy schema content into this skill. The rules live in `${ARCFORGE_ROOT}/scripts/lib/sdd-utils.js` (`DESIGN_DOC_RULES`) and the validator (`validateDesignDoc`) enforces them. If this skill and the validator ever disagree, the validator wins.

**Validate before writing to disk:**

- Context section present (matching the regex printed by `print-schema.js`)
- Change Intent section present
- No pre-authored structured delta section (Added/Modified/Removed/Renamed/Delta)

**ERROR on any missing required section — do not write until resolved.**

**If the `docs/plans/<spec-id>/<YYYY-MM-DD>/` folder already exists**, offer the user a suffix to disambiguate (see Same-Day Iteration UX below).

Write to: `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md`

---

## Decision-Log Output (fr-bs-009)

This contract applies to **both branches**. Every brainstorming session that elicits Q&A — whether a new spec or an iteration on an existing one — MUST emit the Q&A history as a structured decision-log. The refiner's mechanical authorization check (Phase 6) iterates over these rows by `q_id`, so the decision-log is required regardless of which branch produced it.

Brainstorming MUST emit the Q&A history as a structured decision-log in YAML format. The refiner parses this decision-log mechanically via `parseDecisionLog`, so brainstorming MUST NOT emit free-form prose.

**Output path:** `<brainstorming-output-dir>/decision-log.yml`

That is: `docs/plans/<spec-id>/<YYYY-MM-DD>[-suffix]/decision-log.yml`

**Schema source of truth:** Before writing or validating `decision-log.yml`, direct-read `${ARCFORGE_ROOT}/scripts/lib/sdd-schemas/decision-log.md` and follow the `DECISION_LOG_RULES` contract exported via `${ARCFORGE_ROOT}/scripts/lib/sdd-utils.js`. Do not copy a structural template into this skill; the generated schema is authoritative for required fields (`q_id`, `question`, `user_answer_verbatim`, `deferral_signal`), valid/invalid examples, canonical path, and deferral-signal phrases.

**q_id stability rule (fr-bs-009-ac3):**

`q_id` values MUST be stable across the brainstorming session. Assign q_ids sequentially (`q1`, `q2`, `q3`, ...) and persist them across session revisions. Once a question receives `q1`, that q_id MUST NOT be reassigned to a different question within the same session. If a row is added or a question is revised, new rows get the next sequential q_id; existing q_ids stay fixed.

**Deferral-signal detection rule (fr-bs-009-ac4):**

Brainstorming MUST set `deferral_signal: true` according to `DECISION_LOG_RULES.deferral_signal_canonical_phrases` from the generated schema/source constants (currently including `use defaults`, `covered.`, `skip`, and `you decide`). Implementations MAY extend this list with additional deferral phrases, but any extension MUST be documented alongside the decision-log output. The canonical list in `DECISION_LOG_RULES` is authoritative — when the list changes there, the detection rule changes automatically.

**Write the decision-log after each elicitation exchange.** Do not defer writing to the end of Phase 2 — write incrementally so a session interruption does not lose Q&A history.

**When the spec-id is not yet determined (new-spec branch):** the output path depends on `<spec-id>`, which the new-spec branch only confirms at the end of Phase 2. Do not let that ordering drop Q&A rows. Apply this sequence:

1. **Buffer with stable q_ids from the first exchange.** Assign `q1`, `q2`, ... as you elicit and hold the rows in session memory. The q_ids are stable per the rule above, so buffering does not break addressability.
2. **Write on spec-id confirmation.** The moment the user confirms the spec-id, flush the buffered rows to `docs/plans/<spec-id>/<YYYY-MM-DD>[-suffix]/decision-log.yml`.
3. **Append incrementally afterward.** Any later exchanges append to the now-existing file, exactly as the iterate branch does from the start.

Buffering is in-memory session state — it introduces no new on-disk artifact. The iterate branch already knows the spec-id in Phase 0, so it skips straight to step 3's incremental writes from the first exchange.

---

## Same-Day Iteration UX

When the target folder (`docs/plans/<spec-id>/<YYYY-MM-DD>/`) already exists before writing:

Present the user with options:

- **Numeric disambiguator:** `<YYYY-MM-DD>-v2` (sequential same-day iterations)
- **Descriptive suffix:** `<YYYY-MM-DD>-rework`, `<YYYY-MM-DD>-post-review`, `<YYYY-MM-DD>-oauth-pivot` (intent-tagged iterations)

The user picks. The chosen identifier becomes both the folder name and the `design_iteration` written by the refiner later.

The schema accepts any `YYYY-MM-DD(-.+)?` — the suffix is human convention, not a schema constraint.

---

## After the Design (Mandatory)

**1) Write the validated design doc to the confirmed path**

**2) Commit the brainstorming artifacts**

Commit the entire dated plans directory (design.md plus decision-log.yml) and the decision ledger:

```
git add docs/plans/<spec-id>/<YYYY-MM-DD>/
git add specs/<spec-id>/decisions.yml
git commit -m "docs: add <spec-id> design and decision artifacts"
```

If no ledger entries were appended this session and `specs/<spec-id>/decisions.yml` does not exist, skip its `git add` line.

**3) Hand off to refiner**

Always route to `/arc-refining` next:

`/arc-refining` → `/arc-planning` → `/arc-coordinating`

The refiner reads the complete design doc — no structured summary section is needed. The refiner also runs the DAG completion gate before producing a new iteration spec, so if a prior sprint is incomplete it will block.

---

## Red Flags

Stop immediately if you catch yourself thinking:

1. "Requirements are clear, can skip questions"
2. "Time pressure, need to move fast"
3. "These extra features would be good"
4. "User will want this eventually"
5. "Ask all questions at once for efficiency"
6. "This is obvious, no need to explore"
7. "Just one more feature won't hurt"
8. "I can tell from context whether this is new or iteration" — always ask
9. "I'll write a quick ADDED/MODIFIED list to make it easier for the refiner" — forbidden; refiner derives the delta

## Common Rationalizations

| Excuse | Reality |
| -------------------------------- | ------------------------------- |
| "User explained clearly" | Assumptions hide in "clarity" |
| "Time pressure" | Rushing causes rework |
| "Professional solution" | YAGNI violation |
| "Future-proof" | Premature optimization |
| "Batch questions for efficiency" | Overwhelms user, misses context |
| "Requirements are obvious" | Edge cases lurk in obviousness |
| "Better to have it" | Scope creep starts here |
| "Looks like an iteration from context" | Must confirm explicitly with user |
| "I'll pre-author the delta to save the refiner work" | Forbidden — refiner is the diff authority |

## Key Principles

- One question at a time — Don't overwhelm with multiple questions
- Multiple choice preferred — Easier to answer than open-ended when possible
- YAGNI ruthlessly — Remove unnecessary features from all designs
- Explore alternatives — Always propose 2-3 approaches before settling
- Incremental validation — Present design in sections, validate each
- Be flexible — Go back and clarify when something doesn't make sense
- Explicit routing — Always confirm new-topic vs iteration with the user

## After This Skill

Hand off to `/arc-refining` — the refiner reads the committed `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md` and formalizes it into `specs/<spec-id>/spec.xml`. Full SDD pipeline: refining → planning → coordinating.

## Stage Completion Format

```
─────────────────────────────────────────────────
✅ Brainstorm complete → docs/plans/<spec-id>/<YYYY-MM-DD>/design.md (committed)

Next: /arc-refining → /arc-planning → /arc-coordinating
─────────────────────────────────────────────────
```

## Blocked Format

```
─────────────────────────────────────────────────
⚠️ Brainstorm blocked

Issue: [specific missing element]
Location: [design doc section or path]

To resolve:
1. [Specific action]
2. [Specific action]

Then retry: /arc-brainstorming
─────────────────────────────────────────────────
```
