@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/skills/rfc/SKILL.md

@@ -0,0 +1,222 @@
+---
+tier: lite
+name: rfc
+description: "Run an outside-luminary council review on a proposed design. Picks 3-5 luminaries not in the authoring set. Applies each lens to risks and decisions. Writes findings with severity and disposition options. Catches what the authoring lenses miss."
+problem: "Design proposals get one lens set from the authoring session. Blind spots ship into HIGH-severity findings later."
+value: "Outside-luminary council review on a proposed design. Picks 3-5 luminaries not in the authoring set."
+inputs: [A goal doc path, Optional --lenses override for manual pick]
+outputs: [RFC doc at docs/rfcs/, Severity-tagged findings per lens, Disposition options]
+user_invocable: true
+disable_model_invocation: false
+composes_with: [architect-review, pre-mortem, luminary, pick-luminaries, state-a-problem, kiss, value-prop]
+depends_on: [luminary]
+---
+<!-- andon-allow: operator-private -->
+
+# /rfc — outside-luminary council review
+
+## What you get
+
+An RFC document. It carries findings from luminaries the authoring session did not use. Each finding gets a severity. Each severity gets a disposition. You pick which findings cure inline. You pick which defer.
+
+The output is `docs/rfcs/RFC-NNNN-<slug>.md`. Field shape follows RFC-0001 from bassclef-cli scope-b1. See `standards/rfc-shape.md` for the field list.
+
+## When to use it
+
+Use `/rfc` when all of these hold:
+
+- A goal doc or ADR has been drafted with 2-6 authoring luminaries
+- `/architect-review` and `/pre-mortem` have already run against it
+- The scope is consequential enough that a HIGH finding at Step 7 signoff would cost 100+ turns to cure
+- The authoring session did not pick lenses outside its own lens set
+
+Skip `/rfc` when the scope is trivial. A typo cure does not owe a council.
+
+## When NOT to use
+
+Do not use `/rfc` as a substitute for `/architect-review` or `/pre-mortem`. Those two must run first. They ground the RFC in real content.
+INSTEAD: run `/architect-review` first. Then run `/pre-mortem`. Then dispatch `/rfc`.
+
+Do not use `/rfc` on scope where the authoring set already crosses 6+ luminaries. The outside-set constraint is hard to honor without repeating what already got said.
+INSTEAD: for wide authoring sets, run a second `/pre-mortem` with a new lens instead of `/rfc`. The new lens gets fresh eyes without the outside-set constraint.
+
+Do not use `/rfc` to fix findings. `/rfc` surfaces findings; the operator picks the cure.
+INSTEAD: dispatch `/build` or open a follow-on goal to ship the cure.
+
+## FAQ
+
+### What is the outside-set constraint?
+
+The RFC picks luminaries who are NOT in the goal doc's `authoring_luminaries` list. This prevents lens echo chamber. The same lenses that shaped the design cannot review it.
+
+Per bassclef-cli#38 — RFC-0001 caught 6 HIGH findings. All 6 came from lenses outside the authoring set. Without the RFC pass, they would have hit at Step 7 signoff.
+
+The 6 HIGH findings came from `linus-torvalds` + `hyrum-wright` + `frederick-brooks` + `saltzer-schroeder` + `don-norman`. None of these were in scope-b1's authoring set.
+
+### Which luminaries make good outside-set picks?
+
+Pick lenses that reveal blind spots the design lenses cannot see. Five standing candidates per RFC-0001 evidence:
+
+<!-- FKGL-EXEMPT: table row shape carries lens + role paired -->
+
+| Lens | What it catches |
+|---|---|
+| `linus-torvalds` | Adopter compatibility (keep userspace working); silent adopter migration |
+| `hyrum-wright` | Observable behavior binding; schema-as-API surface |
+| `frederick-brooks` | Second-system effect; scope creep beyond the goal |
+| `saltzer-schroeder` | Defense in depth; least privilege; security envelope |
+| `don-norman` | User model; progress signals; error messages; adopter mental model |
+
+<!-- /FKGL-EXEMPT -->
+
+Other strong picks — `alan-cooper` (persona review), `martin-fowler` (refactoring debt), `michael-nygard` (stability), `clayton-christensen` (JTBD fit).
+
+### What does a severity look like?
+
+Three levels per RFC-0001:
+
+- **HIGH** — would break an adopter or cost 100+ turns to cure at Step 7. Cure inline or defer with a specific plan.
+- **MEDIUM** — would cost 20-50 turns to cure post-ship. Cure inline if scope allows.
+- **LOW** — nice-to-have. Advisory only.
+
+### What are disposition options?
+
+Three shapes per RFC-0001:
+
+- **Revised A** — accept scope. Cure HIGH findings inline.
+- **Revised B** — trim scope. Move some steps to a follow-on plan doc.
+- **Revised C** — split scope. Ship the safe part now. Defer the risky part.
+
+The operator picks. Deferrals land in a follow-on plan doc.
+INSTEAD of silent drops: the follow-on doc is the landing pad. Every deferral gets a home.
+
+### How does /rfc compose with /architect-review + /pre-mortem?
+
+<!-- FKGL-EXEMPT: workflow table shape -->
+
+| Skill | When it fires | What it produces |
+|---|---|---|
+| `/architect-review` | After goal doc draft; before RFC | audit findings against ADRs + tenets |
+| `/pre-mortem` | After goal doc draft; before RFC | risk ledger with lenses from authoring set |
+| `/rfc` | After both above; before Step 4 build | RFC doc with outside-set findings + disposition |
+| `/build` | After RFC disposition | ships the revised scope |
+
+<!-- /FKGL-EXEMPT -->
+
+### What is the estimated cost?
+
+Per bassclef-cli#38 evidence — RFC-0001 took ~50 turns to run. Ratio ~1:12 turn savings vs curing HIGH findings at Step 7. The ratio compounds per consequential goal.
+
+### How does /rfc know which luminaries to pick?
+
+Two modes:
+
+- **auto** (default) — dispatches `/pick-luminaries` with the intent paragraph from the goal doc. Filters out the authoring set. Picks the top 3-5 outside-lens roles (Linus + Hyrum + Brooks + Saltzer-Schroeder + Norman + Cooper). Falls back to the standing 5 when `pick-luminaries` is unavailable at the adopter tier.
+- **manual** — operator names the 3-5 luminaries at dispatch (`/rfc --lenses linus,hyrum,cooper`).
+
+## Details below the fold
+
+### Procedure — full
+
+**Step 0 — Pre-flight.** Verify:
+
+- Goal doc exists at `docs/iteration-bets/<slug>.md`
+- Goal doc has `authoring_luminaries` frontmatter with 2-6 named lenses
+- `/architect-review` output exists (marker or doc; see `.claude/rules/architect-review-discipline.md`)
+- `/pre-mortem` risk ledger exists at `docs/risk-ledgers/<slug>.md`
+
+If any missing, BLOCK with the missing artifact named. Silence is not deferral.
+
+**Step 1 — Read the design content.** Read every artifact the goal doc references. Compose `/state-a-problem` on any finding this pass surfaces.
+
+**Step 2 — Pick the outside-set council.** Per FAQ. Default auto mode. Cite each pick's lens role in one line.
+
+**Step 3 — Apply each lens.** For each picked luminary:
+
+- Read `.claude/luminaries/<slug>.md`
+- Walk each named risk in the ledger + each design decision in the goal doc
+- Write findings with severity (HIGH / MEDIUM / LOW) tied to concrete artifacts
+
+Every finding cites a file path, a decision, or a risk row.
+INSTEAD of abstract concerns: cite the artifact per finding. Vague concerns get dropped or rewritten with a citation.
+
+**Step 4 — Group findings + propose dispositions.** Group by severity. Propose 3-4 disposition options (Revised A / B / C — accept scope / trim scope / split scope). Cite which HIGH findings each disposition addresses.
+
+**Step 5 — Surface to operator.** Print the finding table + disposition options. Wait for pick.
+
+**Step 6 — Write the RFC doc.** Compose `docs/rfcs/RFC-NNNN-<slug>.md` per `standards/rfc-shape.md`. Fields:
+
+- Frontmatter — tier, goal, council, disposition, references
+- Council section — one row per luminary + lens role
+- Findings section — grouped by severity, per-finding artifact citation
+- Disposition section — chosen shape + rationale + deferrals
+- Follow-on plan section — links to `docs/next-longrun-prep-<date>-<slug>.md` if scope trimmed
+
+**Step 7 — Update the risk ledger + goal doc.** Amend the ledger with the RFC absorption. Add an `rfc_signoff` row to the goal doc frontmatter. Update any ADR being amended.
+
+**Step 8 — Land deferrals.** If scope trimmed, write the follow-on plan doc at `docs/next-longrun-prep-<date>-<slug>.md` naming the deferred steps + reason.
+
+**Step 9 — Report.** Surface RFC path + disposition + deferrals. Return control.
+
+### Modes
+
+- Default — auto pick + full 9-step procedure
+- `/rfc --lenses linus,hyrum,cooper` — manual lens picks
+- `/rfc --dry-run` — Steps 0-3 only. Surface findings without writing the RFC doc.
+- `/rfc --council-only` — Steps 0-2 only. Propose the council. Wait for operator confirm before applying lenses.
+
+### Override paths
+
+- `SKIP_RFC_PREFLIGHT=1` — bypass Step 0 checks. Use only when a prior session skipped `/architect-review` or `/pre-mortem` on purpose. The reason must live in the goal doc.
+- `RFC_LENS_MIN=3` — override the 3-lens minimum.
+  INSTEAD: 3-5 lenses is the calibrated range per RFC-0001. Dropping below 3 loses lens diversity.
+- `RFC_LENS_MAX=8` — override the 5-lens ceiling. Wider councils cost more turns.
+  INSTEAD: 5 is the calibrated ceiling per RFC-0001. Add more only when scope crosses multiple bounded contexts.
+
+INSTEAD of habitual overrides: run the 9-step procedure. The turn cost is bounded per RFC-0001 evidence (~50t). The Step-7-signoff cost is not.
+
+### Reads
+
+- `docs/iteration-bets/<slug>.md` — goal doc
+- `docs/risk-ledgers/<slug>.md` — pre-mortem risk ledger
+- `architecture/decisions/ADR-*.md` — any ADR being amended
+- `docs/decompositions/<slug>-domain.md` — decomposition if present
+- `.claude/luminaries/<slug>.md` — one read per picked luminary
+- `standards/rfc-shape.md` — RFC field list
+
+### Writes
+
+- `docs/rfcs/RFC-NNNN-<slug>.md` — the output
+- `docs/risk-ledgers/<slug>.md` — amended with RFC absorption
+- `docs/iteration-bets/<slug>.md` — `rfc_signoff` row added to frontmatter
+- `docs/next-longrun-prep-<date>-<slug>.md` — deferrals if scope trimmed
+- `state/markers/rfc/<slug>.marker` — audit trail
+
+### Grace window on old vocabulary
+
+Old vocabulary — `bet`, `WU`, `appetite`, `chronicle` — still works through 2026-10-31 per ADR-031 and `.claude/rules/we-dont-break-adopters.md`. New RFC docs use `goal`, `step`, `time budget`, `session log`.
+
+## Refs
+
+- bassclef-cli#38 — parent ticket (evolution ask from adopter)
+- RFC-0001 — the exemplar output at `~/src/sunj-labs/bassclef-cli/docs/rfcs/RFC-0001-npm-lite-substrate-bundling-review.md`
+- `.claude/rules/architect-review-discipline.md` — precondition rule
+- `.claude/skills/architect-review/SKILL.md` — precondition skill
+- `.claude/skills/pre-mortem/SKILL.md` — precondition skill
+- `.claude/skills/pick-luminaries/SKILL.md` — auto-mode dependency
+- `standards/rfc-shape.md` — field list (companion standard to ship with this skill)
+- `@luminary linus-torvalds` — standing outside-lens candidate
+- `@luminary hyrum-wright` — standing outside-lens candidate
+- `@luminary frederick-brooks` — standing outside-lens candidate
+- `@luminary jerome-saltzer-and-michael-schroeder` — standing outside-lens candidate
+- `@luminary don-norman` — standing outside-lens candidate
+
+## Anchor luminaries
+
+- `@luminary daniel-kahneman` — outside-view discipline. System 2 slows down when the inside-view lens has run.
+- `@luminary gary-klein` — pre-mortem precedent. `/rfc` extends pre-mortem with an outside-set lens council.
+- `@luminary frederick-brooks` — conceptual integrity via multiple reviewers per "The Mythical Man-Month" §"Aristocracy and Democracy".
+
+## Retirement
+
+Retires if outside-set council review becomes noise (operator dispatches fewer than 1 per month across sessions). Also retires if authoring lens sets grow past 6 luminaries by default. Wider default sets make the outside-set constraint impractical.