feat(brainstorming): modernize spec refinement for capable models

[SUaDtL]

Implements the accepted slice of #597 (full design rationale and deferred decisions D1-D4 live there).

What changed

The brainstorming skill predated several standing steers and read as written for a weaker model. Five phases now replace four:

1. Frame gains a split-before-you-spend check: an idea bundling independently shippable concerns is decomposed before any question budget is spent.
2. Shape the approach (new): genuine candidate approaches with trade-offs and exactly one recommendation; an explicit no-manufactured-alternatives rule; isolation and YAGNI lenses applied while the design is still soft.
3. Refine rewritten to decide-or-ask: parameter-level choices are decided and recorded in a new "Decided parameters" spec section the user reads at approval; genuine forks are asked in full the first time, recommendation leading, batched when independent. Closure becomes a checklist (a rationalization guard naming the four specific excuses for stopping early, each rebutted), and a breaker stops a non-converging loop and forces one adjudication.
4. Write adds Approach and Decided-parameters sections to the spec.
5. Review, approval & handoff: mechanical self-review of the file as written (placeholder / consistency / boundary / testability / vague-language) plus an adversarial pass whose surviving findings are presented WITH the spec — the user approves a challenged design, not a defended one. Finding nothing is a reportable result, not a silent skip.

Existing mechanics preserved unchanged: CONFIRM-NN, NEEDS-TRIAGE + harvest, Governs enrollment, sprint SMARTS auto-approval + logging, blocking-CONFIRM escalation, tdd handoff.

Surfaces

• core/surface/skills/brainstorming/SKILL.md (canonical) → rendered to all three hosts via build-surface
• core/surface/skills/INDEX.md row updated (was pinning "one question at a time")
• site/src/curated/skills/brainstorming.md (hand-written page, no drift gate) aligned
• Versions: ca 2.11.5, ca-codex 0.4.4, ca-pi 0.2.4 + regenerated root manifest + ca-pi changelog entry (its guard requires one)

Verification

• build-surface --check, sync-core --check: clean
• test_build_surface.py: 40/40
• hooks suite (NO_COLOR unset): 1308 passed, 130 subtests
• site: 512 vitest passed, typecheck clean, build 134 pages, link-audit 20057 links OK
• payload gates: ca OK, ca-codex OK, pi guard OK (version + changelog + root metadata advanced together)

https://claude.ai/code/session_01QjJeSbcwPHwMmd6CEZeagB

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 563abc48-cbc5-4e7f-8450-1613bc3f5050

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@core/surface/skills/brainstorming/SKILL.md`:
- Around line 43-63: Clarify the Phase 3 artifact lifecycle in the brainstorming
instructions: either define where the running spec draft exists before Phase 4,
or revise the references in the “Decide the parameters” bullet, the Phase 3
gate, and the later Phase 3 guidance to say decisions are tracked for inclusion
in the Phase 4 spec. Keep the wording consistent across all three references so
agents can satisfy the gate before “Write the spec.”

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 54761dd5-aee4-4a4c-a51a-c16a2a7ff350

📥 Commits

Reviewing files that changed from the base of the PR and between d30f2f2 and ec65f88.

⛔ Files ignored due to path filters (6)

• plugins/ca-codex/routines/INDEX.md is excluded by !plugins/ca-codex/routines/**
• plugins/ca-codex/routines/brainstorming/SKILL.md is excluded by !plugins/ca-codex/routines/**
• plugins/ca-pi/routines/INDEX.md is excluded by !plugins/ca-pi/routines/**
• plugins/ca-pi/routines/brainstorming/SKILL.md is excluded by !plugins/ca-pi/routines/**
• plugins/ca/skills/INDEX.md is excluded by !plugins/ca/skills/**
• plugins/ca/skills/brainstorming/SKILL.md is excluded by !plugins/ca/skills/**

📒 Files selected for processing (10)

• CHANGELOG.md
• README.md
• core/surface/skills/INDEX.md
• core/surface/skills/brainstorming/SKILL.md
• package.json
• plugins/ca-codex/.codex-plugin/plugin.json
• plugins/ca-pi/CHANGELOG.md
• plugins/ca-pi/package.json
• plugins/ca/.claude-plugin/plugin.json
• site/src/curated/skills/brainstorming.md

📜 Review details

🧰 Additional context used

📓 Path-based instructions (2)

core/**

⚙️ CodeRabbit configuration file

This is the single source of truth for all three host plugins. tools/sync-core.py copies core/pysrc/*.py byte-identically into each plugin's hooks/ directory, and tools/build-surface.py renders core/surface/ into each plugin's commands, skills, routines, agents and includes, following core/hosts.json. CI fails the build if any copy drifts from its source. Never suggest editing a file under plugins/ to fix a defect — the fix belongs in core/ and the copies are regenerated from it. Report each defect once, against the core/ file, and do not note that the same issue appears in a vendored copy.

Files:

• core/surface/skills/INDEX.md
• core/surface/skills/brainstorming/SKILL.md

**/*.md

⚙️ CodeRabbit configuration file

Prose in this repo is part of the product — skills and commands are read and executed by agents, so an ambiguous instruction is a defect, not a style nit. Prioritise findings where prose and the mechanism it describes disagree, where a documented command or flag no longer exists, or where an instruction cannot be followed literally without a contradiction. Deprioritise wording, tone and formatting preferences.

Files:

• core/surface/skills/INDEX.md
• CHANGELOG.md
• README.md
• site/src/curated/skills/brainstorming.md
• plugins/ca-pi/CHANGELOG.md
• core/surface/skills/brainstorming/SKILL.md

🪛 LanguageTool

core/surface/skills/brainstorming/SKILL.md

[style] ~96-~96: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... before any question budget is spent. - MUST NOT manufacture alternatives in Phase 2...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~97-~97: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sane approach exists, say so and why. - MUST NOT write an acceptance criterion that ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~98-~98: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... cannot be verified by a single test. - MUST decide parameter-level choices and reco...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~99-~99: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e an open decision without asking it. - MUST stop a non-converging refinement loop a...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~100-~100: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...is a breaker, not a prompt to circle. - MUST run the Phase 5 mechanical self-review ...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~101-~101: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...the adversarial findings at approval. - MUST NOT resolve a [CONFIRM-NN] by guessin...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~102-~102: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...and record it in open-questions.md. - MUST NOT auto-approve a spec carrying a bloc...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~103-~103: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: .../sprint — it escalates to the user. - MUST NOT contradict the NOT-building list or...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~104-~104: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...a conflict to surface, not reconcile. - MUST NOT run decompose's six-layer whole-pro...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🪛 SkillSpector (2.4.4)

core/surface/skills/brainstorming/SKILL.md

[warning] 98: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

---

[warning] 102: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

---

[warning] 98: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

---

[warning] 102: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

🔇 Additional comments (10)

core/surface/skills/brainstorming/SKILL.md (1)

1-42: LGTM!

Also applies to: 64-104

core/surface/skills/INDEX.md (1)

17-17: LGTM!

site/src/curated/skills/brainstorming.md (1)

7-10: LGTM!

Also applies to: 17-23, 27-40

CHANGELOG.md (1)

15-24: LGTM!

README.md (1)

13-13: LGTM!

Also applies to: 122-122

package.json (1)

3-3: LGTM!

plugins/ca-codex/.codex-plugin/plugin.json (1)

4-4: LGTM!

plugins/ca-pi/CHANGELOG.md (1)

7-12: LGTM!

plugins/ca-pi/package.json (1)

3-3: LGTM!

plugins/ca/.claude-plugin/plugin.json (1)

5-5: LGTM!