From arcforge
Explores ideas before implementation by scanning existing specs, detecting pending conflicts, and routing to new feature design or spec iteration paths.
How this skill is triggered — by the user, by Claude, or both
Slash command
/arcforge:arc-brainstorming [topic or feature to explore][topic or feature to explore]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
**NO DESIGN WITHOUT EXPLORATION FIRST**
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.
Before any elicitation, scan specs/ for existing spec_ids.
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.
If no _pending-conflict.md exists, proceed with the standard confirmation gate:
specs/ that contain a spec.xmlFound existing specs: auth, payments, ..."Iterating on <spec-id> (v<N> active)?""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".
This branch fires when the user confirms a new topic and no specs/<spec-id>/spec.xml exists for the chosen spec-id.
Start with context:
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 directionAsk questions one at a time:
Propose 2-3 approaches with trade-offs:
docs/research/<topic>.md after every 2 search operationsApply YAGNI ruthlessly:
Derive spec-id at end of Phase 2 (when scope is clear — not before):
"Proposed spec-id: <suggestion>. OK?"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.
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.
Present design in 200-300 word sections:
The design doc must contain all four elements:
Validate before writing to disk:
docs/plans/<spec-id>/<YYYY-MM-DD>/design.mdERROR 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
This branch fires when the user confirms iteration on an existing spec-id and specs/<spec-id>/spec.xml already exists.
Before asking the user anything:
specs/<spec-id>/spec.xml — understand the current spec version and scopedocs/plans/<spec-id>/*/design.md — understand the evolution historyspecs/<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.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.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.
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.
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:
print-schema.js)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
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:
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.docs/plans/<spec-id>/<YYYY-MM-DD>[-suffix]/decision-log.yml.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.
When the target folder (docs/plans/<spec-id>/<YYYY-MM-DD>/) already exists before writing:
Present the user with options:
<YYYY-MM-DD>-v2 (sequential same-day iterations)<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.
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.
Stop immediately if you catch yourself thinking:
| 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 |
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.
─────────────────────────────────────────────────
✅ Brainstorm complete → docs/plans/<spec-id>/<YYYY-MM-DD>/design.md (committed)
Next: /arc-refining → /arc-planning → /arc-coordinating
─────────────────────────────────────────────────
─────────────────────────────────────────────────
⚠️ Brainstorm blocked
Issue: [specific missing element]
Location: [design doc section or path]
To resolve:
1. [Specific action]
2. [Specific action]
Then retry: /arc-brainstorming
─────────────────────────────────────────────────
npx claudepluginhub gregoryho/arcforge --plugin arcforgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.