| 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:
- List all directories under
specs/ that contain a spec.xml
- If any exist, present them to the user:
Found existing specs: auth, payments, ...
- 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) 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) 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:
- Problem description / motivation — what problem this solves and why
- Proposed solution / architecture — key design decisions
- Identifiable requirements — things the system must do, in prose (not stubs)
- 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:
- Read
specs/<spec-id>/spec.xml — understand the current spec version and scope
- Read all previous design iterations under
docs/plans/<spec-id>/*/design.md — understand the evolution history
- 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.
- 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.
- 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) 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:
- D-id: D-NNN
date: YYYY-MM-DD
spec_version: N
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:
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:
- 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.
- 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.
- 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:
- "Requirements are clear, can skip questions"
- "Time pressure, need to move fast"
- "These extra features would be good"
- "User will want this eventually"
- "Ask all questions at once for efficiency"
- "This is obvious, no need to explore"
- "Just one more feature won't hurt"
- "I can tell from context whether this is new or iteration" — always ask
- "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
─────────────────────────────────────────────────
