diff --git a/docs/conventions/permission-rule-hygiene/README.md b/docs/conventions/permission-rule-hygiene/README.md index 09db11668..d5d7cb3fc 100644 --- a/docs/conventions/permission-rule-hygiene/README.md +++ b/docs/conventions/permission-rule-hygiene/README.md @@ -79,10 +79,12 @@ order: > On entering auto mode, broad allow rules that grant arbitrary code execution are dropped: > Blanket `Bash(*)` or `PowerShell(*)`; Wildcarded interpreters like `Bash(python*)`; Package-manager -> run commands; `Agent` allow rules. Narrow rules like `Bash(npm test)` carry over. Dropped rules are +> run commands; `Agent` allow rules; `Monitor` allow rules, because Claude Code runs Monitor commands +> through the shell. Narrow rules like `Bash(npm test)` carry over. Dropped rules are > restored when you leave auto mode. > — [permission-modes](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) -> ("How the classifier evaluates actions") +> ("How the classifier evaluates actions"; re-fetched 2026-08-26 — the `Monitor` category was +> added upstream in v2.1.236, which before then left Monitor allow rules in effect in auto mode) The [auto-mode configuration reference](https://code.claude.com/docs/en/auto-mode-config#route-all-shell-commands-through-the-classifier) restates it and adds that `autoMode.classifyAllShell: true` suspends even the narrow shell allow rules: diff --git a/docs/topics/fable-field-guide-audit/audit-brief.md b/docs/topics/fable-field-guide-audit/audit-brief.md deleted file mode 100644 index 7c2d662b8..000000000 --- a/docs/topics/fable-field-guide-audit/audit-brief.md +++ /dev/null @@ -1,77 +0,0 @@ -# Audit brief — shared rules for tasks #1-#14 - -Read this before executing any S-unit audit task. - -## What is being compared - -- **Source**: `source-article.md` (S1-S14), a user-facing field guide written for a human - operating Claude Code. -- **Target**: `plugins/playbooks/skills/fable-5/` — `SKILL.md` plus 13 chapters under `context/`. - Agent-facing introspected doctrine written as standing instructions to the model. - -The audience difference is load-bearing. A claim addressed to the human ("disclose your experience -level", "only merge after you pass the quiz") may have no agent-side counterpart by design. That is -a legitimate finding at the unit level, not only in the final disposition — say so explicitly rather -than forcing a gap verdict. - -## Verdict vocabulary - -- **covered** — the playbook states the claim, anywhere, in any wording. -- **partial** — a weaker, narrower, or differently-scoped version is present. -- **missing** — no counterpart exists. -- **contradicted** — the playbook instructs something incompatible with the claim. -- **out-of-scope (audience)** — the claim is directed at the human operator and has no meaningful - agent-side form. Requires a one-line reason. - -Every verdict carries `file:line` evidence. Absence verdicts state where you looked. - -## Rules that change verdicts - -1. **One home per doctrine** (`SKILL.md` meta-rule 2). A shared rule has exactly one owning section - and other chapters cite it. Finding a claim in a chapter other than the one you expected is - still **covered** — never a gap. Search the whole skill before declaring anything missing. -2. **Model-specific claims live in `context/opus-adaptation.md`** and nowhere else (`SKILL.md` - "What this skill is NOT"). Do not propose adding model-behavior claims to other chapters. -3. **The playbook governs how, never what** (meta-rule 1). Proposals that encode project - convention, task content, or user preference belong outside this skill. -4. **Silent application** (meta-rule 4). The playbook forbids narrating compliance, so absence of a - user-visible ceremony is not evidence a rule is missing. - -## Repo doctrine that binds any remediation you propose - -`docs/PLUGIN-PHILOSOPHY.md` governs. The clauses that shape remediations here: - -- **Design boundary** — a plugin is a reusable vertical slice that must work outside this repo and - org. Runtime behavior never depends on publisher names, org-specific variables, repo names, or - absolute paths. -- **Two-lane convention posture** — a convention a consumer could reasonably do differently is - discovered and externalized as configuration, never shipped as a baked-in default. A bare - hardcode in a skill declared agnostic is a defect. -- **Fresh-eyes checkpoints** — a step whose output judges work produced in the same context - delegates that judgment to a fresh-context (non-fork) subagent. Relevant to any remediation you - propose that adds a self-review step. -- **Evidence and validation** — for Claude Code behavior, fetch current official documentation in - the same session; never rely on memory or an old summary. - -## Model-name coupling — standing constraint on remediations - -The operator's standing direction: skill content must not hardcode model names, because a named -model becomes drift the moment the fleet moves. The doctrine in this playbook is meant to hold -across the Claude 5 generation and beyond, not for one model. - -Consequences for your findings: - -- Never propose a remediation whose wording depends on a specific model name or version. -- Prefer capability- or behavior-conditioned phrasing ("when the model's default is X") over - identity-conditioned phrasing ("Fable does X"). -- If the source article's claim is *inherently* model-specific, say so and mark it as a - model-coupling risk rather than proposing text that embeds the name. -- Report, do not resolve, any tension you find between this constraint and the playbook's existing - structure (its name, `context/opus-adaptation.md`, and the naming exception in - `docs/PLUGIN-PHILOSOPHY.md` that sanctions provenance-named playbooks). That tension is tracked - separately. - -## Deliverable - -Findings only. No edits under `plugins/playbooks/skills/fable-5/**`. The repo is on `main` with a -clean tree; branch before any file edit lands. diff --git a/docs/topics/fable-field-guide-audit/coverage-reconcile.md b/docs/topics/fable-field-guide-audit/coverage-reconcile.md deleted file mode 100644 index 78522f2fc..000000000 --- a/docs/topics/fable-field-guide-audit/coverage-reconcile.md +++ /dev/null @@ -1,69 +0,0 @@ -# Coverage reconcile (task #15) - -Completeness gate for the S1-S14 audit. Verified by construction, not inspection. - -## Check 1 — every article body line survives into the audit source - -Script: normalize (lowercase, strip punctuation, collapse whitespace) every content line of -`raw-capture.txt` lines 179-291, drop the known site-chrome lines, and assert each remaining line's -first eight words appear in `source-article.md`. - -- Body lines checked: **113** -- Orphans: **0** - -Scope limit, stated rather than implied: this proves `source-article.md` is faithful to -`raw-capture.txt`. It proves nothing about the live page — a later edit upstream would not be -detected. `raw-capture.txt` is a 2026-07-24 snapshot. - -## Check 2 — the article's own pattern index - -The article supplies its index in S4: 8 named patterns across three phases. Each has a dedicated -audit unit with a persisted ledger. - -| Pattern | Unit | Ledger | -|---|---|---| -| Blind spot pass | S5 | `findings/S5.md` | -| Brainstorms and prototype | S6 | `findings/S6.md` | -| Interviews | S7 | `findings/S7.md` | -| References | S8 | `findings/S8.md` | -| Implementation plan | S9 | `findings/S9.md` | -| Implementation notes | S10 | `findings/S10.md` | -| Pitches and explainers | S11 | `findings/S11.md` | -| Quizzes | S12 | `findings/S12.md` | - -8 of 8. Each ledger's subject term was grep-confirmed present in its own file. - -## Check 3 — the four unknown quadrants - -All four carry their own verdict section in `findings/S2.md`: Known knowns (covered), Known unknowns -(covered), Unknown knowns (covered, playbook stronger), Unknown unknowns (partial — the -achievable-ceiling facet is the gap). - -4 of 4. - -## Check 4 — ledger completeness - -14 units dispatched, 14 ledgers persisted under `findings/`. No unit returned empty; no unit was -dropped. - -## Cross-unit handoffs raised during the audit — all resolved - -| Raised by | Handoff | Resolution | -|---|---|---| -| S2 | Q2 routing asymmetry → S7 | S7 assessed it: interview narrows, does not close. Both are one missing mechanism. | -| S2 | Q3 exemplar move overlaps S8 | S8 audited the exemplar move independently; no double-count. | -| S4 | reader-expertise axis → S11 | S11 declined it: no legitimate home, and attaching it would launder an auditor-originated finding. Kept as a separate observation with its own justification. | -| S13 | F4 explainer shares S11's doctrine | Flagged not-double-counted; S13 supplies a second trigger for whatever home S11 lands on. | -| S1 | post-implementation residue → S11/S12/S14 | All three audited it from their own angle. | - -## Findings this gate did NOT check - -- Whether individual verdicts are correct. That is the auditors' work, and two of them (S6, S7) - shipped without an independent review pass because advisor was rate-limited. Recorded in those - files. -- Whether the remediations are good. That is task #16. - -## Outcome - -No orphan text. No uncovered pattern. No uncovered quadrant. No missing ledger. Coverage is -satisfied by construction. diff --git a/docs/topics/fable-field-guide-audit/disposition-review.md b/docs/topics/fable-field-guide-audit/disposition-review.md index 697450f6c..9af6f7596 100644 --- a/docs/topics/fable-field-guide-audit/disposition-review.md +++ b/docs/topics/fable-field-guide-audit/disposition-review.md @@ -185,9 +185,9 @@ therefore a two-site edit with operative text at both, not one line plus a point Row 12 verified against `trust-and-authority.md:56-60`, an authorization gate with no comprehension component, as asserted. - **Row-level completeness of §6** — spot-checked against S1, S5, S6, S7, S11, S13; every ledger row - survives. The attribution of that property to `coverage-reconcile.md` is loose — that file checks - article-line, pattern, quadrant and ledger coverage, not ledger-row survival — but the property - holds. + survives. The attribution of that property to the audit's coverage-reconcile check (a working + file removed after absorption) is loose — that check covered article-line, pattern, quadrant and + ledger coverage, not ledger-row survival — but the property holds. - **The twelve cost-asymmetry sites** — eleven verify cleanly; `planning.md:51` ("Information gain per unit cost sets the order") is an ordering rule and a soft fit. - **R15-R17, R19, R20, R24 citations** — `context-economy.md:37`, `execution.md:128`/`:133`, diff --git a/docs/topics/fable-field-guide-audit/dispositions.md b/docs/topics/fable-field-guide-audit/dispositions.md index 3a61c806e..76301bc7f 100644 --- a/docs/topics/fable-field-guide-audit/dispositions.md +++ b/docs/topics/fable-field-guide-audit/dispositions.md @@ -28,7 +28,8 @@ one root cause appears once as a remediation and many times as evidence. **R13, reclassified during synthesis** — as A2 (§7), D1 (§3) and D4 (§3) respectively — so those three numbers are absent from §5 by design, not by omission. Every row from every ledger survives as a row here, including the no-change ones — collapsing them would discard the -completeness property `coverage-reconcile.md` established. +completeness property the audit's coverage-reconcile check established (that working file was +removed once its conclusion was absorbed here). Audit-originated findings (not derivable from any article claim) are quarantined in §7 so they cannot be laundered into article-derived gaps. diff --git a/docs/topics/fable-field-guide-audit/findings/S10.md b/docs/topics/fable-field-guide-audit/findings/S10.md deleted file mode 100644 index 9c892425d..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S10.md +++ /dev/null @@ -1,155 +0,0 @@ -# S10 — fresh session + implementation notes - -Searched: full reads of `SKILL.md`, `context-economy.md`, `planning.md`, `execution.md`, -`orchestration.md`, `recovery.md`; targeted greps across all 13 chapters for `fresh session|new -session|handoff|work note|implementation note|resume note|artifact|seed|prime`; -`conservative|deviat|log it|decision log|worklog|multi-session|long-horizon`; `lesson|next -attempt|retro|scratch|temporary|delete`; `unknown|surprise|edge case`. - -## (a1) Planning output becomes a durable artifact — COVERED - -`planning.md:13` ("Plan as durable artifact when work will outlive the current context window"), -`:29` (every step boundary is "a state you could commit or hand off from"), `:108` ("whoever resumes -from it, including a future you with a fresh context"); `context-economy.md:37`. - -## (a2) Deliberate fresh session at a clean phase boundary — PARTIAL - -Every context-reset trigger in the skill is initiated by loss or degradation, never by successful -phase completion: - -- `context-economy.md:40` — trigger is "context loss is foreseeable — a handoff is planned, the - session nears its end, compaction is imminent." -- `context-economy.md:47` — trigger is "resuming after compaction, a handoff, or a fresh session", - i.e. the *arrival* side only. -- `context-economy.md:64` — the agent recommending a fresh session exists, but only as escalation - step 3 after decay signals persist. - -The playbook handles the fresh session as something that happens *to* the agent, or as a remedy for -degradation. It never treats a clean phase boundary — plan is good, now discard the planning context -on purpose — as a reason to reset. - -Nearest doctrine, and why it does not close the gap: `orchestration.md:44` — "Hoist shared context -into the spec: paste the key facts you already hold … instead of sending each worker to rediscover -them." Same *mechanic* (seed a clean window with compiled findings), opposite *subject*: it seeds a -subordinate while the parent keeps its context. The article's move retires the parent's own context. -Citing `:44` as coverage would paper over that. - -Not out-of-scope (audience): the agent cannot open its own top-level session, but -`context-economy.md:64` already establishes "recommend a fresh session" as in-repertoire. The -agent-side form exists — it is simply gated on degradation rather than on phase completion. - -Remediation: one trigger bullet in `context-economy.md` §"Externalize conclusions when they -stabilize". Shape — a phase completes and its output is a compiled artifact the next phase consumes -(a settled plan, a spec, a prototype); the artifact, not your context, is the handoff; recommend -continuing in a clean context seeded with it, because the exploration that produced the artifact is -now dead weight competing with execution. No model name; no repo path or artifact filename (say -"durable artifact", never a specific filename — PLUGIN-PHILOSOPHY design boundary). - -## (b) Planning never eliminates unknown unknowns — COVERED - -`problem-framing.md:67`; `planning.md:100` ("TRIGGER — the moment an outcome differs from the -prediction"), `:49`; `recovery.md:22-26` (sunk-cost release — the "different tack" decision, owned -here), `:33,35`; `SKILL.md:106`. - -Fully owned, correctly distributed under meta-rule 2 — framing owns the pre-work hunt, planning owns -the surprise classifier, recovery owns the switch decision. - -## (c1) Notes file for cross-attempt learning — PARTIAL + meta-rule 2 placement conflict - -The *artifact* is covered; the *purpose* is not, in any general-purpose chapter. - -- `context-economy.md:37-40` mandates the durable work note, but its stated purpose throughout is - context-loss insurance — `:31` "these evaporate at context loss and re-derive at full price", - `:39` "After any context loss, your notes are recall-grade." The audience is a future self inside - the same work. -- `recovery.md:26` is the only general-chapter statement of cross-attempt learning, and it is - narrow: "record the abandoned path in one line so a later pass does not re-walk it." -- `opus-adaptation.md:52` is the only full-purpose match: "write lessons and state to durable files - as you go (one lesson per note, why it mattered, delete notes proven wrong)." - -**Placement conflict, reported as its own finding.** `opus-adaptation.md` is reserved for -model-specific behavioral claims (`SKILL.md:146`). "Write lessons to durable files as you go" is not -a model-behavior claim — it is general doctrine sitting in the chapter that cannot be its home. -Consequence: the article's implementation-notes concept has *no* general-purpose owner. Any -remediation is a **promotion**, not an addition. - -Remediation: promote the lesson-note purpose from `opus-adaptation.md:52` into `context-economy.md` -§"Externalize conclusions when they stabilize" as a second purpose alongside loss insurance -(decisions made and why, so a later attempt inherits them instead of re-deriving), leaving in -`opus-adaptation.md` only the genuinely model-conditioned residue — that this needs deliberate -practice rather than arriving by default. Permitted by the brief's rule 2: model-specific claims -live only there; not everything there is model-specific. - -## (c2) Conservative deviation, log, continue — COVERED, playbook strictly stronger - -`planning.md:102` is a near-verbatim counterpart including the conservatism rationale: "**Local** — -the step needed a different tactic but its end-state holds → absorb it with the *conservative* -variant — the tactic that adds the least new surface and forecloses the fewest later options — note -the delta, continue. Mid-plan is the worst vantage for judging a clever deviation's blast radius." - -## Resolution of the stated tension - -**Compatible — but not as "different magnitudes." The divergence sits at the aggregation layer, not -the move layer.** - -The two sources agree completely on what to do about *one* surprise: take the conservative variant, -record the delta, continue. - -They differ in two things the article omits entirely: - -1. **A classifier.** `planning.md:102-104` sorts every surprise three ways — local (end-state holds - → absorb), structural (invalidates a *later* step's premise → stop, rewrite the affected steps), - premise-level (contradicts what the task itself assumed → stop entirely, return to the user). The - article's trigger is "hit an edge case that forces you to deviate from the plan", which is - **magnitude-blind**: an edge case found in the code can just as easily be structural or - premise-level, and the article prescribes the same "keep going" for all three. Verified against - the article's own example prompt — no qualifier, no classifier, no exit condition. -2. **A counter.** `planning.md:106` — "two consecutive local surprises, or one structural surprise, - ends execution and forces an explicit replan." The article's rule as written is an unbounded - loop. - -The article's instruction is correct for exactly the case the playbook calls *local*, and the -playbook's threshold is precisely the safeguard the article lacks. `planning.md:106` names the -article's failure mode by description: "Serial patch-and-continue is how a coherent plan degrades -into an incoherent one — each patch locally reasonable, the sum indefensible." - -**Which governs: the playbook.** Not on incumbency — on merit. The article's rule is a strict subset -that drops the classifier and the counter, converting bounded absorb-and-continue into unbounded -patch-and-continue. **The remediation direction here points at the source article, not at the -skill.** The one place in S10 where the playbook is the stronger document. - -Residual, not a defect: the article's Deviations *heading* — a named, reviewable section collecting -the absorbed deltas — is slightly more concrete than `planning.md:102`'s bare "note the delta". -Below the bar for its own remediation, but it is the shape a (c1) promotion would naturally carry. - -## Additional finding — internal seam, not a source-article gap - -The article's notes file is explicitly **temporary**, which lands on an unreconciled seam: - -- `context-economy.md:37` mandates writing a durable work note. It never states where the note lives - or what happens to it at task end. -- `execution.md:128` scopes the completion sweep to "the entire working state — every file modified - or untracked beyond your census baseline." -- `execution.md:133` names as debris "Scratch files, experiment outputs, and generated artifacts - that landed inside the project tree." - -A work note written into the project tree is untracked, beyond the census baseline, and is a scratch -file in the project tree. Neither chapter carves it out or cites the other (`execution.md:132` cites -debugging's probe-marker rule; nothing addresses the work note). No exemption language anywhere. - -Remediation: one clause, single home. Preferred owner is `context-economy.md` §"Externalize -conclusions when they stabilize", stating the note's disposition at task end (survives as a -deliverable, is folded into the change description, or is removed) so `execution.md`'s sweep has an -unambiguous answer; `execution.md:133` then needs no edit. The alternative — an exception clause at -`execution.md:133` — is worse: it puts the note's lifecycle in a chapter that does not own it. - -## Verdict summary - -| Claim | Verdict | Primary evidence | -|---|---|---| -| (a1) planning output → durable artifact | covered | `planning.md:13,29,108`; `context-economy.md:37` | -| (a2) deliberate fresh session at phase boundary | **partial** | `context-economy.md:40,47,64`; `orchestration.md:44` (wrong subject) | -| (b) unknown unknowns / different tack | covered | `problem-framing.md:67`; `planning.md:49,100`; `recovery.md:22-26,33,35`; `SKILL.md:106` | -| (c1) notes file for cross-attempt learning | **partial** + placement conflict | `context-economy.md:37-40`; `recovery.md:26`; `opus-adaptation.md:52` | -| (c2) conservative deviation, log, continue | covered, playbook stronger | `planning.md:102`, bounded by `:103-104,106` | -| work-note vs debris-sweep seam | internal inconsistency | `context-economy.md:37` vs `execution.md:128,133` | diff --git a/docs/topics/fable-field-guide-audit/findings/S11.md b/docs/topics/fable-field-guide-audit/findings/S11.md deleted file mode 100644 index 88af0f3ad..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S11.md +++ /dev/null @@ -1,158 +0,0 @@ -# S11 — pitches and explainers - - - -**Search basis.** Five ripgrep sweeps across all 14 files: (a) -`buy-in|approval|approvals|reviewer|stakeholder|pitch|explainer|shareable|Slack|third.part|PR -descri|pull request|demo|GIF`; (b) `unknown|prototype|durable note|persist|scratch|\.md`; (c) -`audience|persuad|convince|sign.off|adopt|advocate`; (d) `package|bundle|assemble|final -document|write-up|for a reader|readers`; (e) -`expertis|novice|beginner|inexperien|jargon|vocabulary|starting point|depth of -explan|technical level|familiar`. - - -Full reads: `SKILL.md`, `communication.md`. Targeted reads: -`problem-framing.md:55-104`, `execution.md:80-108`, `context-economy.md:24-48`, -`reasoning-moves.md:114-133`, `trust-and-authority.md:44-62`. Not every chapter read end to end. - -## Claim 1 — Shipping requires buy-in and approvals — OUT-OF-SCOPE (audience) - -A fact about the human's organization. The model has no approvals process to satisfy. - -Nearest agent-side analogue, and it is a different rule: `trust-and-authority.md:56-59` gates -outward-visible actions ("an artifact published or shared", "a review comment posted") on -live-session authorization. That is consent-to-act, not securing-approval-from-others — the -playbook's only "approval" concept runs user→agent, never agent-artifact→third-party. - -Remediation: none. Encoding an org's shipping process is *what* the work is, not *how* -(`SKILL.md:15`, `:145`). - -## Claim 2 — Accelerates UNDERSTANDING; reviewers start with the same unknowns — MISSING - -Both halves absent — the artifact-production instruction and the stated rationale. - -- The "same unknowns" rationale appears nowhere. The unknowns machinery at - `problem-framing.md:58-69` is aimed exclusively at clearing the request's unknowns *before - building*; `:69` closes it as "Each cell cleared before building is a rework cycle that never - ships." No line carries the cleared-unknowns record forward to any downstream reader. -- No section instructs producing an explanatory artifact for a third party. Closest are - `execution.md:88` ("a reviewer must be able to reconstruct your intent from the diff alone, - without the conversation transcript") and `:92` ("Move the missing 'why' into the artifact"). - Both bound the payload to the diff and its description; neither produces a standalone document, - and neither cites reader-unknowns as the reason. - -**The axis that separates article from playbook:** every reviewer-facing rule in the playbook is -*defensive* — survive a cold review (`execution.md:84-96`, `reasoning-moves.md:124`). S11's artifact -is *persuasive* — win buy-in. **The playbook has no persuasion register at all.** - -Remediation: none that survives repo doctrine cleanly. Producing a persuasion document is task -content, not method. The one method-shaped residue belongs to Claim 3. - -## Claim 3 — Accelerates APPROVALS; experts want the failure points accounted for — PARTIAL - -Substance present and near-verbatim; downstream reuse absent. - -- Substance: `problem-framing.md:67` — "enumerate what an experienced practitioner of this domain - would ask about that the request never mentions — failure handling, concurrency, migration of - existing data, the operational story, the second consumer." Exactly S11's "common failure points - they would have anticipated." -- The gap is temporal and directional. `problem-framing.md:60` triggers the pass pre-build, and - `:67` terminates it at "Surface the result as a short list **before locking the frame**" — - surfaced to the *user*, in session, to shape the plan. Three candidate carriers past - implementation were checked: the durable work note (`context-economy.md:35-40`) is scoped to - expensive conclusions for *your own* re-orientation after context loss; the closing message - (`communication.md:112-118`) is scoped to the operator; the diff-reviewability rules - (`execution.md:88-92`) are scoped to the diff. Nothing carries the blind-spot list into anything a - reviewer reads. - -**Candidate remediation (the only viable one).** `reasoning-moves.md:128` already states an -open-ended bar — "run every critic whose audience this artifact actually has" — and `:126` asserts -that section's ownership of the critic roster ("No other chapter runs this critic"). A fourth critic -fits that hook without a one-home collision: a critic defined by the information they lack — holding -only the artifact, no session access, who must decide whether to *accept* the work rather than -merely understand it. Its concrete note is S11's surviving method-shaped residue: whether the -artifact shows the domain's standard failure questions were considered, or leaves the approver to -ask them. Wording must stay format-agnostic — naming Slack, a PR description, a design doc, or a -demo GIF would bake in a convention a consumer could reasonably do differently (two-lane posture). - -## Claim 4 — Packages prototype, spec and notes into one shareable document — MISSING - -- The three inputs exist individually and are never joined: prototype at `problem-framing.md:66`; - completion criteria/spec at `:94-104`; the durable note at `context-economy.md:35-40`. Grep for - `package|bundle|assemble|final document|write-up` returns no assembly instruction anywhere. -- One directional hit: `trust-and-authority.md:56` names "an artifact published or shared" as a - consent-gate *trigger*, presupposing such artifacts exist but instructing nothing about producing - one. -- **Composition conflict worth recording:** `context-economy.md:33` explicitly forbids padding the - durable note with anything below the re-derivation-cost bar, and `:32` scopes it to expensive - conclusions. The playbook's one persistent artifact is deliberately *not* a shareable explainer — - repurposing it would contradict its own persistence bar. - -Remediation: none. Assembling a deliverable is task execution. - -## The key distinction, tested directly - -**Does "Write the closing message for a reader who wasn't watching" cover a third-party approval -artifact? No.** Four axes, one of which generalizes: - -- **Audience axis — generalizes.** `communication.md:116-117` (expand session-internal shorthand, - use concrete identifiers over pointing words) hold for any reader without the transcript. -- **Reader identity — does not.** `communication.md:118` names the reader outright: "The user - returns hours later having forgotten the session's middle." Same at `reasoning-moves.md:125`, - which routes this standard through the critic "**The user** seeing only the final message." The - reader is the operator with amnesia, not a party who never had session access. -- **Purpose axis — does not.** The section's own test at `:118` is "could someone holding only this - message and the diff **act correctly**?" Act, not approve. Enablement, not persuasion. -- **Artifact axis — does not.** `communication.md:114` triggers on "every turn-ending message". The - unit is a reply inside the session, not a document that leaves it. - -**Any home for producing a reviewer-facing artifact? No.** Full inventory of third-party-reader -surfaces: the diff and its change description (`execution.md:84-96`), the cold-diff-reviewer critic -(`reasoning-moves.md:124`), the maintainer-a-year-out critic (`:126`). All three defensive, all -three bounded to code. `reasoning-moves.md:128` is the only structurally open hook. - -**Does "reviewers start with the same unknowns you did" appear anywhere? No.** - -## Cross-cutting - -No model-specific claim in S11; the Claim 3 remediation is phrased by the critic's missing -information. One-home check: the critic roster is owned by `reasoning-moves.md:120-128` (ownership -asserted at `:126`), so adding a critic there creates no second home; placing it in -`communication.md` *would* collide. Meta-rule 4 does not apply — the absence found is of an artifact -and a rationale, not of a user-visible ceremony. - -## S4 handoff — the reader-expertise axis - -**Verdict: no home here. Drop it from the article-derived ledger.** Attaching it to S11 would -launder an auditor-originated observation into an article-derived gap. - -The absence claim itself is accurate, independently re-verified. The only expertise-conditioned -rules in the entire skill are `problem-framing.md:60` and `:69`, and both calibrate the -*investigative breadth of the blind-spot pass*, not explanation depth or vocabulary in output. So -`communication.md:16-23` (decision load only) and `:112-118` (transcript-independence only) do stand -as the complete calibration set for output. - -Why S11 does not host it — three independent reasons: - -1. **S11's rationale runs the opposite direction.** "Reviewers start with the same unknowns you did" - asserts the reader's starting knowledge *matches* the author's — a shared-baseline claim, which - is the premise under which an expertise-differential axis would be unnecessary. -2. **S11's second reader is an expert, and the prescription is content coverage, not depth.** - "Experts want to see you accounted for the unknowns" asks *what to include*, not *how deeply to - explain*. S11 varies payload by reader, never register. -3. **The Claim 3 remediation is defined by missing session context, not missing domain expertise.** - The approver critic knows the domain — that is precisely why they can spot an unaddressed failure - point. Folding a depth/vocabulary rule in would break the mechanism `reasoning-moves.md:122` - states ("each one is defined by information they do NOT have"). - -**Disposition:** keep it as an auditor-originated observation in its own section, carrying its own -justification rather than an S-unit citation — and restate it more precisely than "no -reader-expertise axis exists", which `problem-framing.md:60,69` falsifies on its face. Accurate -form: *the playbook's single expertise axis calibrates investigative breadth -(`problem-framing.md:69`); no rule calibrates output register — explanation depth or vocabulary — to -any reader's expertise.* Two caveats: it has no S-unit to derive a trigger from, and any remediation -would have to clear the two-lane posture, since "how much to explain to whom" is close to a -convention a consumer could reasonably set differently. If the disposition has no section for -auditor-originated findings, drop it. diff --git a/docs/topics/fable-field-guide-audit/findings/S12.md b/docs/topics/fable-field-guide-audit/findings/S12.md deleted file mode 100644 index 3062c4fed..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S12.md +++ /dev/null @@ -1,137 +0,0 @@ -# S12 — quizzes as a merge gate - -## Headline - -The playbook has **no comprehension gate** and **no outward-facing form of the S12 rationale**. It -DOES hold the agent-side twin of that rationale — behavior routes through code you did not modify — -but exclusively as an input to the agent's own verification, planning and reading discipline, never -as an obligation to tell the operator what the diff omits. - -An agent-facing playbook cannot hold a gate the operator applies to themself. The honest agent-side -counterpart is narrower and is exactly one thing: **name the behavior that changed in code the diff -does not contain.** - -## C1 — "accomplished more than I realized" — PARTIAL - -`communication.md:112-118` — "Write the closing message for a reader who wasn't watching"; `:118` -"The user returns hours later having forgotten the session's middle." Covers the transcript-is-gone -premise. `communication.md:31` — asked-vs-delivered delta, covers UNDER-delivery ("Silence about Y -reads as Y done"), not over-delivery. `communication.md:67-76` — "Surface every unbriefed decision" -in a visible block; nearest real counterpart. `execution.md:76` scope fence and -`communication.md:61` scope ask-category prevent unbriefed growth rather than reporting it after. - -Gap: covers DECISION-level surprise, not VOLUME-level surprise after a long autonomous run. Nothing -keys on session length. Subsumed by R1. - -## C2 — Diffs give only light understanding — PARTIAL (agent-side twin strong, outward form absent) - -Agent-side twin: - -- `verification.md:58` — "Walk every caller of the thing you changed that you did not modify, - because contract changes break at the call sites you were not looking at." -- `verification.md:23` — verify at the outermost boundary; "inner layers can each be correct while - the wiring between them is not." -- `planning.md:83` — "Compile-time reference counts systematically undercount blast radius." -- `planning.md:85` — "a change correct at the edit site and wrong at three call sites you never - opened." - -Diff-legibility doctrine, differently scoped: `execution.md:88` — the standard is that "a reviewer -must be able to reconstruct your **intent** from the diff alone." Intent, not behavior. -`execution.md:92` — "If a hunk needs the chat to make sense, the diff is incomplete." -`reasoning-moves.md:124` — the "reviewer reading the diff cold" critic. - -Why this is a gap, not coverage: every remedy above repairs THE DIFF. The information S12 names -cannot go in the diff — it lives in files the change never touched. `execution.md:88` is satisfiable -by a perfectly legible diff that still leaves the reader with no idea which existing paths now carry -new behavior. - -**Direct tension to record:** `communication.md:20` instructs cutting "file-by-file recaps the -version-control diff already shows" — presuming the diff is a sufficient record of what changed. C2 -asserts precisely that it is not. Defensible for recaps, but as written there is no carve-out for -behavior the diff cannot carry. - -## C3a — The quiz mechanism — OUT-OF-SCOPE (audience) - -A user-requested deliverable, i.e. WHAT the work is, which meta-rule 1 places outside this skill. - -Where the auditor looked and found nothing: grepped the full skill for -`teach|learn|educat|quiz|comprehen|walk them through`. Every hit unrelated (`recovery.md:22`, -`execution.md:74`, `calibration.md:82`, `context-economy.md:3`). **No teaching or explaining -doctrine exists anywhere in the skill.** - -## C3b — Operator understanding is the agent's responsibility — MISSING - -Nearest existing rule, genuinely close: `communication.md:84` — "Give each option enough to decide -from the message alone — what it costs, what it forecloses; if choosing requires a follow-up -question, the options were underspecified." The one place the playbook makes the operator's ability -to decide the agent's responsibility. Scoped to presenting options, never to a completed change -awaiting approval. - -Also note `communication.md:118` — the actionability test is "could someone holding only this -message **and the diff** act correctly?" It explicitly leans on the diff, which is the assumption C2 -attacks. - -R1 closes the actionable slice. A general "ensure the operator understands" rule is NOT -recommended — unfalsifiable, the agent cannot observe operator comprehension, and it would collide -with `communication.md:16-23`. - -## C4 — "I only merge after I pass the quiz" — OUT-OF-SCOPE (audience) - -Operator self-discipline; the playbook can neither administer nor observe it. - -Adjacent agent-side rule that IS held, and is a different gate: `trust-and-authority.md:56-60` -consent gate — "a push to a shared branch" needs explicit live-session authorization; approval of -one outward action never extends to the next. `:66-67` strong example is literally "Change complete, -verified, committed locally. Say the word and I'll push and open the PR." `SKILL.md:31` floor. - -**The distinction that matters:** the playbook's gate is **authorization**; S12's is -**comprehension**. Authorization can be granted without comprehension, and nothing requires the -agent to check that the operator understands what they are authorizing. Not repairable agent-side -beyond R1. - -## C5 — The explanatory artifact — OUT-OF-SCOPE (audience), with a flagged default-direction tension - -`communication.md:20` cut recaps; `:21` "Large work with a clean result gets a short message"; `:23` -never pad. These govern the agent's discretionary turn-ending message, not a user-requested report, -so NOT contradicted. But the default after a large clean session points at brevity, and no trigger -exists under which an unprompted explanatory pass is warranted. - -## R1 — RECOMMENDED - -Add one bullet to `communication.md` § "Write the closing message for a reader who wasn't watching", -inserted before the closing test at `:118`. Illustrative wording: - -> Name the behavior that changed in code you did not edit — an existing handler, dispatcher, or call -> site now reached under new conditions, a default that now resolves differently. The diff shows the -> lines you wrote, never the paths they activate, so a reader reconstructing the change from the -> diff alone systematically under-reads its effect. - -Why this home and shape: - -- `communication.md` owns the closing message; `execution.md` § "Keep the diff reviewable" owns diff - SHAPE, and this information provably cannot live in the diff. One-home respected, and the existing - test at `:118` — "this message **and the diff**" — is exactly the clause this completes. -- The agent is the only party who can supply it: it already holds the caller walk from - `verification.md:58` and the consumer census from `planning.md:73-83`. Reports evidence already - gathered; adds no new work. -- Falsifiable and observable — a named path, or an explicit "none". -- Translates the audience honestly: does not pretend the agent can gate the operator's merge, only - that it owes the operator what the diff withholds. - -Optional secondary: a one-line cross-reference from `execution.md:92` to the new bullet, since a -reader arriving via the "reviewer reading the diff cold" critic lands in `execution.md` first. - -## R2 — NOT recommended, recorded for the disposition - -Extend the consent gate at `trust-and-authority.md:56-60` so a request for authorization on outward -work the operator has not inspected carries what they need to evaluate it, generalizing -`communication.md:84`. Declined because: it crosses two chapters' ownership boundary, its trigger -("has not inspected") is unobservable to the agent, and R1 already delivers the substantive content. -If the disposition wants the comprehension angle represented beyond R1, this is the place — but it -needs a falsifiable trigger first. - -## Constraint checks - -No model-name coupling in any proposed text; nothing in S12 is inherently model-specific. -`opus-adaptation.md` correctly untouched. Meta-rule 4 clean — R1 emits substantive content, not a -compliance announcement. R1 adds no self-review step, so `orchestration.md:61-72` unaffected. diff --git a/docs/topics/fable-field-guide-audit/findings/S13.md b/docs/topics/fable-field-guide-audit/findings/S13.md deleted file mode 100644 index ab9c89f69..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S13.md +++ /dev/null @@ -1,130 +0,0 @@ -# S13 — launch-video worked example - -> Reviewed with the advisor; F4's absence verdict was re-grounded on its advice (second term cluster -> plus a full `communication.md` read) before shipping. - -## F1 — Generating options is useless until you can evaluate them — PARTIAL (highest-value gap) - -Four near-neighbours, none encoding the precondition: - -- `problem-framing.md:66` — the unknown-knowns cell asserts the operator "cannot articulate but - **will recognize on sight**: taste, workflow fit," and prescribes "show instead of asking." - Recognition is stated as a given. No precondition test, no fallback when recognition does not - arrive — exactly the S13 color-grading failure. -- `calibration.md:60-61` — closest the skill comes to the *shape* of the finding: a stop trigger - fires when "you are comparing options on dimensions where they do not differ", and **SURVEY DEPTH - = PURSUIT DEPTH** states "enumerate options only as deep as you would actually pursue them… a - comparison you will not act on is decoration." The principle that an unactionable comparison is - waste is already doctrine — but aimed exclusively at the *agent's own* pursuit depth, never at - whether the operator receiving the comparison can act on it. One step short. -- `communication.md:80-85` — "Always name a recommendation" fires on "any time you present two or - more options." Its self-check at `:84` ("if choosing requires a follow-up question, the options - were underspecified") is the nearest evaluability gate, but it locates the defect in **option - specification** and prescribes "specify more." In an unfamiliar or aesthetic domain, more - specification does not close the gap — the reader's missing evaluation vocabulary does. `:83` ("a - menu without a pick makes them redo your synthesis") recognizes reader cost but treats a - recommendation as sufficient remedy; a recommendation whose basis the operator cannot read is - still unjudgeable. -- `problem-framing.md:109` — structurally the S13 recovery: "If you cannot write a checkable - criterion, treat it as a frame defect… either you do not yet understand the problem, or the task - is genuinely judgment-shaped — say so and agree on a proxy or a review checkpoint before - starting." But (a) its trigger is "before the first mutating action" on a change with a done-state, - not on an option-generation move; (b) its remedy is proxy/checkpoint negotiation, never acquiring - domain literacy; (c) neither `:66` nor `communication.md:80` cites it, so the precondition never - reaches the path that actually generates options. -- `problem-framing.md:69` scales **question breadth**, not evaluation capacity — adjacent lever, - different lever. -- `reasoning-moves.md:101-118` — taste is a signal set counted off candidates, exercised by the - **agent** over correctness-equivalent options. Silent on domain taste the operator must supply, - and on whether the evaluator exists at all. - -Ripple: `SKILL.md:58` distills the rule with the same unqualified "show a prototype… where the user -cannot articulate what they want." - -**Candidate remediation — placement matters more than wording.** Owner stays at -`problem-framing.md:66` (the decision is *whether to generate candidates at all*). But that -section's trigger (`:60`) is task-scale and fires once at frame time, before candidates exist — so -an owner-only edit cannot fire at the moment S13 failed. Upgrade the `communication.md:80` side from -a pointer to an actual gate: its trigger ("any time you present two or more options") is naturally -re-entrant and is the real checkpoint. Shape — before presenting options, test that the reader can -evaluate them; when the user has disclosed inexperience in the domain, or cannot say why one -candidate beats another, the candidates are unjudgeable and N of them cost N times one; establish -the domain's evaluation dimensions and what moves them first. Plus a clause on `SKILL.md:58`. This -placement also absorbs F3 without a new recovery signal. - -## F2 — Probe the uncertain capability first — COVERED as doctrine; PARTIAL as routing - -It is **not** distinct from the existing order-by-risk rule. It *is* that rule: - -- `planning.md:35` — "**Plan-shaping unknowns** ('does the dependency support streaming at all?') - change the plan's structure — resolve them before committing to the plan." Verbatim the - feasibility shape. -- `planning.md:41-43` — "the step whose failure would invalidate the most downstream work goes - first… extract its uncertain core into the smallest probe that yields a real answer," with a - pre-committed stop-line at `:49`. - -So feasibility-first ordering needs no home of its own; proposing one would violate meta-rule 2. - -The residual defect is routing, and it survives meta-rule 1 because it is an **active misroute**, -not "I expected this in chapter X and found it in Y": `problem-framing.md:65` sends the -known-unknowns cell to a *named* section ("the ambiguity sort above already handles these"), and -that section (`:43-56`) handles request-*reading* ambiguity only. A can-this-work-at-all unknown -lands in a section that structurally cannot process it, and nothing in `problem-framing.md` cites -`planning.md`'s "Order by risk and information gain." - -Related narrowing: the only prototype the framing chapter names (`:66`) is a **taste-elicitation** -prototype. S13's Remotion prototype is a **feasibility** prototype ("wasn't sure it was possible… -to see if it would work") — different cell, different purpose. The chapter's vocabulary makes -"prototype" read as a taste move only. - -Remediation: one pointer line at `problem-framing.md:65` — unknowns of the can-this-work-at-all -shape route to `planning.md` §"Order by risk and information gain". Pointer-not-copy; no new -doctrine. - -## F3 — No trigger fires on evaluator-side failure — MISSING - -Every stuck-state trigger in `recovery.md` is keyed to a **failed action**: attempt counting fires -"after every failed action" (`:7`); the four signals are same-action-failed-twice, -same-question-re-answered, oscillating edits, fix-chain-longer-than-three (`:11-14`); altitude change -fires on "second failed tactic at the same level" (`:35`); the tool-failure taxonomy (`:50-54`) -classifies tool errors. - -In S13 nothing failed mechanically — the variations were produced successfully — and the attempt -count was one. The failure was on the evaluator's side and no signal detects it. - -Remediation: fold into F1's re-entrant gate rather than adding a fifth loop signal. A reply to an -options message that does not select is the F1 precondition firing late, and the correct move is -identical. A standalone recovery signal would open a second home for one rule. - -## F4 — Ask the agent to explain the underlying mechanism — MISSING (shared doctrine with S11) - -No chapter contains a move that produces an explainer to build the *operator's* understanding. - -Where the auditor looked: full reads of `SKILL.md`, `problem-framing.md`, `planning.md`, -`reasoning-moves.md`, `recovery.md`, and all of `communication.md` (`:1-118`); plus two grep clusters -across every file — `teach|explain(er)|walk me through|domain|expertise|mental model` and -`brief|primer|orient|background|literacy|vocabular|concept|tutorial|onboard|educat|walkthrough| -intuition`. Every hit is agent-internal orientation, never operator-facing: `calibration.md:12`, -`debugging.md:71`, `recovery.md:44`, `context-economy.md:45-52`, `orchestration.md:44`. - -Same doctrine S11 audits. Do **not** open a second home. The disposition should treat S13 as -supplying a *second trigger* for whatever home S11 lands on: the explainer is not only a pre-commit -alignment device, it is the mechanism by which the operator acquires the evaluation criteria F1 -requires. Flagged so the two units are not double-counted. - -## F5 — "Start from what you do know" — PARTIAL, low value, no remediation - -`problem-framing.md:64` names the cell — "**Known knowns** — what the request states. Execute." — -but scopes it to the request's stated content and assigns the action "Execute." In S13 the known -knowns were the *launchpad for probing*, not the thing to execute. The playbook has no notion of -anchoring exploration at the nearest known-working capability and extending outward. - -No remediation: narrative connective tissue in a worked example, not a rule with a trigger and a -failure mode. Recorded as observed-and-declined so the disposition does not re-derive it. - -## Cross-cutting - -Nothing in S13 is inherently model-specific; every remediation is capability-conditioned and names -no model or version. S13's beats read as operator-side actions in the source, but each has a genuine -agent-side counterpart — offer the explainer, test evaluability before generating, probe feasibility -first. No out-of-scope (audience) verdict warranted for this unit. diff --git a/docs/topics/fable-field-guide-audit/findings/S14.md b/docs/topics/fable-field-guide-audit/findings/S14.md deleted file mode 100644 index ffb95ce24..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S14.md +++ /dev/null @@ -1,114 +0,0 @@ -# S14 — closing claims - -All 14 files searched. Lexical families: cheap/expensive/cost/rework/fraction; -ceiling/bottleneck/capability; misframe/replan/surprise/frame; correct/reject/redo/comes-back; -explainer/brainstorm/interview/prototype/exemplar/reference/quiz. - -## C14.1 — "The better models get, the more you can achieve" — PARTIAL + MODEL-COUPLING RISK - -- `problem-framing.md:62` — "the work's quality ceiling is set by the cells nobody clears": approach - quality, not executor capability, sets what is reachable. -- `problem-framing.md:3` — "a wrong frame executed flawlessly costs more than a right frame executed - roughly, because flawless execution is convincing": better execution *amplifies* frame error. -- `SKILL.md:11` — "every line encodes something a strong model does NOT reliably do untold": the - playbook's own premise that capability does not retire the approach. Already capability-conditioned - phrasing — the shape the brief prefers. - -The comparative-across-generations half is inherently model-generation-coupled and addressed to the -human choosing a model. Flagged, **no remediation**. - -**Structural note for synthesis:** C14.1 has no legal home even in principle. Model-behavior claims -are confined to `opus-adaptation.md`, but that chapter is scoped to one model's documented default -deltas with sources (`:3-7`, `:61`) and cannot hold a cross-generation trend claim. Reporting, not -resolving. - -## C14.2 — Long-horizon task came back wrong → suspect unknowns first — PARTIAL - -Every constituent move exists; none is triggered by the S14 condition. All present triggers fire on -a signal the agent observes **mid-flight**: - -- `planning.md:100-106` — surprise classification; `:104` premise-level → "returns to the user and - the framing conversation, not to a plan patch." Trigger: per-step prediction mismatch during - execution. -- `calibration.md:80-89` — four tripwires; `:82` "External feedback (a failed check, a user - correction) is the expensive way to learn you were wrong." Forward-looking: installs tripwires so - the diagnostic is never needed, rather than supplying one. -- `recovery.md:66-73` — "Stuck as information"; `:71` "the wall may be built into the request." - Trigger: persistent stuckness, i.e. *blocked*, not *delivered-and-wrong*. -- `reasoning-moves.md:58-64` — re-derive and diff the formulation, but `:60` triggers *before* the - first expensive step and `:64` caps it at once per task. -- `execution.md:104` — two-patch rule, edit-level. -- `communication.md:96-102` — a user correction generalizes to its class and forces a sweep. This is - the playbook's live response to the S14 condition, and it is execution-level: widen the class, - sweep siblings. Nothing routes attribution to the frame. - -Gap: no rule fires on "a completed long-horizon deliverable was returned as wrong", and -`SKILL.md:126-140` has no routing row for it. `problem-framing.md:5` re-fires on the re-request only -incidentally, with no ordering that examines specification before execution. - -Remediation (capability-neutral): one section in `problem-framing.md` plus a `SKILL.md` routing row. -Trigger — a multi-step or session-spanning deliverable is returned as wrong or not-what-was-meant. -Rule — before re-executing, diff the complaint against the recorded frame and re-run the quadrant -pass; attribute to an uncleared quadrant cell before attributing to execution, because re-executing -against an unchanged frame reproduces the same error at full cost. Placement caveat: `recovery.md` -is the alternative host but its declared scope is self-observed stuck states, not returned -deliverables — confirm the owner against meta-rule 2. - -## C14.3 — The diagnostic points at the MAP, not the model — PARTIAL - -The attribution move exists only in narrower forms: `calibration.md:86` ("your model of the system -is wrong, not that you are unlucky"), `execution.md:104`, `recovery.md:71`. Each attributes to the -agent's model of the *system* or to the request's *premise* under stuckness. No line states the -specification-before-execution ordering. The C14.2 remediation covers this and embeds no model -identity. - -## C14.4 — A plan that lets operator and agent adapt — COVERED, more specified than the source - -`planning.md:33-37` (plan-shaping vs value-filling; value-filling deferred to the step that needs -it); `:41-51` (order by risk and information gain, smallest probe first, `:49` stop-lines with -pre-committed kill criteria); `:29` (every step boundary a safe stopping point); `:98-108` (`:106` -hard replan threshold, `:104` routes premise-level surprises to the user — the operator half of "you -and Claude"). Core doctrine `SKILL.md:64-65`. - -## C14.5a — Cost asymmetry as a GENERAL principle — PARTIAL - -Stated ~12 times as a per-tactic justification clause, never as a named standing principle with one -home: `problem-framing.md:3`, `:30` ("hypotheses are cheap to test now and expensive to test as -shipped code"), `:66` ("a fraction of full-build cost"), `:69` ("a rework cycle that never ships"), -`:82`; `reasoning-moves.md:56`, `:60`, `:79` ("a line instead of a migration"); `planning.md:49`, -`:51`, `:55`; `calibration.md:82`. - -Core doctrine states the behavior without the economics: `SKILL.md:58` says clear the request's -unknowns before building; no core-doctrine line names the asymmetry that makes the rule generalize -to discovery moves the playbook has not enumerated. - -**Live meta-rule 2 tension:** a shared rule re-derived as rationale across four chapters with no -owning section. - -Remediation: name it once in `problem-framing.md` — its opening paragraph (`:3`) already carries the -adjacent frame-cost economics — stating that every discovery move is priced against the rework it -prevents, and that the price rises monotonically with how much has been built on the unknown; the -per-tactic clauses then cite rather than re-derive. Optionally one line under `SKILL.md` "### Framing -— problem-framing". Fully capability-neutral. - -## C14.5b — The closing enumeration — PARTIAL - -Prototype and reference exemplar present and owned (`problem-framing.md:66`; `SKILL.md:58`); -blind-spot pass at `problem-framing.md:67`. **Zero occurrences anywhere in the skill for explainer, -brainstorm, interview, quiz.** Those four are S6/S7/S11/S12's units — the S14-scoped finding is only -that the closing enumeration cannot be marked covered while four of five members have no agent-side -instrument; per-instrument verdicts deferred to avoid double-counting. - -## C14.6 — "start your next project by asking Claude to find your unknowns" — OUT-OF-SCOPE (audience) - -An instruction to the human about how to open a session. Its agent-side inversion (hunt the -request's unknowns unprompted) is already standing doctrine at `problem-framing.md:58-69` and -`SKILL.md:58`, so no agent-side form of the *ask* is meaningful. - -## Net - -Two real gaps, both cross-cutting rather than S14-local: no post-delivery diagnostic ordering -frame-attribution ahead of execution-attribution (C14.2/C14.3), and the cost asymmetry present as -pervasive rationale with no owning section (C14.5a — a meta-rule 2 violation shape). C14.4 is -covered and stronger than the source. C14.1 is a model-coupling risk with no legal home in the -current structure. No contradictions found. diff --git a/docs/topics/fable-field-guide-audit/findings/S2.md b/docs/topics/fable-field-guide-audit/findings/S2.md deleted file mode 100644 index fbb9f212d..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S2.md +++ /dev/null @@ -1,101 +0,0 @@ -# S2 — four unknown quadrants - -Target: `plugins/playbooks/skills/fable-5/context/problem-framing.md` § "Hunt the request's -unknowns, quadrant by quadrant" (lines 58-69). - -**Result: 3 covered, 1 partial.** - -## Audience reframe (not a gap) - -The source frames the quadrants as the operator's self-inventory. The playbook reframes the same -taxonomy agent-side — "The gap between the request and reality sorts into four cells; each cell has -a different clearing move" (`problem-framing.md:62`). Counterparts exist for all four cells, so this -is legitimate audience translation, not `out-of-scope (audience)`. The playbook also adds a trigger -the source has no counterpart for (`problem-framing.md:60`) — additive. - -## Q1 — Known knowns — COVERED - -`problem-framing.md:64` — "**Known knowns** — what the request states. Execute." - -Name exact, definition equivalent under the reframe. The tactic is degenerate, but the source -assigns no clearing move to this cell either. - -## Q2 — Known unknowns — COVERED - -`problem-framing.md:65` — "**Known unknowns** — questions the user knows are open. The ambiguity -sort above already handles these." Cited owner is `problem-framing.md:43-56`; its user-facing exit -is `:52`; the ask-gate governing that exit is `context/communication.md:45-65`, cross-linked at -`problem-framing.md:51`. Citation instead of restatement is `SKILL.md:16` meta-rule 2 — compliant -delegation, not thinning. - -**Routing asymmetry** (named, not an S2 gap): the source's mechanism is operator-side inventory — -the human brings their open questions. The playbook's is agent-side enumeration — the agent -generates readings and surfaces the divergent residue. An operator-held open question the agent's -enumeration never produces has no elicitation path in this section. S2 is a taxonomy and prescribes -no elicitation tactic; the article's elicitation tactic is S7. **Handoff to the S7 unit.** - -## Q3 — Unknown knowns — COVERED (playbook stronger than source) - -`problem-framing.md:66` — "**Unknown knowns** — details the user cannot articulate but will -recognize on sight: taste, workflow fit, the 'not quite what I meant'. Prose questions cannot -extract these — show instead of asking: a sketch, a throwaway prototype, or one fully worked example -surfaces them at a fraction of full-build cost. In the same cell: when the user describes a desired -pattern in prose, hunt a concrete exemplar… a reference carries the dozen decisions their prose -dropped." Distilled at `SKILL.md:58`. - -Two distinct tactics where the source assigns none at S2. **The exemplar move overlaps S8.** - -## Q4 — Unknown unknowns — PARTIAL - -Two facets in the source: (a) what haven't I considered at all, what knowledge am I not aware of; -(b) do I know how good something can be. - -**(a) COVERED** — `problem-framing.md:67`: "**Unknown unknowns** — gaps neither of you has -considered. Run a deliberate blind-spot pass over the request: enumerate what an experienced -practitioner of this domain would ask about that the request never mentions — failure handling, -concurrency, migration of existing data, the operational story, the second consumer. Surface the -result as a short list before locking the frame…" Scaling rule at `:69`, distilled at `SKILL.md:58`. - -**(b) MISSING — the achievable-ceiling facet.** No section instructs establishing the achievable -quality range for the artifact, or treats not-knowing-the-ceiling as a clearable unknown. - -Where the auditor looked: whole skill (`SKILL.md` + all 13 `context/*.md`) grepped -case-insensitively for `ceiling|how good|best possible|state[- ]of[- ]the[- ]art|ambition|quality -bar|raise the bar|what good looks like|exemplar|benchmark|aspir|achievable|good enough|mediocre| -settle for|reference point|comparison class|what excellent|how well|bar for`, and separately -`unknown|quadrant|blind.?spot|taste`. Read in full: `context/calibration.md` (governs effort and -deliberation budget by reversibility tier at `:51-56` — how much to spend, never how good the result -can be), `context/reasoning-moves.md:88-133` (steelman is about rejected options `:92`; taste is -tie-breaking among already-correct candidates `:101-118`; the critics pass is artifact-vs-audience -`:120-128`), `context/communication.md:1-74`, `SKILL.md`. The other `ceiling` hits are unrelated: -`context/orchestration.md:43` (worker output length cap), `context/reasoning-moves.md:74` (premortem -prose). - -**Near-miss, flagged so synthesis does not mismerge it:** `problem-framing.md:62` contains the -literal words "quality ceiling" — "the work's quality ceiling is set by the cells nobody clears". -That is a motivation clause for the section, NOT the source's claim (the operator does not know the -achievable range for this class of artifact). A `ceiling` grep during task #16 lands there; it is -not the same claim. - -### Candidate remediation — two sites, both required - -1. `problem-framing.md:67`, appended to the unknown-unknowns cell: a second axis on the same pass, - aimed at the request's implied quality target. Shape — when you cannot name a reference point for - how good this class of artifact gets (a comparable in their codebase, a widely-used - implementation, a published standard), you cannot distinguish an adequate result from a - ceiling-limited one, and neither can a user who has never seen the better version; name what the - strong version looks like and what separates it from the obvious one, and put that in the frame. -2. `SKILL.md:58`, a matching clause on the existing core-doctrine line, which currently distills - only the prototype/exemplar move and the blind-spot pass. - -**Trigger must be frame-time**, before the approach is chosen — stated explicitly in the -remediation text, because a ceiling-establishing move that could fire later collides with -`context/reasoning-moves.md:118` ("taste selects among correct candidates *while the choice is -open*… Once a solution is working and verified, elegance alone reopens nothing"). Naming the trigger -is what keeps the two compatible. - -Constraint compliance checked: governs how the frame is built, not what the work is (`SKILL.md:15` -meta-rule 1); no model name, version, org, repo, or path; no baked-in convention a consumer could -reasonably do differently — the reference point is discovered per task, not shipped as a default -(PLUGIN-PHILOSOPHY two-lane posture). Owning home is the unknown-unknowns cell, so meta-rule 2 is -satisfied by adding it there and citing from `SKILL.md`. diff --git a/docs/topics/fable-field-guide-audit/findings/S3.md b/docs/topics/fable-field-guide-audit/findings/S3.md deleted file mode 100644 index 2617df5b3..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S3.md +++ /dev/null @@ -1,103 +0,0 @@ -# S3 — "reducing unknowns is the skill" - -**Central question, answered first:** the playbook encodes unknown-*hunting* as trigger-gated -tactics, never as a standing prior that unknowns exist. **Partial.** - -Discriminator: every arm of the unknown-hunting doctrine that is not size-gated fires on -**self-detection** — `problem-framing.md:60` third arm ("the request is confident in its center and -silent at its edges") and `problem-framing.md:45` second arm ("any moment you catch yourself -choosing between readings mid-work"). Both presuppose the agent has *already noticed* the gap. An -assume-unknowns-exist prior is precisely what supplies that noticing, and no line installs it. - -Qualifier lowering remediation urgency without changing the verdict: the chapter gate at -`problem-framing.md:5` is broad enough that most substantive requests reach the chapter. The real -narrowing is the inner trigger at `:60`. - -Seven rows — collapsing S3 loses real coverage. - -## Row 1 — best agentic operators carry few unknowns — OUT-OF-SCOPE (audience) - -Describes the human's own epistemic state. Agent-side counterpart exists and is covered: -`problem-framing.md:69` — "Scale the pass to the user's disclosed starting point: 'I know this -domain' narrows it to the request's silent edges; 'I've never done this' widens it to the domain's -whole checklist." - -## Row 2 — in sync with the codebase — COVERED - -`execution.md:15-26` (trigger: about to modify a file not fully read this session; reading scaled to -blast radius; `:24` mandates extracting local conventions, invariants, hidden couplings). -`execution.md:21` — new files mirror two siblings: "The siblings are the spec; your defaults are -not." `reasoning-moves.md:180` — "you have finished the single most relevant file and feel -oriented — that feeling is the cue, not the finish line," with the bar "no conclusion about a -surface from exactly one file while it has an unread sibling, caller, or test." - -Not identity-coupled — do not sweep into the model-coupling flag. - -## Row 3 — in sync with model behaviors — OUT-OF-SCOPE structurally + MODEL-COUPLING RISK - -Quarantined by design: `SKILL.md:146` ("behavioral claims about specific models live only in -`context/opus-adaptation.md`, with sources"), `SKILL.md:17` (meta-rule 3). The chapter does exactly -this — `opus-adaptation.md:7`, sources at `:63-68`. - -The claim is *inherently* identity-conditioned; "in sync with model behaviors" is meaningless -without a named model. The playbook already carries that coupling (`SKILL.md:17` names two models; -`opus-adaptation.md:1` is version-titled). Reported, not resolved. - -No remediation possible — any satisfying text would have to name a model. - -## Row 4 — "but they also assume unknowns" (the posture claim) — PARTIAL - -Present but gated or self-detection-dependent: `problem-framing.md:5` (chapter trigger); `:60` (the -quadrant hunt); `SKILL.md:58` — the always-active core-doctrine line carries the gate verbatim: -"**For session-scale work**, clear the request's unknowns before building"; `problem-framing.md:73` -(falsification pass, gated, with an explicit SKIP). - -Nearest ungated neighbors — partial-supporting, not covering; all self-directed (object = the -agent's own plan or theory, not the request's completeness): `calibration.md:85` convenience -tripwire, `:87` smoothness tripwire, `:74` ("The *more* familiar the pattern, the more this trigger -applies — not less"); `reasoning-moves.md:156-158` "Hold exactly one named biggest risk" (genuinely -ungated, restated always-on at `SKILL.md:49`, but its object is execution risk); `:166` ("Absence -never announces itself", scoped to reading passes); `:48`. - -### Candidate remediation — two homes evaluated - -- **Rejected — a fifth tripwire in `calibration.md:80-89`.** All four existing tripwires take the - agent's own plan or theory as object (`:84` your prediction, `:85` your plan, `:86` your model of - the system, `:87` your theory). A tripwire about the *request* breaks that section's - object-consistency. -- **Recommended — `problem-framing.md` preamble at line 3** (above the chapter trigger at line 5), - paired with a bullet in the always-active `SKILL.md` framing block (`:52-58`). Only the `SKILL.md` - bullet is truly ungated, since the chapter itself loads on trigger (`SKILL.md:128`) — so the - posture must land in both to be standing. Shape: a prior, not a procedure — every request arrives - with unknowns attached; a request that reads complete is evidence about how it was written, not - about what it covers; no trigger firing is not evidence the request has none. - -## Row 5 — reducing unknowns is the skill — PARTIAL - -Same gating. The reduction *moves* are strong — `problem-framing.md:66` and `:67` — but reachable -only through `:60`. Subsumed by Row 4's remediation. - -## Row 6 — planning for unknowns is the skill — COVERED - -Materially different from Row 5: weak on *assuming* unknowns, strong on *handling* the ones it has. - -`planning.md:33-37` ("Any unknown resolvable with under a minute of tool use… gets resolved during -planning instead of recorded as a risk. A risk list full of one-minute lookups is deferred -laziness"). `reasoning-moves.md:56` (promotion to load-bearing is a countable moment at the second -dependent step). `reasoning-moves.md:80` gate 3 ("A condition you cannot check cheaply is carried as -a named assumption at recall grade"). `planning.md:49` (stop-lines pre-commit each risky step's kill -criterion). - -## Row 7 — the skill is learnable by working with the agent — OUT-OF-SCOPE (audience) - -About the human's skill acquisition over time; the agent has no cross-session lever, and encoding -one would be user-preference content that meta-rule 1 places outside this skill. - -## Where the auditor looked - -Read in full: `SKILL.md`, `problem-framing.md`, `reasoning-moves.md`, `opus-adaptation.md`. Read in -part: `calibration.md:62-89`, `planning.md:1-50`, `execution.md:14-33`. Greps across all 14 files: -`unknown|assume|assumption`, and `looks complete|seems complete|appears complete|no gaps|nothing -missing|feels (done|complete|oriented|confident)|absence of|silent at|by default assume|default -(prior|posture)`. Second grep returned four hits total, all cited — no line anywhere asserts a -default prior about unknowns. diff --git a/docs/topics/fable-field-guide-audit/findings/S4.md b/docs/topics/fable-field-guide-audit/findings/S4.md deleted file mode 100644 index aabcad3f3..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S4.md +++ /dev/null @@ -1,116 +0,0 @@ -# S4 — specificity balance, discovery accelerator, starting point - -## (a) Specificity balance — COVERED (both branches) - -Present as agent-side counterparts rather than prompt-writing advice. - -Too-specific branch — three independent pivot licenses: - -- `problem-framing.md:22-41` "Detect the pre-chosen solution" — an over-specified request naming a - mechanism with no symptom gets 1-3 tool calls linking mechanism to symptom before implementation, - then a four-arm branch (fits / inconclusive / contradicts-and-reversible / - contradicts-and-expensive → stop and present). -- `problem-framing.md:111-122` "Challenge the task when challenging is cheaper than executing it" — - four evidence-gated triggers, plus the execute-faithfully-on-reaffirmation clause. -- `planning.md:98-108` — surprise classified local / structural / premise-level; premise-level - "returns to the user and the framing conversation" (`:104`). `:106` is near-verbatim: the tell is - "writing an adapter or workaround whose only purpose is preserving the plan's original shape… the - moment you are bending code to protect the plan, invert the relationship." -- Reinforced by `reasoning-moves.md:134`, `SKILL.md:65`. - -Too-vague branch: `calibration.md:70-78` "Underthinking: familiar shape is not actual fit" — -sharpest match; the trigger fires *harder* the more familiar the pattern. Plus -`execution.md:36-42`, `execution.md:55-60`, `SKILL.md:78`, `communication.md:91` (precedence ladder -ends "project convention files > your defaults"), `problem-framing.md:43-56` + -`communication.md:45-65`. - -`opus-adaptation.md:11,18-19` also carries a literalism correction, but it is model-specific and -lives there by design — deliberately excluded from the verdict rather than leaned on. - -## (b) Fails BOTH ways — split verdict - -- **Remedy — COVERED.** `problem-framing.md:58-69` (quadrant hunt; the agent runs the clearing - passes itself rather than depending on the operator having run them) and `:71-82` (falsification - pass — "your frame is assembled from what you happened to notice; the constraint that kills it - lives in what you did not", `:75`; budgeted by reversibility tier at `:82`). `:43-56` handles the - known-unknown cell. -- **Both-ways diagnosis — OUT-OF-SCOPE (audience).** The causal claim that un-enumerated unknowns - simultaneously produce over- and under-specification is absent. It is rationale addressed to the - human writing the prompt; it changes no agent action beyond what `:58-82` already mandates. - Adding it would be explanatory prose with no trigger, against meta-rule 4. - -## (c) Faster discovery engine — COVERED (3 of 4), PARTIAL (external research) - -Covered: codebase search — `problem-framing.md:77`, `debugging.md:27` (literal error-string search -before theorizing), `execution.md:41`, `calibration.md:25`. Broader topic knowledge — -`problem-framing.md:67` states the asymmetry outright. Faster iteration from failure — -`debugging.md:10`: drive iteration time under ~30s per run; "loop time is the hard cap on how many -experiments the session can afford." - -**Partial — external research: machinery present, trigger absent.** - -- Present: `orchestration.md:10` names "long external documents" as a context-flooding delegation - shape; `:44` requires a worker spec to state "what counts as authoritative"; `calibration.md:16` - lists "doc fetch" among identifier-lookup options; `communication.md:52` counts "a doc you - fetched" as session evidence. -- Absent: nothing routes an unknown *to* an external source. `calibration.md:12` sets the need — - recall reliability tracks invariance, "anything version-shaped does not [age well]" — but the only - licensed remedy is the `:16` trigger, scoped to typing an exact identifier. The check/skip matrix - (`calibration.md:32-38`) has no branch for "the local environment does not contain the answer." - Both `orchestration.md` hits presuppose research already decided upon. - -Remediation (optional, low priority): a branch in `calibration.md` (owning chapter for check/skip -and recall grading) for a version- or ecosystem-shaped claim no local artifact can settle. Two -binding constraints: PLUGIN-PHILOSOPHY's design boundary forbids naming a tool or assuming network -access — phrase as "an authoritative external source, when the session has one," with explicit -fall-through to the downgrade-to-unverified move at `calibration.md:35` when it does not. -**Counter-argument for disposition:** `:35` arguably already covers this tool-agnostically, making -the gap stylistic rather than behavioral. - -## (d) Operator's starting point — PARTIAL, and the residue is a genuine agent-actionable gap - -Where it exists — complete set, confirmed by keyword sweep across all 14 files (`starting point`, -`experience`, `inexperien`, `expertise`, `thought partner`, `familiar with`, `disclos`, `novice`): - -- `problem-framing.md:60` — the section trigger fires when "the user has disclosed inexperience with - the domain." -- `problem-framing.md:69` — "Scale the pass to the user's disclosed starting point…" -- Thought-partner half, partial: `problem-framing.md:66` gives the collaborative moves but not the - stance. - -**The gap: both hooks are gated on the word *disclosed*.** If the operator volunteers nothing, -`:69`'s scaling instruction has no input and the `:60` trigger never fires on that clause. Nothing -anywhere licenses asking. The four ask-categories at `communication.md:56-61` are values, cost, -irreversibility, scope — operator experience is none of them; `problem-framing.md:43-56` sorts -*request-reading* ambiguities, not operator-state unknowns. - -Audience split: only the article's imperative *to the human* ("disclose your experience") is -out-of-scope. The elicit-and-calibrate counterpart is squarely agent-actionable and is the real gap. - -Remediation: one sentence in `problem-framing.md` adjacent to `:69`, which already owns the -scaling — when the starting point is undisclosed *and* the two poles would produce materially -different pass widths, ask for it in one line before running the pass. **The gate is load-bearing, -not decoration:** ungated, the addition collides with `problem-framing.md:51` ("a session that asks -about everything trains the user to stop reading its questions") and with the decide-or-ask ordering -at `communication.md:49-54`. Keep the home in `problem-framing.md` and cite from `communication.md` -rather than adding a fifth ask-category. - -## Adjacent finding — auditor-originated, routes to S11 - -The playbook has no reader-expertise axis for calibrating *explanation depth or vocabulary*: -`communication.md:16-23` calibrates only to decision load (`:21` "Scale length to the reader's -decision load, not to your effort"), and `:112-118` only to transcript-independence. Confirmed -absent by a second sweep (`reader`, `audience`, `explain`, `teach`, `vocabulary`, `jargon`) across -all 14 files. - -**Not an S4 claim** — `source-article.md` S4 says nothing about explanation depth. Do not bank it as -S4-derived; it belongs with S11 if it survives there. - -## Coverage limits on the absence claims - -Read in full: `SKILL.md`, `communication.md`, `problem-framing.md`, `calibration.md`, -`orchestration.md:1-40`. Targeted reads of `planning.md`, `execution.md`, `reasoning-moves.md`. -`verification.md`, `debugging.md`, `recovery.md`, `context-economy.md`, `trust-and-authority.md` are -covered by keyword sweep plus full heading listing, not full reads — the (b), (c) and (d) absence -claims rest on four independent keyword sets across all 14 files rather than exhaustive reading of -those five. diff --git a/docs/topics/fable-field-guide-audit/findings/S5.md b/docs/topics/fable-field-guide-audit/findings/S5.md deleted file mode 100644 index 72895e3a5..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S5.md +++ /dev/null @@ -1,120 +0,0 @@ -# S5 — blind spot pass - -Searched the whole skill for `blind.?spot`, `unknown unknown`, `practitioner`, `teach`, `prompt -better`, `inexperien`, `unfamiliar`, `non-code` before any absence verdict. - -## C1 — Trigger: new part of the codebase — PARTIAL - -`problem-framing.md:60` has three arms: session-scale task, OR user-disclosed domain inexperience, -OR request confident at its center and silent at its edges. "New codebase area" is none of them; it -reaches the pass only if the operator happens to disclose inexperience. - -Nearest unfamiliar-territory trigger is `problem-framing.md:73` ("in territory you have not touched -this session"), but that gates the *falsification* pass, which `:69` scopes as "aimed at the code -instead of the request" — the opposite direction from S5. - -Remediation: fourth trigger arm at `:60` — the work sits in a region of the codebase or domain -neither you nor the user has worked in. - -## C2 — Trigger: unfamiliar non-code work — PARTIAL - -The section's wording is domain-agnostic — "an experienced practitioner of this domain" (`:67`), -"the user's disclosed starting point" (`:69`) — but every enumerated probe is software-systems -shaped: "failure handling, concurrency, migration of existing data, the operational story, the -second consumer" (`:67`). - -Gating problem: chapter entry is `problem-framing.md:5` — "names a mechanism, changes behavior, -touches 2+ files, or whose because-clause you cannot fill from the request alone." A color-grading -request matches only the because-clause catch-all. `SKILL.md:128` routes on the same code-shaped -conditions; `SKILL.md:11` frames the whole playbook as "an engineering session." - -Remediation: at `:67`, mark the enumerated list as the software instance of a general move and name -one non-code exemplar axis, so the checklist reads as domain-parameterized rather than exhaustive. -Do NOT widen `:5` — blast radius across all eight sections; belongs in the final disposition. - -## C3 — Symptom: not knowing what questions to ask — COVERED - -`problem-framing.md:67` — "enumerate what an experienced practitioner of this domain would ask about -that the request never mentions"; `SKILL.md:58` carries it in core doctrine. - -## C4 — Symptom: not knowing what good looks like — PARTIAL - -`problem-framing.md:66` and `:94-109` both have the agent establishing a bar for *itself*. Neither -addresses the operator having no quality bar because the domain is new to them — and `:66`'s -exemplar move asks the user for a reference, which presumes they know a good one exists. - -Fold into C8; the quality bar is one item of what gets explained back. (Overlaps the S2 Q4(b) -achievable-ceiling gap — dedupe at synthesis.) - -## C5 — Symptom: not knowing what historical work exists — COVERED (different home), with caveat - -`problem-framing.md:77` (prior-art search: "its scars tell you what already failed") and `:78` -(version-control history: "an absence you are about to fill may be deliberate"). Per meta-rule 2, -another section is still covered. - -Caveat for disposition: scoped to the falsification pass, whose output constrains the agent's frame -with no requirement to relay history to the operator. Discovered, not transferred. - -## C6 — Symptom: not knowing what potholes to avoid — PARTIAL - -`problem-framing.md:80`; `reasoning-moves.md:70-82` (premortem asserted as fact, three narratives, -three disposal gates). Both are agent-internal design adversaries. The premortem disposes findings -into blocked / fix-now / accept (`reasoning-moves.md:77-79`) — none of which is "tell the operator -this is known domain lore." S5's potholes are lore the operator lacks, not failure modes of the -chosen design. - -## C7 — Tactic: find the operator's unknown unknowns — COVERED - -`problem-framing.md:67` names the move literally — "Run a deliberate blind-spot pass over the -request" — echoed at `SKILL.md:58`. Incidental win: because the playbook uses the literal phrase -"blind-spot pass" and the cell label "unknown unknowns," the operator's deliberate literal -invocation from S5 lands on named doctrine. - -## C8 — Tactic: EXPLAIN them back so the operator can prompt better — PARTIAL (the real gap) - -Correction to the brief's hypothesis: the pass is **not** agent-internal. `problem-framing.md:67` -already mandates operator-facing output — "Surface the result as a short list before locking the -frame." - -The actual delta is two-fold, both halves absent: - -1. **Depth.** "Surface as a short list" is disclosure of open questions. S5 asks for explanation — - teach enough of the domain that the operator recognizes the questions themselves. A bare list - handed to a novice is a different artifact. -2. **Purpose.** `:67`'s terminus is "before locking the frame" — the output serves *this* task. - S5's terminus is "so that I can prompt better" — capability that outlives the task. Nothing - states a capability-transfer purpose. `communication.md:20` ("include exactly what changes what - the reader does next") and `:112-119` both optimize for the reader's next action, which arguably - argues *against* teaching content that does not change it. - -Meta-rule 4 does not block this — it forbids narrating playbook compliance, not sharing findings, -and `:67` already mandates a user-visible surface. - -Remediation at `problem-framing.md:67`, replacing the surface clause: where the user has disclosed -unfamiliarity, the surfaced list must carry enough explanation for them to evaluate each item — what -the question is, why it bites in this domain, what a good answer looks like. - -**Placement caution:** tension with `communication.md:20`. If this lands, one of the two needs an -explicit carve-out under meta-rule 2. Flagged, not resolved. - -## C9 — Operator context shapes the pass — COVERED - -`problem-framing.md:69` — "Scale the pass to the user's disclosed starting point…" Also supplies the -trigger arm at `:60`. The operator-side instruction (disclose who you are) is theirs; the agent-side -counterpart (act on the disclosure) is present. - -## Direct answers - -- **(i) First-class with its own trigger? PARTIAL.** Named ("a deliberate blind-spot pass", `:67`) - and elevated to core doctrine (`SKILL.md:58`), so not buried — but structurally the fourth bullet - of a four-cell list, inheriting `:60`'s trigger rather than owning one. Concrete consequence, not - cosmetic: that trigger omits S5's headline case (C1) and sits behind code-shaped chapter entry - (C2). -- **(ii) Teaching outcome captured? PARTIAL** — surfacing required, explanation and prompt-better - purpose absent (C8). -- **(iii) Non-code domain in scope? PARTIAL** — the pass's language is domain-agnostic, its examples - and chapter gate are not (C2). - -## Model-coupling check - -No S5 claim is model-specific; no candidate remediation names a model or version. diff --git a/docs/topics/fable-field-guide-audit/findings/S6.md b/docs/topics/fable-field-guide-audit/findings/S6.md deleted file mode 100644 index 886bb691a..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S6.md +++ /dev/null @@ -1,159 +0,0 @@ -# S6 — brainstorms and prototypes - - - -Searched all 14 files (`SKILL.md` + 13 chapters, 1509 lines) for: prototype, brainstorm, sketch, -mock, throwaway, exemplar, on-sight, visual, design approach, parallel, explor*, scope, alternativ*, -candidate, options, revert. - - -**`brainstorm` appears zero times in the skill.** The prototype half is doctrine; the brainstorm -half (C4-C7) holds the gaps. - -> Caveat from the auditor: its independent-reviewer pass was rate-limited, so this ledger has had -> no second-opinion check. - -## C1 — Trigger: area dense in unknown knowns — COVERED (doctrine) / PARTIAL (trigger scope) - -`problem-framing.md:66` — "**Unknown knowns** — details the user cannot articulate but will -recognize on sight… show instead of asking: a sketch, a throwaway prototype, or one fully worked -example surfaces them at a fraction of full-build cost." Distilled at `SKILL.md:58`. - -The partial: the article's trigger is *density of unknown knowns*, independent of task size. The -playbook gates the whole quadrant pass at `problem-framing.md:60` — session-scale work OR disclosed -inexperience OR confident-center/silent-edges. The button-in-a-frame case fires none of those, so -the owning cell is never entered. - -Remediation: fourth disjunct on the `:60` trigger, keyed to criterion shape — the acceptance -criterion is one the user can only judge on sight. - -## C2 — Cost asymmetry — PARTIAL - -General argument covered: `problem-framing.md:66` ("at a fraction of full-build cost"), `:69` ("Each -cell cleared before building is a rework cycle that never ships"), `:3`, `:82`. - -- Mechanism (a) **small spec changes imply drastically different implementations — MISSING.** No - statement of non-linear spec-to-code sensitivity anywhere. Closest is `planning.md:104` - (premise-level surprise returns to the user) — handles the consequence, never names the cause. -- Mechanism (b) **agents revert prior changes poorly** — the fact IS attested at - `execution.md:106` ("never hand-reverse from memory — hand-reversal is how orphaned fragments and - half-undone lines survive into the final diff"), and `execution.md:103` routes around it via - mechanical VCS revert. Not a contradiction — an *unused premise*. The playbook knows the fact but - never spends it as a reason to prototype first. - -Remediation: one clause in the unknown-knowns cell — a criterion learned after building is an -implementation change, not an edit. Pointer to `execution.md:106`, not a restatement. - -## C3 — Throwaway prototype skips real wiring — PARTIAL, with a latent contradiction - -"throwaway prototype" is named at `problem-framing.md:66`, but its defining property is absent: the -value comes from what it OMITS, and the omission is correct rather than incomplete. - -Three standing rules read a deliberately-unwired artifact as a defect, with no carve-out: - -- `reasoning-moves.md:166` what-should-exist pass — "a write path predicts a failure branch… a - subscribe predicts an unsubscribe". Every omission in a mock toolbar scores as a finding. -- `problem-framing.md:98-107` completion criteria plus mandatory negative criterion, written "before - the first mutating action" — a prototype has no survivable behavior to name. -- `execution.md:133` — "Scratch files, experiment outputs, and generated artifacts that landed - inside the project tree". A single-file HTML mock is exactly scratch-file-shaped and gets swept at - `execution.md:124-133`. - -Remediation: declare the elicitation artifact a distinct artifact kind — its completeness bar is -"does it surface the criterion", not "does it work"; the what-should-exist pass and the debris sweep -apply to the real change; the prototype is retired by explicit decision, not by sweep. One-line -pointers at `execution.md:124` and `reasoning-moves.md:166` per meta-rule 2. - -## C4 — Several parallel design approaches — MISSING + CONTRADICTED (strongest S6 finding) - -The playbook prescribes the singular: `problem-framing.md:66` — "a sketch, a throwaway prototype, or -ONE fully worked example." Generating N deliberately-divergent directions as the extraction -instrument appears nowhere. - -Everything adjacent governs choosing among candidates already on the table, not manufacturing a -spread: `reasoning-moves.md:103` (taste trigger is "two or more candidate solutions are on the -table"), `:90`, `:108`; `communication.md:80-85`. Nearest structural analogues — -`planning.md:60` ("Enumerate 2-3 alternatives") and `reasoning-moves.md:74` ("Produce three -narratives") — are both about the AGENT's own decision, never an artifact set built for operator -reaction. - -- **Contradiction 1** — `calibration.md:61`: "SURVEY DEPTH = PURSUIT DEPTH: enumerate options only - as deep as you would actually pursue them… a comparison you will not act on is decoration." A - 4-direction spread is 3 directions you will not pursue; the rule reads as a stop signal exactly - when the tactic is correct. -- **Contradiction 2** — `communication.md:82`: "Mark exactly one option as recommended, list it - first", hardened by `:83` ("'either works' is abdication"). When the spread exists to elicit an - aesthetic judgment only the operator holds, leading with the agent's pick pre-empts the judgment - being elicited. - -Also missing: visual/UI design as the canonical instance — `:66` names "taste, workflow fit" only. - -**Vocabulary hazard:** the playbook's "taste" (`reasoning-moves.md:101-118`) means the AGENT's -code-quality signal; the article's means the OPERATOR's aesthetic. Same word, two referents, one -chapter apart. - -Remediation (owning home = the unknown-knowns cell): license the divergent spread — when the -criterion is on-sight-only, several deliberately different directions beat one refined candidate, -and the divergence must run along the dimension the operator cannot articulate, not N variations of -one idea. Then a one-line `except` at `calibration.md:61` (the survey-depth cap governs options the -agent will act on; an elicitation spread is a deliverable, not a comparison) and at -`communication.md:82` (recommendation is owed on decisions the agent is making; naming a favorite in -a taste-elicitation spread front-loads the judgment being asked for). - -## C5 — Almost every session opens with brainstorming — OUT-OF-SCOPE (audience) + MISSING + TENSION - -The habit is the operator's own workflow; the agent cannot open a session it does not open. -Audience-legitimate. - -Agent-side counterpart — lead with a scope-setting pass rather than the first edit when extent is -unset — has no home. `reasoning-moves.md:7` fires "at task start" but only CLASSIFIES work into four -kinds; Exploration is one label among four, and its only default is the escape hatch at `:14`, not -an opener. - -**Tension:** `planning.md:7` ("Two yeses → act directly; a plan here is transcription") and `:11` -("Planning here is procrastination wearing rigor's clothes") encode a deliberate act-directly bias -that an "almost every session explores first" rule would erode. - -Remediation: do NOT port the frequency claim. Narrow trigger form only — when the request's scope -boundary is not derivable from the request itself, the first move is a scope-setting pass, not the -first edit. Flag as a judgment call between two defensible postures. - -## C6 — Agent finds missed approaches; sometimes misses the forest — COVERED, consequence MISSING - -Asymmetry in the agent's favor: `problem-framing.md:67` ("you often know the domain's standard -questions better than the user does, and this pass is where that asymmetry pays"); `:118`. - -Forest-for-the-trees: `reasoning-moves.md:134-142`, `:144-152`, `:58-68`, `:11` ("Failure: -converging on the first coherent story"). - -Missing is the operational consequence the article draws — because the agent's convergence is -unreliable, brainstorm output belongs to the operator to react to, not to the agent to resolve. -Same gap as C4; fixing C4 covers it. - -## C7 — Guards against BOTH too-narrow and too-wide scope — PARTIAL (effectively one-directional) - -Too-wide heavily armed: `problem-framing.md:84-92`, `execution.md:108-122` ("scope creep dressed as -diligence"), `communication.md:61`. - -Too-narrow: thin and indirect. `problem-framing.md:67` is the only general-audience instrument, and -it targets the request's silences, not the scope's lower bound. The one place under-scoping is named -outright is `opus-adaptation.md:17` — which is model-specific by design and cannot serve as the -general home, leaving the general case genuinely uncovered. - -Nothing frames a pre-work pass as the instrument that sets the bound in EITHER direction. - -Remediation: at `problem-framing.md:84-92`, make the bound bidirectional by pointer, not new -doctrine — the exclusion list has an upper bound (`:88`) and a lower one (the blind-spot pass at -`:67`); a scope stated without testing both is one bound short. - -## Model-coupling risk - -None of the S6 claims is inherently model-specific. C2(b) is the only one phrased about agent -capability; its playbook-safe form already exists behavior-conditioned at `execution.md:106`. - -## Cross-unit overlap for synthesis - -C1 and C7 land in the same `problem-framing` quadrant material S2 audits. C5's tension is with -`planning.md:7-11`. diff --git a/docs/topics/fable-field-guide-audit/findings/S8.md b/docs/topics/fable-field-guide-audit/findings/S8.md deleted file mode 100644 index 6693a313f..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S8.md +++ /dev/null @@ -1,117 +0,0 @@ -# S8 — references - -Searched all 14 files. Term families swept: reference/exemplar/prior-art; -screenshot/picture/image/visual/photo/video/mock/sketch/diagram; documentation/docs/spec/RFC; -cross-language/different-language/translate/port/reimplement/polyglot; -vendor/third-party/upstream/external/library/crate/package/framework/stack/folder; -fidelity/richer/concrete; template/sample/snippet/blueprint/canonical/worked-example. - -## C1 — Trigger: lacking the vocabulary — COVERED - -`problem-framing.md:66` — "when the user describes a desired pattern in prose, hunt a concrete -exemplar (in their codebase, or ask them for a reference)". Promoted to core doctrine at -`SKILL.md:58` — "hunt a reference exemplar where the user cannot articulate what they want". - -## C2 — Trigger's second half: describing costs more than it is worth — PARTIAL - -`problem-framing.md:66` conditions on *inability* to articulate, never on the *cost* of -articulating. The owning section's trigger at `:60` gates the whole quadrant pass on session-scale -work OR disclosed inexperience OR confident-center-silent-edges — so a user who could describe it -but only expensively never trips the trigger, and neither does a sub-session-scale task. - -Remediation: widen the `:66` condition to cover the economics — "cannot articulate, or could only at -a cost exceeding pointing at one". Caveat: `:60`'s session-scale gate still governs; if the cheaper -trigger should fire on smaller tasks the clause needs its own trigger line rather than inheriting -`:60`'s. - -## C3 — The fix is a reference — COVERED - -`problem-framing.md:66`, rationale stated — "a reference carries the dozen decisions their prose -dropped". `SKILL.md:58`. In-project variants: `problem-framing.md:77` (prior art in the codebase); -`execution.md:21` ("read two sibling files of the same kind and mirror their structure… The siblings -are the spec; your defaults are not"). - -## C4 — Reference media are RANKED — MISSING - -No ranking, and no enumeration of admissible reference media, anywhere in the skill. `:66` says -"exemplar"/"reference" without typing them. Zero hits for screenshot, picture, image, diagram, mock, -video, template, sample, snippet, blueprint across all 14 files. The only `sketch`/`prototype`/ -`worked example` mentions (`problem-framing.md:48-49`, `:66`) are artifacts the agent *produces for -the user* — opposite direction from a reference it *consumes*. `orchestration.md:58` "sample the -rest" is statistical sampling, unrelated. - -Remediation: state the selection *principle*, not a fixed list — take the highest-fidelity form -available: the form that carries naming, structure and edge-case handling rather than implying them. -A hardcoded five-tier ordinal (implementation > schema > prose docs > diagram > image) is exactly -the shape PLUGIN-PHILOSOPHY's two-lane clause targets — a design-led consumer could reasonably rank -a component spec above a tangentially-relevant implementation, so the enumerated list is a baked-in -default in a skill declared agnostic. - -## C5 — Source conveys richer detail than a screenshot — MISSING - -`:66`'s "a reference carries the dozen decisions their prose dropped" is on a *different axis* — it -contrasts the user's prose against a concrete artifact. S8's claim contrasts artifact types *among -themselves*. Axis test: a rule comparing description-to-artifact does not state a rule comparing -artifact-to-artifact, so `:66` is not a weaker version of C5, it is a different claim. - -Remediation: subsumed by C4's fidelity principle. No separate text. - -## C6 — Cross-language references — MISSING (highest-value S8 remediation) - -Zero hits for cross-language, different language, translate, port, reimplement, polyglot across all -14 files. `:66`'s parenthetical is source-*unbounded* — the playbook is silent on -out-of-stack/out-of-language sources, not restrictive. But it never says what survives the crossing -(semantics/structure) versus what does not (syntax/idiom), which is the load-bearing half of the -claim. - -Remediation: extend `:66` — a reference in a different language, framework or stack still qualifies; -what ports is the semantics and structure, never the syntax; the form the port takes is governed by -the execution chapter's "Write in the codebase's dialect, not yours". Fills the gap AND closes the -seam below; cites rather than restates. - -## C7 — Ask-the-user is agent-initiated? — COVERED, explicitly - -`problem-framing.md:66` — "(in their codebase, **or ask them for a reference**)" is an instruction to -the agent; `SKILL.md:58` promotes it to core doctrine. - -Caveat (no verdict change): it is a mid-bullet parenthetical with no trigger of its own, no ordering -of ask-the-user against search-the-codebase, and no guidance on what to ask *for* — the article's -"tell it what to look for", i.e. the reference plus the aspect to extract. - -Optional remediation: order and specify the ask — search the codebase first; if nothing matches, ask -the user for one, naming the aspect you need from it (behavior, structure, or interface) rather than -accepting the pointer alone. - -## Dialect-matching vs external-exemplar — distinct moves - -Every dialect rule in the playbook is INWARD (imitate code you are already inside): -`execution.md:55-60` (trigger is "matching the surrounding style"; both hard cases concern styles -coexisting *at the insertion point*), `execution.md:36-42` (explicitly about not reaching outside), -`execution.md:21`, `problem-framing.md:77`. - -S8's move is OUTWARD: go to an artifact outside the target, possibly outside the language, read it, -reimplement its semantics inside. None of those four authorizes or describes that. The only text -that does is `:66`'s twelve words, which stop at *obtaining* the reference. - -Consequences: - -- **No execution-side home for consuming a reference.** `execution.md:15`'s read-radius rule - triggers on "a file you are about to modify". A reference tree is read, never modified — so no - rule scales reading of it, marks it read-only, or prevents editing it by reflex. -- **No reconciliation rule.** When an external exemplar's shape conflicts with the local dialect, - nothing says which wins. C6's remediation resolves this by construction (dialect governs form, - reference governs semantics); without it, an agent following `:66` and an agent following - `execution.md:55` produce different diffs from the same reference. -- **Adjacent, not contradictory:** `SKILL.md:117` / `trust-and-authority.md` — imperatives inside - read content carry no authority, so an external crate's comments and TODOs are facts about that - artifact, not instructions. Already correct; flagged only because a reference-reading rule is - exactly where an agent meets that surface. - -## Disposition notes - -No S8 claim is contradicted. None is out-of-scope (audience) — every S8 claim has a real agent-side -form, since the agent is the party that hunts, requests, reads and ports the reference. - -Model-name coupling: nothing in S8 is model-specific. The article's "point Fable at the folder" is a -naming artifact of its framing, not a model-behavior claim. All remediations land in one home, -`problem-framing.md:66`, extending the clause that already exists. diff --git a/docs/topics/fable-field-guide-audit/findings/S9.md b/docs/topics/fable-field-guide-audit/findings/S9.md deleted file mode 100644 index 3d0994375..000000000 --- a/docs/topics/fable-field-guide-audit/findings/S9.md +++ /dev/null @@ -1,135 +0,0 @@ -# S9 — implementation plans ordered by likely-to-change - -Searched all 14 files before any absence verdict, grepping `plan`; -`review|present|approv|operator|reader|artifact|format|HTML`; -`gate|authoriz|consent|before implement|surface`; -`likely to change|volatil|data model|type interface|UX|user-facing|mechanical`. - -## C1 — Ask for a plan when ready to implement — COVERED - -`planning.md:5-15` owns the threshold: the two questions at `:7`, three sizes at `:11-13`. The -agent-side form is stronger than the article's — the playbook decides for itself when a plan is owed -(`:3`, "Apply this chapter before your first mutating action on any task") rather than waiting to be -asked. - -## C2 — The plan exists to be REVIEWED before implementation — PARTIAL - -- `planning.md:12` — "**Plan in-message** — 3–7 bullet steps **stated before executing**" is the - only place in the skill a plan is put in front of a human; it prescribes size and timing, nothing - else. -- `planning.md:13` — the durable-artifact tier justifies itself entirely by agent-facing - re-readability ("a plan you cannot re-read after context loss silently degrades into vibes"); - `context-economy.md:49-50` confirms the plan is a thing *you* re-read on resume. -- `communication.md:76` — "Surface hard-to-reverse decisions before building dependent work on top - of them… an early veto is cheap; a late one cascades." -- `planning.md:61` + `SKILL.md:26` — permanent-tier ritual includes "surface to the user before - acting." - -Absent: any statement that a plan is *for* review, any approval gate on a plan, any handling of -operator revisions to one. The playbook's plan is a set of falsifiable predictions the agent -executes against (`planning.md:19-25`); the article's is a proposal a human edits. - -## C3 — Foreground the parts most likely to change — MISSING as a presentation rule - -`planning.md:3` states the chapter's charter — "when a plan is owed, **what a plan must contain, how -to order and slice steps**, and when to abandon a plan." Ordering is enumerated; foregrounding is -not. `## The shape of a useful plan` (`:17-37`) covers per-step fields, sizing, unknown-binning — -nothing on reader attention. - -Nearest coverage is by category, not layout: `planning.md:60` puts "structures other work will build -on" in the **expensive** tier, `:61` puts "public contract changes" in **permanent**, and `:92` -pulls the contract-defining step ahead of its consumers. Same underlying property, applied to -execution rigor instead of review prominence. - -## C4 — "surface things I might actually need to alter" — PARTIAL - -`communication.md:67-76` is the identical rationale at decision grain: visible block, `:71` format -"what you chose → what it changes for them → the evidence basis", `:75` "The reader can only veto -what they can see." `communication.md:51,58-61` explains why the agent's own uncertainty cannot find -these items — the ask-categories "are the user's calls by nature, and evidence about the code cannot -settle a question about their values." Scoped to decisions already taken mid-work, never to a plan's -layout. - -## C5 — Bury mechanical refactoring at the bottom — PARTIAL - -The separation is doctrine twice: `planning.md:30` "Never fuse behavior-preserving and -behavior-changing work in one step"; `execution.md:90` "One intent per change. Mechanical -transformations (rename, move, reformat) travel separately from behavior changes." - -The deprioritization half has no counterpart. Nothing contradicts it *as presentation* — but as a -rigor claim it would collide with `planning.md:65` ("Confidence never lowers the tier") and the -blast-radius census (`:71-85`), since a mechanical sweep is often the highest-blast-radius item in a -plan. - -## C6 — "write the plan in HTML" — OUT-OF-SCOPE (audience) - -Output format is user preference about *what* is produced; meta-rule 1 excludes it. - -## Resolution of the ordering tension - -**(i) Does the playbook address plan PRESENTATION as distinct from execution?** No, and the omission -is structural. `planning.md:3` enumerates the chapter's four jobs; review ergonomics is not among -them. `communication.md` owns human-facing composition but every trigger is a *message* trigger — -`:7` "every turn-ending message, and every answer to a direct question", `:18` "whenever you are -deciding what to include in a reply". A plan artifact read by a human sits in the seam: -`planning.md` treats it as an execution script, `communication.md` never claims it. - -The closest line in the skill is `opus-adaptation.md:57` — "**Size plan granularity to the executor, -not to yourself**… When you write a plan or worker spec, ask who runs it before choosing step size." -The playbook already accepts that a plan is shaped by its consumer; the only consumer it -contemplates is the one who *executes*, never the one who *reviews*. - -**(ii) Does either axis subsume the other?** No, and the playbook supplies the reason. - -- Risk-first (`planning.md:41`, `SKILL.md:64`) sorts by what *reality* could contradict; its unit is - the agent's own uncertainty, discharged by a probe with a kill criterion (`planning.md:43-49`). -- Revision-likelihood sorts by what the *human* could contradict; its unit is operator preference, - which per `communication.md:51` the agent's evidence structurally cannot settle. -- They dissociate both ways. A data-model shape can carry zero execution risk — nothing falsifiable, - the agent is right that it works — and still be the one thing the operator wants changed. The top - execution risk ("does this endpoint return per-item timestamps?", `planning.md:49`) is usually - something the operator has no opinion on. -- Independent degrees of freedom: burying mechanical work in the presentation says nothing about - when it executes. Forcing one order to serve both purposes sacrifices one. - -**(iii) Both needed?** Yes. A plan whose function is to be corrected is only as good as where -attention lands — the principle the playbook already spends a section on at message grain -(`communication.md:16-23`, "Measure in decisions, not words"). The plan artifact is the one -high-stakes human-facing surface where it is never applied. Conversely, a plan sorted purely by -operator-tweak likelihood would defer the kill-criterion probe and reintroduce the step-6 failure -`planning.md:45` exists to prevent. - -## Candidate remediation - -**Shape (load-bearing):** do **not** re-sort plan steps. `planning.md:29` makes each step boundary a -safe stopping point and `:41` fixes their order by risk; re-sorting by revision likelihood breaks -execution semantics and contradicts `SKILL.md:64`. The correct shape is a **second view over the -same plan** — a short decisions-first preface above the risk-ordered step list. - -**Home:** `planning.md`, a new short section after `## The shape of a useful plan` (that chapter -owns "what a plan must contain"), citing `communication.md`'s "Surface every unbriefed decision" for -the line format rather than restating it. The charter sentence at `planning.md:3` needs the -presentation job added alongside the existing four. - -**Substance** (capability-conditioned; nothing model-specific): - -- Trigger: any plan a human will read before you execute it (both tiers, `:12` and `:13`). -- Lead with the choices the *user* would most plausibly make differently — the ones encoding - preference rather than fact: data shapes, interfaces and contracts other work will bind to, - anything user-observable. Rank by the rework a late veto would cause — `communication.md:76` - applied to a plan instead of a decision. -- Steps whose only content is a behavior-preserving mechanical transformation go last in the - presentation; there is nothing there for the reader to decide. Executable order stays risk-first. -- **Guardrail, must be explicit:** presentation prominence is not rigor. A step placed last is not - verified less — `planning.md:65`, the census at `:71-85`, and the verification floors at - `SKILL.md:89-92` apply unchanged. The article's "I trust you on that part" is an operator - allocating *their* attention, not the agent lowering its own bar. - -**Second, smaller candidate:** name the plan's dual purpose in `planning.md:13`. As written the -durable tier justifies itself solely by context loss; one clause naming operator review closes the -C2 partial without new machinery. - -**Note for disposition:** if reviewers prefer one home for all human-facing composition, the -alternative is a `communication.md` section with a cite from `planning.md`. The auditor recommends -`planning.md` — the rule concerns a plan's internal structure, and `communication.md`'s triggers are -all message-composition triggers that would have to be widened to reach an artifact. diff --git a/docs/topics/fable-field-guide-audit/raw-capture.txt b/docs/topics/fable-field-guide-audit/raw-capture.txt deleted file mode 100644 index 751a9d659..000000000 --- a/docs/topics/fable-field-guide-audit/raw-capture.txt +++ /dev/null @@ -1,573 +0,0 @@ -A field guide to Claude Fable 5: Finding your unknowns | Claude | Claude by Anthropic -Meet Claude -Products -Claude -Claude Code -Claude Cowork -@Claude -Features -Claude for Chrome -Claude for Microsoft 365 -Skills -Claude apps built for -Design -Science -Security -Models -Mythos -Fable -Opus -Sonnet -Haiku -Platform -Build on Claude -Overview -Pricing -Developer docs -Console login -Works with Claude -Ecosystem -Marketplace -Connectors -Plugins -Solutions -Use cases -AI agents -Coding -Company size -Enterprise -Startups -Departments -Cybersecurity -Legal -Industries -Customer support -Financial services -Government -Healthcare -Higher education -K-12 teachers -Life sciences -Nonprofits -Pricing -Overview -API -Resources -Insights -Blog -Customer stories -Anthropic news -Learn -Anthropic Academy -Courses -Tutorials -Use cases -Connect -Events -Community -Login -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Meet Claude -Products -Claude -Claude Code -Claude Cowork -@Claude -Features -Claude for Chrome -Claude for Microsoft 365 -Skills -Claude apps built for -Design -Science -Security -Models -Mythos -Fable -Opus -Sonnet -Haiku -Platform -Build on Claude -Overview -Pricing -Developer docs -Console login -Works with Claude -Ecosystem -Marketplace -Connectors -Plugins -Solutions -Use cases -AI agents -Coding -Company size -Enterprise -Startups -Departments -Cybersecurity -Legal -Industries -Customer support -Financial services -Government -Healthcare -Higher education -K-12 teachers -Life sciences -Nonprofits -Pricing -Overview -API -Resources -Insights -Blog -Customer stories -Anthropic news -Learn -Anthropic Academy -Courses -Tutorials -Use cases -Connect -Events -Community -Login -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Contact sales -Contact sales Contact sales -Try Claude -Try Claude Try Claude -Blog -Blog -/ -A field guide to Claude Fable 5: Finding your unknowns -Explore here -Ask questions about this page -Copy as markdown -A field guide to Claude Fable 5: Finding your unknowns -Category -Claude Code -Product -Claude Code -Date -July 6, 2026 -Reading time -5 -min -Share -Copy link https://claude.com/blog/a-field-guide-to-claude-fable-finding-your-unknowns -When working with Claude Code, I’m often reminded of the difference between the map and the territory. -The map, a representation of the work to be done, is my prompts and skills and context, it’s what I give Claude. The territory is where the work needs to happen, the codebase, the real world, its actual constraints. -The difference between the map and the territory is what I call unknowns . When Claude runs into an unknown, it needs to make a decision based on its best guess of what I want. The more work being done, the more unknowns Claude might run into. -Claude Fable is the first model where I find the quality of the work is bottlenecked by my ability to clarify its unknowns. -Importantly, just planning ahead isn’t always enough. You can find unknowns deep in implementation, or your unknowns may point you to the fact that you should actually be solving the problem in a different way altogether. -I’ve found that working with Fable is an iterative process of discovering my unknowns before, during, and after implementation. -No items found. -Prev Prev -0 / 5 -Next Next -Get Claude Code -Desktop -VS Code -JetBrains -On the web -Slack -curl -fsSL https://claude.ai/install.sh | bash -Copy command to clipboard -irm https://claude.ai/install.ps1 | iex -Copy command to clipboard -Or read the documentation -Try Claude Code -Try Claude Code Try Claude Code -Developer docs -Developer docs Developer docs -eBook -Knowing your unknowns -What are your unknowns? When I come to Claude with a problem I tend to break it down in 4 ways: -Known Knowns: This is essentially what is in my prompt. What do I tell the agent that I want? -Known Unknowns: What haven't I figured out yet, but I’m aware that I haven’t? -Unknown Knowns: What's so obvious I’d never write it down, but would recognize it if I saw it? -Unknown Unknowns: What haven't I considered at all? What knowledge am I not aware of? Do I know how good something can be? -The best agentic coders have relatively few unknowns. Watching someone like Boris or Jarred prompt, it is obvious to me that they know what they want in-detail. They are deeply in-sync with both the codebase and the model behaviors. -But they also assume unknowns. In many ways, reducing and planning for your unknowns is the skill of agentic coding. But luckily, this is a skill you can improve at, by working with Claude. -Help Claude help you -Instructing Claude is a delicate balance. If you are too specific, Claude will follow your instructions even when a pivot may be more appropriate. If you are too vague, Claude will often make choices and assumptions based on industry best practices that may not be a fit for your task. -When you don’t account for your unknowns, you fail both ways. You don't know when the path will be filled with obstacles, and you don’t know when the path will be clear, but you still want Claude to veer. -Claude can help you discover your unknowns faster. It can search through your codebase and the internet extremely quickly, and it knows much more about the average topic than you. It can also iterate from failure faster. -The most important part of this process is to give Claude context about your starting point. For example, tell it where you are in your thought process; disclose your experience with the problem and codebase; and let it work with you like a thought partner. -In this article I detail some of the patterns I use to uncover these unknowns including: -Pre-implementation: -Blind spot pass -Brainstorms and prototype -Interviews -References -Implementation plan -During implementation: -Implementation notes -Post implementation -Pitches and explainers -Quizzes -Pre-implementation -Blind Spot Pass -When starting work, one of the most useful things you can do is understand your blind spots. For example, if you’re writing a feature in a new part of the codebase, or using Claude to help you with unfamiliar work like iterating on a design, you’re likely to have a lot of unknown unknowns . -You may not know what questions to ask, what good looks like, what historical work has been done, or what potholes to avoid. -In these situations, you can ask Claude to help you find your unknown unknowns and explain them to you. I like to use the literal words “blind spot pass” and “unknown unknowns.” Giving it context on who you are and what you know is usually important for Claude to understand the best way to start collaborating with you. -Example prompts : -“I'm working on adding a new auth provider but I know nothing about the auth modules in this codebase. Can you do a blind spot pass to help me figure out my relevant unknown unknowns and help me prompt you better.” -“I don’t know what color grading is but I need to grade this video. Can you teach me to understand my unknown unknowns about color grading, so that I can prompt better?” -Brainstorms and prototypes -When I’m working in an area with a lot of unknown knowns , involving criteria I only know to define when I see it, I like to ask Claude to brainstorm and prototype with me. -It’s extremely valuable to identify and verbalize unknown knowns early during prototyping, because finding them out during implementation can be (relatively) expensive. Small changes in a feature or spec can cause drastically different implementations in code, and it can be more difficult for your agent to revert previous changes. -For example, you may just want to see how a button added to a frame looks without having to wire up a backend route or maintaining additional state in the frontend. -Another example is visual design, which for me, is something that is difficult to articulate, but I know what I want when I see it. In these cases, I’ll ask for several design approaches to an artifact. -I also start almost every coding session with an exploration or brainstorming phase. This helps me start with intent to define the project’s scope. Claude often finds high-value approaches I would have missed, and sometimes misses the forest through the trees. Brainstorming prevents me from setting too narrow or too wide a scope. -Example prompts: -"I want a dashboard for this data but I have no visual taste and don't know what's possible. Make me an HTML page with 4 wildly different design directions so I can react to them.” -“Before wiring anything up, make a single HTML file mocking the new editor toolbar with fake data. I want to react to the layout before you touch the real app." -"Here's my rough problem: users churn after onboarding. Search the codebase and brainstorm 10 places we could intervene, from cheapest to most ambitious. I'll tell you which ones resonate." -Interviews -Once I’ve done sufficient brainstorming, I likely still have unknowns. -In this case, I ask Claude to interview me about any unknowns or ambiguities. When asking Claude to interview you, try and give it context about your problem to guide its questions. -‍ Example prompt: -"Interview me one question at a time about anything ambiguous, prioritize questions where my answer would change the architecture." -References -Sometimes you can’t describe what you want in detail. For example, you might not have the language or it might be so complicated that it would take you quite a while. -In this case, the best approach is a reference. While you can include diagrams, documentation or pictures, the absolute best reference is source code . -If you have a library that implements something in a certain way or a design component you really like, just point Fable at the folder and tell it what to look for, even if it’s in a different language. This provides Claude much richer detail around the markup and structure, compared to for example a screenshot. -Example prompts: -"This Rust crate in vendor/rate-limiter implements the exact backoff behavior I want. Read it and reimplement the same semantics in our TypeScript API client." -Implementation Plans -When I think I’m ready to implement, I tend to ask Claude to put together an implementation plan for me to review. The plan focuses on the parts that might be most likely to change such as  data models, type interfaces, or UX flows. This allows Claude to surface things I might actually need to alter. -Example prompt: -"Write an implementation plan in HTML, but lead with the decisions I'm most likely to tweak with: data model changes, new type interfaces, and anything user-facing. Bury the mechanical refactoring at the bottom, I trust you on that part." -During implementation -Implementation notes -Once I am satisfied with my plan, I make a new session and pass any artifacts to the prompt. This gives Claude a fresh context window but with all of the information it compiled from your planning. For example, I might pass in a spec file and a prototype and ask an agent to implement it. -But the truth is that no matter how much planning you do, there are always unknown unknowns lurking. The agent may find during its work that it needs to take a different tack due to an edge case it found in the code. -I ask Claude Code to keep a temporary ‘implementation-notes.md’ (or .html) file where it keeps track of decisions it makes so we can learn for our next attempt. -Example prompt: -"Keep an implementation-notes.md file. If you hit an edge case that forces you to deviate from the plan, pick the conservative option, log it under 'Deviations', and keep going." -Post implementation -Pitches and explainers -One of the most important parts of shipping something is getting buy-in and approvals.  Building pitch and explainer artifacts in the final document helps: -Accelerate understanding when reviewers start with the same unknowns you did -Accelerate approvals when experts want to see you accounted for the unknowns and common failure points they would have anticipated -Example prompt: -"Package the prototype, the spec, and the implementation notes into a single doc I can drop in Slack to get buy-in. Lead with the demo GIF." -Quizzes -After a long working session, Claude might have accomplished a lot more than I realized. Reading the code diffs can only give me a light understanding of what happened, since much of the behavior will depend on existing code paths. -Asking Claude to quiz me about the change after giving me a bunch of context helps me understand what happens. I only merge after I pass the quiz perfectly. -Example prompt: -“I want to make sure I understand everything that's happened in this change. Give me a HTML report on the changes for me to read and understand with context, intuition, what was done, etc. and a quiz at the bottom on the changes that I must pass.” -How this comes together: launching Fable -The launch video for Fable was edited end-to-end using Claude Code. This was a new domain for me and I’m by no means an expert. -So I started with what I did know. I knew that Claude could use code to edit videos and transcribe them, but I wasn’t sure if it was accurate enough. I then asked Claude to explain to me how transcription like Whisper worked, and whether I would be able to accurately cut out things like ums or large pauses using ffmpeg. -I wanted Claude to create a UI that was timed with the words I was saying, but wasn’t sure it was possible so I asked Claude to create a prototype video using Remotion and a transcription to see if it would work. -Finally, the video itself looked a bit muted, which I knew was the result of color grading but I didn’t really know what color grading was. My first pass attempt was to try and get Claude to do a few variations to pick, but I realized that I didn’t know what “good” looked like when it came to color grading. So instead, I asked Claude to teach me about color grading to discover my unknowns. -Matching the Map and Territory -The better models get, the more you can achieve with the right approach. When a long-horizon task comes back wrong, it's likely you need to spend more time defining your unknowns or creating an implementation plan that allows for you and Claude to adapt through them. -Every explainer, brainstorm, interview, prototype, and reference is a cheap way to find out what you didn't know before it gets expensive to fix. -So start your next project by asking Claude to help you find your unknowns. -This article was written by Thariq Shihipar, member of technical staff, Anthropic. -FAQ -No items found. -Related posts -Explore more product news and best practices for teams building with Claude. -Jul 24, 2026 -Claude models explained: choosing the best model for your use case -Enterprise AI -Claude models explained: choosing the best model for your use case Claude models explained: choosing the best model for your use case -Claude models explained: choosing the best model for your use case Claude models explained: choosing the best model for your use case -Jul 24, 2026 -The new rules of context engineering for Claude 5 generation models -Claude Code -The new rules of context engineering for Claude 5 generation models The new rules of context engineering for Claude 5 generation models -The new rules of context engineering for Claude 5 generation models The new rules of context engineering for Claude 5 generation models -Jul 22, 2026 -Building verification loops in Claude Code with skills -Claude Code -Building verification loops in Claude Code with skills Building verification loops in Claude Code with skills -Building verification loops in Claude Code with skills Building verification loops in Claude Code with skills -Jul 21, 2026 -How Anthropic secures its AI-native software development lifecycle -Claude Code -How Anthropic secures its AI-native software development lifecycle How Anthropic secures its AI-native software development lifecycle -How Anthropic secures its AI-native software development lifecycle How Anthropic secures its AI-native software development lifecycle -Transform how your organization operates with Claude -See pricing -See pricing See pricing -Contact sales -Contact sales Contact sales -Get the developer newsletter -Product updates, how-tos, community spotlights, and more. Delivered monthly to your inbox. -Subscribe Subscribe -Please provide your email address if you'd like to receive our monthly developer newsletter. You can unsubscribe at any time. -Thank you! You’re subscribed. -Sorry, there was a problem with your submission, please try again later. -Homepage Homepage -Next Next -Thank you! Your submission has been received! -Oops! Something went wrong while submitting the form. -Write -Button Text Button Text -Learn -Button Text Button Text -Code -Button Text Button Text -Write -Help me develop a unique voice for an audience -Hi Claude! Could you help me develop a unique voice for an audience? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Improve my writing style -Hi Claude! Could you improve my writing style? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Brainstorm creative ideas -Hi Claude! Could you brainstorm creative ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Learn -Explain a complex topic simply -Hi Claude! Could you explain a complex topic simply? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Help me make sense of these ideas -Hi Claude! Could you help me make sense of these ideas? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Prepare for an exam or interview -Hi Claude! Could you prepare for an exam or interview? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Code -Explain a programming concept -Hi Claude! Could you explain a programming concept? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Look over my code and give me tips -Hi Claude! Could you look over my code and give me tips? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Vibe code with me -Hi Claude! Could you vibe code with me? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to— like Google Drive, web search, etc.—if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can—an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -More -Write case studies -This is another test -Write grant proposals -Hi Claude! Could you write grant proposals? If you need more information from me, ask me 1-2 key questions right away. If you think I should upload any documents that would help you do a better job, let me know. You can use the tools you have access to — like Google Drive, web search, etc. — if they’ll help you better accomplish this task. Do not use analysis tool. Please keep your responses friendly, brief and conversational. -Please execute the task as soon as you can - an artifact would be great if it makes sense. If using an artifact, consider what kind of artifact (interactive, visual, checklist, etc.) might be most helpful for this specific task. Thanks for your help! -Write video scripts -this is a test -Anthropic Anthropic -© [year] Anthropic PBC -Products -Claude -Claude Claude -Claude Code -Claude Code Claude Code -Claude Code for Enterprise -Claude Code for Enterprise Claude Code for Enterprise -Claude Cowork -Claude Cowork Claude Cowork -@Claude -@Claude @Claude -Claude Design -Claude Design Claude Design -Claude Science -Claude Science Claude Science -Claude Security -Claude Security Claude Security -Download app -Download app Download app -Pricing -Pricing Pricing -Log in -Log in Log in -Features -Claude for Chrome -Claude for Chrome Claude for Chrome -Claude for Microsoft 365 -Claude for Microsoft 365 Claude for Microsoft 365 -Skills -Skills Skills -Models -Mythos -Mythos Mythos -Fable -Fable Fable -Opus -Opus Opus -Sonnet -Sonnet Sonnet -Haiku -Haiku Haiku -Solutions -AI agents -AI agents AI agents -Code modernization -Code modernization Code modernization -Coding -Coding Coding -Customer support -Customer support Customer support -Cybersecurity -Cybersecurity Cybersecurity -Enterprise -Enterprise Enterprise -Financial services -Financial services Financial services -Government -Government Government -Healthcare -Healthcare Healthcare -Higher education -Higher education Higher education -K-12 teachers -K-12 teachers K-12 teachers -Legal -Legal Legal -Life sciences -Life sciences Life sciences -Nonprofits -Nonprofits Nonprofits -Small business -Small business Small business -Claude Platform -Overview -Overview Overview -Developer docs -Developer docs Developer docs -Pricing -Pricing Pricing -Ecosystem -Ecosystem Ecosystem -Marketplace -Marketplace Marketplace -Claude on AWS -Claude on AWS Claude on AWS -Google Cloud -Google Cloud Google Cloud -Microsoft Foundry -Microsoft Foundry Microsoft Foundry -Regional compliance -Regional compliance Regional compliance -Console login -Console login Console login -Resources -Blog -Blog Blog -Claude partner network -Claude partner network Claude partner network -Community -Community Community -Connectors -Connectors Connectors -Courses -Courses Courses -Customer stories -Customer stories Customer stories -Engineering at Anthropic -Engineering at Anthropic Engineering at Anthropic -Events -Events Events -Plugins -Plugins Plugins -Powered by Claude -Powered by Claude Powered by Claude -Service partners -Service partners Service partners -Tutorials -Tutorials Tutorials -Use cases -Use cases Use cases -Company -Anthropic -Anthropic Anthropic -Careers -Careers Careers -Policy -Policy Policy -Economic Futures -Economic Futures Economic Futures -Research -Research Research -News -News News -Policy on the AI Exponential -Policy on the AI Exponential Policy on the AI Exponential -Responsible Scaling Policy -Responsible Scaling Policy Responsible Scaling Policy -Security and compliance -Security and compliance Security and compliance -Transparency -Transparency Transparency -Programs -Startups -Startups Startups -Research Labs -Research Labs Research Labs -Help and security -Availability -Availability Availability -Status -Status Status -Support center -Support center Support center -Terms and policies -Privacy choices -Cookie settings -We use cookies to deliver and improve our services, analyze site usage, and if you agree, to customize or personalize your experience and market our services to you. You can read our Cookie Policy here . -Customize cookie settings -Reject all cookies -Accept all cookies -Necessary -Enables security and basic functionality. -Required -Analytics -Enables tracking of site performance. -Off -Marketing -Enables ads personalization and tracking. -Off -Save preferences -Privacy policy -Privacy policy Privacy policy -Responsible disclosure policy -Responsible disclosure policy Responsible disclosure policy -Terms of service: Commercial -Terms of service: Commercial Terms of service: Commercial -Terms of service: Consumer -Terms of service: Consumer Terms of service: Consumer -Terms of Service: US K-12 -Terms of Service: US K-12 Terms of Service: US K-12 -Data Processing Agreement: US K-12 -Data Processing Agreement: US K-12 Data Processing Agreement: US K-12 -Usage policy -Usage policy Usage policy -x.com x.com -LinkedIn LinkedIn -YouTube YouTube -Instagram Instagram -English (US) -English (US) -日本語 (Japan) -Deutsch (Germany) -Français (France) -한국어 (South Korea) -Italian (Italy) -Claude Code -Coding diff --git a/docs/topics/fable-field-guide-audit/source-article.md b/docs/topics/fable-field-guide-audit/source-article.md index 2d9332b2e..712a184a8 100644 --- a/docs/topics/fable-field-guide-audit/source-article.md +++ b/docs/topics/fable-field-guide-audit/source-article.md @@ -3,182 +3,22 @@ - URL: - Author: Thariq Shihipar, member of technical staff, Anthropic - Published: July 6, 2026 -- Captured: 2026-07-24 (curl + tag-strip; site chrome removed, body text verbatim; markdown - formatting reconstructed — emphasis, list markers, heading levels). Unedited capture: - `raw-capture.txt` (article body is lines 179-291). -Section IDs (S1–S14) are the audit units referenced by the task list. - ---- - -## S1 — Map and territory (opening frame) - -When working with Claude Code, I'm often reminded of the difference between the map and the territory. - -The map, a representation of the work to be done, is my prompts and skills and context, it's what I give Claude. The territory is where the work needs to happen, the codebase, the real world, its actual constraints. - -The difference between the map and the territory is what I call unknowns. When Claude runs into an unknown, it needs to make a decision based on its best guess of what I want. The more work being done, the more unknowns Claude might run into. - -Claude Fable is the first model where I find the quality of the work is bottlenecked by my ability to clarify its unknowns. - -Importantly, just planning ahead isn't always enough. You can find unknowns deep in implementation, or your unknowns may point you to the fact that you should actually be solving the problem in a different way altogether. - -I've found that working with Fable is an iterative process of discovering my unknowns before, during, and after implementation. - -## S2 — Knowing your unknowns (the four quadrants) - -What are your unknowns? When I come to Claude with a problem I tend to break it down in 4 ways: - -- **Known Knowns**: This is essentially what is in my prompt. What do I tell the agent that I want? -- **Known Unknowns**: What haven't I figured out yet, but I'm aware that I haven't? -- **Unknown Knowns**: What's so obvious I'd never write it down, but would recognize it if I saw it? -- **Unknown Unknowns**: What haven't I considered at all? What knowledge am I not aware of? Do I know how good something can be? - -## S3 — Unknown-reduction is the skill - -The best agentic coders have relatively few unknowns. Watching someone like Boris or Jarred prompt, it is obvious to me that they know what they want in-detail. They are deeply in-sync with both the codebase and the model behaviors. - -But they also assume unknowns. In many ways, reducing and planning for your unknowns is the skill of agentic coding. But luckily, this is a skill you can improve at, by working with Claude. - -## S4 — Help Claude help you (specificity balance, discovery accelerator, starting point) - -Instructing Claude is a delicate balance. If you are too specific, Claude will follow your instructions even when a pivot may be more appropriate. If you are too vague, Claude will often make choices and assumptions based on industry best practices that may not be a fit for your task. - -When you don't account for your unknowns, you fail both ways. You don't know when the path will be filled with obstacles, and you don't know when the path will be clear, but you still want Claude to veer. - -Claude can help you discover your unknowns faster. It can search through your codebase and the internet extremely quickly, and it knows much more about the average topic than you. It can also iterate from failure faster. - -The most important part of this process is to give Claude context about your starting point. For example, tell it where you are in your thought process; disclose your experience with the problem and codebase; and let it work with you like a thought partner. - -In this article I detail some of the patterns I use to uncover these unknowns including: - -Pre-implementation: - -- Blind spot pass -- Brainstorms and prototype -- Interviews -- References -- Implementation plan - -During implementation: - -- Implementation notes - -Post implementation: - -- Pitches and explainers -- Quizzes - -## S5 — Pre-implementation: Blind Spot Pass - -When starting work, one of the most useful things you can do is understand your blind spots. For example, if you're writing a feature in a new part of the codebase, or using Claude to help you with unfamiliar work like iterating on a design, you're likely to have a lot of unknown unknowns. - -You may not know what questions to ask, what good looks like, what historical work has been done, or what potholes to avoid. - -In these situations, you can ask Claude to help you find your unknown unknowns and explain them to you. I like to use the literal words "blind spot pass" and "unknown unknowns." Giving it context on who you are and what you know is usually important for Claude to understand the best way to start collaborating with you. - -Example prompts: - -- "I'm working on adding a new auth provider but I know nothing about the auth modules in this codebase. Can you do a blind spot pass to help me figure out my relevant unknown unknowns and help me prompt you better." -- "I don't know what color grading is but I need to grade this video. Can you teach me to understand my unknown unknowns about color grading, so that I can prompt better?" - -## S6 — Pre-implementation: Brainstorms and prototypes - -When I'm working in an area with a lot of unknown knowns, involving criteria I only know to define when I see it, I like to ask Claude to brainstorm and prototype with me. - -It's extremely valuable to identify and verbalize unknown knowns early during prototyping, because finding them out during implementation can be (relatively) expensive. Small changes in a feature or spec can cause drastically different implementations in code, and it can be more difficult for your agent to revert previous changes. - -For example, you may just want to see how a button added to a frame looks without having to wire up a backend route or maintaining additional state in the frontend. - -Another example is visual design, which for me, is something that is difficult to articulate, but I know what I want when I see it. In these cases, I'll ask for several design approaches to an artifact. - -I also start almost every coding session with an exploration or brainstorming phase. This helps me start with intent to define the project's scope. Claude often finds high-value approaches I would have missed, and sometimes misses the forest through the trees. Brainstorming prevents me from setting too narrow or too wide a scope. - -Example prompts: - -- "I want a dashboard for this data but I have no visual taste and don't know what's possible. Make me an HTML page with 4 wildly different design directions so I can react to them." -- "Before wiring anything up, make a single HTML file mocking the new editor toolbar with fake data. I want to react to the layout before you touch the real app." -- "Here's my rough problem: users churn after onboarding. Search the codebase and brainstorm 10 places we could intervene, from cheapest to most ambitious. I'll tell you which ones resonate." - -## S7 — Pre-implementation: Interviews - -Once I've done sufficient brainstorming, I likely still have unknowns. - -In this case, I ask Claude to interview me about any unknowns or ambiguities. When asking Claude to interview you, try and give it context about your problem to guide its questions. - -Example prompt: - -- "Interview me one question at a time about anything ambiguous, prioritize questions where my answer would change the architecture." - -## S8 — Pre-implementation: References - -Sometimes you can't describe what you want in detail. For example, you might not have the language or it might be so complicated that it would take you quite a while. - -In this case, the best approach is a reference. While you can include diagrams, documentation or pictures, the absolute best reference is source code. - -If you have a library that implements something in a certain way or a design component you really like, just point Fable at the folder and tell it what to look for, even if it's in a different language. This provides Claude much richer detail around the markup and structure, compared to for example a screenshot. - -Example prompts: - -- "This Rust crate in vendor/rate-limiter implements the exact backoff behavior I want. Read it and reimplement the same semantics in our TypeScript API client." - -## S9 — Pre-implementation: Implementation Plans - -When I think I'm ready to implement, I tend to ask Claude to put together an implementation plan for me to review. The plan focuses on the parts that might be most likely to change such as data models, type interfaces, or UX flows. This allows Claude to surface things I might actually need to alter. - -Example prompt: - -- "Write an implementation plan in HTML, but lead with the decisions I'm most likely to tweak with: data model changes, new type interfaces, and anything user-facing. Bury the mechanical refactoring at the bottom, I trust you on that part." - -## S10 — During implementation: Implementation notes - -Once I am satisfied with my plan, I make a new session and pass any artifacts to the prompt. This gives Claude a fresh context window but with all of the information it compiled from your planning. For example, I might pass in a spec file and a prototype and ask an agent to implement it. - -But the truth is that no matter how much planning you do, there are always unknown unknowns lurking. The agent may find during its work that it needs to take a different tack due to an edge case it found in the code. - -I ask Claude Code to keep a temporary 'implementation-notes.md' (or .html) file where it keeps track of decisions it makes so we can learn for our next attempt. - -Example prompt: - -- "Keep an implementation-notes.md file. If you hit an edge case that forces you to deviate from the plan, pick the conservative option, log it under 'Deviations', and keep going." - -## S11 — Post implementation: Pitches and explainers - -One of the most important parts of shipping something is getting buy-in and approvals. Building pitch and explainer artifacts in the final document helps: - -- Accelerate understanding when reviewers start with the same unknowns you did -- Accelerate approvals when experts want to see you accounted for the unknowns and common failure points they would have anticipated - -Example prompt: - -- "Package the prototype, the spec, and the implementation notes into a single doc I can drop in Slack to get buy-in. Lead with the demo GIF." - -## S12 — Post implementation: Quizzes - -After a long working session, Claude might have accomplished a lot more than I realized. Reading the code diffs can only give me a light understanding of what happened, since much of the behavior will depend on existing code paths. - -Asking Claude to quiz me about the change after giving me a bunch of context helps me understand what happens. I only merge after I pass the quiz perfectly. - -Example prompt: - -- "I want to make sure I understand everything that's happened in this change. Give me a HTML report on the changes for me to read and understand with context, intuition, what was done, etc. and a quiz at the bottom on the changes that I must pass." - -## S13 — How this comes together: launching Fable (worked example) - -The launch video for Fable was edited end-to-end using Claude Code. This was a new domain for me and I'm by no means an expert. - -So I started with what I did know. I knew that Claude could use code to edit videos and transcribe them, but I wasn't sure if it was accurate enough. I then asked Claude to explain to me how transcription like Whisper worked, and whether I would be able to accurately cut out things like ums or large pauses using ffmpeg. - -I wanted Claude to create a UI that was timed with the words I was saying, but wasn't sure it was possible so I asked Claude to create a prototype video using Remotion and a transcription to see if it would work. - -Finally, the video itself looked a bit muted, which I knew was the result of color grading but I didn't really know what color grading was. My first pass attempt was to try and get Claude to do a few variations to pick, but I realized that I didn't know what "good" looked like when it came to color grading. So instead, I asked Claude to teach me about color grading to discover my unknowns. - -## S14 — Matching the Map and Territory (closing claims) - -The better models get, the more you can achieve with the right approach. When a long-horizon task comes back wrong, it's likely you need to spend more time defining your unknowns or creating an implementation plan that allows for you and Claude to adapt through them. - -Every explainer, brainstorm, interview, prototype, and reference is a cheap way to find out what you didn't know before it gets expensive to fix. - -So start your next project by asking Claude to help you find your unknowns. - -This article was written by Thariq Shihipar, member of technical staff, Anthropic. +The article body is not held here — read it at the URL above. This file keeps only the +audit's section-ID legend: the S1–S14 IDs below are the audit units referenced throughout +`dispositions.md` and `repair-ledger.md`, mapped to the article's sections in reading order. + +- S1 — Map and territory (opening frame) +- S2 — Knowing your unknowns (the four quadrants) +- S3 — Unknown-reduction is the skill +- S4 — Help Claude help you (specificity balance, discovery accelerator, starting point) +- S5 — Pre-implementation: Blind Spot Pass +- S6 — Pre-implementation: Brainstorms and prototypes +- S7 — Pre-implementation: Interviews +- S8 — Pre-implementation: References +- S9 — Pre-implementation: Implementation Plans +- S10 — During implementation: Implementation notes +- S11 — Post implementation: Pitches and explainers +- S12 — Post implementation: Quizzes +- S13 — How this comes together: launching Fable (worked example) +- S14 — Matching the Map and Territory (closing claims) diff --git a/docs/topics/shadowed-skill-renames/PLAN.md b/docs/topics/shadowed-skill-renames/PLAN.md index 29897105a..a7f5af95e 100644 --- a/docs/topics/shadowed-skill-renames/PLAN.md +++ b/docs/topics/shadowed-skill-renames/PLAN.md @@ -10,12 +10,11 @@ Every skill and plugin name in the marketplace denotes what it actually does, fo ### Locked decisions -**Naming grammar (codify in PLUGIN-PHILOSOPHY, PR 1):** +**Naming grammar (codified in PR 1):** the grammar shipped and now lives in +[`docs/PLUGIN-PHILOSOPHY.md` § Naming](../../PLUGIN-PHILOSOPHY.md#naming), which supersedes the +bullet list this plan carried (it has since grown further exceptions decided after this plan). +Read it there. -- Imperative verbs; namespace supplies the object. Documented deviation from the official gerund preference (cite the page, copy nothing) — rationale: sentence-composability ("/explore X, then /research, then /interview me") and collection-consistency (itself official guidance). -- Verb meanings: `audit`/`scan` = read-only report; `check` = deterministic pass/fail gate; `clean`/`tidy`/`fix` = mutates; `setup` = plugin config; `update` = vendor refresh. -- `audit` mutation: read-only by default; mutation only behind an explicit user override (flag/argument), safety qualifiers permitted. Bare invocation never mutates. -- Sanctioned exceptions: nouns for knowledge routers (`principles`, `methodology`) and lifecycle-object routers (`worktree`, `pull-request`); vendor-wrapper stutter (`firecrawl:firecrawl`); `-deep` suffix = heavier isolated execution tier. - Cross-plugin references: required-for-contract → declared plugin dependency (native auto-install; link the official doc); optional enhancement → "if installed" soft reference with graceful degradation; bare unguarded references forbidden. **Skill renames** (dir + frontmatter `name` move together; description sharpened third-person what+when): diff --git a/plugins/claude-config/.claude-plugin/plugin.json b/plugins/claude-config/.claude-plugin/plugin.json index 252ac30c9..c15682f6d 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.40.9", + "version": "0.40.10", "description": "Nine configuration-health skills (plus setup) 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-permission-state (the permission rules actually in effect \u2014 every settings scope merged with per-rule provenance, what auto mode drops on entry, config written where nothing reads it, and which managed intents are enforced versus loosenable), draft-auto-mode-rules (interview and draft a paste-ready autoMode classifier block; prints only, never writes), audit-instructions (locally-owned instruction surfaces vs current model capability \u2014 proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane \u2014 posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target \u2014 three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate \u2014 delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).", "author": { "name": "Melodic Software", diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index 0b1757554..f53bdc7a2 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -3,6 +3,12 @@ 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.40.10] + +### Changed + +- **`audit-pass` doctor-handoff treats `DISABLE_DOCTOR_COMMAND` as unconfirmed throughout.** A 2026-08-26 re-check (two fetch routes) found the env-vars row absent again — its documented status has now flipped twice — so the item title, the re-check note, and the suppression-channels paragraph all route it through the existing detection-over-prediction posture instead of citing a documented basis. From the repo-wide derivability/point-dont-copy audit, tightened per PR #3387 review. + ## [0.40.9] ### Changed diff --git a/plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md b/plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md index d2491b39c..552a672d3 100644 --- a/plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md +++ b/plugins/claude-config/skills/audit-pass/reference/doctor-handoff.md @@ -39,7 +39,7 @@ from what it does not. 2. **The v2.1.205 behavior cutover.** "Before v2.1.205, `/doctor` opened a read-only diagnostics screen and pressing `f` sent the report to Claude to fix" (same page). A pass that assumes the pre-cutover shape on a current install is checking for the wrong thing. -3. **`DISABLE_DOCTOR_COMMAND` — documented, and it targets exactly this skill.** "Set to `1` to hide +3. **`DISABLE_DOCTOR_COMMAND` — documentation unstable; treat as unconfirmed.** "Set to `1` to hide the `/doctor` setup checkup skill and its `/checkup` alias. Useful for managed deployments where users shouldn't run setup diagnostics from a session. Doesn't affect the `claude doctor` terminal command. Before v2.1.205, this variable hid the `/doctor` diagnostics screen command" @@ -49,11 +49,16 @@ from what it does not. entry claiming it "does not appear in the environment variables list" is **superseded**: it rested on a read of a page long enough to truncate, and this row now confirms both the variable and the v2.1.205 cutover the point above states. Note the scope the row draws: the variable hides the - session skill, **not** `claude doctor` in the terminal. + session skill, **not** `claude doctor` in the terminal. **Re-checked 2026-08-26 (two fetch + routes): the row is absent from the current env-vars page again**, so the variable's documented + status has now flipped twice (absent 2026-07-24 → present 2026-08-10 → absent 2026-08-26). + Treat it as *unconfirmed*: the detection-over-prediction posture below already covers this — name + it only as a suspected cause, never as a documented basis, until a fetch shows the row again. -**Suppression channels — one is now documented, one is still not.** Item 3 and a `skillOverrides` +**Suppression channels — both unconfirmed, for different reasons.** Item 3 and a `skillOverrides` settings key were both carried in from this skill's design phase, and the 2026-07-24 read recorded -both as absent from the official pages. Item 3 is no longer absent. `skillOverrides` still is: no +both as absent from the official pages. Item 3's documentation has since flipped twice (see its +re-check note above), so it stays unconfirmed. `skillOverrides` is unconfirmed the simpler way: no such key appeared in [settings](https://code.claude.com/docs/en/settings) as of 2026-07-24, and that read has **not** been refreshed here — this pass re-derived the `env-vars` half only, so treat it as UNVERIFIED and probe. It may be real but undocumented, or stale. @@ -61,8 +66,8 @@ UNVERIFIED and probe. It may be real but undocumented, or stale. So the pass **detects absence rather than predicting it**: it checks whether `/doctor` actually resolves in this environment, and reports the outcome. If it does not resolve while the version floor is met, the run says so and names these channels as the suspected causes — `DISABLE_DOCTOR_COMMAND` -now with a documented basis, `skillOverrides` still unconfirmed — rather than asserting either as the -reason. Detecting beats predicting either way: the variable's presence in the list says an operator +(documentation status unstable across fetches, see above) and `skillOverrides`, both unconfirmed — +rather than asserting either as the reason. Detecting beats predicting either way: the variable's presence in the list says an operator *could* have set it, never that they did. **Recheck trigger:** any Claude Code minor release, or any change to how bundled skills are diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index 138d07543..8e924bf31 100644 --- a/plugins/claude-ops/.claude-plugin/plugin.json +++ b/plugins/claude-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-ops", - "version": "0.38.9", + "version": "0.38.10", "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used \u2014 a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which drops descriptions least-invoked-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface \u2014 every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json \u2014 full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces \u2014 built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills \u2014 against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry \u2014 OTEL store, collector, hook-event JSONL, ccusage \u2014 with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand \u2014 marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view \u2014 queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action \u2014 an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures \u2014 the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index 394a61438..31614d024 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,13 @@ All notable changes to the `claude-ops` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.38.10] + +### Changed + +- **`audit-install-state` surfaces table caught up to the current `claude-directory` docs** (verified 2026-08-26): adds the swept `uploads//`, `feedback/drafts/` (shorter-of-two-windows retention), and `usage-data/` rows, and splits `image-cache/` from `paste-cache/` to record its distinct all-other-sessions sweep rule — load-bearing for the skill's `age-exceeds-window` reasoning. +- **`observability` read-routing retention summary became a pointer** at `operator-setup-retention.md#retention-knobs` instead of a duplicated defaults table. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.38.9] ### Changed diff --git a/plugins/claude-ops/skills/audit-install-state/reference/surfaces.md b/plugins/claude-ops/skills/audit-install-state/reference/surfaces.md index 532d1f4b7..e198b2cf3 100644 --- a/plugins/claude-ops/skills/audit-install-state/reference/surfaces.md +++ b/plugins/claude-ops/skills/audit-install-state/reference/surfaces.md @@ -1,7 +1,7 @@ # What lives in a Claude Code installation directory, and who owns it Basis for every row: — read through the raw -markdown endpoint (`.../claude-directory.md`), not a summarizing fetch. Verified 2026-08-11. +markdown endpoint (`.../claude-directory.md`), not a summarizing fetch. Verified 2026-08-26. The distinction this file exists to make: **a path Claude Code already manages is not a cleanup candidate, however old its contents look.** Hand-pruning a swept path fights the product's own @@ -33,7 +33,11 @@ Three facts about it that change how a finding should be read: | `file-history//` | Pre-edit snapshots for checkpoint restore | | `plans/` | Plan files written during plan mode | | `debug/` | Per-session debug logs (`--debug` / `/debug` only) | -| `paste-cache/`, `image-cache/` | Large pastes and attached images | +| `paste-cache/` | Large pastes | +| `image-cache/` | Attached images. **Different sweep rule:** on each sweep the directories of all *other* sessions are removed whatever their age — so an old `image-cache//` disappearing immediately is expected, never an `age-exceeds-window` signal | +| `uploads//` | Remote Control / web attachments | +| `feedback/drafts/` | Feedback drafts — swept after `cleanupPeriodDays` **or** 30 days, whichever is shorter | +| `usage-data/` | `/insights` reports and cached analysis data | | `session-env/` | Per-session environment metadata | | `tasks/` | Per-session task lists | | `shell-snapshots/` | Shell state captured at startup; removed on clean exit | diff --git a/plugins/claude-ops/skills/observability/context/read-routing.md b/plugins/claude-ops/skills/observability/context/read-routing.md index 3a23f74a2..a2a59571f 100644 --- a/plugins/claude-ops/skills/observability/context/read-routing.md +++ b/plugins/claude-ops/skills/observability/context/read-routing.md @@ -58,17 +58,12 @@ Hooks ──▶ hook-events.jsonl 5. Scope by `session_id`, `trace_id`, or time — one Collector file serves all worktrees. 6. ccusage for cost — do not reconstruct billing from OTEL metrics when ccusage is available. -## Retention (summary) +## Retention -| Store | Knob | Default | -|---|---|---| -| OTEL structure (logs + traces) | `CC_OTEL_RETENTION_DAYS` | 7 days | -| OTEL API bodies (logs only) | `CC_OTEL_BODY_RETENTION_DAYS` | 2 days | -| JSONL hook events | `/claude-ops:observability clean --keep-days N` | 30 days | -| JSONL skill usage | `/claude-ops:observability clean --skill-usage-scope ` | 365 days (opt-in; inert without the flag) | -| Aspire RAM | none | restart to reclaim | - -Full prune mechanics: [operator-setup-retention.md](operator-setup-retention.md) "Pruning the store (retention) — two tiers". +Retention knobs and their defaults are defined once in +[operator-setup-retention.md](operator-setup-retention.md#retention-knobs); full prune +mechanics in the same file, "Pruning the store (retention) — two tiers". (Aspire holds +telemetry in RAM only — restart to reclaim.) ## Anti-patterns diff --git a/plugins/discipline/.claude-plugin/plugin.json b/plugins/discipline/.claude-plugin/plugin.json index cd328ed08..573f5eadc 100644 --- a/plugins/discipline/.claude-plugin/plugin.json +++ b/plugins/discipline/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discipline", - "version": "0.12.17", + "version": "0.12.18", "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a typed full inventory of the session's claims — assumptions, asserted facts, concrete specifics, load-bearing premises — verified at a configurable depth and reported as a per-item ledger), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output; the audit runs both ways, also catching an existing script that over-reaches into judgement), use-your-skills (actually use the skills already in context — scan the listing, map the task, invoke the fitting skill instead of reinventing it, and name skills when delegating to a subagent), and reuse-or-replace (anti-fragmentation — new work reuses an established way of doing something or openly replaces it (migrate the old uses, record the decision), never silently stands up a second parallel way; divergence is allowed but owes a recorded reason proportional to blast radius), and scrutinize-dont-coast (adversarial self-scrutiny — stop coasting on your own recent output and re-examine whether it is sound, not merely confidently produced, through a fresh-context pass blind to the reasoning that made it, then remediate with the user; it stops the trajectory first and remediates collaboratively rather than autonomously). Plus further species that are not correctors (examples, not a fixed list — each skill's own description is authoritative), including setup, sweep-all, a posture-batch runbook that composes them — it fans out an audit-only subagent per in-scope corrector, then applies the corrections on the main thread in a fixed order, with batch membership and order set by each corrector's own colocated tier metadata and an optional userConfig overlay — and wait-what, a one-shot user-invoked-only communication repair: type /discipline:wait-what when the last message did not land and the model re-pitches it, backing up as far as needed, adding the missing context, in ASD-STE100 Simplified Technical English, using the project's ubiquitous language; never model-invoked and never in the batch. Firing a corrector is a re-anchor, not an accusation; the audit may return clean.", "author": { "name": "Melodic Software", diff --git a/plugins/discipline/CHANGELOG.md b/plugins/discipline/CHANGELOG.md index b9ba84b21..e705e58ed 100644 --- a/plugins/discipline/CHANGELOG.md +++ b/plugins/discipline/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the `discipline` plugin are documented here. Format follo Entries below `0.9.0` were released under the plugin's former name, `re-anchor`. +## [0.12.18] + +### Changed + +- **`setup` step 6 fork-mode framing matches current docs.** Fork subagents are on by default in interactive sessions on Claude Code >= v2.1.232 (off by default in non-interactive `-p` and Agent SDK sessions; `CLAUDE_CODE_FORK_SUBAGENT` overrides either way, re-checked 2026-08-26) — the step no longer frames fork-spawning as needing explicit enabling. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.12.17] ### Changed diff --git a/plugins/discipline/skills/setup/SKILL.md b/plugins/discipline/skills/setup/SKILL.md index fb55b0f46..3c63c72e9 100644 --- a/plugins/discipline/skills/setup/SKILL.md +++ b/plugins/discipline/skills/setup/SKILL.md @@ -67,8 +67,10 @@ Official contract: ). + conversation-inheriting fork subagents. Fork mode is on by default in interactive sessions + on Claude Code >= v2.1.232 (off by default in non-interactive `-p` and Agent SDK sessions; + `CLAUDE_CODE_FORK_SUBAGENT` overrides either way: + , re-checked 2026-08-26). `sweep-all` preflights this itself and degrades when the fan-out cannot inherit; that runbook owns the behavior; report the prerequisite here only so an unavailable fan-out reads as expected rather than as a misconfiguration, and do not restate what the degraded pass does. diff --git a/plugins/playwright/.claude-plugin/plugin.json b/plugins/playwright/.claude-plugin/plugin.json index 0be3bab58..580cd9b59 100644 --- a/plugins/playwright/.claude-plugin/plugin.json +++ b/plugins/playwright/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "playwright", - "version": "0.6.4", + "version": "0.6.5", "description": "Live E2E browser automation via Microsoft's @playwright/cli — named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context, plus a vendored upstream baseline and maintainer drift-check update flow.", "author": { "name": "Melodic Software", diff --git a/plugins/playwright/CHANGELOG.md b/plugins/playwright/CHANGELOG.md index ebb86c42e..c82561faf 100644 --- a/plugins/playwright/CHANGELOG.md +++ b/plugins/playwright/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `playwright` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.5] + +### Changed + +- **Unsourced "27K vs 114K / roughly 4x" token figure removed** from README and the skill description/body — the number is not in upstream `@playwright/cli`'s docs (checked 2026-08-26), matching this changelog's 0.5.0 precedent of dropping unsourced performance figures. The qualitative claim (artifacts on disk, only paths in context) stands. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.6.4] ### Changed diff --git a/plugins/playwright/README.md b/plugins/playwright/README.md index 408008438..721b5e37a 100644 --- a/plugins/playwright/README.md +++ b/plugins/playwright/README.md @@ -6,8 +6,8 @@ token-efficient live browser automation: named sessions, accessibility-ref snapshots (click/fill by ref, not CSS selector), screenshots, console and network capture, network mocking, tracing, video, and auth-state persistence. Snapshots and screenshots write to disk and only -paths come back into context, roughly a 4x token reduction versus -Playwright MCP in upstream's measurement. +paths come back into context, a substantial token reduction versus +Playwright MCP's in-context payloads. Invoke it with `/playwright:playwright`, or let Claude reach for it when you ask for an E2E test, a screenshot, or any live browser flow. diff --git a/plugins/playwright/skills/playwright/SKILL.md b/plugins/playwright/skills/playwright/SKILL.md index bad4a5334..7dfb35c56 100644 --- a/plugins/playwright/skills/playwright/SKILL.md +++ b/plugins/playwright/skills/playwright/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Live E2E browser automation via Microsoft's @playwright/cli: named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, network mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context (roughly 4x fewer tokens than Playwright MCP). Use when: 'E2E test', 'browser automation', 'take a screenshot', 'test the UI flow', 'click element', 'fill form', 'mock network', 'record a video', 'check console errors', 'playwright'." +description: "Live E2E browser automation via Microsoft's @playwright/cli: named sessions, accessibility-ref snapshots, click/fill by ref, screenshots, console and network capture, network mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context (far fewer tokens than Playwright MCP). Use when: 'E2E test', 'browser automation', 'take a screenshot', 'test the UI flow', 'click element', 'fill form', 'mock network', 'record a video', 'check console errors', 'playwright'." when_to_use: "live browser testing, UI smoke tests, snapshot the page, auth state persistence, `/playwright:playwright update` (maintainers)" argument-hint: "[update] [--check|--apply]" user-invocable: true @@ -17,7 +17,7 @@ metadata: # Playwright CLI, live browser automation -Wraps Microsoft's [`@playwright/cli`](https://github.com/microsoft/playwright-cli) for token-efficient browser automation. Snapshots and screenshots write to disk; only paths come back into context, roughly a 4x token reduction versus Playwright MCP (27K vs 114K per workflow in upstream's measurement). +Wraps Microsoft's [`@playwright/cli`](https://github.com/microsoft/playwright-cli) for token-efficient browser automation. Snapshots and screenshots write to disk; only paths come back into context, a substantial token reduction versus Playwright MCP's in-context payloads. Requires `playwright-cli` on PATH (`npm install -g @playwright/cli`). If it is missing, tell the user to install it rather than substituting a different automation surface. diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index 98b02598c..877e13d05 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.34.6", + "version": "0.34.7", "description": "Session-lifecycle toolkit of fourteen skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear-and-resume), continue-in-background (delegate the task to a fresh background agent that continues it now \u2014 same save-point engine as handoff, delivered by launching a detached claude --bg session seeded with the resume prompt; launches only on explicit user request), keep-going (recover and continue after any interruption OR when live off-thread work looks stalled \u2014 inventory off-thread work, inspect its real output, act only on evidence, then continue; after a usage limit lifts it continues rather than summarizing-and-stalling), find-handoff (recover a lost handoff after /clear \u2014 when the resume prompt was written but never copied \u2014 via a read-only detection ladder: known-location glob of the handoffs dir, then a bounded, recency-ranked transcript scan for the handoff directive and dashed-rail markers, then a confirm-before-resume gate; surfaces only the resume prompt + metadata, never raw transcript content), clean-stop (get to a durable, linked stopping point before the machine may go away \u2014 sweep every repo/worktree for uncommitted, unpushed, or PR-less work, push it durable, put breadcrumbs in PR/issue bodies, then give a free-and-clear verdict), retro (structured end-of-session retrospective with transcript metrics and learning codification), running-retro (in-flight retrospective checkpoints that spawn a subagent to analyze the transcript so far and append classified findings to a cumulative running ledger \u2014 capture and route only, the live counterpart to retro; also owns a detached-observer substrate that can watch a session out-of-band and run the checkpoint autonomously after the session ends), orient (read-only session orientation \u2014 synthesize where we stand, what we are doing, and why, from durable + off-thread state the built-in /recap never sees: ledgers, handoffs, workflow checklists, running-retro ledgers, open PRs and work-items, and git), orchestrate (arm a session or worker with proactive-orchestration imperatives), reanchor (verify a session's working assumptions are still true against live reality \u2014 referenced PRs/issues/branches, base-branch drift, renamed/version-drifted surfaces, stale memory-tier files, and the goal a handoff records, compared across the chain so a re-derived goal reports as drift \u2014 before building on them), reconcile (retire finished off-thread work and reconcile this session's task ledger with reality \u2014 the prune-and-reconcile counterpart to keep-going's resume: inventory the work this session spawned, inspect its real state, retire the finished and close proven-done tasks, auto-settling the finished and gating any kill of still-running work; sibling sessions in the project are reported read-only), setup (check-centric verification of the observer's runtime prerequisites and configuration), and show-options (lay out which skills fit this moment as a ranked, nothing-hidden menu \u2014 a shortlist per bucket plus the complete remainder by name, resolved from the full installed catalog rather than the truncated in-context listing, so the human decides and no option is withheld for looking already-done).", "author": { "name": "Melodic Software", diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index fa3e1696b..9c5ba4b18 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog — session-flow plugin +## [0.34.7] + +### Changed + +- **`retro`'s ecosystem-improvement catalog points at the hook-events docs instead of copying them.** The ~25-row Hook Events table (a capability list the official docs own, and one that grows faster than a copy can track) is replaced by a pointer to . From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.34.6] ### Changed diff --git a/plugins/session-flow/skills/retro/reference/ecosystem-improvement-catalog.md b/plugins/session-flow/skills/retro/reference/ecosystem-improvement-catalog.md index 229ea37a6..240c5ec3c 100644 --- a/plugins/session-flow/skills/retro/reference/ecosystem-improvement-catalog.md +++ b/plugins/session-flow/skills/retro/reference/ecosystem-improvement-catalog.md @@ -113,34 +113,11 @@ matcher syntax, and environment variables against the current hooks documentatio - A quality gate was missed that could be enforced by a hook - A specific tool usage pattern should be blocked or warned about -### Hook events (verify the current list before recommending) +### Hook events -| Hook Event | Use Case | Matcher | -| --- | --- | --- | -| SessionStart | One-time setup when a session begins or resumes | startup, resume, clear, compact | -| Setup | Repo setup/maintenance runs (`--init`, `--init-only`, `--maintenance`) | init, maintenance | -| UserPromptSubmit | Inject context or validate before Claude processes a prompt | (none) | -| UserPromptExpansion | When a user-typed command expands into a prompt | command name | -| PreToolUse | Block or warn before a tool executes | tool name | -| PermissionRequest / PermissionDenied | Permission dialog appears / tool call auto-denied | tool name | -| PostToolUse | Validate output after a tool succeeds (e.g., format check) | tool name | -| PostToolUseFailure | React to failed tool calls | tool name | -| PostToolBatch | After a batch of parallel tool calls resolves | (none) | -| Notification | When Claude Code sends a notification | notification type | -| MessageDisplay | While assistant message text is displayed | (none) | -| SubagentStart / SubagentStop | When subagents spawn or finish | agent type | -| TaskCreated / TaskCompleted | Task-list lifecycle — creation and completion | (none) | -| TeammateIdle | When an agent-team teammate is about to go idle | (none) | -| Stop | When Claude finishes responding | (none) | -| StopFailure | When the turn ends due to an API error | error type | -| InstructionsLoaded | When a CLAUDE.md or rules file loads into context | session_start, nested_traversal, path_glob_match, include, compact | -| ConfigChange | When a config file changes during a session | config source | -| CwdChanged | When the working directory changes | (none) | -| FileChanged | When a watched file changes on disk | filenames to watch | -| WorktreeCreate / WorktreeRemove | Worktree lifecycle — environment setup, cleanup | (none) | -| PreCompact / PostCompact | Before / after context compaction | manual, auto (PreCompact only) | -| Elicitation / ElicitationResult | MCP server user-input requests and responses | MCP server name | -| SessionEnd | When a session terminates | termination reason | +The hook-event catalog (event names, use cases, matchers) is owned by the official docs: read +the current list at before recommending — it grows and +changes faster than any copy here could track, so no copy is kept here. ### Recommendation format diff --git a/plugins/source-control/.claude-plugin/plugin.json b/plugins/source-control/.claude-plugin/plugin.json index f79199376..e710d9399 100644 --- a/plugins/source-control/.claude-plugin/plugin.json +++ b/plugins/source-control/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "source-control", - "version": "0.55.20", + "version": "0.55.21", "description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-authored-by trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop \u2014 safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /babysit-loop (the loop-lane merge lane: a standing or drain loop that invokes babysit-prs per cycle, configured through repo-scoped babysit_loop_* keys on the layered source-control.md seam, with merge authority human-only until the target repo's tracked config adopts the lane, a gate-proven C2-mechanical baseline once adopted, and standing merge-rung raises binding from the team-tracked layer only \u2014 with one named exception, where an invocation line explicitly typing both the autopilot tier keyword and the dedicated raise argument --merge c3-this-run widens that single invocation's merge authority up to C3 behind a fresh independent frontier-tier resolver, while C4-structural and C5-untrusted-provenance stay unconditionally human-merge), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply \u2014 interview the repo and write the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep \u2014 never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.", "author": { "name": "Melodic Software", diff --git a/plugins/source-control/CHANGELOG.md b/plugins/source-control/CHANGELOG.md index c07951776..8610feda6 100644 --- a/plugins/source-control/CHANGELOG.md +++ b/plugins/source-control/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `source-control` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.55.21] + +### Changed + +- **`worktree-root-convention` version-floors row hedges the git 2.56 `worktree:`/`worktree/i:` includeIf claim** as unreleased as of 2026-08-26 (latest upstream tag v2.55.0; the 2.55 docs do not list the condition), so a config is not authored against an unshipped floor. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.55.20] ### Changed diff --git a/plugins/source-control/reference/worktree-root-convention.md b/plugins/source-control/reference/worktree-root-convention.md index cd46128f4..c88e5092f 100644 --- a/plugins/source-control/reference/worktree-root-convention.md +++ b/plugins/source-control/reference/worktree-root-convention.md @@ -139,8 +139,9 @@ last-wins picks it up) alongside the identity keys. Verified properties `.git/config`** — repo-local config is not cloned, so the exception vanishes on re-clone (twice, for a dotfiles repo with two peer clones). - **Version floors:** `gitdir:`/`gitdir/i:` 2.13, `onbranch:` 2.23, - `hasconfig:remote.*.url:` 2.36, `worktree:`/`worktree/i:` **2.56** — a - config authored for 2.56 degrades silently on 2.55. + `hasconfig:remote.*.url:` 2.36, `worktree:`/`worktree/i:` **2.56 — unreleased as of + 2026-08-26** (latest tag v2.55.0; the 2.55 docs do not list the condition yet, so verify it + shipped before authoring for it) — a config authored for 2.56 degrades silently on 2.55. - **Per-worktree overrides need `config.worktree`** behind `extensions.worktreeConfig` — no `gitdir:` pattern can distinguish two worktrees of one repository. diff --git a/plugins/testing/.claude-plugin/plugin.json b/plugins/testing/.claude-plugin/plugin.json index df26db33f..250967071 100644 --- a/plugins/testing/.claude-plugin/plugin.json +++ b/plugins/testing/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "testing", - "version": "0.7.8", + "version": "0.7.9", "description": "Test-stage discipline across all ecosystems: coverage-gap analysis and test planning (`/testing:plan`), TDD test authoring and placement (`/testing:write`), live E2E plus non-UI smoke verification (`/testing:run-e2e`), failing-test root-cause diagnosis with the reproduce \u2192 isolate \u2192 fix \u2192 retest loop (`/testing:diagnose`), and a deterministic can't-fail test audit with a fail-closed gate mode and opt-in findings persistence (`/testing:audit`).", "author": { "name": "Melodic Software", diff --git a/plugins/testing/CHANGELOG.md b/plugins/testing/CHANGELOG.md index d17ee5561..354c09a00 100644 --- a/plugins/testing/CHANGELOG.md +++ b/plugins/testing/CHANGELOG.md @@ -3,6 +3,13 @@ All notable changes to the `testing` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.9] + +### Changed + +- **`run-e2e` MCP handshake shapes point at the spec instead of copying it.** The `initialize` request/response JSON blocks are replaced by a pointer naming the pinned `2025-06-18` revision and , noting revisions after `2025-11-25` replace the handshake with per-request metadata (verified 2026-08-26), so the smoke test is scoped to legacy/dual-era servers. +- **Duplicated "27K vs 114K" token figures removed** from the SKILL body and `context/e2e.md` in step with the playwright plugin dropping the unsourced origin figure; the comparison is now qualitative. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.7.8] ### Changed diff --git a/plugins/testing/skills/run-e2e/SKILL.md b/plugins/testing/skills/run-e2e/SKILL.md index 4ee220b3b..b80497521 100644 --- a/plugins/testing/skills/run-e2e/SKILL.md +++ b/plugins/testing/skills/run-e2e/SKILL.md @@ -71,4 +71,4 @@ The workflow steps themselves live in [context/e2e.md](context/e2e.md). - **Semantic locators ONLY**. Accessibility-based element refs from snapshots, never CSS selectors or XPath that break on cosmetic changes - Orchestrator version coupling + health-check waits. Wait for the orchestrator's health signal before driving flows; don't poll blindly -- Playwright CLI vs MCP token budget (~27K vs ~114K per workflow). CLI by default; detail in [context/e2e.md](context/e2e.md) +- Playwright CLI vs MCP token budget: CLI is substantially cheaper (artifacts go to disk, only paths enter context). CLI by default; detail in [context/e2e.md](context/e2e.md) diff --git a/plugins/testing/skills/run-e2e/context/e2e.md b/plugins/testing/skills/run-e2e/context/e2e.md index cfc82cde1..7a70f7feb 100644 --- a/plugins/testing/skills/run-e2e/context/e2e.md +++ b/plugins/testing/skills/run-e2e/context/e2e.md @@ -24,12 +24,12 @@ Before ANY live testing, verify tool availability. The e2e orchestrator and any ## Token Optimization: CLI by default -**Critical for context budget.** Playwright MCP consumes ~114K tokens for a multi-step workflow. Playwright CLI consumes ~27K tokens for the same work — 4.2x reduction. CLI writes snapshots and screenshots to disk so the agent reads only what it needs. +**Critical for context budget.** Playwright MCP streams snapshots and screenshots into context on every step; Playwright CLI writes them to disk so the agent reads only what it needs — a substantially smaller per-workflow token cost. | Approach | When to use | Token cost | |----------|------------|------------| -| **Playwright CLI** (via `/playwright:playwright` when installed) | Default — all navigation, interaction, snapshots, screenshots | ~27K tokens/workflow | -| **Playwright MCP** | Opt-in for stateful exploratory flows needing a continuous in-context browser (check how the consuming project enables/disables it in its MCP config) | ~114K tokens/workflow | +| **Playwright CLI** (via `/playwright:playwright` when installed) | Default — all navigation, interaction, snapshots, screenshots | Low — artifacts on disk, paths in context | +| **Playwright MCP** | Opt-in for stateful exploratory flows needing a continuous in-context browser (check how the consuming project enables/disables it in its MCP config) | High — payloads stream into context | | **Orchestrator MCP + curl** | API-only verification, health checks, structured log inspection | Minimal | **CLI mechanics** (commands, sessions, snapshots, storage, tracing, network mocking, Windows quirks): see `/playwright:playwright`, when the playwright plugin is installed. This skill (`/testing:run-e2e`) owns the broader orchestrator + API + UI story. diff --git a/plugins/testing/skills/run-e2e/context/non-ui.md b/plugins/testing/skills/run-e2e/context/non-ui.md index 343d8ce27..7f6b3e3e1 100644 --- a/plugins/testing/skills/run-e2e/context/non-ui.md +++ b/plugins/testing/skills/run-e2e/context/non-ui.md @@ -39,34 +39,14 @@ When unit tests pass but the server fails to register, the gap is the JSON-RPC ` 3. Read one line from stdout; parse as JSON-RPC response 4. Assert `result.protocolVersion`, `result.serverInfo.name`, and `result.capabilities` match expected shape -**Initialize request shape** (per MCP spec [modelcontextprotocol.io/specification/2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)): - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "2025-06-18", - "capabilities": {}, - "clientInfo": {"name": "smoke-test", "version": "0.0.0"} - } -} -``` - -**Expected response shape:** - -```json -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "protocolVersion": "2025-06-18", - "capabilities": { "tools": {} }, - "serverInfo": { "name": "", "version": "" } - } -} -``` +**Request/response shapes:** the MCP spec owns the `initialize` request and response schemas — +read them there rather than from a copy here (the protocol is versioned; a restated shape drifts +when it revs). This recipe was written against the pinned `2025-06-18` revision +(); check the current +revision via and match the recipe to the +revision your server SDK actually implements — revisions after `2025-11-25` replace the +`initialize` handshake with per-request metadata, so this handshake smoke test applies to +legacy/dual-era servers only (verified 2026-08-26). **Per-runtime spawn:** diff --git a/plugins/toolchain/.claude-plugin/plugin.json b/plugins/toolchain/.claude-plugin/plugin.json index db7b3b2ea..6714ccb72 100644 --- a/plugins/toolchain/.claude-plugin/plugin.json +++ b/plugins/toolchain/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "toolchain", - "version": "0.13.5", + "version": "0.13.6", "description": "Repo-agnostic polyglot verification toolchain: build + test + lint for changed files across .NET, Python, TypeScript, Bash, PowerShell, Markdown, Go, YAML, and cross-cutting surfaces (`/toolchain:check`, `/toolchain:lint` with format-only `--fix` and gated `--code-fix`), plus a re-runnable `/toolchain:setup` with check (report the configured ecosystems and their command surface) and apply (interview, infer, and write the tracked per-ecosystem command config those skills resolve first).", "author": { "name": "Melodic Software", diff --git a/plugins/toolchain/CHANGELOG.md b/plugins/toolchain/CHANGELOG.md index b6db48138..697f63a02 100644 --- a/plugins/toolchain/CHANGELOG.md +++ b/plugins/toolchain/CHANGELOG.md @@ -3,6 +3,12 @@ All notable changes to the `toolchain` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.13.6] + +### Changed + +- **`check`'s .NET gotcha scopes the `--project` requirement to the opt-in MTP runner.** Under VSTest — still the .NET 10 default — a bare positional project path is accepted; the rejection only occurs under Microsoft.Testing.Platform (enabled via `global.json`/`dotnet.config`). `--project` works in both, so the recipe still prefers it (re-checked against Microsoft's dotnet-test docs, 2026-08-26). From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.13.5] ### Changed diff --git a/plugins/toolchain/skills/check/context/dotnet.md b/plugins/toolchain/skills/check/context/dotnet.md index 0c3d0ea96..5b95d1772 100644 --- a/plugins/toolchain/skills/check/context/dotnet.md +++ b/plugins/toolchain/skills/check/context/dotnet.md @@ -27,7 +27,7 @@ dotnet build "$REPO_ROOT/path/to/Project.csproj" \ # All tests via solution dotnet test "$REPO_ROOT/" --no-build -# Single test project (.NET 10 requires --project flag) +# Single test project (--project works under both VSTest and MTP; required under MTP) dotnet test --project "$REPO_ROOT/path/to/Project.Tests.csproj" ``` @@ -49,7 +49,7 @@ dotnet format "$REPO_ROOT/" ## Gotchas -- **`--project` is required** for test project paths in .NET 10 SDK (10.0.1xx+). Bare positional paths are rejected: `dotnet test path/to/Project.csproj` fails with "Specifying a project for 'dotnet test' should be via '--project'" +- **`--project` is required** for test project paths **under the opt-in Microsoft.Testing.Platform (MTP) runner** (enabled via `global.json` / `dotnet.config`), where bare positional paths are rejected: `dotnet test path/to/Project.csproj` fails with "Specifying a project for 'dotnet test' should be via '--project'". Under VSTest — still the .NET 10 default — a bare positional project path is accepted. `--project` works in both, so prefer it either way (re-checked against Microsoft's dotnet-test-mtp/vstest docs, 2026-08-26) - **`--nologo` breaks xUnit v3** MTP runner. The flag passes through to the xUnit executable which rejects it as "Unknown option". Result: zero tests ran, exit code 5. Same issue with `-v q`. Use plain `dotnet test` or `-v n` - **`TreatWarningsAsErrors` repos** — when the repo turns warnings into errors globally, every warning is build-breaking; don't dismiss a warning as cosmetic - **VS locks analyzer DLLs** — if `dotnet build` fails with MSB3021 while Visual Studio is open, close VS or skip analyzers for quick iteration diff --git a/plugins/work-items/.claude-plugin/plugin.json b/plugins/work-items/.claude-plugin/plugin.json index a3c2456fb..fe76281e2 100644 --- a/plugins/work-items/.claude-plugin/plugin.json +++ b/plugins/work-items/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "work-items", - "version": "0.39.30", + "version": "0.39.31", "description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github, local-markdown, jira, gitea, and linear adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, a macro-journey router over spec containers (rollup, per-container execution shape, next-step routing), raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.", "author": { "name": "Melodic Software", diff --git a/plugins/work-items/CHANGELOG.md b/plugins/work-items/CHANGELOG.md index 375534114..a81dce6a4 100644 --- a/plugins/work-items/CHANGELOG.md +++ b/plugins/work-items/CHANGELOG.md @@ -3,6 +3,13 @@ All notable changes to the `work-items` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.39.31] + +### Changed + +- **`setup`'s gh-auth-status rationale consolidated to its owner.** `reference/autonomous-apply.md` and `reference/check.md` now point at `reference/providers.md` for why the account-level `gh auth status` check is the wrong gate, keeping only their operative instructions. +- **`track recheck`'s Cadence Duration Table became a pointer** at `add.md#cadence-duration-table`, honoring the plugin's own defined-once-in-add.md claim. From the repo-wide derivability/point-dont-copy audit (PR #3387). + ## [0.39.30] ### Changed diff --git a/plugins/work-items/skills/setup/reference/autonomous-apply.md b/plugins/work-items/skills/setup/reference/autonomous-apply.md index 0d4df17ed..d5282e66a 100644 --- a/plugins/work-items/skills/setup/reference/autonomous-apply.md +++ b/plugins/work-items/skills/setup/reference/autonomous-apply.md @@ -19,7 +19,7 @@ Applied to the three passes: | pass | unattended resolution | | --- | --- | -| Provider binding (`apply` step 1, which runs the "Provider binding" procedure) | **Binding already present and valid. Keep it, and re-bind nothing.** That is the procedure's own read-first RECOMMENDED answer, so this rule resolves to it silently: a repo bound to `local-markdown`, `jira`, or a consumer-local provider stays on it, and a working `gh` never switches it to `github`. Re-binding is a switch-providers decision, which no default can stand in for. (A present binding the probe already FAILs never reaches here. `apply` runs `check` first, and that probe FAILs a malformed shape, a provider resolving to no adapter, a missing required config key, and a `github` binding this checkout cannot derive a repo for.) **Binding absent**. Bind `github` with `config.lease_ttl_hours: 24`, both RECOMMENDED, **only when `gh` is installed AND `gh repo view --json owner,name` resolves in this checkout**. The old test was `gh auth status`, which proves only that an account is authenticated somewhere, never that this repository is hosted on GitHub, so a local-only or non-GitHub checkout was bound to a provider whose every repo-scoped verb then fails. `gh repo view` is the adapter's own derivation and the operative test: it subsumes authentication for the host this checkout uses, and it is not the machine-wide check `gh auth status` is (that one tests every account on every known host and exits 1 if any has an issue, per `gh auth status --help`, so an unrelated stale credential would refuse a good bind). Report the resolved `owner/repo` in the summary alongside the other defaults taken. Otherwise stop: `local-markdown` and `jira` need `storage_dir` / `config.jira` values that have no defaults and cannot be inferred, so there is no provider left to choose safely. Report "tracker binding needs a provider decision; run `/work-items:setup apply` with a user present". | +| Provider binding (`apply` step 1, which runs the "Provider binding" procedure) | **Binding already present and valid. Keep it, and re-bind nothing.** That is the procedure's own read-first RECOMMENDED answer, so this rule resolves to it silently: a repo bound to `local-markdown`, `jira`, or a consumer-local provider stays on it, and a working `gh` never switches it to `github`. Re-binding is a switch-providers decision, which no default can stand in for. (A present binding the probe already FAILs never reaches here. `apply` runs `check` first, and that probe FAILs a malformed shape, a provider resolving to no adapter, a missing required config key, and a `github` binding this checkout cannot derive a repo for.) **Binding absent**. Bind `github` with `config.lease_ttl_hours: 24`, both RECOMMENDED, **only when `gh` is installed AND `gh repo view --json owner,name` resolves in this checkout**. `gh repo view` is the adapter's own derivation and the operative test; `gh auth status` is not — [`providers.md`](providers.md) owns the rationale for why the account-level check is the wrong gate. Report the resolved `owner/repo` in the summary alongside the other defaults taken. Otherwise stop: `local-markdown` and `jira` need `storage_dir` / `config.jira` values that have no defaults and cannot be inferred, so there is no provider left to choose safely. Report "tracker binding needs a provider decision; run `/work-items:setup apply` with a user present". | | Role labels (step 2) | Keep the defaults, the RECOMMENDED answer, and the one that writes nothing. The pass runs and completes as a no-op: `config.role_labels` is left absent, so every role resolves to its documented fallback. A remap is a repo-vocabulary decision no default can stand in for. | | Work-class labels (step 3) | When any canonical member is missing: if the repo declares a label-as-code owner, stop, name the missing labels and point remediation at that owner. Otherwise stop: "work-class axis needs provisioning; run `/work-items:setup apply` with a user present". Never create labels ad hoc unattended. | | Capability-tier labels (step 4) | When `capability-tier: frontier` is missing: if the repo declares a label-as-code owner, stop. Name the missing label and point remediation at that owner. Otherwise stop: "capability-tier axis needs provisioning; run `/work-items:setup apply` with a user present". Never create labels ad hoc unattended. | diff --git a/plugins/work-items/skills/setup/reference/check.md b/plugins/work-items/skills/setup/reference/check.md index 354c12486..ecd697abb 100644 --- a/plugins/work-items/skills/setup/reference/check.md +++ b/plugins/work-items/skills/setup/reference/check.md @@ -33,9 +33,9 @@ check. them here (`gh repo view --json owner,name`, per the tracker CONTRACT's "Setup (binding file)"), so a shape-valid `github` binding in a non-GitHub checkout would otherwise PASS every probe and surface only when a verb fails at call time. Probe that same call **unconditionally**, never - behind a `gh auth status` precheck, which tests every account on every known host and exits 1 if - any has an issue (`gh auth status --help`), so an unrelated stale credential would skip the probe - and let the very binding this exists to catch go unreported. Verdict on *why* the call failed + behind a `gh auth status` precheck ([`providers.md`](providers.md) owns why that account-level + check is the wrong gate), so an unrelated stale credential cannot skip the probe and let the + very binding this exists to catch go unreported. Verdict on *why* the call failed rather than on failure alone: - Resolves → INFO naming the `owner/repo` the seam will address. - No remote, or no remote pointing at a known GitHub host → FAIL: nothing here can derive a repo, diff --git a/plugins/work-items/skills/track/actions/recheck.md b/plugins/work-items/skills/track/actions/recheck.md index b35f7e13a..25e7b054a 100644 --- a/plugins/work-items/skills/track/actions/recheck.md +++ b/plugins/work-items/skills/track/actions/recheck.md @@ -41,14 +41,8 @@ Refuse to advance `last_checked`/`next_due` or close the associated issue when t 1. **Update dates.** Always set `last_checked` to today. Only advance `next_due` if it's in the past or today — if it's already in the future, the recurring-issues automation has already advanced it and re-advancing would skip a cycle. -| Cadence | Days | -|---------|------| -| `weekly` | 7 | -| `biweekly` | 14 | -| `monthly` | 30 | -| `quarterly` | 90 | -| `semi-annual` | 180 | -| `annual` | 365 | +Cadence-to-days values: the Cadence Duration Table in [`add.md`](add.md#cadence-duration-table) +(defined once there; do not restate it here). 1. **Edit `.github/recurring-schedule.json`:**