diff --git a/plugins/claude-config/.claude-plugin/plugin.json b/plugins/claude-config/.claude-plugin/plugin.json index b8a23266a..229ad80a0 100644 --- a/plugins/claude-config/.claude-plugin/plugin.json +++ b/plugins/claude-config/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-config", - "version": "0.21.0", + "version": "0.21.1", "description": "Five audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), and audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it).", "author": { "name": "Melodic Software", diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index ef571722b..f2473fbea 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -3,6 +3,55 @@ All notable changes to the `claude-config` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.21.1] + +### Added + +- **`audit-instructions`: row I8-d, short-turn assumptions** (criteria 1.8.0 → 1.9.0). Tier + `behavioral`, `Model scope: fable-5` — the promotion gate is unmet and stays unmet: the claim + appears in one model guide and on no model-agnostic page, so the row is inert on other targets + and reports `skipped-for-target`. + + **Detect** is instruction text resting on the premise that a turn is short — a forced + interim-status cadence ("summarize every N tool calls"), a directive to answer quickly, any + progress rhythm pinned to a turn rather than to the work. Individual requests now run for + minutes at higher effort and autonomous runs for hours, so such a rhythm fires on work that has + not reached a reportable boundary and interrupts exactly the long runs the model is used for. + Four fences keep it off legitimate text: an output-length instruction is I8 base's subject, not + this one's (the axis here is the turn's duration, never the reply's size); a latency or duration + requirement the surface genuinely owns — an SLA, a downstream timeout, a human review rhythm — is + a constraint it is entitled to state; a document *about* the pattern is exempt on the same + audience test I8-b, I17, I18 and I20 already use; and a cadence carrying its own explicit + observability or interruptibility rationale is a design the surface is entitled to make — that is + the very guarantee the row's Remediate line protects — exempt unless evidence shows it was + calibrated to an obsolete turn length rather than to the work. + + The row is **lane-only, not seeded** by `instruction-scan.sh`, and `SKILL.md` now says so + alongside the existing I8-c disclosure. A pattern family was considered and declined: the + phrasings are too varied for a rule that would earn its false-positive rate, and the one + candidate string in this repository resolves to the exempt meta case, so the family would have + shipped with a known false positive and no true one. + + The guide pairs this behavior with advice to adjust **client timeouts, streaming, and progress + indicators**. That half is harness client configuration rather than instruction content, so the + row states plainly that it is out of scope and that no row claims it — the shape that *would* + reach this catalog is instruction text prescribing a short client timeout, and none is attested. + +### Changed + +- **`audit-instructions`: I8's base row gains one named worked instance — the delegation + throttle.** A cap on concurrent workers, a one-at-a-time rule, or an instruction to block until + each subagent returns, *where the surface's own ground is that subagent handling is unreliable*. + Current guidance runs the other way (readier dispatch, asynchronous orchestrator-to-worker + communication), so such a throttle is the base row's generic case with a name on it — which is + why it lands as recognition material inside I8 rather than as a fourth rule competing with it. + The qualifier is the whole fence: **a cap carrying its own non-model rationale is not this + instance.** Reviewability of returns, rate limits, cost, and shared mutable state each justify a + bound on their own terms, and that justification belongs to the surface making it. The base row's + Source gains the guide's "Parallel subagents" sentence as the instance's basis; the row restates + no volatile literal and so owes no per-row verification stamp under the catalog's own + binds-on-touch rule. + ## [0.21.0] ### Added diff --git a/plugins/claude-config/skills/audit-instructions/SKILL.md b/plugins/claude-config/skills/audit-instructions/SKILL.md index 1e5bf2f90..8f9de638d 100644 --- a/plugins/claude-config/skills/audit-instructions/SKILL.md +++ b/plugins/claude-config/skills/audit-instructions/SKILL.md @@ -256,7 +256,9 @@ bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/scripts/instruction-scan.s It emits `file:line:check-id` candidate rows for I6 (bare prohibitions lacking a rationale marker), I10 (reasoning-echo directives), and the I8 families under per-family ids — `I8-a` instructed self-check, `I8-b` conservative-reporting, `I8-c` don't-think / don't-reason (I8-c's -tag-naming sub-detect is lane-only, not seeded); `--count` prints the row count. Advisory — a +tag-naming sub-detect is lane-only, not seeded, as are I8's base row and `I8-d` short-turn +assumptions, whose phrasings are too varied for a pattern that would earn its false-positive rate); +`--count` prints the row count. Advisory — a grep cannot judge whether a rationale is genuinely present, whether a restraint clause is a reporting gate, or which model a row targets, so the lane refines every candidate against the catalog's fences and the run's resolved target model. diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index ab178039a..fbedbe0a4 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -1,5 +1,5 @@ --- -version: 1.8.0 +version: 1.9.0 last-updated: 2026-08-03 --- @@ -240,18 +240,30 @@ so this fires for every target model. Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surfaces: all. -The base row and rows I8-a and I8-c carry their own `Model scope` (single-model guide sources; +The base row and rows I8-a, I8-c and I8-d carry their own `Model scope` (single-model guide sources; promotion gate unmet). Row I8-b is unscoped — two model guides converge on it (see the row). **Base row** · Model scope: `fable-5`. - **Detect:** prior-model workarounds and over-prescriptive step lists — instructions enumerating behaviors a current model handles from a brief instruction, or scaffolding that pins an approach. + **One named worked instance, offered for recognition rather than as a separate rule: a delegation + throttle** — a cap on concurrent workers, a one-at-a-time rule, or an instruction to block until + each subagent returns before dispatching the next — where the surface's own ground for it is that + subagent handling is unreliable. Current guidance runs the other way, asking for readier + dispatch and asynchronous orchestrator-to-worker communication, so a throttle resting on that + premise is the generic case with a name on it. **A cap carrying its own non-model rationale is + not this instance** — reviewability of returns, rate limits, cost, or shared mutable state each + justify a bound on their own terms, and that justification is the surface's to make, not this + row's to override. - **Remediate:** propose removal or a briefer instruction; verify via the delete-and-watch loop that default performance holds or improves. - **Bounded by:** the **Stopping condition** below, which is enabled by default. - **Source:** Fable 5 guide — "Skills developed for prior models are often too prescriptive for - Claude Fable 5 and can degrade output quality." + Claude Fable 5 and can degrade output quality." The worked instance's basis is the same guide, + "Parallel subagents" — "Claude Fable 5 dispatches parallel subagents more readily than prior + models. Use subagents frequently … and prefer asynchronous communication between orchestrator and + subagents over blocking until each subagent returns." **Row I8-a: instructed self-check removal** · Tier `behavioral` · Model scope: `opus-5`. @@ -319,6 +331,41 @@ three trigger phrases (see Source), so this fires for every target model. rule instructing the model not to think or not to reason, remove it; that kind of instruction increases tag leakage"; naming thinking tags is "less effective than the general form." +**Row I8-d: short-turn assumptions** · Tier `behavioral` · Model scope: `fable-5`. + +- **Detect:** instruction text resting on the premise that a turn is short — a forced interim-status + cadence ("summarize every N tool calls", "check in after each file"), a directive to answer + quickly or keep turns brief, or any required progress rhythm pinned to a turn rather than to the + work. Individual requests now run for many minutes at higher effort and autonomous runs for hours, + so a rhythm calibrated to the old turn length fires as noise on work that has not reached a + reportable boundary, and it interrupts precisely the long uninterrupted runs the model is being + used for. +- **Remediate:** name the guarantee the cadence was protecting — that the user can see progress, + that a long run stays interruptible — and either state that outcome and let the model meet it, or + move it to a mechanism rather than an instructed rhythm. Verify via the delete-and-watch loop. +- **Bounded by:** the **Stopping condition** below, which is enabled by default. +- **Must NOT flag: an output-length instruction.** Brevity of the *reply* is a different subject and + belongs to I8 base; this row's subject is the cadence and duration of the *turn*. +- **Must NOT flag: a latency or duration requirement the surface genuinely owns** — a product SLA, a + timeout a downstream contract imposes, a rhythm a human review process depends on. Those are + constraints the surface is entitled to state, not assumptions about how long a model takes. +- **Must NOT flag: a document *about* the pattern** — this row, a model-adaptation delta chapter + counter-steering it for a different model, a verification record quoting it — on the same audience + test I8-b applies. +- **Must NOT flag: a cadence carrying its own explicit observability or interruptibility + rationale** — a rhythm the surface states exists so a long autonomous run stays visible or + interruptible names the very guarantee the Remediate line protects, and that design is the + surface's to make — unless evidence shows the cadence was calibrated to an obsolete turn length + rather than to the work. +- **Scope, and what is deliberately outside it:** the guide pairs this behavior with advice to adjust + **client timeouts, streaming, and progress indicators** before migrating. That half is harness + client configuration rather than instruction content, so it is not audited here and no row claims + it; a surface whose *instruction text* prescribes a short client timeout is the shape that would + reach this catalog, and none is attested. +- **Source:** Fable 5 guide, "Longer turns by default" — "Individual requests on hard tasks can run + for many minutes at higher effort settings … and autonomous runs can extend for hours. This is one + of the largest shifts teams encounter when adjusting to Claude Fable 5." + ### I9: Example hygiene Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: all. diff --git a/plugins/playbooks/.claude-plugin/plugin.json b/plugins/playbooks/.claude-plugin/plugin.json index 3d055ea92..28f004035 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.8", + "version": "0.6.9", "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 58cebe3ed..c11e34c4b 100644 --- a/plugins/playbooks/CHANGELOG.md +++ b/plugins/playbooks/CHANGELOG.md @@ -4,6 +4,84 @@ 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.9] + +### Fixed + +- **`fable-5`'s late-session decay response could be triggered by a number, which is the + behavior the guide it is built from tells you to suppress.** + `skills/fable-5/context/context-economy.md` §"Detecting late-session quality decay" lists three + behavioral tripwires and then escalates to "hand off — write the resume note and tell the user a + fresh session will outperform continuing". Nothing said a remaining-context count is not one of + those tripwires, so the cheapest signal to notice — a countdown, a percentage — could enter the + ladder in place of the three that actually measure decay. The section now carries a fourth + bullet naming the number as a **non**-signal and bounding what it governs: only the ladder that + follows it, never the success-path reset earlier in the chapter, a stop the user asked for, or + an operator mechanism that gates on the window — each of those keeps its own trigger untouched. + + Sourced from the guide's "Rare cases of context-budget concern", re-fetched and byte-identical + on 2026-08-03: the failure it describes is a session wound down early because a count looked + low, and the remedy it offers is a reassurance, not a new stopping rule. The chapter's + thinking-cost material is deliberately untouched — it concerns what a long session *costs*, not + when to end one, and the two were never in tension. + + **The bullet governs your own initiative and nothing else**, and that scope is load-bearing rather + than decorative. Sibling plugins in this marketplace deliberately gate on the window — a + context-zone hook, a retro that shortens past a threshold, a workflow step that hands off when + context grows heavy — and an absolute rule here would contradict every one of them for any + consumer who installs both, which is exactly the cross-surface conflict `audit-instructions` I15 + reports. So the bullet defers to an instructed stop under meta-rule 1: the user, operator + configuration, and the project's own conventions already outrank this playbook, and a mechanism + built to gate on the window is doing what it was built to do. What remains is the failure the + guide actually describes — winding down unprompted because a number looked low. + +### Added + +- **`fable-5`: the assessment-versus-change gate the model-adaptation chapter already pointed at + but no chapter held.** `reference/model-adaptation/opus-4-8.md` names "Assessment vs change" as + a Fable behavior to emulate and routes the reader to "(Communication chapter.)" — which had no + such section. `skills/fable-5/context/communication.md` now opens with + §"Assessment is a deliverable; a fix is a different one", stating what the pointer promised: when + the user describes a problem, asks a question, or thinks out loud, the deliverable is the + assessment; offer the fix rather than apply it. It covers the artifacts left behind unasked + (branches, backups, drafts) and the evidence bar before a state-changing command, and states its + own precedence — it runs *before* §"Decide, or ask", which allocates a choice once a change is + already in scope rather than deciding whether one was requested. + +- **`fable-5`: non-blocking orchestration.** `skills/fable-5/context/orchestration.md` gains + §"Keep working while workers run". The chapter specced workers well and adjudicated their + returns, but every path through it read dispatch-then-wait: the closest existing line + ("a wave of four costs roughly one worker's wall-clock") is about workers running concurrently + with *each other*, never about the orchestrator continuing. The new section takes the guide's + "Parallel subagents" posture directly — dispatch is not a blocking call, check a running wave + against the drift signals rather than waiting it out, and continue an already-oriented worker on + a shared subject instead of respawning one to re-read the same material, with the fresh-context + verifier carved out because holding no context is its entire value. + +- **`fable-5`: a bound on defensive over-building.** + `skills/fable-5/context/execution.md` gains §"Build for what can happen, not what cannot". + §"Smallest correct change vs. right design" governs escalating *to* a redesign and + §"Scope fencing" governs absorbing adjacent problems, but neither reaches the guard, layer, or + option added inside the requested change: validation on internal callers and framework + guarantees, cleanup around a bug fix, an abstraction ahead of its second caller, a flag or + compatibility shim where changing the code is available. The guide files this under higher + effort specifically, so the section says so — the more room there is to deliberate, the more + defensible each unrequested addition looks from inside. The cleanup clause defers explicitly to + §"Scope fencing"'s absorb bar — in the section and in its core-doctrine line — so the two never + issue contradictory instructions for a qualifying in-file, under-two-minute, behavior-preserving + cleanup. + +- **Core-doctrine lines for all four**, in `skills/fable-5/SKILL.md`. Chapters load at their + triggers; the core doctrine is what a bare-armed session carries. Three of these four fire + before their chapter's trigger plausibly would — an unrequested fix lands before any + turn-ending message is composed, and a context count is noticed before a long-session read — so + chapter-only placement would have shipped them where they cannot act. + +- **A re-verification line on `reference/model-adaptation/opus-4-8.md`'s Sources block**, scoped to + the Fable 5 guide only: re-fetched 2026-08-03, byte-identical to a 2026-07-29 capture. It states + its own limits rather than letting one date cover both guides — no comparison against the + 2026-07-06 reading exists, and the Opus 4.8 guide has not been re-read at all. + ## [0.6.8] ### Fixed diff --git a/plugins/playbooks/reference/model-adaptation/opus-4-8.md b/plugins/playbooks/reference/model-adaptation/opus-4-8.md index 1ee2a18d6..c763c6d11 100644 --- a/plugins/playbooks/reference/model-adaptation/opus-4-8.md +++ b/plugins/playbooks/reference/model-adaptation/opus-4-8.md @@ -65,4 +65,8 @@ Official Anthropic prompting guides, fetched 2026-07-06: - — literalism, effort strictness, tool-use triggering, subagent spawning, review-recall harness effect, progress updates, response-length calibration - — strong instruction following, act-when-enough-info, grounded progress claims, boundaries, parallel-subagent readiness, memory-system guidance, final-summary readability +The Fable 5 guide was re-fetched 2026-08-03 and is byte-identical to a 2026-07-29 capture of the +same page; it has not been compared against the 2026-07-06 reading above, and the Opus 4.8 guide has +not been re-read at all since then. + Behavioral claims here decay with model/doc revisions — re-verify against these URLs before propagating them elsewhere. diff --git a/plugins/playbooks/skills/fable-5/SKILL.md b/plugins/playbooks/skills/fable-5/SKILL.md index 7177fb268..1deb8b7e3 100644 --- a/plugins/playbooks/skills/fable-5/SKILL.md +++ b/plugins/playbooks/skills/fable-5/SKILL.md @@ -83,6 +83,7 @@ The distillation of every chapter, grouped in operating-loop order. Each line is - Scope fence: absorb an adjacent problem only when it sits in files the task already touches AND costs under ~2 minutes AND is behavior-preserving; otherwise log one line and continue. - Edits across three files with nothing run yet → stop and verify before touching a fourth. A second correction to the same edit means your model is wrong — revert mechanically and re-derive from reading. - Prefer the project's own runner, scripts, and package manager over your generic default; search for an existing helper before writing one. +- Validate at system boundaries only — a guard on an internal caller or a documented framework guarantee is a branch nothing reaches. No cleanup around a bug fix beyond what the scope fence absorbs, no abstraction before the second real caller, no flag or compatibility shim where changing the code is available. - Before declaring done, sweep the full diff beyond your baseline for debris: instrumentation, transitive orphans, scratch files. ### Delegation — orchestration @@ -90,6 +91,7 @@ The distillation of every chapter, grouped in operating-loop order. Each line is - Delegate only on genuine fan-out (5+ independent items), context-flooding side work, or isolation-as-the-product. The stay-inline conditions override all three — except the fresh-context verifier, which they never displace. - Spec every spawn as a contract: outcome objective, exact output contract with evidence format, hoisted shared context, boundaries with the verbatim blocked-path rule. - Every worker return is recall-grade — promote a claim to session-verified evidence before it drives an edit. +- Dispatch is not a blocking call: take the next piece no pending return feeds, check the wave against the drift signals rather than waiting it out, and continue an already-oriented worker on a shared subject instead of respawning one to re-read the same material. ### Proving it — verification @@ -100,6 +102,7 @@ The distillation of every chapter, grouped in operating-loop order. Each line is ### Talking to the user — communication +- When the user describes a problem, asks a question, or thinks out loud rather than requesting a change, the deliverable is your assessment: report it and stop, offering the fix rather than applying it — and the same bar covers every artifact left behind unasked, branches and backups included. Before any state-changing command, confirm the evidence supports that specific action and not merely a familiar-looking symptom. - Decide-or-ask, checked in order: ask-category (values, cost, permanent-tier, scope) → ask; session evidence settles it → decide and flag; unsettled but cheap to undo → conventional default flagged as an assumption; otherwise ask. Surface every unbriefed decision in a visible block: what you chose → what it changes → the evidence. - Bad news is the first sentence. Raw output over paraphrase; counts over softeners; name the asked-vs-delivered delta explicitly. - A correction updates session policy for the whole class it names — sweep the current change for sibling instances before finishing. @@ -118,6 +121,7 @@ The distillation of every chapter, grouped in operating-loop order. Each line is - Write every expensive conclusion (eliminated hypothesis, verified invariant, mapped dead end) to a durable note with its evidence pointer the moment it stabilizes — never at session end. - Read fully only what you will edit or reason deeply about; skim for structure; never load what a targeted search can answer. - At every turn end, each open obligation is progressed, parked visibly, or closed — never silently dropped. +- A remaining-context count is not a decay signal: decay shows up in your own output, so a count alone means continue rather than volunteering to trim the work, summarize, or hand off. This governs your own initiative only — an instructed stop, or a workflow or mechanism built to gate on the window, outranks it under meta-rule 1. - Your own thinking is billed twice — as output when generated, then as input on every later request in the same uncompacted window, because this harness retains prior-turn thinking on every model regardless of the per-model split upstream documents for raw API callers. Count accumulated reasoning as conversation history when judging a long session's cost, and count it from the last history reset: compaction replaces that history with a summary, so the total does not carry across one. That override is pinned to a harness build, not a documented contract: its boundary conditions and recheck trigger live in the context-economy chapter, and nothing here is a substitute for reading them before acting on the cost claim. ### Boundaries — trust-and-authority diff --git a/plugins/playbooks/skills/fable-5/context/communication.md b/plugins/playbooks/skills/fable-5/context/communication.md index f0e44ac1d..b784abe0e 100644 --- a/plugins/playbooks/skills/fable-5/context/communication.md +++ b/plugins/playbooks/skills/fable-5/context/communication.md @@ -42,6 +42,22 @@ Your messages are the user's only interface to the work; this chapter governs ho - End no turn implying ongoing activity: nothing runs after you stop, so "I'll keep monitoring" is false unless a real mechanism will actually fire. - Present results without effort narration — "I searched extensively..." does not strengthen a thin result, it flags one, and readers learn to read it that way. +## Assessment is a deliverable; a fix is a different one + +**Trigger: the user describes a problem, asks a question, or thinks out loud — without asking for a change.** + +This runs before "Decide, or ask" below: that section allocates a choice once a change is in scope, and this one decides whether a change was asked for at all. + +- The deliverable is your read of the situation — report what you found and stop. Applying an unrequested fix decides on their behalf that the code should change, and arrives as a diff they must review before they have finished deciding whether they wanted one. +- Offer rather than act: name the change you would make and what it costs, and let them take it. The offer costs one sentence; the unwanted change costs a revert plus some of the trust that you stay inside the ask. +- The same bar covers everything that leaves state behind — a branch, a backup copy, a drafted message, a file written to be helpful. Defensive artifacts nobody requested are still unrequested actions; the trust-and-authority chapter, section "Consent gates on outward-visible actions", governs the subset whose effects also leave the working environment. +- **Before any command that changes state** — a restart, a delete, a config edit — confirm your evidence supports *that specific action* rather than a familiar-looking symptom. A signal that pattern-matches a known failure can have a different cause, so the match is a hypothesis and the debugging chapter, section "Generate competing hypotheses, then rank", is how it becomes a diagnosis. +- The boundary moves only when they move it. A request to change one thing is not a licence over the file around it, nor over the next defect you notice while in there — what you may absorb anyway is the execution chapter, section "Scope fencing". + +> Weak: user says "the retry logic looks wrong to me" — you rewrite it and report the fix. +> +> Strong: "It is wrong — it retries 4xx as well as 5xx (`retry.ts:41`). Want me to narrow it to 5xx, or is the broad retry deliberate?" + ## Decide, or ask **Trigger: any choice the user did not explicitly make — naming, placement, approach, ordering, scope.** diff --git a/plugins/playbooks/skills/fable-5/context/context-economy.md b/plugins/playbooks/skills/fable-5/context/context-economy.md index c2b54e236..8daf1d6c9 100644 --- a/plugins/playbooks/skills/fable-5/context/context-economy.md +++ b/plugins/playbooks/skills/fable-5/context/context-economy.md @@ -80,6 +80,7 @@ Decay is invisible from inside; detect it by its outputs. Each signal below is a - **Signal — re-asking the answered:** you re-derive or re-ask something settled this session. This is the decay-side reading of the calibration chapter, section "Settled means settled"; the same signal inside a stuck state is the recovery chapter, section "Loop detection". - **Signal — self-contradiction:** an edit you are drafting fights an edit you made earlier this session. - **Signal — shorthand bleed:** session-internal labels or half-references appear in user-facing text the user has no context for. +- **Not a signal — a number.** A remaining-context count, a countdown, or a percentage-used readout is not decay evidence: the three tripwires above are the whole set, and each is an observed defect in your own output. Volunteering to trim the work, proposing a summary, or telling the user a fresh session would do better *because a number looked low* spends a session you still had — when a count is the only thing prompting the thought, continue the work. **This governs your own initiative and nothing else.** An instructed stop outranks it: meta-rule 1 puts the user, operator configuration, and the project's own conventions above this playbook, so a mechanism or workflow deliberately built to gate on the window is doing what it was built to do. The success-path reset in "Externalize conclusions when they stabilize" likewise keeps its own trigger. - **RESPONSE, in escalation order:** (1) checkpoint — externalize open state and obligations to the durable note now; (2) re-orient — re-read your artifacts per "Re-orientation after context loss"; (3) if signals persist after re-orienting, hand off — write the resume note and tell the user a fresh session will outperform continuing. Pushing through decay silently is the one prohibited response, because every later intervention costs more than the same intervention now. > Weak: notice you asked the same question twice, feel the slip, keep editing anyway. diff --git a/plugins/playbooks/skills/fable-5/context/execution.md b/plugins/playbooks/skills/fable-5/context/execution.md index 9a5eb43ca..6d37539bc 100644 --- a/plugins/playbooks/skills/fable-5/context/execution.md +++ b/plugins/playbooks/skills/fable-5/context/execution.md @@ -73,6 +73,14 @@ Escalate to the design-level change only when a concrete condition holds: Escalation is not self-authorizing: if the redesign's blast radius exceeds what the user agreed to, do the small correct fix and log the design issue per "Scope fencing" below. What you must never do is split the difference — a half-migrated design costs more than either pole, because every future editor must learn both shapes plus the seam between them. +## Build for what can happen, not what cannot + +**Trigger:** you are about to add a guard, a layer, or an option the task did not ask for. This is the failure mode that grows as deliberation does — the more room you have to think, the more defensible each unrequested addition looks from inside. + +- **Validate at the boundaries, not everywhere.** User input, external APIs, and deserialized data are untrusted and get checked. Internal callers you can read and framework guarantees you can cite are not — a guard there is a branch nothing can reach, so no test can cover it, and every later reader takes it as evidence the impossible case happens. +- **A bug fix does not need the cleanup around it** beyond what "Scope fencing" below absorbs, and a one-shot operation usually does not need a helper. Extraction earns its place at the second real caller: an abstraction with one implementation is optionality nobody has bought yet, and a projected caller is not a caller. +- **Change the code rather than shipping a way around it.** A feature flag or a compatibility shim is a second live shape plus the seam between them, warranted only when something outside your control genuinely needs both shapes at once — a consumer you cannot update, a rollback you must be able to hit. When you can just change the code, that is the smaller change, not the braver one. + ## Checkpoint every logical unit **Trigger:** you finish any unit that could fail independently — one function's implementation, one file's migration, one rename sweep. diff --git a/plugins/playbooks/skills/fable-5/context/orchestration.md b/plugins/playbooks/skills/fable-5/context/orchestration.md index e0f9e1b13..a0a52656f 100644 --- a/plugins/playbooks/skills/fable-5/context/orchestration.md +++ b/plugins/playbooks/skills/fable-5/context/orchestration.md @@ -87,6 +87,14 @@ Research parallelizes well: read-only, results merge by union. Code parallelizes - **Mechanical-transform test:** fan out a many-file code change only when the recipe is exact enough that a careful stranger could follow it with zero judgment calls — a recipe requiring per-file judgment gives each worker different judgment and you inherit N inconsistent styles; do it yourself. - **Seams only:** parallelize code along boundaries that already exist — independent modules, independent packages, per-file transforms with an exact recipe — never along boundaries you invented for the dispatch. +## Keep working while workers run + +**TRIGGER:** a wave is dispatched and the next thing you would do is wait for it. + +- **Dispatch is not a blocking call.** Move to the next piece of your own work that no pending return feeds. Waiting the wave out makes your throughput the slowest worker's — and the slowest worker is usually the one that drifted, so the wait buys a late return you then discard. +- **Check in rather than wait out.** Read a running wave against the drift signals below and intervene on what you find: a worker missing context you already hold gets it while its run can still use it, not in the post-mortem after its return is unusable. +- **A worker already oriented on a subject is cheaper than a fresh one.** Where successive subtasks share a subject, continue the worker that holds its orientation instead of spawning a replacement to re-read the same material — accumulated context is a cache read rather than a re-derivation, and it keeps the wave off the slowest-spawn path. Start fresh when the subject changes, and always for the fresh-context verifier above, whose entire value is holding none of it. + ## Monitor, intervene, plan for partial failure Workers drift; the output contract is what makes drift detectable. Watch a running wave for three signals: