feat: rewrite the shape skill around the Change model

[levifig]

Change

docs/changes/20260707-shape-skill-rewrite/ — the Change artifact lives in this diff. It was shaped, implemented, and its fog register fully resolved on this branch; draft status here means the human H1–H2 review hasn't happened yet. Flipping ready-for-review is that declaration.

What & Why

The shape skill — the primary shaping surface — still taught the retired spec-first model: SPEC-NNN ID generation, a status lifecycle, and a breakdown handoff, all superseded by the TRANSITIONAL note. Beyond staleness, three structural gaps: technique selection during shaping was judgment-by-vibes, no step surfaced unknown unknowns (interviews can only clear questions someone knows to ask), and nothing taught the loaf change CLI boundary the pilot shipped.

This PR rewrites /shape around the Change model with a fog-routed narrowing protocol: every named unknown carries a quadrant tag that dispatches it to exactly one technique — [KU] known unknowns → grilling (one question at a time, architecture-changing answers first), [UK] unknown knowns → reaction artifacts (build the smallest thing the user can react to), [UU] suspected blind spots → blindspot pass (reconnaissance before the interview). Decomposition is absorbed from breakdown, re-principled from execution order to likelihood-of-change order so review attention lands on what's most likely to need changing. A critique gate closes shaping before loaf change check and the opt-in draft-PR offer.

Riding along per the recorded acceptance contract: cli-reference → loaf-reference, thinned from a ~1,450-line generated command catalog to an 82-line operational router (operating rules + compact drift-proof command index) with three hand-authored references, including the guided config-maintenance workflow (loaf config check --json → --fix → targeted questions → re-validate → install --upgrade → doctor).

Review focus

• Decision 8 (change.md): fog routes name in-session techniques, never skill invocations — the blindspot evidence for why research/brainstorm can't serve the handoff is in research/blindspot-routing-targets.md. This is the most load-bearing design call.
• Decision 4: likelihood-of-change ordering as breakdown's absorbed judgment — check references/decomposition.md keeps what mattered from the Right Size Test.
• H1: does references/cli-boundary.md read true to internal/cli/change.go behavior (violations vs. derived executability, --require-executable ownership)?
• H2: do the three technique references return fog entries, not decisions — is reconnaissance-not-orders actually enforced by the text?
• One recorded deviation: the altitude fog entry asked for dual inline/references drafts as a reaction artifact; the implementer judged directly (inline register, referenced mechanics) and review accepted it — disposition in the change doc's Open Questions.
• Veto point: the one-line fog-register comment added to templates/change.md (applied recommended answer; convention, never parsed by check).
• loaf-reference: is the 82-line router the right altitude, and is the config/deprecations.json entry (since: v2.0.0-alpha.6, one-release window) the correct retirement contract?

Verification

All executable gates green on this branch; re-run locally:

loaf change check docs/changes/20260707-shape-skill-rewrite   # 0 violations, executable: yes
npm run build                                                  # targets + artifact verify
node cli/scripts/eval-skill-routing.mjs --dry-run              # 119 cases, suite validation passed
grep -rn "SPEC-" content/skills/shape/                         # zero hits (V3)
npm run test                                                   # full Go suite

Human review (H1–H2) is this PR's review; H3 (ordering rule observed working) trails on the first Change shaped with the new skill.

Migration / breaking changes

• /shape now produces a Change under docs/changes/, never a numbered spec — documented behavior since the TRANSITIONAL note; this makes the skill match it. loaf spec/loaf task surfaces are untouched (conversion pass owns them).
• Installed tools: cli-reference retires via the deprecation manifest — loaf install --upgrade removes stale copies; loaf-reference installs in its place.
• The breakdown skill still exists and still works; this PR only stops shape from referencing it. Its retirement belongs to the guidance sweep.

Deferred

• Quiz merge gate + deviations harvest → the conversion-and-guidance-sweep Change (recorded in the change doc's Out; walkthrough/quiz are one artifact with two reading modes).
• implement/ship cannot receive a Change yet (input detection, --require-executable preflight, Verification-Contract-as-merge-gate) → sweep; captured as a spark with evidence in research/blindspot-implement-ship.md.
• Routing-skill contract gaps and spec residue across brainstorm/idea/triage/research → skill-surface-tightening; captured as a spark with evidence in research/blindspot-routing-targets.md.
• Breakdown deletion and the repo-wide spec-language sweep → conversion strictly before sweep (pilot Decision 4).

[levifig]

Architectural walkthrough — read this before the diff

(The Decision 20 pattern: architecture first, code second.)

What structurally changed

Shaping used to be a linear interview that ended in a numbered spec, with technique choice (interview? brainstorm? research?) left to whatever the agent felt like. The center of the rewrite is a dispatch table: every named unknown gets a quadrant tag, and the tag — not agent judgment — picks the technique.

                      ┌─ [KU] known unknown ──→ grilling (arch-impact order) or research spike
messy input ─→ fog ───┼─ [UK] unknown known ──→ reaction artifact in the Change's research/
   register           └─ [UU] blind spot ─────→ blindspot pass  ──→ names it ──→ re-routes as KU/UK

Two structural rules fall out of the blindspot evidence (research/blindspot-routing-targets.md):

1. Techniques run in-session, never as skill invocations (Decision 8). The routing-target skills can't serve the handoff — research re-interviews already-scoped questions and writes evidence to .agents/reports/; brainstorm forces a strategic frame and sends resolutions forward into intake instead of back into the session. Shape executes grilling, reaction artifacts, and blindspot passes itself and writes evidence into the Change's own research/.
2. The blindspot pass precedes grilling (Decision 2). Interviews can only clear questions someone already knows to ask; reconnaissance has to run first or its findings arrive too late to interview about.

Where things live

• content/skills/shape/SKILL.md (164 lines) — register format, routing table, defined terms, and the 10-step process stay inline; they're read every session.
• content/skills/shape/references/ (6 files) — technique mechanics load on demand: grilling.md, blindspot-pass.md, reaction-artifact.md (the mattpocock grill-me/prototype imports per Decision 7), decomposition.md (breakdown's Right Size Test, re-principled to likelihood-of-change ordering — Decision 4), cli-boundary.md (written from internal/cli/change.go's actual behavior, not re-description), critique-gate.md (the pilot's gate, generalized — Decision 9).
• Deleted: SPEC-ID generation, the spec lifecycle state machine, templates/spec.md (verified unreferenced), and the breakdown handoff.

The loaf-reference rider

cli-reference → loaf-reference, and the architecture inverted: instead of a ~1,450-line generated catalog duplicating loaf --help, the generator now emits an 82-line router — operating rules plus a compact command index (one row per command, still generated from the same metadata, so new commands can't silently vanish like loaf doctor did). The judgment-heavy content is hand-authored in references/: configuration.md (the guided config-maintenance workflow), command-routing.md (decision guide, Change-first), troubleshooting.md (the three-doctor split, LOAF_DB isolation). Old name retires through config/deprecations.json so loaf install --upgrade cleans installed copies. One mechanism worth knowing: per-target placeholder substitution works inside references/ too — {{IMPLEMENT_CMD}} renders as /loaf:implement in the plugin and /implement for Cursor.

Commit map

Commit	Carries
a8f81336	The Change contract + blindspot-pass evidence (three reviewer reports in research/)
8cfd715e	CLI-reference review fixes (missing loaf doctor, Change-blind decision guide)
b9eb676d / 05dcc4ee	The rename + deprecation retirement / build refresh
627f00f6 / 2ab7df15	The thinning to the operational router / build refresh
70da8a24 / 507e76c5	The shape rewrite itself (U1–U5) / build refresh

Provenance: the fog taxonomy and blindspot/interview/tweakable-plan patterns harvest Thariq's "A Field Guide to Fable" (flagged as a confirming input per the pilot's survivorship-bias rule — third independent convergence after Wayfinder and the SDD Blueprint); grilling/prototype semantics import from the mattpocock review evidence; the loaf-reference contract came from the Codex-session convergence. All cited in the change doc's Source Inputs.

[levifig]

Review guide — H1/H2 checkpoints and your veto points

Suggested reading order: docs/changes/20260707-shape-skill-rewrite/change.md (the contract — Decisions 1–10 especially) → content/skills/shape/SKILL.md → references/grilling.md + blindspot-pass.md + decomposition.md → content/skills/loaf-reference/SKILL.md + references/configuration.md → the eval-fixture diff (cli/scripts/eval-skill-routing.mjs).

H1 — CLI boundary accuracy

references/cli-boundary.md claims to describe loaf change init/check as they actually behave. Check it against internal/cli/change.go: violations vs. derived executability, --require-executable as implement's preflight (not shape's), branch-mismatch as warning-not-violation, the byte-one frontmatter rule. If a reader who's never seen the Change model can run init/check and read the output correctly from this doc alone, H1 passes.

H2 — reconnaissance, not orders

Each technique reference must return fog entries and evidence, never decisions. The give-away failure would be any wording that lets the technique conclude ("therefore we should…"). Spots to poke: blindspot-pass.md § Deliverable, reaction-artifact.md § Never a Deliverable, grilling.md's recommended-answer rule (a recommendation attached to a question ≠ a decision made for you).

Judgment calls made during implementation (all adjudicated, flag any you'd reverse)

1. Altitude deviation — the fog entry asked for dual inline/references drafts as a reaction artifact; the implementer judged directly (inline register, referenced mechanics) because a fully-inline draft would breach the 500-line rule. Accepted; disposition recorded in the change doc's Open Questions.
2. Shared grilling template deferral honored — shape got its own grilling.md from the mattpocock evidence instead of consuming the shared templates/grilling.md (whose glossary-mutation duty doesn't fit shape); a prior journal decision to that effect was found and respected.
3. V3 rewording — two "no SPEC-NNN" prohibitions technically tripped the zero-SPEC- grep; reworded so the gate is a clean mechanical zero.

Your explicit veto points

• The one-line fog-register comment added to templates/change.md's Open Questions (applied recommended answer; convention, never parsed by check).
• config/deprecations.json: cli-reference retired since: v2.0.0-alpha.6, window: one-release — is that the retirement contract you want?
• The claude-code build caps skill descriptions at 250 chars, so that target truncates the new description's negative-routing tail. Standard behavior for every skill, but say so if you want the first sentence reworked.

What deliberately did NOT change

• breakdown/ still exists and works — its retirement belongs to the guidance sweep (pilot Decision 4 ordering).
• loaf spec / loaf task CLI surfaces untouched — conversion pass owns them.
• ship untouched — the quiz gate and deviations harvest are recorded in the change doc's Out for the sweep.
• implement can't consume a Change yet — known, evidenced (research/blindspot-implement-ship.md), spark-captured, sweep-bound.

Verification to re-run locally

loaf change check docs/changes/20260707-shape-skill-rewrite   # 0 violations, executable: yes
node cli/scripts/eval-skill-routing.mjs --dry-run              # 119 cases
grep -rn "SPEC-" content/skills/shape/                         # zero hits
npm run test && npm run build

H3 (the likelihood-of-change ordering observed actually steering a review) trails on the first Change shaped with the new skill — not a gate here.

[levifig]

External review — round 1 (Codex, off-PR) — findings and dispositions

Adversarial two-axis review (general standards ∥ contract conformance), diff/repo-only; the reviewer ran the Verification Contract gates itself. Verdict was not merge-ready pending two mechanical fixes — both now landed in 1e143980 + 920dfc6f.

#	Severity	Finding	Disposition
1	Blocker	internal/cli/change_template.md (the Go-embedded template loaf change init actually scaffolds from) drifted from the canonical content/skills/shape/templates/change.md when the fog-register comment landed — TestChangeTemplateMatchesCanonicalContent failed, and freshly initialized Changes were missing the comment (verified empirically in a scratch repo).	Confirmed and fixed — canonical copy re-synced byte-identical; drift test and full suite green. Root cause was a verification gap in the fix round (template edited after the last full test run).
2	Should-fix	shape/SKILL.md Step 3 claimed loaf change init <slug> "puts you on branch <slug>" — false; runChangeInit only prints the git switch -c suggestion. An agent following it literally could commit shaping work to main. Treated as blocking H1 even though outside V1–V4.	Confirmed and fixed — Step 3 now states init prints the branch and does not switch; the shaper runs git switch -c <slug>. Matches references/cli-boundary.md, which was verified accurate throughout.
3	Nit	config/deprecations.json retires cli-reference since: v2.0.0-alpha.6, which doesn't exist yet.	Accepted as-is — since is display-only (never version-compared in install_deprecations.go), matches the existing forward-dating precedent, and names the release that will carry the retirement.
4	Nit	Thinned loaf-reference doesn't follow the Critical Rules/Verification/Quick Reference/Topics section order — inherited from the generator, not introduced here.	Deferred — whether generated reference skills get a documented section-order exception goes to the skill-surface-tightening Change.
5	Probe	idea/triage/orchestration/bootstrap/breakdown still describe shape as producing a SPEC.	Correctly out of scope — already recorded in this Change's Out and sweep-bound; reviewer concurred it's deferred, not missed.
6	Probe	Deprecation-entry consumption vs install_deprecations.go; information loss from the loaf-reference thinning.	Clean — entry matches the externalization precedent; every removed guidance block survives on another surface (nearest miss, the project-identity note, is covered by docs/ARCHITECTURE.md).

Reviewer confirmed V1–V4 independently (check executable, build + eval dry-run at 119 cases, zero SPEC- grep, tests) apart from the drift test above, and validated all of cli-boundary.md's behavioral claims against change.go plus live --json output.

One meta-note: the reviewer's own gh was blocked all session by the account guard, so this round was diff-only — the exact failure mode PR #99 (github-account convergence) exists to end.