arc-brainstorming

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) 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:

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) 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          # 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:

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
─────────────────────────────────────────────────