diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 9a9a2207e..cc6ec567a 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -569,6 +569,30 @@ the session default model changes): | Mechanical prep, one tier down | Sonnet 5 | | Bulk mechanical sweeps | Haiku 4.5 | +That ladder is a cost ordering, and one capability does not travel down it: **interleaved thinking — +a thinking block between tool calls rather than only before the first and after the last.** Claude Code +models it per model, as the `interleaved_thinking` capability value +([model config: customize pinned model display and capabilities](https://code.claude.com/docs/en/model-config#customize-pinned-model-display-and-capabilities), +verified 2026-08-03; a pinned model's unlisted capabilities are disabled). The per-model roster is +upstream-owned — resolve it at +[thinking: interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking), +which today states that interleaving is automatic on every model supporting adaptive thinking with +no beta header, and that Claude Haiku 4.5 does not support it (verified 2026-08-03; recheck trigger: +a new Haiku generation reaches GA, or that page's per-model sentence changes). + +The dispatch consequence, phrased as capability rather than family name so it survives an alias +moving under it: **require interleaving only where extended reasoning between tool results is +load-bearing — a mid-sweep judgement that has to change what gets called next. A task that chains +calls, or that reasons over its results at the end, does not need it.** The boundary is much +narrower than the capability's name suggests, and the same page draws it: "Consecutive tool calls do +not require interleaved thinking. Claude can chain tool calls with or without interleaved thinking; +interleaving changes where thinking blocks appear between tool calls, not whether tool calls can +chain." What the capability adds is a thinking block at that seam, so what its absence removes is +deliberation *at that point* — not the tool result from context, and not the ability to act on it. +So the bottom tier row stands for bulk mechanical sweeps and for straightforward triage or research +passes that decide at the end; the case it does not cover is a fan-out whose worth is deliberating +partway through, where the next call must change because of what the last one returned. + The **dispatch-seam** tier enforcement is structural at two binding sites: `plugins/implementation/agents/implementer.md` and `plugins/implementation/agents/phase-verifier.md` (both bind the loop-lane convention's strong-tier @@ -589,6 +613,15 @@ support falls back to the highest supported level at or below it verified 2026-07-29). The ladder itself — level names, per-model availability, per-model defaults — is upstream-owned: resolve it from the model-config page at decision time, never from this document. +What a pin actually buys is bounded by how allocation works: thinking is adaptive, so the model +"evaluates each request and decides for itself whether to think and how much", and the caller sets +an intent and optionally the effort while the model "allocates reasoning where it judges reasoning +will help" ([steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost), +verified 2026-08-03). A lane pin is therefore a posture, never a switch — a lane pinned `low` still +thinks where the model judges thinking earns its cost, and a turn carrying no thinking is that +mechanism working rather than a pin misfiring. Authoring conformance follows the posture: pin the +lane, then let allocation vary per request instead of writing prose that tries to force it uniform. + Lane rules, dated 2026-07-29 (recheck trigger: a model change on any pinned lane, or the model-config effort table changes — the effort scale is calibrated per model, so the same level name is not the same underlying value across models): @@ -619,13 +652,37 @@ name is not the same underlying value across models): relatively small quality gains and can lead to overthinking. A pin above `high` (e.g. `xhigh`) is a deliberate per-lane choice grounded in the target model's own recommended-levels guidance, never a reflex. -- **Shallow output from a pinned-`low` lane raises the lane's effort** rather than prompting - around it; only a lane that must stay `low` for latency gets upstream's targeted steering - guidance instead. +- **Effort is the first lever in either direction; steering prose is the second.** Upstream states + the order plainly — set the effort level matching the lane's workload, then "add prompt guidance + only if Claude's triggering still doesn't match your needs at that level" — and gives the + rationale that lowering effort "is usually the better first lever, since it is a calibrated + control rather than a wording-sensitive instruction" + ([steering thinking: steering how often Claude thinks](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#steering-how-often-claude-thinks), + verified 2026-08-03). Both directions: shallow output from a pinned-`low` lane raises the lane's + effort rather than prompting around it, and a lane thinking more than the work needs lowers the + pin before any prose telling the model to think less — upstream states that reduce direction + outright and warns it "may reduce quality on tasks that benefit from reasoning". A lane that must + hold its level for latency is the one case that reaches for steering prose first; it then owes + the measurement upstream asks for — a representative sample run with and without the guidance, + compared on trigger rate, output tokens, latency, and quality — because steering effectiveness is + wording-sensitive in a way a level is not. Authoring a lane's prose against its own pin, in + either direction, is the inversion this rule exists to catch. - **Cache caveat**: changing effort between requests invalidates cached prompt prefixes, so a skill pin firing mid-session is expected to cost the main conversation's cache (harness-side request assembly unconfirmed), while a subagent pin is scoped to the subagent's own requests — - treat skill-lane pins as cache-costly in cost-sensitive loops. + treat skill-lane pins as cache-costly in cost-sensitive loops. State the outcome and not the + mechanism: the platform page and the harness page agree that an effort change forces a full + re-read but describe *why* differently, so an explanation that picks one is asserting more than + either source supports. Two corollaries follow. Setting a lane's effort explicitly to the model's + own default is a no-op that "does not break the cache", so a pin that merely documents the + default costs nothing. And **per-message steering is the cache-safe escape hatch** — guidance + appended to the newest user message "leaves earlier cache breakpoints intact, where a + configuration or effort change does not", which is what makes a skill's invocation-time + instructions cheaper than a mid-session pin. The convention that falls out, and the reason a lane + pin is a design-time choice rather than a per-task one: pick the level once and keep it, steer + per message when one turn needs more or less, and move the configuration only at natural breaks + between tasks ([steering thinking: prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#prompt-caching), + verified 2026-08-03). Session-level effort is the consumer's own knob, out of plugin scope: `low` through `xhigh` persist via the `effortLevel` setting, while `max` and `ultracode` are session-only — `max` is diff --git a/plugins/playbooks/.claude-plugin/plugin.json b/plugins/playbooks/.claude-plugin/plugin.json index ee39ec28f..01d861942 100644 --- a/plugins/playbooks/.claude-plugin/plugin.json +++ b/plugins/playbooks/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "playbooks", - "version": "0.6.2", + "version": "0.6.3", "description": "Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); skill-authoring — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).", "author": { "name": "Melodic Software", diff --git a/plugins/playbooks/CHANGELOG.md b/plugins/playbooks/CHANGELOG.md index c14626e42..b41b43437 100644 --- a/plugins/playbooks/CHANGELOG.md +++ b/plugins/playbooks/CHANGELOG.md @@ -4,6 +4,32 @@ All notable changes to the `playbooks` plugin are recorded here. The `version` i `.claude-plugin/plugin.json` is the delivery vehicle — a consumer receives a change only after that version increases. +## [0.6.3] + +### Added + +- **`fable-5` calibration gains the product-surface scope rule.** + `skills/fable-5/context/calibration.md` adds "A claim's product surface travels with it": a + behavioral claim about Claude is a fact about the surface documenting it, and it transfers to the + surface the session runs on only after a per-claim check — never on vendor authority alone. The + rule is scoped to CROSS-surface transfer, which is the row's actual thesis: docs for the running + surface clear the check where they stand, so Claude Code's own docs read inside Claude Code are + not downgraded. A dated archive entry is scoped to its date on top of that. Two worked + divergences carry it, both genuine published text from Anthropic's claude.ai system prompts and + both false read as facts about this harness — "Claude does not retain information across chats" + (Claude Opus 4.1 entry, dated August 5 2025) against Claude Code's two documented cross-session + mechanisms, CLAUDE.md files and auto memory; and "Claude cannot open URLs, links, or videos" + (Claude Sonnet 3.5 entry, dated November 22 2024) against the documented `WebFetch` tool. Both are + stamped to their entry rather than stated in the present tense, because **neither sentence + survives in a current entry** — wrong-surface and stale-entry are independent errors, and the + staleness is the rule's second half rather than a defect in the example. Verified 2026-08-03 + against [published system prompts](https://platform.claude.com/docs/en/release-notes/system-prompts), + [memory](https://code.claude.com/docs/en/memory), and + [tools reference](https://code.claude.com/docs/en/tools-reference); recheck trigger: a new dated + entry restores or reverses either sentence, or Claude Code's memory or tool surface changes. + `skills/fable-5/SKILL.md` carries the distilled line under core doctrine, "Ground truth and + checking — calibration", per the chapter/core-doctrine pairing the rest of that file follows. + ## [0.6.2] ### Fixed diff --git a/plugins/playbooks/skills/fable-5/SKILL.md b/plugins/playbooks/skills/fable-5/SKILL.md index 161207fec..cae46e37f 100644 --- a/plugins/playbooks/skills/fable-5/SKILL.md +++ b/plugins/playbooks/skills/fable-5/SKILL.md @@ -44,6 +44,7 @@ The distillation of every chapter, grouped in operating-loop order. Each line is - Trust no count or zero-hit result until you have ruled out output caps and validated the probe against a known-present example. - Pre-register a prediction before any action with observable output — no expectation means surprise is undetectable. - Settled means settled: reopen a session-verified, untouched fact only on contradicting evidence, never data-free doubt. +- A behavioral claim about Claude is a fact about the surface documenting it, and it transfers to the surface you are running on only after a per-claim check — never on vendor authority alone, which is what makes a scope slip invisible. Docs for your own surface clear that check where they stand; a claim from another surface (consumer apps, the raw API) is a hypothesis until checked, and a dated archive entry is scoped to its date on top of that. ### Thinking — reasoning-moves diff --git a/plugins/playbooks/skills/fable-5/context/calibration.md b/plugins/playbooks/skills/fable-5/context/calibration.md index 7a778e2a4..a9312c4c2 100644 --- a/plugins/playbooks/skills/fable-5/context/calibration.md +++ b/plugins/playbooks/skills/fable-5/context/calibration.md @@ -27,6 +27,21 @@ Rank every belief by its distance from observation: direct observation this sess > Weak: "The test passed, so the parser works, so the import pipeline works, so the report is correct." — the final claim stands three steps from evidence. > Strong: open the actual report output once; the claim is now zero steps from evidence. +## A claim's product surface travels with it + +Same-vendor documentation is the easiest scope error to make, because it never feels like an inference: you read an authoritative sentence about Claude and it lands as a fact about the Claude you are. It is a fact about the surface that sentence documents. Consumer claude.ai and mobile, the raw API, and this harness are different products with different tools, memory, and system prompts; a claim crosses between them only after a per-claim check against the target surface's own docs. + +- TRIGGER: about to act on a behavioral claim about Claude that you did not observe on this surface this session — official vendor documentation included, and especially then, since its authority is what makes the scope slip invisible. +- RULE: name the surface a claim documents before using it. Same surface as the one you are running on — Claude Code's own docs, here — and naming it IS the check: it clears at that point and nothing further is owed. A different surface makes the claim a hypothesis about yours, one inference step out, and settling it costs a single lookup in the target surface's own docs. +- RULE: a dated archive is scoped to its date as well as its surface. A published prompt entry describes one model on one day; a sentence's later absence is not a correction you can read off the page. + +Two worked divergences, both genuine published text from Anthropic's claude.ai system prompts, both false about this harness, and both already superseded (verified 2026-08-03 against the [published system prompts](https://platform.claude.com/docs/en/release-notes/system-prompts), [Claude Code memory](https://code.claude.com/docs/en/memory), and the [tools reference](https://code.claude.com/docs/en/tools-reference)): + +- "Claude does not retain information across chats" — Claude Opus 4.1 entry, dated August 5 2025. Here, two documented mechanisms carry knowledge across sessions: CLAUDE.md files and auto memory. +- "Claude cannot open URLs, links, or videos" — Claude Sonnet 3.5 entry, dated November 22 2024. Here, `WebFetch` is a documented tool. + +Neither sentence survives in a current entry, which makes wrong-surface and stale-entry independent errors: a reader who caught only the surface mismatch would still be quoting a retired prompt. Clear both before a vendor sentence becomes a premise. + ## The check / skip decision Checking is an investment, not a virtue. Decide with the rules below. Already-settled exits first: a session-verified, untouched claim is evidence, not a claim needing a check — it leaves this matrix entirely (see "Settled means settled"). Among the rest, precedence: silent-failure mandate, then the gating-and-expensive test (its ≤2-call cost cap lives inside it), then the loud-fast-free skip, then DEFAULT.