docs(spec): SKILL brain structure — mode-based vs connector-based (direction proposal)

[jordanrburger]

Direction-setting proposal — for review, no decision baked in and no implementation here. This sets the long-term shape of how every Scout instance's brain is organized, so it's deliberately up for debate. Companion to #149/#150/#152.

The fork

Scout has two brains that diverged in structure: a running vault's SKILL.md is mode-based (organized by run mode), the engine is connector-based (per-connector sections + a Run Modes dispatch table). They don't match, so every /scout-update that touches the brain throws a merge conflict, and the regenerated runner references a "Run Modes table" the mode-based brain lacks. Worth settling deliberately.

What the proposal does

1. Lays out all three structures concretely (mode-based / connector-based / hybrid).
2. Genuinely evaluates them on six criteria, weighted toward vault↔engine convergence, self-improvement-loop fit, distributability (legibility explicitly de-prioritized — the main argument for mode-based).
3. Recommends connector-based from that analysis — it ends the merge tax by construction and is the shape the modular self-improvement loop + the optional-connector catalog are built for. The honest cost is human legibility, flagged for you to challenge.
4. Migration = upstream-first: finish porting the vault's ~24 Patterns + capabilities into the engine's connector phases (partly done), then the vault re-renders and adopts — convergence by construction, no risky local re-graft.
5. Zero-loss gate: a completeness checklist (every Pattern/capability/mode-behavior present in the engine brain before adoption) + behavioral dry-run validation of all three modes.

Asking reviewers

• Is connector-based actually right — or does de-prioritized legibility (human-graspability for trust/debugging) matter more long-term?
• Acceptable that the migration is gated on finishing the upstream effort?
• The validation harness (safely dry-running the three modes) needs design — thoughts?

Spec: docs/superpowers/specs/2026-06-22-skill-brain-structure-direction-design.md

🤖 Generated with Claude Code

[jordanrburger]

Design review — SKILL brain structure (mode- vs connector-based)

Verdict: 🟡 Merge with minor changes — relabel from RFC to an Accepted ADR

The analysis is sound and the divergence-tax framing is accurate (a mode-based vault brain vs connector-based phases/ causes a 3-way-merge conflict on every /scout-update, and the regenerated runner references a Run Modes table the mode-based brain lacks). But the recommended connector-based architecture has already been built and shipped: phase_assembly.py + bootstrap.py assemble phases/{connectors,core,modes,research}/ with section-level mode filtering, and phases/core/00-run-modes.md is the live dispatch table. This PR's only commit sits on top of the briefing-mode-layer commit (ced9247, #153) — i.e. it was authored one day after the layer it "proposes" shipped.

So as a forward-looking RFC ("is connector-based actually right?") it would plant a permanently false signal that the architecture is still undecided. As a design-rationale record it's genuinely valuable — the clearest single explanation of why Scout went connector-based and what trade-off (human legibility) was consciously accepted. Keep it, relabeled:

1. Header Status: Proposed (direction) — for review → Status: Accepted — implemented, with the decision date and the PRs that executed it (briefing-mode #153/ced9247, the connector phases/ backport, etc.).
2. Add a one-line "Implementation status" banner at the top.
3. Convert the "Asking reviewers / open questions" section into "decisions taken / accepted trade-offs."
4. Correct the migration inventory — some listed-as-pending items already landed (e.g. phases/core/monday-preview.md, weekend scope in 00-run-modes.md); the genuinely-remaining items are a personal-text connector phase and the ~24-Pattern port.

Don't merge as-is — the "for review / is this right?" framing is the problem, not the content. (Alternative, if the team prefers immutable RFCs: fold the rationale into 2026-06-21-briefing-mode-layer-design.md instead.)

_{🤖 Claude Code-assisted design review.}