diff --git a/.claude/rules/skill-bodies-state-current-rules.md b/.claude/rules/skill-bodies-state-current-rules.md new file mode 100644 index 0000000000..fa849e2563 --- /dev/null +++ b/.claude/rules/skill-bodies-state-current-rules.md @@ -0,0 +1,36 @@ +--- +description: "Skill and agent bodies state the current rule and its reason, never the incident, PR, or model that motivated it; read before editing any skill body" +paths: + - "plugins/*/skills/**" + - "plugins/*/agents/**" +--- + +# Skill bodies state current rules + +A skill body is read by the model on every invocation. Its authority is the behavior it +prescribes, not the incident that motivated it, so the body carries the rule and the reason and +nothing about how the rule got there. This follows the bundled `/claude-api prompt-audit` guide +(Group 2, "Brittle skill files"), applied fleet-wide in the 2026-09 audit recorded in +[`docs/specs/prompt-audit-skills-2026-09.md`](../../docs/specs/prompt-audit-skills-2026-09.md). + +Keep out of a skill or agent body: + +- Issue and pull-request numbers from this repository, incident IDs, and past-tense narration of + why a rule exists ("this was added after ...", "an earlier version claimed ..."). +- Pinned model names in behavioral guidance. A rule that only holds on one model belongs in the + `playbooks` model-adaptation chapters, not in a skill body. +- Date-conditional guidance ("before 2026-08 ...", "until version X ships ..."). +- Hardcoded paths, flags, and version numbers stated as bare fact with no verification. + +Keep in the body: + +- The rule, stated in the present tense, with the reason beside it. +- A pointer to an external upstream source (an official doc page, an upstream issue) when the rule + restates a volatile specific it cannot defer to at read time, recorded as the four-part + verification record the + [upstream-drift convention](../../docs/conventions/upstream-drift/README.md) defines: claim, + basis, as-of date, recheck trigger. A dated verification with a trigger is the correct form; an + undated claim is the defect. + +History belongs in the plugin's `CHANGELOG.md`, the commit message, and `docs/adr/`. A reader who +needs the archaeology finds it there; the model reading the skill does not need it to act. diff --git a/.claude/rules/worktree-base-ref.md b/.claude/rules/worktree-base-ref.md new file mode 100644 index 0000000000..8ff89274a4 --- /dev/null +++ b/.claude/rules/worktree-base-ref.md @@ -0,0 +1,22 @@ +--- +description: "This repository sets no worktree.baseRef; new worktrees branch from the remote default branch (Claude Code's default). Never add worktree.baseRef: head back, even when a reviewer says a merge dropped it" +paths: + - ".claude/settings.json" + - ".claude/settings.local.json" +--- + +# No worktree.baseRef in this repository + +Claude Code's `worktree.baseRef` setting picks the ref a new worktree branches from. Unset, it +is `fresh`: the repository's default branch as fetched from the remote, so every worktree +starts from the latest `main`. The value `head` branches from the local checkout's HEAD +instead, which spawns worktrees from whatever a session happens to have checked out. + +The operator withdrew the `head` override on 2026-09-02 (topic-docs convention 3.1.0, in +[`docs/conventions/topic-docs/CHANGELOG.md`](../../docs/conventions/topic-docs/CHANGELOG.md)), +and the setting stays absent on purpose. Do not add `worktree` to either settings file, and do +not "restore" it because a diff against another branch shows it missing: `origin/main` can carry +it for a while after a branch that removed it opens, and a review comment reading that diff +will call the removal a regression. It is not. Before restoring any key a review says a merge +dropped, run `git log -S'""' -- .claude/settings.json` on the branch and read the commit +that removed it. diff --git a/.claude/settings.json b/.claude/settings.json index f63a910487..4512e55af2 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -18,9 +18,6 @@ } ] }, - "worktree": { - "baseRef": "head" - }, "enabledPlugins": { "actionlint@melodic-software": true, "adhd@melodic-software": true, diff --git a/AGENTS.md b/AGENTS.md index 930c9d3da0..6592eb64b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,11 @@ context, read the file directly. | `.claude/rules/catalog-taxonomy.md` | `.claude-plugin/marketplace.json` | Where the marketplace category taxonomy lives; read before adding or changing a plugin's category | | `.claude/rules/hook-budget.md` | `plugins/*/hooks/**` | Marketplace-wide latency budget for always-on hooks; read before adding or widening a hook | | `.claude/rules/ruff-pin.md` | `**/*.py` | Python linting runs through the pinned ruff wrapper, never a bare ruff on PATH | +| `.claude/rules/skill-bodies-state-current-rules.md` | `plugins/*/skills/**, plugins/*/agents/**` | Skill and agent bodies state the current rule and its reason, never the incident, PR, or model that motivated it; read before editing any skill body | +| `.claude/rules/worktree-base-ref.md` | `.claude/settings.json, .claude/settings.local.json` | This repository sets no worktree.baseRef; new worktrees branch from the remote default branch (Claude Code's default). Never add worktree.baseRef: head back, even when a reviewer says a merge dropped it | +| `plugins/autonomy/AGENTS.md` | `plugins/autonomy/**` | autonomy plugin: contributor conventions | | `plugins/machine-health/skills/audit/AGENTS.md` | `plugins/machine-health/skills/audit/**` | machine-health audit skill: contributor conventions | +| `plugins/provenance/skills/audit/AGENTS.md` | `plugins/provenance/skills/audit/**` | Editing the provenance audit skill: contributor conventions | +| `plugins/work-items/skills/work-loop/AGENTS.md` | `plugins/work-items/skills/work-loop/**` | work-loop: contributor conventions | diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 3c020d279d..a67e294713 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -70,7 +70,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc - [`bugs`](../plugins/bugs) — Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own. - [`debugging`](../plugins/debugging) — Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem. - [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written), and write-for-humans (the same moment for the other reader — end-user READMEs, RFCs, release notes and guides — resolving the consuming project's own style guide first). -- [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean — deletes zero-information comments, dissolves code-expressible ones into names and structure behind the strongest proof each edit admits (a token-level proof for deletions and local renames, a discovered test net for the rest; safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill. +- [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean — deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill. - [`coupling`](../plugins/coupling) — Iteratively reduces coupling in any repository at any altitude — documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped. - [`repo-hygiene`](../plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default. - [`repo-fleet-hygiene`](../plugins/repo-fleet-hygiene) — Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes. @@ -82,7 +82,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc - [`playbooks`](../plugins/playbooks) — Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); skill-authoring — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers). - [`claude-config`](../plugins/claude-config) — 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 — 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 — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane — 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 — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it), 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). - [`claude-memory`](../plugins/claude-memory) — Keeps a repo's Claude Code memory layer healthy and under your control, against criteria derived from official Claude Code documentation. The audit skill checks the instruction/memory layer (CLAUDE.md, CLAUDE.local.md, .claude/rules/, auto-memory) with a deterministic script-backed spine plus judgment-tier checks. The stateless skill inspects, disables, and (confirm-gated) purges Claude-written auto memory across all settings scopes. -- [`claude-ops`](../plugins/claude-ops) — 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 — a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-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 — 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 — 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, plus on Windows a kernel-object census (Token objects against uptime, paged pool) that names a host-level leak beneath all four suspects; 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 — built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills — 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 — OTEL store, collector, the per-session hook event log and hook-event JSONL, ccusage — with trend reports, a per-session report of what fired, what was blocked and the event timeline, 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 — 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 — 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 — 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, the skill-usage log and the hook log root live, places the root's self-ignoring guard, and detects retired conventions. Plus an opt-in, default-off per-session hook event log (one JSON line per hook event on every event the generated registry marks observable, written to /sessions/.jsonl, with SessionEnd retention by session count or age and an optional detached pre-prune command), 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 — 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 routes envelopes under the same root: per session when the envelope carries a session id, else into the shared hook-events.jsonl the observability skill reads. +- [`claude-ops`](../plugins/claude-ops) — 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 — a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-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 — 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 — 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 — built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills — 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 — OTEL store, collector, hook-event JSONL, ccusage — 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 — 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 — 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 — 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 — 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. - [`rate-limit-guard`](../plugins/rate-limit-guard) — Shared rate-limit guard for loop lanes: a statusline wrapper tees the subscription rate-limit windows to a fixed machine-scope file, a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume. - [`context-guard`](../plugins/context-guard) — Per-session context-window observability plus the first shipped consumer: a statusline wrapper tees each session's context_window fields to a per-session snapshot file, a zone resolver classifies usage into smart/acceptable/dumb bands (percentage bands plus window-class token bands, conservative-min combination, zones.json SSOT with shipped defaults), a reader contract fixes how consuming sessions interpret the snapshots, and zone-crossing hooks report once per transition into a worse zone across two channels — the continuation menu to the operator, who owns that choice, and to the model only the zone determination plus the counter-steer that a zone word is not a decay signal (advisory by default; an optional blocking mode gates new mutating work on a fresh dumb-zone snapshot with handoff-writing exempt), with a PostCompact hook persisting an evidence-degraded marker. - [`context-budget`](../plugins/context-budget) — Measure a Claude Code session's fixed startup context payload per item, on the consumer's machine at a pinned, version-stamped binary — including per-tool attribution of the built-in tool pools that /context reports only as lump sums, derived live by A/B bare-name-deny differencing with enforced comparability rules (skill-listing signature, one mode, one binary), an SDK-primary exact meter degrading to a version-aware headless /context parser and then to an honest structured error (never a wrong number), and a per-project measure-toggle-remeasure ledger under the plugin data directory recording every lever's real before/after delta. Report-only: prints exact config, applies nothing. @@ -106,7 +106,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc ## Presentation - [`playgrounds`](../plugins/playgrounds) — One-step access to Anthropic's first-party playground plugin: declares the cross-marketplace dependency, routes playground-shaped requests to the upstream skill when it is installed, emits the install commands when it is not, and carries field-tested prompt recipes, cloud-session delivery guidance, and consumer cautions. Generates nothing itself. -- [`visualization`](../plugins/visualization) — On-demand visualization router: infers what in the current conversation should be shown visually, then decides the best FORM (a mermaid diagram, a markdown table, a hand-authored SVG/CSS chart, ASCII/Unicode art, code-shape sketches, a rich rendered page — or, where the bundled design skill is available, a hand-editable design canvas) and the best MEDIUM (inline terminal, a local HTML file, or a published Artifact) via a decision matrix over content shape, complexity, and a configurable medium preference. Renders good defaults and asks only when the target is genuinely ambiguous and no form was named. A form-and-medium decision layer in front of the craft capabilities — it routes chart craft and artifact-design fundamentals to those capabilities when installed and never restates them. +- [`visualization`](../plugins/visualization) — On-demand visualization router: infers what in the current conversation should be shown visually, then decides the best FORM (a mermaid diagram, a markdown table, a hand-authored SVG/CSS chart, ASCII/Unicode art, a rich rendered page — or, where the bundled design skill is available, a hand-editable design canvas) and the best MEDIUM (inline terminal, a local HTML file, or a published Artifact) via a decision matrix over content shape, complexity, and a configurable medium preference. Renders good defaults and asks only when the target is genuinely ambiguous and no form was named. A form-and-medium decision layer in front of the craft capabilities — it routes chart craft and artifact-design fundamentals to those capabilities when installed and never restates them. ## Project Management diff --git a/docs/adr/0028-audit-skill-bodies-fleet-wide-against-the-current-model-and-apply-directly.md b/docs/adr/0028-audit-skill-bodies-fleet-wide-against-the-current-model-and-apply-directly.md new file mode 100644 index 0000000000..5ba934bc5d --- /dev/null +++ b/docs/adr/0028-audit-skill-bodies-fleet-wide-against-the-current-model-and-apply-directly.md @@ -0,0 +1,119 @@ +# Audit skill bodies fleet-wide against the current model and apply the findings directly + +- Status: accepted +- Date: 2026-09-02 +- Supersedes: [ADR-0004](0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md) decisions D-1 and D-3, for the skill-body audit lane only; the promotion gate of [ADR-0006](0006-scope-model-doctrine-per-version-behind-a-promotion-gate.md) as retained by [ADR-0007](0007-host-per-model-doctrine-outside-skill-private-surfaces.md), for applied prompt-audit findings only + +## Context + +Claude Code ships a `prompt-audit` procedure inside its bundled `claude-api` skill. It reads +an instruction surface against a named target model, classifies each dated pattern into one +of four groups (obsolete scaffolding, brittle history and volatile specifics, worked examples +that constrain, and request-building code the model executes by hand), and prescribes a +concrete action per finding: remove, rewrite, move, replace with an API feature, add, or flag. +Its keep list is as binding as its pattern tables, and it states that an audit which finds +nothing changes nothing. + +In September 2026 the operator ran that procedure over every skill in this marketplace with +Claude Fable 5.1 as the target model. The run is recorded in +[`docs/specs/prompt-audit-skills-2026-09.md`](../specs/prompt-audit-skills-2026-09.md): one +fresh-context auditor per plugin, one report per plugin, the lead's per-finding decisions, one +commit per plugin with a patch bump and evals updated in step, and a follow-up inventory. The +sweep closed on 2026-09-05 over all 74 plugins: 63 took a commit and 11 were clean (one +single-skill plugin and ten whose only in-scope file the setup lane had audited). Across the +64 reports the lead applied 805 finding ids and withheld 207, the withheld set listed in the +record by plugin. The branch changed 694 files under `plugins/`, and no skill lost a step, a +gate, or a safety refusal in the record's five-skill behavioral spot-check. + +Three accepted decisions stood in the way, and the operator ruled before the first wave that +none of them binds this lane: + +- **ADR-0004 D-1, the incumbent-first gate.** No remediation ships until it proves no existing + skill already covers it. A prompt-audit finding is a text defect at a `file:line`; its + remediation is the hunk the procedure prescribes. An incumbent search per hunk would cost + more than the hunk and answer a question the procedure already answered (the pattern table + is the incumbent). +- **ADR-0004 D-3, no bulk sweep of `plugins/**`.** Findings were to land as checks in the + plugin that owns each surface, never as a sweep. That decision was written for a + practitioner article whose claims were a third unbacked. The prompt-audit guide is the + vendor's own procedure for the vendor's own model, and its findings are edits, not + criteria. Landing them as checks would leave every body unchanged. +- **ADR-0006's promotion gate, retained verbatim by ADR-0007.** Doctrine sourced from a single + model's guide is model-scoped by default and reaches fleet-wide only when a model-agnostic + upstream document states the claim or several model guides converge on it. The audit labels + every finding `fleet` or `fable-5-1`. Applying only the `fleet` set would leave the + `fable-5-1` set, which exists precisely because the target model changed, unapplied on the + model it targets. + +ADR-0004 D-15, arbitration over blanket deletion, was honored in form: every applied finding +carries the constraint's rationale and why it no longer holds for the target model, and the +guide's keep list (exact scripts for fragile operations, safety gates, working redundancy) +was applied as written. Two further ADRs were checked and left accepted: +[ADR-0005](0005-bound-instruction-surface-work-by-question-not-population.md) bounds +instruction-surface work by the question it asks, and this lane asks one question (is this +passage a dated prompting pattern for the target model), so it is consistent. +[ADR-0008](0008-admit-only-present-text-defects-to-the-instruction-audit-catalog.md) governs +what enters the `audit-instructions` catalog; this lane edits bodies and records catalog gaps +without adding rows, so it is consistent. Whether either should retire on other grounds is the +operator's call at PR time and is not decided here. + +## Decision + +**A skill-body audit against the current model runs as a fleet-wide sweep and applies its +high and medium confidence findings directly**, one commit per plugin, without an +incumbent-first gate and without scoping applied findings to the model that motivated them. + +The procedure is the bundled `prompt-audit` guide at the Claude Code version that ran it, +with the target model named at Step 0. Where the migration guide carries guidance for a prior +model and none for the target, the prior model's guidance applies; on conflict the target +model wins. + +Three rules travel with the decision: + +1. **Labels are recorded, not gated.** Every finding carries `fleet` or `fable-5-1`. Both are + applied. The label exists so a consumer on another model can read what changed and why; + it does not decide whether the change ships. The promotion gate of ADR-0006 continues to + govern the `playbooks` model-adaptation chapters and the `audit-instructions` catalog's + `Model scope` rows, which are doctrine surfaces. It does not govern edits to skill bodies + that remove a pattern the target model no longer needs. +2. **Repo conventions yield to the procedure inside the lane.** A CI gate or a static check + that blocks a warranted change is changed in the same commit, and the change is recorded in + the run's record. The first instance is `skill-quality`'s check 3, which hard-failed any + dropped trigger phrase and so blocked the guide's Group 2 fix for trigger-case + enumeration; it is now advisory. +3. **Skill bodies state current rules.** The path-scoped rule + `.claude/rules/skill-bodies-state-current-rules.md` codifies the guide's Group 2 for + `plugins/*/skills/**` and `plugins/*/agents/**`: a body carries the rule and its reason + in the present tense, and history belongs in the CHANGELOG, the commit, and `docs/adr/`. + +Mechanism changes the audit exposes (extracting a hand-executed shell block into a script, +adding a pre-compute block, parameterizing a hardcoded vendor) are follow-ups, not audit +hunks. The record inventories them and the PR body carries them verbatim. + +## Consequences + +**Bodies change fleet-wide in one PR, and the diff is large.** The record is the reviewable +unit: each plugin's row names its commit, its applied and withheld finding ids, and the +trigger phrases it deliberately dropped. A reviewer who wants the archaeology reads the +report the record points at; the body no longer carries it. + +**The incumbent-first gate loses its blanket status.** ADR-0004 D-1 still binds lanes that +propose new machinery, where a duplicate is the risk. It no longer binds text-defect lanes +whose remediation is a prescribed hunk. The cost is that a future sweep can apply a hunk an +existing check would have caught differently; the record's catalog-gaps section is where that +shows up, and the `audit-instructions` catalog is extended from it under ADR-0008's +admission rule. + +**Fable 5.1-specific edits are live on every model.** A consumer running an older model reads +bodies tuned for the current one. The label in the record says which edits those are, and the +`playbooks` adaptation chapters remain the place to counter-steer per model. This is the +trade the operator chose over leaving the target model under-served. + +**Trigger phrases can be dropped on purpose.** Check 3 warns instead of failing, so a +description that consolidates near-synonyms into an intent category ships with the warning +recorded. A reviewer confirms the intent is still named or restores the phrase; the check no +longer decides. + +**The audit repeats per model change.** The playbooks' own regeneration trigger fired with +Fable 5.1 (record follow-up F14). Each future target model re-runs this lane from the +record's method section, with the previous run's withheld items as the first candidates. diff --git a/docs/conventions/topic-docs/CHANGELOG.md b/docs/conventions/topic-docs/CHANGELOG.md index 55ad1a920a..9efcca56eb 100644 --- a/docs/conventions/topic-docs/CHANGELOG.md +++ b/docs/conventions/topic-docs/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog — topic-docs convention +## 3.1.0 — 2026-09-02 + +Minor under the Versioning rule: no tier moves, no `topic-docs.yaml` key is renamed, the slug +spec is untouched, and no visibility guarantee an implementer may rely on changes. The contract +already forbade any skill, gate, or audit from assuming the `worktree.baseRef: "head"` override +was in force, so withdrawing it changes the matrix's shape, not what a context may rely on +seeing. + +- **The `worktree.baseRef: "head"` mechanism is withdrawn.** This repository no longer sets it + in `.claude/settings.json`, and the convention no longer asks consuming repositories to. A + worktree Claude Code creates branches from the repository's default branch on the remote, + which is Claude Code's default, `"fresh"`, per the official worktrees page fetched + 2026-09-02. The native mechanisms are now three: `.worktreeinclude`, by-value worker returns, + and the tracker as the cross-lane index. +- **Visibility matrix**: the "spawned from local HEAD" row is gone. The remaining worktree row + describes the default base, with the memory column still conditional on a `.worktreeinclude`, + and the consequences paragraph now says a contract document reaches a spawned worktree only + once merged to the default branch. +- **Consumer adoption** materializes one file, `.worktreeinclude`. The committed-settings + snippet and its untracked-settings pull-collision rollout caveat are removed with it. + ## 3.0.0 — 2026-09-01 Major under the Versioning rule: the memory tier's slice shape, the reserved-name set, and the diff --git a/docs/conventions/topic-docs/README.md b/docs/conventions/topic-docs/README.md index 948023f6f4..7fbd3d1d2f 100644 --- a/docs/conventions/topic-docs/README.md +++ b/docs/conventions/topic-docs/README.md @@ -379,39 +379,36 @@ Versioning). ### Context × tier visibility matrix -The worktree rows assume the consuming repo materializes both native -mechanisms below (`worktree.baseRef: "head"` and `.worktreeinclude`); -without them, every spawned worktree behaves as the default-base row. +The worktree row describes a worktree Claude Code creates with its +default base. A `--worktree` session and every subagent worktree branch +from the repository's default branch on the remote: the official +worktrees page (fetched 2026-09-02) documents the default, `"fresh"`, +as branching from the repository's default branch on the remote, +usually `main`, so the worktree starts from a clean tree matching the +remote. Only when no remote is configured, or `origin/HEAD` is neither +cached nor fetchable, does the worktree fall back to the local `HEAD`. +The memory column assumes the consuming repo carries a +`.worktreeinclude`; without one, the memory tier is plain invisible +there. | Context | Memory `//` | Contract `//` (branch tier) | Durable (vault backend) | Machine state (`${CLAUDE_PLUGIN_DATA}`) | |---|---|---|---|---| | Writing checkout (same session or another session in it) | visible | visible, including uncommitted edits | visible | visible | -| Worktree spawned from local HEAD (`worktree.baseRef: "head"`) | invisible, except `.worktreeinclude`-carried patterns (one-way copy at creation time) | committed state visible; uncommitted edits invisible | visible | visible (machine-global) | -| Worktree spawned from the default base (`origin/HEAD`) | invisible, except `.worktreeinclude`-carried patterns | invisible — task-branch commits absent | merged state only | visible | +| Worktree spawned by Claude Code (default base, the remote default branch) | invisible, except `.worktreeinclude`-carried patterns (one-way copy at creation time) | invisible; task-branch commits are absent | merged state only | visible | | Sibling lane (worktree on another branch) | invisible | invisible | merged state only | visible | | Cloud clone / CI checkout | invisible | pushed commits only | pushed state only | invisible | Two consequences drive the rules below: a contract document is visible -to an isolated context only as **committed** state (commit plan updates -with their phase — the lifecycle already requires this), and a memory +to an isolated context only as **committed** state, and to a spawned +worktree only once merged to the default branch (commit plan updates +with their phase; the lifecycle already requires this), and a memory document is visible **only in the checkout that wrote it** unless a `.worktreeinclude` pattern carries it. ### Native mechanisms -Four native mechanisms, no custom machinery: - -- **`worktree.baseRef: "head"`** — committed project - `.claude/settings.json`. Spawned worktrees (including subagent - worktrees) branch from local `HEAD` instead of `origin/HEAD`, so they - carry the task branch's contract commits. Verified honored at - project-settings scope on CC 2.1.212, including from linked worktrees - (a linked-worktree session reads its *own* checkout's - `.claude/settings.json`, and `"head"` resolves to that worktree's - `HEAD`). Escape hatch: a personal `.claude/settings.local.json` - (resolved to the main checkout, covering every worktree) silently - overrides this machine-wide — no skill, gate, or audit may assume the - setting is universally in force. +Three native mechanisms, no custom machinery: + - **`.worktreeinclude`** — repository root, `.gitignore` syntax; only files that match a pattern *and* are gitignored are copied. The copy is **one-way at worktree-creation time**: later edits sync in neither @@ -450,21 +447,10 @@ the memory-slice path of the raw capture. ### Consumer adoption -Repository settings and root files never travel with -marketplace-installed plugins (plugins run from an isolated cache), so -each consuming repository materializes the two files itself: - -```json -{ - "worktree": { - "baseRef": "head" - } -} -``` - -as committed `.claude/settings.json`, and a `.worktreeinclude` at the -repository root (substitute a non-default resolved `memory_dir` for -`.work`): +Repository root files never travel with marketplace-installed plugins +(plugins run from an isolated cache), so each consuming repository +materializes `.worktreeinclude` itself at the repository root +(substitute a non-default resolved `memory_dir` for `.work`): ```text .work/.gitignore @@ -507,14 +493,11 @@ snapshots themselves match no reserved-name pattern and are never carried, deliberately). Also gitignore `.claude/worktrees/` so worktree contents never appear -as untracked files. Rollout caveats: pulling a commit that adds -`.claude/settings.json` into a clone already holding an untracked file -at that path fails with "untracked working tree file would be -overwritten" — move the local file aside, pull, then merge its values -back; on Windows, deep repository base paths can trip git's path limit -inside nested worktrees (`'$GIT_DIR' too big`) — keep the repository -base path short. Routing this materialization through a setup-skill -apply action is a recorded follow-on, not built today. +as untracked files. Rollout caveat: on Windows, deep repository base +paths can trip git's path limit inside nested worktrees +(`'$GIT_DIR' too big`), so keep the repository base path short. Routing +this materialization through a setup-skill apply action is a recorded +follow-on, not built today. ## The tracked concern file — `.claude/topic-docs.yaml` diff --git a/docs/specs/prompt-audit-skills-2026-09.md b/docs/specs/prompt-audit-skills-2026-09.md new file mode 100644 index 0000000000..9eaf40375b --- /dev/null +++ b/docs/specs/prompt-audit-skills-2026-09.md @@ -0,0 +1,652 @@ +# prompt-audit over every skill, 2026-09 + +Record of running the bundled `/claude-api prompt-audit` (Claude Code 2.1.258) over every skill in this marketplace against Claude Fable 5.1. Written so the unapplied remainder is resumable without re-auditing, so the catalog gaps it exposed are filed, and so the follow-ups ship in the same PR. + +## Decay rule + +Point-in-time, stamped 2026-09-02. The check is the quoted text, never the status and never the line number. If a finding's quoted source text is still present at or near the cited path, the finding is open. A quote that matches nothing has been applied, superseded, or moved. + +## Contents + +- [Stated assumptions](#stated-assumptions) +- [Corpus](#corpus) +- [Method](#method) +- [Results by wave](#results-by-wave) +- [Behavioral spot-check](#behavioral-spot-check) +- [Catalog gaps](#catalog-gaps) +- [Withheld findings](#withheld-findings) +- [Brief](#brief) +- [Follow-ups](#follow-ups) + +## Stated assumptions + +Per prompt-audit Step 0, established from the request and the repository, not by asking. + +- **Scope.** Every markdown file under `plugins/*/skills/` excluding `vendor/` and `evals/`, plus `plugins/*/agents/*.md`. Descriptions and trigger text are in scope under the guide's trigger-versus-behavior split. +- **Target model.** Claude Fable 5.1, named by the operator and the newest model the repository's own docs point at. Where the migration guide carries Opus 5 guidance with no Fable 5.1 counterpart, Opus 5 guidance applies; on conflict Fable 5.1 wins. +- **Labels.** Each finding is labeled `fleet` (reason documented model-agnostically or convergent across current model guides) or `fable-5-1` (reason specific to Claude Fable 5.1). Both are applied at high and medium confidence. +- **Repo conventions are not binding.** ADRs, CI gates, and `check-skill.sh` were updated or removed where they blocked a warranted change; a superseding ADR lists each accepted decision this audit contradicted. + +## Corpus + +Fresh `origin/main` at e69547e3e (2026-09-02). + +| Measure | Count | +|---|---| +| Plugins | 74 | +| Skills (SKILL.md, excluding vendor and eval fixtures) | 241 | +| Skill-owned markdown files in scope | 798 | +| Lines in scope | ~115,000 | +| Agent definitions | 13 | + +Greppable signals before the audit: 308 caps-emphasis words (`MUST|NEVER|ALWAYS|CRITICAL|IMPORTANT`), 245 numbered-step headers, 210 bare prohibition bullets, 162 migration-relative phrasings, 285 tracker references, 475 dated stamps, 103 Claude Code version pins, 7 retired-model mentions, 2 numeric output caps, 1 narration suppressor, 0 think-step-by-step scaffolds. + +## Method + +One fresh-context subagent per plugin (Claude Fable 5.1 through wave 3b; Claude Opus 5 with the same briefs from wave 3b onward, once the Fable model limit began refusing subagent turns, the target model unchanged) reads the prompt-audit guide and the Fable 5.1 migration sections, audits every in-scope file of that plugin, and writes a report with one row per finding (`file:line`, quoted evidence, pattern row, why obsolete for the target, confidence, action, label, catalog row) and one proposed hunk per finding. The main session reviews each report and records a per-finding decision, then either applies the accepted hunks itself (the lead applied every plugin with about fourteen or fewer accepted hunks by hand from wave 3b onward, thirty-one plugins in all) or dispatches an Opus 5 applier with the same brief (twelve plugins). Either way the applier updates the skill's evals when its body changed, runs `check-skill.sh` on each touched skill, bumps the plugin's patch version with a CHANGELOG line, and commits once per plugin. Eleven setup-only plugins whose single in-scope file the setup lane had already audited took their rows from that lane without a second auditor. + +Waves, ordered by usage, pipeline centrality, and signal density: + +| Wave | Plugins | +|---|---| +| 1 | session-flow, planning, source-control, implementation, plus every `setup` skill as one cross-cutting lane | +| 2 | work-items, review, discovery, verification, toolchain, testing, bugs, debugging, discipline | +| 3a | claude-config, claude-ops, claude-memory, playbooks | +| 3b | skill-quality, plugin-quality, autonomy, instruction-placement, context-budget, context-guard, rate-limit-guard, guardrails, computer-use, overengineering, improvement | +| 4a | docs-hygiene, code-tidying, repo-hygiene, repo-fleet-hygiene, disk-hygiene, codebase-health, ai-slop, provenance | +| 4b | tdd, mutation-testing, event-storming, architecture, coupling, naming, domain-driven-design, mcp-tools, evals, performance, prototype, visualization, wizard, machine-health | +| 5 | knowledge, songwriting, education, adhd, ai-briefing, kindle-dedrm, context7, firecrawl, x, dometrain, miro, playwright, github, playgrounds, desktop-notification, eol-normalizer, actionlint, bash-format, biome-format, go-format, markdown-format, powershell-format, ruff-format, typos-format | + +## Fleet decisions + +Calls made once so that per-plugin auditors' identical findings are treated the same way everywhere. + +- **Gather-block wording.** The "Repository context. Gather first" block that replaced git pre-compute lines in about 55 skills carries the sentence "Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git." That is the fleet standard. The issue number and "do not fold them back" it replaced were archaeology; the remaining contrast is structural, not a version diff, and is not rewritten per plugin. +- **"The pipe is the bound" sentence.** Kept fleet-wide in its one-sentence form. It stops a read-time cap from replacing the pipe, which is a live constraint, not harness trivia. +- **Third-party "think before code" priming.** Every presence-gated invocation of `andrej-karpathy-skills:karpathy-guidelines` (debugging, implementation, planning) is removed, not kept: its first primed rule is the plan-before-acting scaffold prompt-audit Group 1b deletes, and the plugin exists in no installed marketplace. The surviving scope rules (simplest change, surgical edits) stay as one plain sentence. +- **Phantom `dotnet-*` and `cloudflare` references.** Every forward reference to `dotnet-diag:*`, `dotnet-msbuild:*`, `dotnet-test:*`, `dotnet-data:*`, and `cloudflare:web-perf` is removed (toolchain, implementation, testing, verification). No installed marketplace carries them and the toolchain plugin's own text called the family "planned". +- **Descriptions.** Near-synonym trigger lists become intent categories with a few exact phrases kept; `check-skill.sh` check 3 is advisory (follow-up F5) and the dropped phrases are recorded per plugin below. + +## Cross-cutting commits + +Landed on the branch before or alongside the waves, each its own commit: + +| Commit | What | +|---|---| +| a4450c48c | Removed the `worktree.baseRef: head` override from `.claude/settings.json` and its rationale from the topic-docs convention (operator request during the audit). | +| 973da374a | Scaffold: this record, the topic Brief, the `skill-bodies-state-current-rules` rule, the regenerated rules index. | +| ce8e6b58a | Moved git pre-compute out of the composed substitution block in 50 skills across 22 plugins, so worktree-isolated sessions can load them; each plugin patch-bumped; one docs-hygiene test re-anchored to the new bullet shape. Prompted by the interview skill failing to load in this worktree. | +| a694011bf | `skill-quality` check 3 (trigger-phrase preservation versus the base ref) made advisory: a dropped phrase warns naming it instead of failing the run (follow-up F5); tests retargeted; 0.20.10. | + +## Results by wave + +One row per applied plugin. "Applied" and "Withheld" name finding ids from `.work/prompt-audit-skills/reports/.md`; setup-lane items carry their `T` and `setup-F` ids. Withheld ids are listed in [Withheld findings](#withheld-findings). The check-3 phrases each plugin deliberately dropped are listed after the table, computed by `check-skill.sh` with `CHECK_SKILL_BASE_REF=origin/main`. Where `origin/main` claimed a version the branch had used, the Version cell names the final number and the one the plugin commit carried; the renumber landed in one commit before the PR (`scripts/check-changelog-parity.sh --check-bump origin/main` names collisions, and `.work/prompt-audit-skills/changelog-collisions.py` also catches the branch's earlier headings that a later main entry overtook). Every branch CHANGELOG carries only the branch's own entries above the fork point until the merge. + + +| Wave | Plugin | Commit | Version | Applied | Withheld | +|---|---|---|---|---|---| +| 1 | session-flow | 221e8bdec, renumbered in 498dd4812 | 0.35.2 (renumbered from 0.34.22 before the PR, above main's 0.35.1) | F1 to F25 (one `apply-modified`) | F26 to F36 | +| 1 | source-control | 01268af79 | 0.55.53 (renumbered from 0.55.40 before the PR, above main's 0.55.52) | F1 to F71, setup-lane T2 | F72 to F81 | +| 2 | work-items | 7c5078774 | 0.39.63 (renumbered from 0.39.52 before the PR, above main's 0.39.62) | F1 to F16, setup-lane T1 sites 6 to 11, T2, T4 site 4, setup-F2, setup-F3 | F17 to F23 | +| 3a | claude-memory | d8452ead8 | 0.11.16 (renumbered from 0.11.15 before the PR, above main's 0.11.15) | F1 to F11 (one `apply-modified`) | F12 | +| 1 | planning | 66314fd1c | 0.36.4 (renumbered from 0.35.5 before the PR, above main's 0.36.2; the branch's earlier 0.35.4 entry became 0.36.3) | F1 to F29 (F1 to F7 already landed in ce8e6b58a; F35 `apply-modified`), L1 | F30 to F34, F36 | +| 1 | implementation | 12b3180de | 0.16.3 (renumbered from 0.16.2 before the PR, above main's 0.16.1; the branch's earlier 0.16.1 entry became 0.16.2) | F1 to F14 (F1 already in place), L1 | F15 to F20 | +| 2 | toolchain | b0367f42f | 0.13.13 | F1 to F12 | F13 to F18 | +| 2 | review | 64cc882d8 | 0.26.19 (renumbered from 0.26.17 before the PR, above main's 0.26.17; the branch's earlier 0.26.16 entry became 0.26.18) | F1 to F15, setup-lane T2 | F16 to F21 | +| 2 | verification | d057a497b | 0.6.4 | F1 to F5, F7, F10 (as L1), L1, setup-lane F7 | F6 (superseded by L1), F8, F9 | +| 2 | debugging | e6ffe3293 | 0.7.4 | F1, F2, F5 to F12, F14 | F3, F4, F13 | +| 2 | bugs | 0cef022b1 | 0.9.10 (renumbered from 0.9.9 before the PR, above main's 0.9.8; the branch's earlier 0.9.7 entry became 0.9.9) | F1 to F8, F10 to F13 (F13 `apply-modified`) | F9, F14 to F17 | +| 2 | testing | e502b6d3c | 0.7.16 (renumbered from 0.7.14 before the PR, above main's 0.7.14; the branch's earlier 0.7.13 entry became 0.7.15) | F1 to F4, F9 to F24, F27 (`apply-modified`) | F5 to F8, F25, F26, F28 | +| 2 | discipline | 0bb0e9c1f | 0.13.3 (renumbered from 0.13.2 before the PR, above main's 0.13.2) | F1 to F11, setup-lane T1 and T2 (F5, part of F2, F1's `batched-pass.md:76` clause, and T1's `point-dont-copy:49` clause subsumed by neighbouring hunks) | F12 to F15 | +| 3a | playbooks | d7b8900f7 | 0.9.7 | F1 to F12 (F1 `apply-modified`: new `reference/model-adaptation/fable-5-1.md` re-verified against the live Fable 5.1 prompting page on 2026-09-03, two claims attributed to the bundled migration reference instead; fable-5 eval case 4 added) | F13 to F16 | +| 3a | claude-ops | 371004078 | 0.42.9 (renumbered from 0.41.12 before the PR, above main's 0.42.7; the branch's earlier 0.41.6 entry became 0.42.8) | F1 to F25 | F26 to F38 | +| 4b | tdd | a643f73b1 | 0.4.7 | F1 (applied by the lead) | none | +| 4b | domain-driven-design | 53bbeaa37 | 0.3.2 | F1 to F3 (applied by the lead; F1 also corrects the README's install note) | F4 | +| 4b | coupling | 3822d48e7 | 0.1.6 | F1, F2 (applied by the lead) | F3 (fleet gather-block wording), F4 | +| 3a | claude-config | cc5d76494 | 0.40.35 (renumbered from 0.40.31 before the PR, above main's 0.40.34) | F1 to F29 (F9 stamps dated 2026-09-04 against the bundled migration reference; F10 hunk 14 keeps the closing sentence its replacement omitted; setup eval 2 reworded) | F30 to F33 | +| 3b | rate-limit-guard | 0763a8c81 | 0.7.34 (renumbered from 0.7.26 before the PR, above main's 0.7.33) | F1 (in the synced context-guard source copy), F2, F3, F6, setup-lane T2, T3, T7 (the two synced reference files edited at their registered context-guard source and synced; context-guard's own bump follows in its commit) | F4, F5 | +| 3b | context-guard | de35c27ad | 0.7.43 (renumbered from 0.7.32 before the PR, above main's 0.7.42) | F1, F2, F4 to F14 (F7 `apply-modified`; F3 and the synced-file setup-lane hunks landed in 0763a8c81), setup-lane T2, T3, T7, F19 (F11 re-synced both rate-limit-guard copies) | F15 to F17 | +| 3b | guardrails | 0b080653a | 0.32.4 (renumbered from 0.31.3 before the PR, above main's 0.32.3) | F1, setup-lane T2, T4 site 2 | none | +| 2 | discovery | b15ecc2cf | 0.19.5 (renumbered from 0.19.4 before the PR, above main's 0.19.3; the branch's earlier 0.19.3 entry became 0.19.4) | F1 to F23, L1, setup-lane F7 and F8 (F8 applied without the version stamp: the sub-agents reference confirms three of the four windows, so setup-lane F20 stays open under F6) | F24 to F26 | +| 3b | skill-quality | dce79fff5 | 0.20.15 (renumbered from 0.20.14 before the PR, above main's 0.20.13; the branch's earlier 0.20.10 entry became 0.20.14) | F1 to F7 | F8, F9 | +| 4b | naming | 9d55edd90 | 0.5.4 | F1 to F5 (applied by the lead) | F6 | +| 4b | evals | 64af28cc1 | 0.2.1 | F1 to F3 (applied by the lead; design eval case 7 asserts the conditional reasoning-then-discard form) | F4 | +| 4b | mcp-tools | 4d957d6bc | 0.3.3 | F1 to F5 (applied by the lead) | F6 | +| 4b | prototype | be7060bd6 | 0.10.5 (renumbered from 0.10.4 before the PR, above main's 0.10.3; the branch's earlier 0.10.2 entry became 0.10.4) | F1 to F7 (applied by the lead; `scripts/allowed-tools-pairing.test.sh` passes) | F8 | +| 3b | autonomy | eab25fd78 | 0.22.27 (renumbered from 0.22.25 before the PR, above main's 0.22.26) | F1 to F22, setup-lane T1 sites 12 and 13, T7, F13 to F18 (F15 adds `plugins/autonomy/AGENTS.md` and `CLAUDE.md`; a prior applier's partial edits were reconciled on disk before the commit) | F23 to F29 | +| 3b | plugin-quality | 3d2b4c794, caa46c4d3 | 0.7.9 (above main's 0.7.8; the branch CHANGELOG lacks main's 0.7.7 and 0.7.8 entries until the merge) | F1 to F7, F9 to F18, setup-lane T2, F5, F6 (audit eval case 1 and the setup eval `retirement-r002-overlay-warns-never-silent` reworded; the second commit removes one merged-into-skills aside the first left in the reference index) | F8 (follow-up F19), F19 to F22 | +| 3b | context-budget | 75db56cea | 0.6.23 (renumbered from 0.6.22 before the PR, above main's 0.6.22) | F1 to F3 (applied by the lead) | F4 to F9 | +| 3b | instruction-placement | d73d824a2 | 0.11.27 (renumbered from 0.11.24 before the PR, above main's 0.11.26) | F1 to F6 (applied by the lead; delta eval case 1 renamed `quiet-run-is-short-and-complete`; the manifest description still says setup verifies "the one thing no other gate can see", out of audit scope, follow-up F2) | F7, F8 | +| 4a | repo-hygiene | 77074974e | 0.10.32 (renumbered from 0.10.31 before the PR, above main's 0.10.30; the branch's earlier 0.10.27 entry became 0.10.31) | F1 to F8 (applied by the lead; `scripts/allowed-tools-pairing.test.sh` and `scripts/lib/cleanup-paths.test.sh` pass) | F9 | +| 3b | improvement | 9f090fb7f | 0.1.9 (renumbered from 0.1.8 before the PR, above main's 0.1.7; the branch's earlier 0.1.7 entry became 0.1.8) | F1 to F8 (applied by the lead) | F9 to F11 | +| 3b | computer-use | 50e9b4733 | 0.1.4 (above main's 0.1.3) | F1 to F9 (applied by the lead; F1 supersedes setup-lane F21; setup eval case 3 reworded) | F10 to F13 | +| 3b | overengineering | 3ee952f2b | 0.3.8 (renumbered from 0.3.7 before the PR, above main's 0.3.6; the branch's earlier 0.3.6 entry became 0.3.7) | F1 to F9 (applied by the lead; F4 `apply-modified` as eval edits to audit cases 10 and 11 and realign case 7; realign case 8 reworded under F6) | F10 to F12 | +| 4b | visualization | cf7c71a51 | 0.5.1 (above main's 0.5.0; the branch CHANGELOG lacks main's 0.5.0 entry until the merge) | F1 to F3 (audited and applied by the lead on 2026-09-05 after the wave-4b auditor died at the session restart) | none | +| 4a | codebase-health | 419decd94 | 0.8.9 (above main's 0.8.7 and the branch's 0.8.8) | F1 to F10 (applied by the lead; F8 supersedes the setup lane's clean verdict on `setup/SKILL.md`) | F11 | +| 4b | mutation-testing | 94e7c256a | 0.3.15 (above main's 0.3.13 and the branch's 0.3.14) | F1 to F10 (applied by the lead) | F11 (follow-up F21) | +| 4a | ai-slop | 820f59b57 | 0.5.11 (renumbered from 0.5.10 before the PR, above main's 0.5.9; the branch's earlier 0.5.8 entry became 0.5.10) | F1 to F11 (applied by the lead; F6 as a move into audit step 6) | F12 | +| 4b | architecture | 249274f96 | 0.6.10 (renumbered from 0.6.9 before the PR, above main's 0.6.8; the branch's earlier 0.6.8 entry became 0.6.9) | F1 to F12 (applied by the lead; F12 as a move into a sixth diagram pattern) | F13, F14 | +| 4a | repo-fleet-hygiene | 946fa0cac | 0.23.18 (above main's 0.23.17; the branch CHANGELOG lacks main's 0.23.16 and 0.23.17 entries until the merge) | F1 to F12, setup-lane F1 and F4 (applied by the lead; audit eval case 14 retargeted to the shipped apply consumer) | F13 to F15 | +| 4a | provenance | d5a24e57b | 0.5.6 (renumbered from 0.5.5 before the PR, above main's 0.5.4; the branch's earlier 0.5.2 entry became 0.5.5) | F1 to F13 (applied by the lead; F1 and F11 create `plugins/provenance/skills/audit/AGENTS.md`, indexed in the root `AGENTS.md` in the same commit; setup-lane T1 site 4 was already applied on the branch) | F14 (follow-up F20), F15 | +| 4a | disk-hygiene | fab3fe5f3 | 0.21.8 (renumbered from 0.21.7 before the PR, above main's 0.21.7) | F1 to F14, setup-lane T1 sites 2 and 3 (applied by the lead) | F15 (follow-up F6), F16 | +| 4b | wizard | none | unchanged | clean (one skill; the auditor verified every `template.sh` claim against the current file) | F1, F2 | +| 5 | actionlint | bba869139 | 0.8.36 (renumbered from 0.8.35 before the PR, above main's 0.8.35) | setup-lane F10 (applied by the lead; the plugin's only in-scope file is `skills/setup/SKILL.md`, audited in full by the setup lane) | setup-lane F25, T9 | +| 5 | bash-format | none | unchanged | clean (only in-scope file is `skills/setup/SKILL.md`, audited in full by the setup lane) | setup-lane T8 | +| 5 | miro | none | unchanged | clean (only in-scope file is `skills/setup/SKILL.md`, audited in full by the setup lane) | setup-lane F22 | +| 5 | biome-format, desktop-notification, eol-normalizer, go-format, markdown-format, powershell-format, ruff-format, typos-format | none | unchanged | clean (each plugin's only in-scope file is `skills/setup/SKILL.md`, listed under the setup lane's clean files) | none | +| 4b | performance | 7bc6ba2ba | 0.1.2 (above main's 0.1.1; the branch CHANGELOG lacks main's 0.1.1 entry until the merge) | F1 to F20 (Opus applier; target eval case 3 and verify eval cases 2, 3, and 7 reworded from run narration to mechanism; every instructive figure kept) | F21 (follow-up F6) | +| 4a | code-tidying | e90a5374a | 0.16.2 (renumbered from 0.15.7 before the PR, above main's 0.16.0; the branch's earlier 0.15.3 entry became 0.16.1) | F1 to F22, setup-lane T1 site 1 (Opus applier; F13 `apply-modified` at sites 5 and 6, the CodeScene figure left unrestated under follow-up F6; F12's stamp inherited from the discipline and claude-ops surfaces that carry the same 2026-08-10 basis) | F23 | +| 4b | machine-health | 68309e1ef | 0.12.13 (above main's 0.12.12; the branch CHANGELOG lacks main's 0.12.7 to 0.12.12 entries until the merge) | F1 to F13, setup-lane T2 and F9 (applied by the lead; F4 `apply-modified` keeps the PATH-entry sentence; F8's promotion sentence reworded to "dropping its (future) marker") | F14 to F16 | +| 4b | event-storming | 9128e0e36 | 0.6.8 (above main's 0.6.7) | F1 to F23 (Opus applier; F7 and F13 resolved as prose inside existing files, so the mechanism-change escape did not fire; one F15 replacement word changed to the spelling the typos gate accepts) | none | +| 4a | docs-hygiene | d86a59eed | 0.21.37 (renumbered from 0.21.36 before the PR, above main's 0.21.35; the branch's earlier 0.21.33 entry became 0.21.36) | F1 to F20, F22 to F25 (Opus applier; audit-noise eval case 12 and extract-ssot eval case 9 reworded; F1 also corrects the `emit-findings.sh` header comment) | F21, F26, F27 | +| 5 | education | d5931a6ce | 0.10.4 (above main's 0.10.3; the branch CHANGELOG lacks main's 0.10.3 entry until the merge) | F1 to F9 (applied by the lead; setup eval `validates-rendered-quiz-policy-without-settings-edits` names the workspace root) | F10 (follow-up F6) | +| 5 | playwright | 291127ed4 | 0.6.9 (above main's 0.6.8) | F1 to F5 (applied by the lead; F2 keeps 'playwright' and 'E2E test' quoted; F3 keeps the socket-error recovery on the `kill-all` line in `reference/sessions.md`) | F6, F7 (follow-up F6) | +| 5 | kindle-dedrm | 5eee64b9e | 0.7.15 (above main's 0.7.14; the branch CHANGELOG lacks main's 0.7.12 to 0.7.14 entries until the merge) | F1 to F9 (applied by the lead; F8 keeps 'set up Kindle DRM removal' and 'convert Kindle books to EPUB' quoted; the superseded paywall wording in `scripts/check-drift.sh` comments is outside the audit, follow-up F2) | F10, F11 | +| 5 | knowledge | b80ad5588 | 0.13.45 (above main's 0.13.44; the branch CHANGELOG lacks main's 0.13.38 to 0.13.44 entries until the merge) | F1 to F25 (Opus applier; F9 folded into F10's move, which adds `docpage-digest/context/anthropic-docs-queue.md`; F18 appends section 6 to the plugin-level `reference/ingest-deferred-decisions.md` as the move destination the finding names; F4 also drops the fail-open clause in `map-corpus/verification/inventory-format.md`; course-digest eval case 5 stack-neutral; three deletions forced small grammar repairs, listed in the applier report) | F26 (no replacement proposed), F27 (follow-up F6), F28 | +| 5 | songwriting | f39de8e2b | 1.4.23 (above main's 1.4.22; the branch CHANGELOG lacks main's 1.4.22 entry until the merge) | F1 to F10, F9b, setup-lane T4 site 3 with its eval (Opus applier; F4 as its twelve spoke hunks with no ledger note, F8 site 4 resolved by F9b, F9b as a delete because the CHANGELOG already carries the history; ledger row S21 added) | F11, F12 (follow-up F6) | +| 5 | context7 | b159dc98e | 0.5.4 (above main's 0.5.3) | F1 to F11 (applied by the lead; F1 also points `setup/SKILL.md:91` at `context/mcp.md`, superseding the setup lane's withheld F23 site; F5 and F6 keep two and three exact phrases) | F12 | +| 5 | firecrawl | 9a703216a | 0.5.9 (above main's 0.5.8; the branch CHANGELOG lacks main's 0.5.8 entry until the merge) | F1 to F7 (applied by the lead; F1 blanks the seeded sync record for `update.sh --apply` to repopulate; F5 also corrects the Actions list, F8's description half; update eval case 1 says "read-only mode") | F8, F9, F10 | +| 5 | x | 13c0cbcc4 | 0.2.3 (above main's 0.2.2) | F1 to F4, F7 (applied by the lead; F7 is a lead call outside the catalog, replacing a real account name in a shipped example with a placeholder; F4 keeps four exact phrases) | F5 (follow-up F6), F6 | +| 5 | ai-briefing | b07154b5c | 0.7.26 (above main's 0.7.25; the branch CHANGELOG lacks main's 0.7.21 to 0.7.25 entries until the merge) | F1 to F13 (Opus applier; F9 `apply-modified` keeps a version-free drift-trigger row; F6's Role cells filled from each script's header, one left empty where no header exists; F13 applied file-wide, two of its named sites already removed by F7 and F11) | F14 (follow-up F6), F15 | +| 5 | adhd | ccc3d2e04 | 0.4.7 (above main's 0.4.6) | F1, F3, F4 (applied by the lead) | F2 (declined: the five-item list cap is the style skill's own domain-grounded product spec, keep-list 1), F5 (follow-up F6), F6 | +| 5 | dometrain | b7a4413bf | 0.2.10 (above main's 0.2.9; the branch CHANGELOG lacks main's 0.2.9 entry until the merge) | F1 to F8, F12 (applied by the lead; F7 is the setup item the lane did not record; F12 as the same caps normalization) | F9, F10 (follow-up F23), F11 (follow-up F6) | +| 5 | github | 9116abf80 | 0.3.14 (above main's 0.3.13; the branch CHANGELOG lacks main's 0.3.12 and 0.3.13 entries until the merge) | F1 (applied by the lead; the `gh api` write-surface list in advise and audit now carries its verification date, gh version, and recheck trigger) | F2 (keep-list 6), F3 (follow-up F6) | +| 5 | playgrounds | fbf13a922 | 0.1.1 (above main's 0.1.0) | F1, F2 (applied by the lead; F1 keeps four exact phrases) | F3, F4 (follow-up F6) | + + +Notes on the wave-1 and wave-2 commits: + +- source-control: `babysit-prs/scripts/tests/test_skill_contract.py` asserts the replacement prose for F2, F23, F35, F36, and F38 instead of the removed markers; no behavior assertion changed. F26 edited `guard_contract.py` claim strings and regenerated `reference/guard-contract.md`. +- session-flow: `keep-going/context/continuation.md` retargets one pointer to the renamed section. The setup-lane items the wave-1 commits left open on paper (session-flow T4 site 1 and F11, source-control T2 at `setup/SKILL.md:119-121`) were checked on 2026-09-05 and are already applied; no second commit was needed. +- work-items: every gate green except `onboard-adapter/scripts/generate-adapter.test.sh` case 116, which fails on this host with unchanged files (follow-up F10). +- claude-memory: audit eval case 10 reworded to the new text. +- planning: `tests/interview-defenses.test.sh` refreshes four section digests the accepted edits changed (Stance, Step 4, the open-question register, the unattended path); every pinned defense line inside them still matches. Nine eval-case digest assertions in that suite fail on this host with `interview/evals/evals.json` unchanged (follow-up F10). `interview/SKILL.md:217` retargets one pointer to the handoff discipline after F19 emptied the flush section. L1 landed on the check flow's step 3 (the `vault_backend` wording), which is where planning carries it. + +### check-3 dropped phrases + +Each phrase below was a single-quoted trigger in the skill's description at `origin/main` and is absent after the rewrite. The description now names the intent category instead. + +- **session-flow** keep-going (9): 'are you stuck', 'carry on', 'continue', 'keep going', 'pick up where you left off', 'poke it', 'resume', 'we got interrupted', 'you got cut off'. +- **source-control** babysit-loop (8): '--merge c3-this-run', 'autopilot', 'babysit loop', 'babysit the PR queue continuously', 'drain the PR queue', 'keep merges flowing', 'run the babysit loop', 'stand up the merge lane'. babysit-prs (7): 'advance all open PRs', 'babysit PRs', 'babysit my PRs', 'babysit worker', 'keep my PRs moving', 'run the PR queue on autopilot', 'watch my open PRs'. setup (8): 'check babysit config', 'configure babysit', 'configure commit convention', 'override the team convention locally', 'set my personal commit convention', 'set up source-control', 'source-control setup', 'what commit format does this repo use'. +- **work-items** track (22): 'add a ticket', 'add a work item', 'add an issue', 'audit stale claims', 'audit work items', 'check overdue recurring items', 'claim a work item', 'close a ticket', 'close a work item', 'close an issue', 'list issues', 'list tickets', 'list work items', 'recheck a recurring item', 'search work items', 'start a ticket', 'start a work item', 'start an issue', 'what work items are open', 'whats due', 'work items dashboard', 'work-item stats'. work (11): 'auto-select a work item', 'do the next thing', 'grab the next ticket', 'grab the next work item', 'pick work', 'start on the backlog', 'what should I work on next', 'work an item', 'work the next issue', 'work the next item', 'work the next ticket'. decompose (15): 'break a plan into tickets', 'create issues from plan', 'decompose into tickets', 'decompose this PRD', 'decompose', 'publish the brief to the tracker', 'publish the spec as a container', 're-decompose', 're-slice', 'reroute the plan', 'spec container', 'split this plan into work items', 'the spec changed, redo the tickets' (the original joined the halves with an em dash), 'turn the plan into tickets', 'vertical-slice this plan'. ship (11): 'close out the container', 'container status', 'drive the spec', 'macro status', 'resume the multi-session effort', 'ship the container', 'ship this spec', 'spec journey', 'whats next in the container', 'where are we on the spec', 'work the spec container'. +- **claude-memory**: none. +- **implementation**, **toolchain**, **verification**, **discovery**, **guardrails**, **claude-ops**, **rate-limit-guard**, **context-guard**, **skill-quality**, **evals**, **mcp-tools**, **autonomy**, **context-budget**, **instruction-placement**, **improvement**, **computer-use**, **codebase-health**, **ai-slop**: none. +- **mutation-testing** audit (4): 'are my tests actually checking this', 'audit test quality', 'mutation score for this change', 'persist the surviving mutants for the fix pass'. principles (6): 'is mutation testing worth it', 'killed vs survived mutant', 'should we gate on mutation score', 'what is mutation testing', 'which mutation operators', 'why is my mutation score low'. +- **architecture** improve (2): 'architecture improvement', 'architecture scan'. +- **repo-fleet-hygiene** audit (6): 'audit repositories', 'cross-repo git cleanup report', 'merged remote branches', 'moved repos', 'renamed GitHub owner', 'repo fleet hygiene'. +- **provenance**, **disk-hygiene**, **actionlint**: none. The clean plugins (wizard and the setup-only wave-5 plugins) have no commit and dropped nothing. +- **performance** goal (2): 'how fast should this be', 'what is a realistic goal'. snapshot (4): 'benchmark this change', 'how noisy is this machine', 'is it actually faster', 'measure this before I change it'. target (2): 'pick a performance target', 'where is the time going' (the report also predicted 'what is slow here', which the description still carries as an unquoted intent and check 3 did not report). verify (3): 'check my benchmark numbers', 'did the optimization actually work', 'double-check before I claim this'. +- **code-tidying** batch-simplify (5): 'simplify everything under ', 'simplify everything', 'simplify just this folder', 'simplify my branch changes', 'simplify the whole repo'. +- **machine-health** audit (4): 'check my computer', 'health check', 'run health check', 'workstation audit'. +- **event-storming**, **docs-hygiene**: none. +- **education** eli5 (2): 'I need the visual version', 'draw me how this works'. +- **playwright** playwright (8): 'browser automation', 'check console errors', 'click element', 'fill form', 'mock network', 'record a video', 'take a screenshot', 'test the UI flow'. +- **kindle-dedrm** manage (6): 'check if DeDRM setup is current', 'clean up Kindle DRM tools', 'extract keys from my Kindle library', 'remove DRM from Kindle books', 'sync new Kindle books I bought', 'undo DeDRM setup'. +- **knowledge**, **songwriting**: none. +- **context7** lookup (4): 'check context7 for X', 'how do I configure X', 'latest docs for X', 'whats the API for X'. setup (4): 'add the Context7 MCP server', 'configure context7', 'context7 auth', 'context7 setup'. +- **firecrawl**: none (the description keeps all six quoted phrases and drops only their prose restatements). +- **x** read (3): 'I pasted an X link', 'read this tweet', 'what does this X post say'. +- **ai-briefing**, **adhd**, **dometrain**, **github**: none. +- **playgrounds** use (4): 'explore this parameter space', 'let me tweak parameters and see the result', 'sliders to balance this', 'tune this visually'. +- **plugin-quality** audit (4): 'find bugs/gaps in this plugin', 'find gaps in this plugin', 'is this hook well-designed', 'is this plugin well-designed'. +- **repo-hygiene** clean (9): 'clean caches across all repos', 'clean up my stashes', 'clear build artifacts across all my repos', 'clear build artifacts', 'fresh clone state', 'prune git across the fleet', 'remove caches', 'reset all my repos', 'reset to origin'. +- **overengineering** audit (6): 'enforcement clutter', 'process cruft', 'retire dead automation', 'too many guards', 'what automation can we retire', 'why does this check exist'. delta (4): 'delta since the last run', 'only show me what is new', 'recurring overengineering check', 'weekly automation-cruft check'. realign (5): 'act on the audit findings', 'execute the overengineering findings', 'peel back these hooks', 'retire the automation we agreed to retire', 'start the ablation window'. +- **visualization** visualize (11, against main's 0.5.0 description): 'diagram this', 'draw this', 'make a picture of this', 'render this as', 'show me a diagram of this', 'show me the shape of this', 'sketch this', 'turn this into a visual', 'visualize this', 'visualize', 'what is the best way to show this' (the word "visualize" stays in the description as an unquoted intent verb). +- **naming** name-it-better (3): 'better name', 'come up with a name', 'need a name for'. +- **prototype** explore-directions (5): 'explore design options', 'prototype this screen', 'show me options for this dashboard', 'try a different layout for the settings screen', 'try a few designs'. pressure-test (3): 'does this reducer handle the edge case', 'is this data shape right', 'prototype this logic'. +- **review** fanout (5): 'breadth review', 'fan out review', 'review from every angle', 'review this from all sides', 'run all reviewers'. +- **debugging** debug (4): 'intermittent failure', 'investigate this bug', 'performance regression', 'something is wrong with'. +- **tdd** principles (3): 'TDD cycle', 'what makes a good test', 'when to mock'. +- **claude-config** audit-instructions (4): 'after a model upgrade', 'contradictory instructions', 'instructions the model no longer needs', 'outdated harness claim'. audit-permission-state (4): 'what does auto mode drop', 'what scopes did you check', 'which settings file is my rule coming from', 'why is my allow rule ignored'. +- **playbooks** skill-authoring (7): 'skill authoring', 'skill categories', 'skill design', 'skill structure', 'skill tips', 'skill types', 'write a skill'. fable-5: check 3 reported one span of unquoted description prose between two apostrophes (a parser artifact of the removed Opus-routing clause), not a trigger phrase. +- **discipline** do-your-research (2): 'fact check this', 'fact-check'. do-your-research-deep (1): 'fact-check all these claims'. setup (4): 'configure re-anchor', 'is re-anchor configured', 're-anchor setup', 'set up re-anchor' (the plugin's former name; setup evals 1 to 3 now say "discipline setup"). +- **bugs** write (2): ' gives wrong output when ', 'bug-report this'. +- **testing** audit (8): 'are any of my tests vacuous', 'assertion-free tests', 'audit tests for tautologies', 'find tests that cannot fail', 'gate cant-fail tests in CI', 'persist test-audit findings for the fix pass', 'tautological tests', 'tests pass but prove nothing'. run-e2e (6): 'click through the UI', 'does the app actually work', 'e2e', 'run it end to end', 'smoke test', 'test the app'. write (4): 'add test coverage', 'where should this test go', 'write a unit test for this', 'write tests'. +- **planning** draft-goal-condition (8): '/goal or /loop', 'my /goal is too long / over the limit', 'set up an autonomous goal', 'should this be a routine', 'should this be a workflow', 'turn this into a completion condition', 'what kind of loop is this', 'write a goal condition'. devils-advocate (5): 'argue against this', 'challenge this plan', 'find the holes in this', 'is the incumbent still the right choice', 'reconsider the current approach'. + +## Behavioral spot-check + +Run 2026-09-05 over the five wave-1 skills the Brief names: session-flow `handoff`, `orchestrate`, and `keep-going`, source-control `commit`, and planning `interview`. For each skill, two blind fresh-context Opus 5 agents invoked the skill on the same fixture, one reading the body and its spokes at the fork point `e69547e3e` and one at the branch tip, neither aware of the other ref and neither allowed a side effect beyond writing its own output file. The fixtures, the agent brief, the ten outputs, and the lead's notes are under `.work/prompt-audit-skills/spot-check/` (gitignored). This is a sanity check on one fixture per skill, not a measurement; behavior measurement stays routed to `claude-config:unhobble` (follow-up F3). What the before-and-after pairs showed: + +- **handoff.** Same full-path save-point, same sections, same position panel and rails prompt; the branch-tip run dated every UNVERIFIED tag and used placeholders for the probes it had not run (session id, remote URL) where the fork-point run wrote this session's real values into a fixture worktree that does not exist. Response length grew by about eight percent. +- **orchestrate.** Same armed imperatives, same verbatim brief in rails, and both flagged 24 identical three-line edits as head-count decomposition; the branch-tip run doubled the response by expanding the per-worker spec into a full brief with a mismatch status, stating the verifier's four binary criteria, and listing the commands it must run before filling placeholders. The audit did not shorten this skill's output; it made the spawn spec explicit. +- **keep-going.** Same inventory, same refusal to kill the background task or re-dispatch the applier, same one-sentence goal alignment; the branch-tip run named the summarize-and-stall anti-pattern it was avoiding, reran the read-only test command when completion could not be proven instead of treating ambiguity as alive, and checked push state and for an existing PR before the PR step. Slightly shorter. +- **commit.** Same config probes, ladder resolution, staging preconditions, scoped formatter pass, exec-bit check, subject pre-check, and heredoc commit with the same two trailers; the branch-tip run said it in half the lines by tabulating probe results and per-path checks. No check dropped. +- **interview.** Same survey, slug, ledger-before-asking, recommendation-plus-alternatives shape, and closing probe; the fork-point run invented repository facts the fixture never stated (a mount file, a middleware path, a dependency, a test runner) and built recommendations on them, while the branch-tip run separated the three given facts under a resolved-not-asked heading, marked the one recommendation that depended on an unrun grep as conditional, asked five independent questions and deferred the four dependent ones to round two, and named the gate script it deliberately did not run yet. Longer, because it said what it did not know. + +Across the five, no skill lost a step, a gate, or a safety refusal. The direction of change is toward fewer fabricated specifics and more explicit statements of what was and was not verified, with length moving either way. + +## Catalog gaps + +Findings whose pattern has no row in `plugins/claude-config/skills/audit-instructions/reference/criteria.md`, or that the auditor filed under a row it does not quite match. One line per finding, generated from the reports and decisions by `.work/prompt-audit-skills/gen-record-sections.py`; "withheld" marks the ones that were not applied. Each shape below is a candidate row for the criteria file (follow-up F24). + +- **adhd** F2 (`plugins/adhd/skills/shape/SKILL.md:129-136` and `plugins/adhd/skills/clarify/SKILL.md:227`, withheld): Group 1f, "Output-shaping choreography - one pattern, remove every limb": numeric. +- **adhd** F4 (`plugins/adhd/skills/clarify/SKILL.md:150-151`): Group 2, "History narratives: past tense ... past-tense narration of why a rule". +- **ai-slop** F3 (`plugins/ai-slop/skills/audit/reference/rewrite-guide.md:61-62`): Group 2, "The recency trap: one session's stumble encoded as a permanent rule", and. +- **ai-slop** F7 (`plugins/ai-slop/skills/audit/SKILL.md:87-88`): Group 1d, "Migration-relative phrasing: 'X now works differently', 'also counts'". +- **ai-slop** F8 (`plugins/ai-slop/skills/audit/reference/rewrite-guide.md:71-72`): Group 1d, "Migration-relative phrasing". +- **ai-slop** F9 (`plugins/ai-slop/skills/audit/reference/catalog.md:126-127`): Group 1d, "Migration-relative phrasing". +- **ai-slop** F10 (`plugins/ai-slop/skills/audit/reference/catalog.md:140-141`): Group 1d, "Migration-relative phrasing". +- **architecture** F8 (`plugins/architecture/skills/improve/research/deepening/html-report.md:84`): Group 1f, "Output-shaping choreography: numeric output ceilings ('under 120 words'"). +- **autonomy** F26 (`plugins/autonomy/reference/trigger-dispatch.md:22-26`, withheld): Group 2, Time-sensitive content (vendor-state claims marked unverified, with a wire-time recheck trigger and no date). +- **autonomy** F27 (`Boris playbook attributions: plugins/autonomy/reference/guardrails.md:13-17; guardrails/work-classes.md:92-95; guardrails/security-review.md:35-37; runner.md:45`, withheld): Group 2, History narratives (provenance paragraphs that assign each idea to its source). +- **bugs** F15 (`plugins/bugs/skills/write/SKILL.md:118 and plugins/bugs/skills/write/context/template.md:43-44, :69-70`, withheld): Group 2, Volatile specifics (an external-API claim with no verification date). +- **claude-config** F15 (`plugins/claude-config/skills/audit-instructions/SKILL.md:2 (description)`): Group 2, Trigger-case enumeration (thirteen phrases, with near-synonym pairs: 'audit instructions' / 'instruction audit'). +- **claude-config** F16 (`plugins/claude-config/skills/audit-permission-state/SKILL.md:2 (description)`): Group 2, Trigger-case enumeration (near-synonym pairs: 'what permissions are actually in effect' / 'show me my effective permissions'). +- **claude-config** F33 (`Time-relative and machine-specific qualifiers`, withheld): Group 2, Time-sensitive content (idiom-dating only; the convention the first two cite owns the measured platform). +- **claude-ops** F37 (`plugins/claude-ops/skills/audit-install-state/reference/surfaces.md:3-4`, withheld): none in prompt-audit's tables (dated, so the Group 2 "no verification date" row does not match). +- **code-tidying** F6 (`plugins/code-tidying/skills/tidy/reference/exclusions.md:72 and plugins/code-tidying/skills/tidy/lanes/self-update.md:33`): Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims with". +- **code-tidying** F7 (`plugins/code-tidying/skills/tidy/lanes/self-update.md:5-15`): Group 2, "Volatile specifics: hardcoded paths ... skills rot factually as code ships". +- **code-tidying** F16 (`plugins/code-tidying/skills/tidy/SKILL.md:195`): Group 1d, "Migration-relative phrasing: 'X now works differently', 'also counts', 'no". +- **code-tidying** F17 (`plugins/code-tidying/skills/tidy/SKILL.md:82`): Group 1d, "Migration-relative phrasing"; the second sentence describes an in-progress. +- **code-tidying** F23 (`plugins/code-tidying/skills/tidy/SKILL.md:2`, withheld): Group 2, "Trigger-case enumeration": a candidate on shape, but not on provenance. +- **codebase-health** F1 (`plugins/codebase-health/skills/audit/SKILL.md`:232-233): Group 1f, output-shaping choreography (numeric output clamp with a stated operational). +- **computer-use** F11 (`plugins/computer-use/skills/diagnose/SKILL.md:62-63`, withheld): Group 2, Volatile specifics: dated and sourced, but with no recheck trigger, which the repo's four-part record (claim, basis, as-of date). +- **computer-use** F12 (`plugins/computer-use/skills/diagnose/reference/windows-quirks.md:5-6`, withheld): Group 2, Volatile specifics: a dated basis with no recheck trigger. +- **context-budget** F7 (`plugins/context-budget/skills/audit/scripts/fixtures/context-sample.md:3-4`, withheld): Group 2, Time-sensitive content (an as-of stamp with no date); outside the prompt surface (no skill body links the fixture). +- **coupling** F4 (`plugins/coupling/skills/reduce/ (4 files, 59 lines)`, withheld): none in prompt-audit.md. +- **debugging** F5 (`plugins/debugging/skills/debug/SKILL.md:6`): Group 1d, fossil (config that outlived the mechanism it served) and prompt-audit Step 6 "a removal is complete only when everything referencing it goes too". +- **debugging** F13 (`plugins/debugging/skills/debug/reference/ecosystem-debugging.md:11`, withheld): Group 2, volatile specifics (API claims with no verification date). +- **debugging** F14 (`plugins/debugging/skills/debug/reference/ecosystem-debugging.md:3-20 and plugins/debugging/skills/debug/templates/checklist.md:7-12`): none in prompt-audit; house-style item outside this audit's scope. +- **disk-hygiene** F16 (`plugins/disk-hygiene/skills/clean/reference/safety-model.md:303-306`, withheld): Group 2, History narratives (a pinned plugin version number), the same row F4 acts on. +- **docs-hygiene** F11 (`extract-ssot/actions/identify.md:403`): Group 1f, numeric output constraint; and Group 1c "Grader and eval vocabulary" in its pressure-toward-being-scored sense. +- **domain-driven-design** F4 (`plugins/domain-driven-design/skills/curate-language/SKILL.md:8`, withheld): none in prompt-audit. +- **dometrain** F10 (`plugins/dometrain/skills/sync/context/update.md:36-38 and 49-53`, withheld): none. +- **evals** F4 (`plugins/evals/skills/methodology/SKILL.md:2 (and design/SKILL.md:2)`, withheld): Group 2, "Trigger-case enumeration". +- **firecrawl** F1 (`plugins/firecrawl/skills/update/UPSTREAM.md:6-10`): Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims with". +- **firecrawl** F10 (`plugins/firecrawl/skills/firecrawl/SKILL.md:41, 42, 46, 49`, withheld): Group 3, "Tool names in the system prompt; prose lists that shadow the real tool list". +- **github** F1 (`plugins/github/skills/advise/SKILL.md:83-88 and plugins/github/skills/audit/SKILL.md:86-91`): Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims". +- **github** F2 (`plugins/github/skills/advise/SKILL.md:2 and plugins/github/skills/audit/SKILL.md:2`, withheld): Group 2, "Trigger-case enumeration". +- **implementation** F17 (`plugins/implementation/skills/implement/context/bugfix.md:28`, withheld): Group 2, Volatile specifics (an undated count describing an external plugin's contents). +- **improvement** F6 (`plugins/improvement/skills/find/context/hotspots.md:112-128`): Group 4, "An LLM executor for a deterministic plan" (routing, tallying, filtering). +- **machine-health** F16 (`plugins/machine-health/skills/audit/references/shared/discovery-guide.md:11` and `plugins/machine-health/skills/audit/SKILL.md:73`, withheld): considered against Group 1f, "Output-shaping choreography: numeric output ceilings". +- **mutation-testing** F1 (`plugins/mutation-testing/skills/audit/context/suppression.md:25-26`): Group 2, "History narratives: past tense, incident IDs, PR numbers, pinned model names". +- **mutation-testing** F5 (`plugins/mutation-testing/skills/audit/context/persist-findings.md:183`): Group 2, "History narratives: past tense". +- **mutation-testing** F6 (`plugins/mutation-testing/skills/audit/context/persist-findings.md:98`): Group 2, "Volatile specifics". +- **mutation-testing** F7 (`plugins/mutation-testing/skills/principles/SKILL.md:2`): Group 2, "Trigger-case enumeration: description lists of near-synonymous example queries". +- **mutation-testing** F8 (`plugins/mutation-testing/skills/audit/SKILL.md:2`): Group 2, "Trigger-case enumeration". +- **naming** F6 (`plugins/naming/skills/name-it-better/SKILL.md:111-112`, withheld): Group 1a, capitalized emphasis with no adjacent reason. +- **overengineering** F1 (`plugins/overengineering/skills/delta/context/baseline-model.md:23`): Group 1d, Fossils, "Migration-relative phrasing". +- **overengineering** F2 (`plugins/overengineering/skills/delta/SKILL.md:278-279`): Group 1d, Fossils, "Migration-relative phrasing". +- **overengineering** F4 (`plugins/overengineering/skills/audit/evals/evals.json cases 10 and 11; plugins/overengineering/skills/realign/evals/evals.json case 7`): prompt-audit Step 6, "A removal is complete only when everything referencing it goes too: tests asserting the old behavior". +- **overengineering** F6 (`plugins/overengineering/skills/realign/SKILL.md:254-257`): Group 2, "History narratives: past tense, incident IDs, PR numbers, pinned model names". +- **planning** F30 (`plugins/planning/skills/interview/SKILL.md:259`, withheld): none (a spoke pointer filed under the boundary section, where it reads as a "does not do" item). +- **planning** F35 (`plugins/planning/skills/plan/SKILL.md:67`): Group 3, routing text naming a skill not present under `plugins/`; Group 1b adjacent. +- **playgrounds** F2 (`plugins/playgrounds/skills/use/SKILL.md:118-119`): Group 2, "History narratives: past tense, incident IDs, PR numbers, pinned model". +- **playwright** F6 (`plugins/playwright/skills/playwright/SKILL.md:74-77`, withheld): Group 2, row "Volatile specifics: hardcoded paths, flags, version numbers, API". +- **playwright** F7 (`plugins/playwright/skills/playwright/reference/windows-quirks.md:82`, withheld): Group 2, row "Volatile specifics: hardcoded paths, flags, version numbers, API". +- **plugin-quality** F18 (`plugins/plugin-quality/skills/audit/SKILL.md:113-114 (add)`): keep-list 11, "Re-baselining adds text too" (the per-target "Behavioral shifts" sections); Group 4, sub-agent architecture. +- **plugin-quality** F21 (`Dated verification stamps with no recheck trigger (six sites)`, withheld): none in prompt-audit's tables (it names the undated claim as the defect, and these are dated). +- **prototype** F8 (`plugins/prototype/skills/explore-directions/SKILL.md:161-162`, withheld): Group 2, "Verbose SKILL.md" (a sentence the model has to reconcile before it can act on it). +- **rate-limit-guard** F6 (`plugins/rate-limit-guard/skills/setup/SKILL.md:239-240`): none (a lowercase sentence start after a full stop; editing residue, not a dated pattern). +- **review** F20 (`plugins/review/skills/code-review/SKILL.md:47-50`, withheld): none (a sentence fragment; outside prompt-audit's pattern tables). +- **setup-lane** T9 (`Reconfiguration paragraph duplicated verbatim across the fleet`, withheld): none in prompt-audit's tables; keep-list 8 (working redundancy is not cruft). +- **setup-lane** F25 (`plugins/actionlint/skills/setup/SKILL.md:100-106`, withheld): Group 2, Volatile specifics (a version-pinned claim); dated, but with no recheck trigger. +- **testing** F1 (`plugins/testing/skills/write/context/organize.md:49 (and write/context/write.md:121)`): Group 2, "Volatile specifics: hardcoded paths, flags, version numbers" (verified stale). +- **testing** F18 (`plugins/testing/skills/write/context/write.md:28-33`): Group 1c, "Strategy coaching next to task rules": an unconditional approval gate, scoped down only by invocation source. +- **testing** F19 (`plugins/testing/skills/write/context/write.md:62`): Group 1c, "Strategy coaching next to task rules": an invitation to refactor existing code beyond the slice under test. +- **testing** F25 (`plugins/testing/skills/diagnose/SKILL.md:68 (and diagnose/context/investigate.md:16, write/SKILL.md:74)`, withheld): Group 2, "Volatile specifics: ... version numbers, API claims with no verification date". +- **testing** F26 (`plugins/testing/skills/run-e2e/context/e2e.md:12`, withheld): Group 2, "Volatile specifics": an undated version floor. +- **testing** F27 (`plugins/testing/skills/diagnose/context/investigate.md:55-60 (and loop.md:111-116, plan/SKILL.md:120-125, run-e2e/context/e2e.md:154-159, write/context/organize.md:61-66, write/context/write.md:151-157)`): The brief's routing rule: a sibling reference naming a skill that does not exist under `plugins/`. +- **toolchain** F14 (`plugins/toolchain/skills/check/context/dotnet.md:52`, withheld): Group 2, Volatile specifics; dated, but with no recheck trigger. +- **toolchain** F15 (`plugins/toolchain/skills/check/context/go.md:38`, withheld): Group 2, Volatile specifics (a verification stamp with a toolchain version but no date and no recheck trigger). +- **verification** F5 (`plugins/verification/skills/measure/context/metrics.md:11-20 (add after the table)`): Group 4, An LLM executor for a deterministic plan (a count is a computation whose inputs fully determine its output); Group 1b. +- **verification** F10 (`plugins/verification/skills/measure/context/metrics.md:90-96 and plugins/verification/skills/measure/context/performance.md:61-68`): the brief's routing rule: a sibling reference is flagged when it names a skill that does not exist in `plugins/`. +- **wizard** F1 (`plugins/wizard/skills/generate/SKILL.md:99-104`, withheld): Group 1a, pressure language. + +## Withheld findings + +Low-confidence and `flag` items, reported but not applied. Grouped by plugin, one line per finding: id, location, the pattern row the auditor cited, the auditor's confidence, and the lead's disposition, generated from the reports and decisions by `.work/prompt-audit-skills/gen-record-sections.py`. The setup-lane group holds the cross-cutting setup-skill findings that no single plugin owns. + +- **adhd** (3): + - F2 (`plugins/adhd/skills/shape/SKILL.md:129-136` and `plugins/adhd/skills/clarify/SKILL.md:227`), Group 1f, "Output-shaping choreography - one pattern, remove every limb": numeric; medium; declined by the lead: the five-item cap is this style skill's own product spec, grounded in the working-memory fact at line 39, not a clamp written against an older model's verbosity; keep-list 1. + - F5 (`plugins/adhd/skills/clarify/SKILL.md:143-156, 191-193`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims"; low; withheld; follow-up F6. + - F6 (`plugins/adhd/skills/clarify/SKILL.md:2` and `plugins/adhd/skills/shape/SKILL.md:2`), Group 2, "Trigger-case enumeration: description lists of near-synonymous example"; low; withheld, low confidence. +- **ai-briefing** (2): + - F14 (`plugins/ai-briefing/skills/generate/references/slide-generation.md:215, :247`), Group 2, Volatile specifics (a command form and a harness command named as bare fact); low; withheld; follow-up F6 (`/reload-plugins` does exist in the current Claude Code build; the record notes it). + - F15 (`plugins/ai-briefing/skills/generate/references/slide-generation.md:99, :157, :165; build-pipeline.md:107`), Group 2, The recency trap (one window's news encoded as a permanent illustration); low; withheld, low confidence. +- **ai-slop** (1): + - F12 (`plugins/ai-slop/skills/audit/reference/catalog.md:1-1098`), Group 2, "Verbose SKILL.md explaining things the model already knows" (signal row); low; withheld, low confidence; owned by `docs-hygiene:audit-progressive-disclosure`. +- **architecture** (2): + - F13 (`plugins/architecture/skills/improve/SKILL.md:25-28`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. + - F14 (`plugins/architecture/skills/improve/SKILL.md:40`), Group 1c, "Padding: repetition as reinforcement"; low; withheld; keep-list 10. +- **autonomy** (7): + - F23 (`plugins/autonomy/skills/setup/SKILL.md:267; plugins/autonomy/skills/setup/context/prerequisite-resolution-slice.md:38-39; plugins/autonomy/reference/prerequisite-resolution.md:86-88`), Group 2, Volatile specifics (a harness-capability claim stated three times with no verification date or recheck trigger); low; withheld; follow-up F6. + - F24 (`plugins/autonomy/reference/telemetry.md:14-15, :22, :69-70`), Group 2, Volatile specifics (undated empirical harness claims and an upstream-status claim); low; withheld; follow-up F6. + - F25 (`plugins/autonomy/reference/runner/escalation.md:140-152`), Group 2, Volatile specifics (harness-capability claims, "today", no date); low; withheld; follow-up F6. + - F26 (`plugins/autonomy/reference/trigger-dispatch.md:22-26`), Group 2, Time-sensitive content (vendor-state claims marked unverified, with a wire-time recheck trigger and no date); low; withheld, low confidence. + - F27 (`Boris playbook attributions: plugins/autonomy/reference/guardrails.md:13-17; guardrails/work-classes.md:92-95; guardrails/security-review.md:35-37; runner.md:45`), Group 2, History narratives (provenance paragraphs that assign each idea to its source); low; withheld, low confidence. + - F28 (`plugins/autonomy/reference/runner.md:12-13 and :33`), Group 2, History narratives (a planning-era tier label, `T4`, defined nowhere in the plugin); low; withheld, low confidence. + - F29 (`plugins/autonomy/reference/autonomous-pipeline-reminder.md:29-66 (out of scope)`), Keep-list 11, Re-baselining adds text too; Group 1d, Fossils (a locally reworded prompting-guide block); low; out of audit scope; follow-up F18. +- **bugs** (5): + - F9 (`plugins/bugs/skills/write/SKILL.md:20-22`), Group 2, History narratives (a rationale for how a fixed command came to be shaped, addressed to whoever might edit it); medium; fleet decision: the "pipe is the bound" paragraph is kept fleet-wide. + - F14 (`plugins/bugs/skills/scan/SKILL.md:119-120`), Group 2, Volatile specifics (a figure stated as bare fact with no source or recheck trigger); low; withheld, low confidence. + - F15 (`plugins/bugs/skills/write/SKILL.md:118 and plugins/bugs/skills/write/context/template.md:43-44, :69-70`), Group 2, Volatile specifics (an external-API claim with no verification date); low; withheld, low confidence. + - F16 (`plugins/bugs/skills/scan/SKILL.md:22-25 and plugins/bugs/skills/write/SKILL.md:24-27`), Group 2, Volatile specifics (a harness-behavior claim with no verification date); low; withheld; follow-up F6 (one dated record on the fleet gather block). + - F17 (`plugins/bugs/skills/scan/SKILL.md:231-246 and plugins/bugs/skills/write/SKILL.md:144-150`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 10. +- **claude-config** (4): + - F30 (Undated `pre-v2.1.211` harness-version claims), Group 2, Volatile specifics (a harness version boundary stated as bare fact with no verification date in the bodies); medium (pattern match); action withheld to `flag`; withheld; follow-up F6. + - F31 (`plugins/claude-config/skills/audit-instructions/reference/conflict-criteria.md:532-533, :540-547`), Group 2, Volatile specifics (an undated local measurement); low; withheld; follow-up F6 (measured figure). + - F32 (`Dated stamps with no recheck trigger, and undated verification notes`), Group 2, Volatile specifics; low; withheld; follow-up F6. + - F33 (`Time-relative and machine-specific qualifiers`), Group 2, Time-sensitive content (idiom-dating only; the convention the first two cite owns the measured platform); low; withheld, low confidence. +- **claude-memory** (1): + - F12 (`plugins/claude-memory/skills/audit/reference/official-guidance.md:168`), Group 2, "Volatile specifics ... with no verification date"; low; withheld; follow-up F6. +- **claude-ops** (13); shared note: withheld; F26, F28, F29, F30, F31, F32, F33, F34, F37 join follow-up F6 (undated harness and upstream claims); F27 and F35 join F6's measured-figure note; F36 and F38 are keep-list 8 and 10: + - F26 (`plugins/claude-ops/skills/audit-install-state/SKILL.md:48-53`), Group 2, Volatile specifics (harness claims with no verification date or recheck trigger); low; see the shared note. + - F27 (`plugins/claude-ops/skills/audit-install-state/SKILL.md:223-224`), Group 2, Volatile specifics (a measured figure with no date or trigger); low; see the shared note. + - F28 (`plugins/claude-ops/skills/audit-native-overlap/SKILL.md:286-289`), Group 2, Volatile specifics (undated harness examples); low; see the shared note. + - F29 (`plugins/claude-ops/skills/inventory/SKILL.md:210-216`), Group 2, Volatile specifics ("Verified" with no date); low; see the shared note. + - F30 (`plugins/claude-ops/skills/changelog/SKILL.md:167 and context/read-actions.md:9-13`), Group 2, Volatile specifics (harness behavior with no verification date); low; see the shared note. + - F31 (`plugins/claude-ops/skills/lanes/SKILL.md:92-104, :214-221 and context/refresh.md:68-80`), Group 2, Volatile specifics (harness claim with a doc link but no verification date), stated three times; low; see the shared note. + - F32 (`plugins/claude-ops/skills/lanes/SKILL.md:189-193, :223-235 and context/refresh.md:10-11`), Group 2, Volatile specifics ("verified" and "confirmed on this machine" with no date or CLI version); low; see the shared note. + - F33 (`plugins/claude-ops/skills/observability/SKILL.md:150-151`), Group 2, Volatile specifics (two harness-defect claims with no date, issue, or trigger); Group 1d model-version workaround shape; low; see the shared note. + - F34 (`plugins/claude-ops/skills/observability/context/read-routing.md:75 and plugins/context/sync.md:122-125`), Group 2, Volatile specifics (upstream issue state stated without a date); low; see the shared note. + - F35 (`plugins/claude-ops/skills/observability/context/operator-setup-retention.md:15-16 and context/data-sources.md:251`), Group 2, Volatile specifics (measured figures with no date or trigger); low; see the shared note. + - F36 (`plugins/claude-ops/skills/audit-performance/SKILL.md:177-193 and audit-skill-visibility/SKILL.md:208-211, :215-217`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; see the shared note. + - F37 (`plugins/claude-ops/skills/audit-install-state/reference/surfaces.md:3-4`), none in prompt-audit's tables (dated, so the Group 2 "no verification date" row does not match); low; see the shared note. + - F38 (`plugins/claude-ops/skills/setup/SKILL.md:80-83 and :85-87`), Group 1c, Padding (near-duplicate sentences across sections); low; see the shared note. +- **code-tidying** (1): + - F23 (`plugins/code-tidying/skills/tidy/SKILL.md:2`), Group 2, "Trigger-case enumeration": a candidate on shape, but not on provenance; low; withheld, low confidence; keep-list 6. +- **codebase-health** (1): + - F11 (`plugins/codebase-health/skills/audit/SKILL.md`:25-28), Group 2, brittle skill files, "API claims with no verification date"; low; withheld; follow-up F6. +- **computer-use** (4): + - F10 (`plugins/computer-use/skills/diagnose/SKILL.md:2`), Group 2, Trigger-case enumeration (partial match); low; withheld, low confidence. + - F11 (`plugins/computer-use/skills/diagnose/SKILL.md:62-63`), Group 2, Volatile specifics: dated and sourced, but with no recheck trigger, which the repo's four-part record (claim, basis, as-of date); low; withheld; follow-up F6 (dated stamp, no recheck trigger). + - F12 (`plugins/computer-use/skills/diagnose/reference/windows-quirks.md:5-6`), Group 2, Volatile specifics: a dated basis with no recheck trigger; low; withheld; follow-up F6 (dated stamp, no recheck trigger). + - F13 (`plugins/computer-use/skills/diagnose/SKILL.md:76-87`), Group 1c, Padding (repetition across sections); low; withheld; keep-list 10. +- **context-budget** (6): + - F4 (`plugins/context-budget/skills/audit/SKILL.md:226-228`), Group 2, Volatile specifics (a version-pinned harness-behavior claim with no verification date and no recheck trigger); low; withheld; follow-up F6. + - F5 (`plugins/context-budget/skills/audit/SKILL.md:34-36`), Group 2, Volatile specifics (an undated claim about a bundled skill's availability and frontmatter); low; withheld; follow-up F6. + - F6 (`plugins/context-budget/skills/audit/reference/engine.md:25-30 (and :52-53)`), Group 2, Volatile specifics (API claims carrying citations but no verification date or recheck trigger); low; withheld; follow-up F6. + - F7 (`plugins/context-budget/skills/audit/scripts/fixtures/context-sample.md:3-4`), Group 2, Time-sensitive content (an as-of stamp with no date); outside the prompt surface (no skill body links the fixture); low; withheld; outside the prompt surface. + - F8 (`plugins/context-budget/skills/audit/SKILL.md:24-26, :51, :86`), Group 1c, Padding (repetition as reinforcement; the same constraint restated across sections); low; withheld; keep-list 8 and 10. + - F9 (`plugins/context-budget/skills/audit/SKILL.md:93`), Group 2, Volatile specifics (a wall-clock range with no date, machine class, or recheck trigger); low; withheld; follow-up F6. +- **context-guard** (3): + - F15 (plugins/context-guard/skills/setup/SKILL.md:37-135 (`check` steps 1, 2, 4, 5)), Group 4, An LLM executor for a deterministic plan; medium; recorded as follow-up F17: moving the probes into a `## Pre-computed context` block is a mechanism change gated by `scripts/check-skill-precompute-compose.sh` and the worktree guard's `$`-expansion rule, not an audit hunk. + - F16 (`Undated harness-capability claims in four sites`), Group 2, Volatile specifics (harness settings keys and behavior stated as bare fact with no verification date); low; withheld; follow-up F6. + - F17 (`plugins/context-guard/reference/reader-contract.md:383-391`), Group 2, History narratives (pinned model names in provenance prose); dated, but with no recheck trigger; low; withheld; follow-up F6. +- **context7** (1): + - F12 (`plugins/context7/skills/lookup/SKILL.md:26 versus context/update.md:52`), Group 1a, the `Default to [tool]` row; read against a convention this plugin states about; low; withheld, low confidence. +- **coupling** (2): + - F3 (`plugins/coupling/skills/reduce/SKILL.md:25-28`), Group 1c, "Padding: ... asides get applied where they don't fit"; also Group 2; medium; fleet decision: the gather-block wording is settled fleet-wide and is not rewritten per plugin. + - F4 (`plugins/coupling/skills/reduce/ (4 files, 59 lines)`), none in prompt-audit.md; low; withheld; house style owned by `ai-slop:audit`. +- **debugging** (3): + - F3 (`plugins/debugging/skills/debug/SKILL.md:25-28`), Group 1d, migration-relative phrasing ("rather than pre-compute lines" is a diff against the previous prompt version the model never saw); medium; fleet decision: the gather-block sentence "Keep these as separate body Bash calls rather than pre-compute lines: ..." is the settled fleet wording (a structural contrast, not a version diff); do not rewrite it per plugin. + - F4 (`plugins/debugging/skills/debug/SKILL.md:21-23`), Group 2, verbose SKILL.md explaining things the model already knows (every paragraph must justify its token cost); medium; fleet decision: the one-sentence "The pipe is the bound and belongs in the command" form is kept fleet-wide (it stops a read-time cap from replacing the pipe); source-control already applied that form. + - F13 (`plugins/debugging/skills/debug/reference/ecosystem-debugging.md:11`), Group 2, volatile specifics (API claims with no verification date); low; withheld, low confidence. +- **discipline** (4): + - T3 (`Gotchas bullets that restate rules already in the body`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 10. + - T4 (`"Does not fabricate a finding" recap of the shared method's non-negotiable`), Group 1c, Padding (repetition as reinforcement across files); signal `do not hallucinate`; low; withheld, low confidence. + - T5 (`Undated harness fork-mode claims`), Group 2, Volatile specifics (harness API claims with a source but no verification date or recheck trigger); low; withheld; follow-up F6. + - F12 (`plugins/discipline/skills/sweep-all/SKILL.md:176-179`), Group 2, Volatile specifics (a measured figure from one run, no date, no recheck trigger); low; withheld, low confidence. +- **discovery** (3): + - F24 (`Undated harness-behavior claims stated as bare fact (multiple files)`), Group 2, Volatile specifics (API and harness claims with no verification date); low; withheld; follow-up F6. + - F25 (`plugins/discovery/skills/explore/reference/dispatch.md:166-187`), Group 2, Volatile specifics; low; withheld, low confidence. + - F26 (`plugins/discovery/agents/explorer.md, agents/researcher.md, agents/intent-tracer.md (Group 4 roster)`), Group 4, Redundant specialist sub-agents (roster check); low; withheld, low confidence. +- **disk-hygiene** (2): + - F15 (`Undated harness-version claims (four sites)`), Group 2, Volatile specifics (harness version numbers and API claims with no verification date); low; withheld; follow-up F6. + - F16 (`plugins/disk-hygiene/skills/clean/reference/safety-model.md:303-306`), Group 2, History narratives (a pinned plugin version number), the same row F4 acts on; low; withheld, low confidence; keep-list 1. +- **docs-hygiene** (3): + - F21 (`extract-ssot/actions/batch.md:35 and 281`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. + - F26 (`extract-ssot/SKILL.md:27, extract-ssot/context/anti-patterns.md:129, extract-ssot/context/decision-framework.md:27-30, 56, 59`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. + - F27 (`audit-encapsulation/context/public-surface-contract.md:5`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. +- **domain-driven-design** (1): + - F4 (`plugins/domain-driven-design/skills/curate-language/SKILL.md:8`), none in prompt-audit; low; withheld; house style owned by `ai-slop:audit`. +- **dometrain** (3): + - F9 (`plugins/dometrain/skills/grounding/SKILL.md:2`), Group 2, Trigger-case enumeration (partial match only); low; withheld, low confidence. + - F10 (`plugins/dometrain/skills/sync/context/update.md:36-38 and 49-53`), none; low; withheld; recorded as follow-up F23 (a documented maintainer command resolves `${CLAUDE_PLUGIN_ROOT}` to the installed cache the next paragraph forbids writing). + - F11 (`plugins/dometrain/skills/setup/SKILL.md:20-26`), Group 2, Volatile specifics (an API claim with no verification date); low; withheld; follow-up F6. +- **education** (1): + - F10 (`plugins/education/skills/teach/SKILL.md:86 (the harness claim, not the tracker ref)`), Group 2, Volatile specifics (a harness-behavior claim with no verification date); low; withheld; follow-up F6. +- **evals** (1): + - F4 (`plugins/evals/skills/methodology/SKILL.md:2 (and design/SKILL.md:2)`), Group 2, "Trigger-case enumeration"; low; withheld, low confidence. +- **event-storming**: none. +- **firecrawl** (3): + - F8 (`plugins/firecrawl/skills/firecrawl/SKILL.md:92 (with lines 2 and 3)`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers"; low; withheld, low confidence; the description half lands with F5. + - F9 (`plugins/firecrawl/skills/firecrawl/context/commands.md:120`), Group 2, "duplicated info across SKILL.md and reference files"; low; withheld, low confidence; keep-list 8. + - F10 (`plugins/firecrawl/skills/firecrawl/SKILL.md:41, 42, 46, 49`), Group 3, "Tool names in the system prompt; prose lists that shadow the real tool list"; low; withheld, low confidence. +- **github** (2): + - F2 (`plugins/github/skills/advise/SKILL.md:2 and plugins/github/skills/audit/SKILL.md:2`), Group 2, "Trigger-case enumeration"; low; withheld, low confidence; keep-list 6. + - F3 (`plugins/github/skills/setup/SKILL.md:62`), Group 2, "Volatile specifics", read as a harness-substitution claim; low; withheld; follow-up F6. +- **guardrails**: none. +- **implementation** (6): + - F15 (`plugins/implementation/skills/implement/SKILL.md:2`), Group 2, Trigger-case enumeration (eight quoted phrases); low; withheld, low confidence. + - F16 (`plugins/implementation/agents/implementer.md:26-51 and plugins/implementation/agents/phase-verifier.md:23-45`), none in prompt-audit's tables; low; withheld; candidate for an instruction-placement pass (agent-file rationale sections). + - F17 (`plugins/implementation/skills/implement/context/bugfix.md:28`), Group 2, Volatile specifics (an undated count describing an external plugin's contents); low; withheld, low confidence. + - F18 (`plugins/implementation/skills/implement-dispatch/SKILL.md:43, 116, 117`), none in prompt-audit's tables (verified true for this repo: both checks run in `.github/workflows/ci.yml`); low; withheld, low confidence. + - F19 (`plugins/implementation/skills/implement/SKILL.md:18, 20`), Group 2, Volatile specifics (a harness-behavior claim about which command shapes a worktree-isolated session accepts); low; withheld; a trailing `\| head` on a git command is accepted by worktree isolation (the worktree skill states it and this session confirms it), so the concern does not hold. + - F20 (`plugins/implementation/skills/implement/context/refactor.md:12`), none in prompt-audit's tables; low; withheld, low confidence. +- **improvement** (3): + - F9 (`plugins/improvement/skills/find/context/ci-health.md:32-36, :40-41; skills/find/SKILL.md:235-237; skills/find/context/unattended.md:74-75`), Group 2, Volatile specifics ("hardcoded paths, flags, version numbers, API claims"); medium (pattern match); action withheld to `flag`; withheld; follow-up F6. + - F10 (`plugins/improvement/skills/find/SKILL.md:227-241`), Group 1c, Padding (repetition as reinforcement); low; withheld; keep-list 10. + - F11 (`plugins/improvement/skills/find/SKILL.md:2`), Group 2, Trigger-case enumeration (description lists of near-synonymous example); low; withheld, low confidence. +- **instruction-placement** (2): + - F7 (`Gotchas sections that restate rules already in the body (four skills)`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 10. + - F8 (`plugins/instruction-placement/skills/realign/context/apply-recipes.md:95-97`), Group 2, Volatile specifics (an undated claim about how other harnesses resolve a file, with no verification record); low; withheld; follow-up F6. +- **kindle-dedrm** (2): + - F10 (`plugins/kindle-dedrm/skills/manage/SKILL.md:143`), Group 1a, "Pressure language", with Group 1c "repetition as reinforcement"; low; withheld, low confidence; keep-list 8. + - F11 (`plugins/kindle-dedrm/skills/manage/references/troubleshooting.md:246-248`), none; low; withheld; subsumed by F3. +- **knowledge** (3): + - F26 (`Trigger-case enumeration in five skill descriptions`), Group 2, Trigger-case enumeration; low; withheld, low confidence; no replacement proposed (check 3 is advisory, so the gate does not block a later consolidation). + - F27 (`Undated external version floors`), Group 2, Volatile specifics (version numbers with no verification date); low; withheld; follow-up F6. + - F28 (`Rule bodies restated across docpage-digest's two Phase 4 spokes`), Group 2, Time-sensitive content (duplicated info across SKILL.md and reference); low; withheld, low confidence; keep-list 8. +- **machine-health** (3): + - F14 (`plugins/machine-health/skills/setup/SKILL.md:2`), Group 2, "Trigger-case enumeration"; low; withheld, low confidence. + - F15 (`plugins/machine-health/skills/audit/references/windows/remediation-policy.md:67`), Group 1a, "Pressure language"; the signal is emphasis with no adjacent "because"; low; withheld, low confidence; the prohibition stays. + - F16 (`plugins/machine-health/skills/audit/references/shared/discovery-guide.md:11` and `plugins/machine-health/skills/audit/SKILL.md:73`), considered against Group 1f, "Output-shaping choreography: numeric output ceilings"; low; withheld; keep-list 4. +- **mcp-tools** (1): + - F6 (`plugins/mcp-tools/skills/audit/reference/checklist.md:38, 105, 106`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims with no verification date"; medium; withheld; follow-up F6. +- **mutation-testing** (1): + - F11 (`plugins/mutation-testing/skills/setup/SKILL.md:80-89`), Group 1b, "Inline lookup tables, point systems, arithmetic rubrics the model must compute → Data in files or tool results"; medium; recorded as follow-up F21 in the record (a new lint script and test). +- **naming** (1): + - F6 (`plugins/naming/skills/name-it-better/SKILL.md:111-112`), Group 1a, capitalized emphasis with no adjacent reason; low; withheld, low confidence. +- **overengineering** (3): + - F10 (`plugins/overengineering/skills/audit/SKILL.md:20-23, plugins/overengineering/skills/delta/SKILL.md:19-23, plugins/overengineering/skills/realign/SKILL.md:19-22`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. + - F11 (`plugins/overengineering/skills/delta/context/recurring-wiring.md:37-38 and 51-53`), Group 2, "Volatile specifics"; medium; withheld; follow-up F6. + - F12 (`plugins/overengineering/skills/audit/SKILL.md:92-93 and 142-144; plugins/overengineering/skills/audit/context/surface-walk.md:95-97; plugins/overengineering/skills/delta/context/recurring-wiring.md:24-25`), model-migration.md, "Migrating to Claude Fable 5.1", Behavioral shifts, "Rare: context anxiety"; low; withheld, low confidence. +- **performance** (1): + - F21 (`plugins/performance/skills/snapshot/SKILL.md:94-96`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims with no verification date"; low; withheld; follow-up F6. +- **planning** (6): + - F30 (`plugins/planning/skills/interview/SKILL.md:259`), none (a spoke pointer filed under the boundary section, where it reads as a "does not do" item); low; withheld, low confidence. + - F31 (`plugins/planning/skills/plan/SKILL.md:198 and 206`), Group 2, Volatile specifics (harness-capability status stated as bare fact, undated); low; withheld; follow-up F6 (undated harness claims). + - F32 (`plugins/planning/skills/interview/context/session-config.md:103-108`), Group 2, Volatile specifics (harness-capability claim, undated); low; withheld; follow-up F6. + - F33 (`plugins/planning/skills/wayfind/SKILL.md:20`), Group 4, Request-building code disagreeing with its own prose contract; low; withheld; follow-up F9 (wayfind pre-compute coerces a non-string container label its own doc forbids). + - F34 (`plugins/planning/skills/wayfind/SKILL.md:2, 90, 189, 200`), Group 3, routing text naming a plugin rather than an invocable skill; low; withheld, low confidence. + - F36 (`plugins/planning/skills/prd/SKILL.md:58 and 92`), Group 1c, Padding (near-duplicate sentences across sections, two differently worded canned messages for one event); low; withheld, low confidence. +- **playbooks** (4): + - F13 (`skills/fable-5/context/calibration.md:66-69`), Group 2, volatile specifics (binary-registry internals), dated and triggered in the correct form; low; withheld, low confidence. + - F14 (`skills/fable-5/context/orchestration.md:97`), Group 2, volatile specifics (restated pricing ratio and TTL), dated but with no recheck trigger of their own; low; withheld; follow-up F6 (missing recheck trigger on the cache-pricing stamp). + - F15 (`skills/boris/SKILL.md:58,133` and `skills/boris/reference/orchestration.md:92-106`), Group 2, pinned model names; judged under the brief's per-model-doctrine criterion; low; withheld; follow-up F13 (boris re-sync). + - F16 (`reference/model-adaptation/opus-5.md:62-63,207-208,243-246`), Group 2, brittle skill files (maintainer bookkeeping in a model-facing chapter); I13 for the citation; low; withheld; follow-up F8 (non-loading citation) and a maintainer note. +- **playgrounds** (2): + - F3 (`plugins/playgrounds/skills/use/SKILL.md:72-73`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims"; low; withheld; follow-up F6 (case 3 quotes the command, unchanged). + - F4 (`plugins/playgrounds/skills/use/SKILL.md:53-56`), Group 2, "Volatile specifics: hardcoded paths, flags, version numbers, API claims"; low; withheld; follow-up F6. +- **playwright** (2): + - F6 (`plugins/playwright/skills/playwright/SKILL.md:74-77`), Group 2, row "Volatile specifics: hardcoded paths, flags, version numbers, API"; low; withheld; follow-up F6. + - F7 (`plugins/playwright/skills/playwright/reference/windows-quirks.md:82`), Group 2, row "Volatile specifics: hardcoded paths, flags, version numbers, API"; low; withheld; follow-up F6 (setup/SKILL.md:34-40 consumes the claim). +- **plugin-quality** (5): + - F8 (`plugins/plugin-quality/skills/audit/SKILL.md:58-92 (and skills/setup/SKILL.md:28-30)`), Group 1b, "Inline lookup tables, point systems, arithmetic rubrics the model must compute" (replacement: data in files or tool results); medium; recorded as follow-up F19 in the record: a synced copy of `context-zone.sh` plus its test, a registry entry, and a sync script is a mechanism change, not an audit hunk. Leave `:58-92` and `setup/SKILL.md:28-30` as they are. + - F19 (`plugins/plugin-quality/agents/auditor.md:117-119`), Group 2, Volatile specifics (two live documentation page titles stated as bare fact with no date; they illustrate the "same subject"); low; withheld; follow-up F6. + - F20 (`plugins/plugin-quality/skills/audit/references/component-types/skill.md:18-20 and :22-24`), Group 2, Volatile specifics (harness-capability claims with no verification date or recheck trigger); low; withheld; follow-up F6. + - F21 (`Dated verification stamps with no recheck trigger (six sites)`), none in prompt-audit's tables (it names the undated claim as the defect, and these are dated); low; withheld; follow-up F6 (dated stamps with no recheck trigger). + - F22 (`plugins/plugin-quality/agents/auditor.md:5`), none in prompt-audit's tables (it does not error on the target and is not a sampling parameter); low; withheld, low confidence; `effort: high` is a fleet convention. +- **prototype** (1): + - F8 (`plugins/prototype/skills/explore-directions/SKILL.md:161-162`), Group 2, "Verbose SKILL.md" (a sentence the model has to reconcile before it can act on it); low; withheld, low confidence. +- **provenance** (2): + - F14 (`plugins/provenance/skills/audit/SKILL.md:2, :82, :227 versus reference/rubric.md:297`), Group 1c, Padding (duplicated wordings of one rule that the model must reconcile); low; withheld; recorded as follow-up F20 in the record (script and test change). + - F15 (`plugins/provenance/skills/audit/SKILL.md:2`), Group 2, Trigger-case enumeration (a description listing near-synonymous example); low; withheld, low confidence. +- **rate-limit-guard** (2): + - F4 (`plugins/rate-limit-guard/skills/setup/reference/unwrap-before-compose.md:11-109 (and SKILL.md:109-200, which drives it)`), Group 4, An LLM executor for a deterministic plan (a call whose inputs fully determine its output executed by the model instead of code); medium; recorded as follow-up F15: scripting the statusline compose transform is a code change with its own tests, not an audit hunk. + - F5 (`plugins/rate-limit-guard/reference/reader-contract.md:206-209`), Group 2, Volatile specifics (a harness-capability claim with no verification date); Group 2, Time-sensitive content ("until it stabilizes"); low; withheld; follow-up F6. +- **repo-fleet-hygiene** (3): + - F13 (`plugins/repo-fleet-hygiene/skills/apply/SKILL.md:2 (frontmatter description)`), Group 2, Trigger-case enumeration (near-synonymous example queries); low; withheld, low confidence. + - F14 (`plugins/repo-fleet-hygiene/skills/audit/SKILL.md:26 and :236`), Group 1c, Padding (near-duplicate sentences across sections); low; withheld; keep-list 10. + - F15 (`plugins/repo-fleet-hygiene/skills/setup/SKILL.md:126-128 (setup delta)`), Group 1c, Padding (limits with escape hatches; commentary about the instruction); low; withheld, low confidence. +- **repo-hygiene** (1): + - F9 (`plugins/repo-hygiene/skills/clean/reference/invocation-forms.md:14-16 (and its successor text after F1)`), Group 2, Volatile specifics (an API/harness capability claim with a source but no verification date); low; withheld; follow-up F6. +- **review** (6): + - F16 (`plugins/review/agents/*.md:6 (all six agents)`), Group 4, Request config (an effort level pinned across a model change); low; withheld; effort sweep is a measurement item. + - F17 (`plugins/review/agents/*.md:5 and plugins/review/skills/fanout/context/run-everything-mode.md:141`), Group 4, Request config (model routing with no recorded baseline); low; withheld; model routing without baseline. + - F18 (`plugins/review/skills/quality-gate/context/pr.md:11-24, plugins/review/skills/quality-gate/context/code.md:7, plugins/review/skills/fanout/SKILL.md:127-129`), Group 2, Volatile specifics (harness capability claims with no verification date); low; withheld; follow-up F6. + - F19 (`plugins/review/skills/security-review/SKILL.md:15-16`), Group 1d, Fossils ("known issue with [tool]" comment); Group 2, Volatile specifics; low; withheld; follow-up F6. + - F20 (`plugins/review/skills/code-review/SKILL.md:47-50`), none (a sentence fragment; outside prompt-audit's pattern tables); low; withheld, low confidence. + - F21 (`plugins/review/agents/ecosystem-specialist.md:22, plugins/review/skills/fanout/context/fix-pass-mode.md:7, plugins/review/skills/quality-gate/context/close-out.md:38, 102, 112, 260, plugins/review/skills/quality-gate/context/spec.md:59, 80, 104`), Group 2, Volatile specifics (hardcoded paths that resolve only in one repository); low; withheld; follow-up F8 (repo-relative citations that resolve only in the marketplace checkout). +- **session-flow** (11): + - F26 (`skills/running-retro/SKILL.md:52-53 and skills/running-retro/context/checkpoint.md:136`), Group 1f, Output-shaping choreography (numeric ceiling); low; withheld, low confidence. + - F27 (`skills/setup/SKILL.md:47-50 and skills/running-retro/SKILL.md:177, 210`), Group 2, Pinned model names; duplicated info across SKILL.md and the manifest; low; withheld, low confidence. + - F28 (`skills/orient/SKILL.md:29-36`), Group 2, Volatile specifics (harness-behavior claims with no verification date); low; withheld; fleet follow-up F6 (verify and stamp undated harness claims). + - F29 (`skills/keep-going/SKILL.md:166-169`), Group 2, Volatile specifics (undated harness claim); low; withheld; follow-up F6. + - F30 (`skills/retro/SKILL.md:116-118`), Group 2, Volatile specifics (a setting default stated as bare fact, undated); low; withheld; follow-up F6. + - F31 (`skills/handoff/context/gotchas.md:43-44 and skills/find-handoff/SKILL.md:213-215`), Group 2, Volatile specifics (undated harness-behavior claims); low; withheld; follow-up F6. + - F32 (`skills/orchestrate/SKILL.md:40-41 and 99-101`), Group 1d, Fossils (a delegation-suppressing guardrail); low; withheld; candidate for the wave-1 behavioral spot-check on orchestrate. + - F33 (`skills/orchestrate/context/sources.md:53-57, 74-76, 80-81, 263-267`), Group 2, Pinned model names (in citations backing a model-agnostic brief); low; withheld; refresh citations on the next sources re-verify. + - F34 (skills/orient/SKILL.md:2, skills/find-handoff/SKILL.md:2, skills/reanchor/SKILL.md:2 (frontmatter `description`)), Group 2, Trigger-case enumeration (near-synonym lists); low; withheld, low confidence. + - F35 (`skills/handoff/context/gotchas.md:37-38`), Group 2, The recency trap (one narrow conditional with a numeric threshold and no stated general principle); low; withheld, low confidence. + - F36 (`skills/workflow/context/philosophy.md:16-18`), Group 1d, Fossils (a context-budget line written for context-limited sessions); low; withheld, low confidence. +- **setup-lane** (13); shared note: withheld; F20, F21, F22, F27 join follow-up F6; F23, F24 join a benchmark-figure note under F6: + - T5 (`Undated harness-release claims`), Group 2, Volatile specifics (version numbers and API claims with no verification date); medium (pattern match); action withheld to `flag`; withheld; follow-up F6. + - T6 (`"Do not invent an organization, repository, marketplace, or environment-variable prefix"`), Group 1c, Prohibition lists; signal `do not hallucinate` ("re-test whether you still need it - removal here is low confidence"); low; withheld, low confidence. + - T8 (`Gotchas sections that restate rules already in the body`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 10. + - T9 (`Reconfiguration paragraph duplicated verbatim across the fleet`), none in prompt-audit's tables; keep-list 8 (working redundancy is not cruft); low; withheld; keep-list 8. + - F12 (`plugins/source-control/skills/setup/SKILL.md:315`), Group 2, The recency trap (a standing invitation to encode each session's stumble as a permanent rule); medium; already covered by source-control F66. + - F20 (`plugins/discovery/skills/setup/SKILL.md:57-62, :63-71, :85`), Group 2, Volatile specifics (harness version numbers stated as bare fact, no verification date, no recheck trigger); low; see the shared note. + - F21 (`plugins/computer-use/skills/setup/SKILL.md:30 and :44`), Group 2, Volatile specifics (product-availability and plan-tier claims with no verification date); low; see the shared note. + - F22 (`plugins/dometrain/skills/setup/SKILL.md:112-113 and plugins/miro/skills/setup/SKILL.md:102-103`), Group 2, Volatile specifics (a hardcoded harness path stated as fact, no verification date); low; see the shared note. + - F23 (`plugins/context7/skills/setup/SKILL.md:91`), Group 2, Volatile specifics; a restated external benchmark figure with no recheck trigger; low; see the shared note. + - F24 (`Measured figures in the statusline guard plugins`), Group 2, Volatile specifics; restated figures with no verification date or recheck trigger; low; see the shared note. + - F25 (`plugins/actionlint/skills/setup/SKILL.md:100-106`), Group 2, Volatile specifics (a version-pinned claim); dated, but with no recheck trigger; low; see the shared note. + - F26 (`plugins/ai-briefing/skills/setup/SKILL.md:99-100`), Group 2, Time-sensitive content ("current" with no date and no statement of what the restriction is); low; see the shared note. + - F27 (`plugins/autonomy/skills/setup/SKILL.md:112-116 and templates/ci-otlp-artifact.md:94-97`), Group 2, Volatile specifics (API and beta-flag claims whose verification stamps carry no date and no recheck trigger); low; see the shared note. +- **skill-quality** (2): + - F8 (`plugins/skill-quality/skills/check/SKILL.md:160-164 and :170-172`), Group 2, Volatile specifics (harness-capability claims with no verification date); low; withheld; follow-up F6. + - F9 (`plugins/skill-quality/skills/setup/SKILL.md:16-20`), Group 2, Volatile specifics; low; withheld; setup lane T5 verdict stands; follow-up F6. +- **songwriting** (2): + - F11 (`plugins/songwriting/skills/co-write/SKILL.md:166-167`), Group 1d, "Migration-relative phrasing", plus the time-relative "today"; low; withheld, low confidence. + - F12 (`plugins/songwriting/skills/object-writing/SKILL.md:99-101`), Group 2, "Volatile specifics"; low; withheld; follow-up F6. +- **source-control** (10): + - F72 (`skills/babysit-prs/reference/freshness.md:20-26,45,80-82`), Group 2, volatile specifics (external API behavior claims with no verification date or recheck trigger); medium; withheld; follow-up F6 (undated external and harness claims). + - F73 (`skills/babysit-prs/reference/safety.md:386-429`), Group 2, volatile specifics (harness-capability claims with version pins and no as-of date; doc links present, no recheck trigger); medium; withheld; follow-up F6. + - F74 (`skills/pull-request/reference/monitor.md:388-389`), Group 2, volatile specifics (a named third-party bot's login, signalling convention, and timing, undated); medium; withheld; follow-up F7 (Codex-specific reviewer shapes). + - F75 (`skills/pull-request/reference/readiness.md:41,83-92,140,147-156`), Group 2, volatile specifics (same as F74; the Gate 5 command bakes a vendor login into a control gate); medium; withheld; follow-up F7. + - F76 (`skills/babysit-prs/reference/loop.md:462-474`), Group 2, volatile specifics (undated harness-capability claims stated as bare fact); low; withheld; follow-up F6. + - F77 (`skills/commit/SKILL.md:96-97,341-346; skills/commit/reference/exec-bit.md:8-11`), Group 1a, trait claims ("you tend to"); Group 2, history narratives ("the observed failure"); low; withheld, low confidence. + - F78 (`skills/pull-request/reference/prep.md:29`), Group 4, request config and architecture (a delegation cap); low; withheld; delegation-cap candidate for a behavioral baseline, alongside session-flow F32. + - F79 (`skills/babysit-prs/reference/stuck-checks.md:62-67,95-98`), Group 2, volatile specifics (marketplace-specific workflow and repository names in a plugin body); low; withheld, low confidence. + - F80 (`skills/pull-request/templates/checklist.md:9`), keep-list item 8 exception (duplicates that disagree): `create.md` §2.4.1 pushes through `push-branch.sh`; low; withheld, low confidence. + - F81 (`skills/babysit-loop/reference/promotion-evidence-resolution.md:9,28,35,44; skills/babysit-prs/reference/safety.md:722`), outside prompt-audit's tables; citation form; low; withheld; follow-up F8 (cross-plugin relative links). +- **tdd**: none. +- **testing** (7): + - F5 (`plugins/testing/skills/diagnose/SKILL.md:12-27`), Group 2, "Verbose SKILL.md explaining things the model already knows"; medium; fleet decision: the gather block keeps its settled wording, including the "pipe is the bound" paragraph and the "rather than pre-compute lines" sentence. + - F6 (`plugins/testing/skills/plan/SKILL.md:12-28`), Group 2, as F5; medium; same. + - F7 (`plugins/testing/skills/run-e2e/SKILL.md:12-27`), Group 2, as F5; medium; same. + - F8 (`plugins/testing/skills/write/SKILL.md:12-27`), Group 2, as F5; medium; same. + - F25 (`plugins/testing/skills/diagnose/SKILL.md:68 (and diagnose/context/investigate.md:16, write/SKILL.md:74)`), Group 2, "Volatile specifics: ... version numbers, API claims with no verification date"; low; withheld; follow-up F6. + - F26 (`plugins/testing/skills/run-e2e/context/e2e.md:12`), Group 2, "Volatile specifics": an undated version floor; low; withheld, low confidence. + - F28 (`plugins/testing/skills/run-e2e/context/e2e-config.md:5, 14, 35-37 (and non-ui.md:3, 5)`), No prompt-audit row; low; withheld, low confidence. +- **toolchain** (6): + - F13 (`plugins/toolchain/skills/lint/SKILL.md:35-37`), Group 2, Volatile specifics (measured figures with no basis, date, or recheck trigger); low; withheld, low confidence. + - F14 (`plugins/toolchain/skills/check/context/dotnet.md:52`), Group 2, Volatile specifics; dated, but with no recheck trigger; low; withheld, low confidence. + - F15 (`plugins/toolchain/skills/check/context/go.md:38`), Group 2, Volatile specifics (a verification stamp with a toolchain version but no date and no recheck trigger); low; withheld, low confidence. + - F16 (`plugins/toolchain/skills/check/SKILL.md:24-27 and plugins/toolchain/skills/lint/SKILL.md:24-27`), Group 2, Volatile specifics (an undated harness-capability claim stated as bare fact); low; withheld; fleet template, follow-up F6 pool. + - F17 (`plugins/toolchain/skills/check/SKILL.md:191-197 and plugins/toolchain/skills/lint/SKILL.md:214-224`), Group 1c, Padding (near-duplicate sentences across sections); low; withheld; keep-list 10. + - F18 (`plugins/toolchain/skills/check/SKILL.md:2`), Group 2, Trigger-case enumeration ('run tests' and 'run the tests' are the same intent); low; withheld, low confidence. +- **verification** (3): + - F6 (`plugins/verification/skills/measure/context/performance.md:65`), Group 2, Volatile specifics (a count about another marketplace's skill, stated as bare fact with no verification date or recheck trigger); medium; superseded by L1 below (the whole bullet goes). + - F8 (`plugins/verification/skills/confirm/SKILL.md:55, :68-69, :75, :138, :145, :153 and plugins/verification/skills/measure/SKILL.md:63-68`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 8 and 10. + - F9 (`plugins/verification/skills/measure/SKILL.md:2`), Group 2, Trigger-case enumeration (nine quoted phrases; 'is it faster', 'did that actually speed it up'); low; withheld, low confidence. +- **visualization**: none. +- **wizard** (2): + - F1 (`plugins/wizard/skills/generate/SKILL.md:99-104`), Group 1a, pressure language; low; withheld, low confidence; keep-list 3 (credential-handling gate carries its reason). + - F2 (`plugins/wizard/skills/generate/SKILL.md:86`), Group 1c, padding row, matching the "near-duplicate sentences across sections"; low; withheld, low confidence; keep-list 8. +- **work-items** (7): + - F17 (`The telemetry upsert is a 60-line shell block the model transcribes, in two files`), Group 4, An LLM executor for a deterministic plan (a fixed sequence whose inputs fully determine its output); medium; recorded as follow-up F11 in the record: extracting the 60-line upsert into `plugins/work-items/scripts/lane-telemetry-upsert.sh` is a mechanism change that needs its own script, test suite, and loop-lane convention review, not an audit hunk. Leave both fenced blocks and the classifier-fallback section as they are. + - F18 (`Undated harness-behavior claims (6 sites)`), Group 2, Volatile specifics (harness and tool claims with no verification date or recheck trigger); low; withheld; follow-up F6. + - F19 (`Gotchas that restate rules already in the body`), Group 1c, Padding (repetition as reinforcement; near-duplicate sentences across sections); low; withheld; keep-list 10. + - F20 (`Purpose paragraphs that restate the description verbatim`), Group 1c, Padding (repetition as reinforcement); low; withheld; keep-list 8. + - F21 (`Remaining near-duplicate trigger pairs`), Group 2, Trigger-case enumeration (the same row as F11, at a scale too small to call growth); low; withheld, low confidence. + - F22 (`decompose/context/container-lifecycle.md:14, "Step 3 (above)"`), none in prompt-audit's tables; a stale relative pointer left behind when the section moved out of `SKILL.md` into a context file; low; withheld, low confidence. + - F23 (`onboard-adapter/SKILL.md:5-8 and :12, YAML comments carrying maintainer rationale`), Group 2, History narratives (a justification for a frontmatter value, addressed to maintainers); low; withheld, low confidence. +- **x** (2): + - F5 (`plugins/x/skills/read/SKILL.md:153-154, 226`), Group 2, "Volatile specifics"; medium; withheld; follow-up F6 (needs live egress to re-verify). + - F6 (`plugins/x/skills/read/SKILL.md:160-192 and plugins/x/skills/read/context/failure-modes.md:30-92`), Group 2, "duplicated info across SKILL.md and reference files"; Group 1c, "repetition"; low; withheld; keep-list 8. + +## Brief + +The contract this run executed against, graduated verbatim from `docs/topics/prompt-audit-skills/PLAN.md` before the slice was pruned; the PR body names the pre-prune commit. The file's Plan section was empty because execution ran from the execution contract in its acceptance criteria. Every acceptance criterion below was met before the PR opened; the deferred question Q1 stays with the operator and both ADRs stay accepted. + +### TLDR + +Run the bundled `/claude-api prompt-audit` over every skill in this marketplace against Claude Fable 5.1, apply the high and medium confidence findings in waves, and ship one PR with a durable record, per-plugin version bumps, updated evals, and an inventoried follow-up list. + +### Goal + +Every skill body, its context and reference files, and every agent definition has been audited for dated prompting patterns using `shared/prompt-audit.md` (Groups 1a to 1f, 2, 3, 4 and the keep list), with Claude Fable 5.1 as the target model. Findings at high or medium confidence are applied; low-confidence and flag items are recorded. Findings are mapped to the in-repo catalog row (`claude-config:audit-instructions` I1 to I29) where one exists so catalog gaps are visible. + +### Constraints + +- Target model is Claude Fable 5.1. Where the migration guide has Opus 5 guidance and no Fable 5.1 guidance, use the Opus 5 guidance; on conflict Fable 5.1 wins. +- Existing ADRs, CI gates, `check-skill.sh`, and repo conventions are not binding on the audit. When one blocks a warranted change it is updated or removed in the same commit, and a superseding ADR is written at the end for every accepted decision the audit contradicted. +- Scope is `plugins/*/skills/**/*.md` excluding `vendor/` and `evals/`, plus `plugins/*/agents/*.md`. Hooks prompt text, output styles, `.claude/rules`, `CLAUDE.md` and `AGENTS.md` are out of audit scope except for edits that codify the Group 2 history rule. +- Descriptions and trigger text are in scope under prompt-audit's own split: routing text may keep calibrated urgency; enumerated near-synonym trigger lists become intent categories; a dropped phrase that `check-skill.sh` check 3 rejects means the check is updated, not the phrase restored. +- Group 2 history narratives are applied as written: incident IDs, PR numbers, past-tense narration, pinned model names, and date-conditional guidance are removed from skill bodies. A dated verification with a recheck trigger is kept; an undated volatile claim is verified or removed. +- Findings carry a label, `fleet` or `fable-5-1`. Both labels are applied at high and medium confidence; the label is recorded so a consumer on another model can read what changed. +- Every touched plugin gets a patch version bump and a one-line CHANGELOG entry in the same commit as its hunks. One commit per plugin. +- A skill's `evals/evals.json` is updated in the same commit whenever its body changes. +- One worktree, one branch (`docs/prompt-audit-skills`), one PR. + +### Acceptance criteria + +- The record `docs/specs/prompt-audit-skills-2026-09.md` exists with: stated assumptions (scope, target model), corpus, per-wave findings tables (file:line, evidence, pattern, why obsolete, confidence, action, label, catalog row), applied versus withheld, catalog gaps, and a `## Follow-ups` section. +- Every skill in scope has a row in the record: findings applied, findings withheld, or `clean`. +- Execution contract, per skill: audit report written to `.work/prompt-audit-skills/reports/.md`; accepted hunks applied; evals in step; `bash plugins/skill-quality/scripts/check-skill.sh ` passes (or the check was updated and its test updated); plugin commit landed with bump and CHANGELOG entry. Per wave: every plugin closed, record updated, handoff written. +- Static gates green on the branch: `scripts/affected-tests.sh --run`, `scripts/check-changelog-parity.sh --check`, `--check-bump origin/main`, `--check-preserved origin/main`, `--check-order`, `scripts/check-purged-em-dashes.sh`, markdownlint, `scripts/check-skill-precompute-compose.sh --all`. +- Behavioral spot-check recorded for wave 1's five most-used skills (session-flow handoff, orchestrate, keep-going, source-control commit, planning interview): before and after invocation on one fixture by a fresh subagent, difference described in the record. +- A path-scoped rule under `.claude/rules/` states the Group 2 history rule for `plugins/*/skills/**` and is indexed in AGENTS.md's on-demand table. +- A superseding ADR records every accepted ADR decision the audit contradicted (at minimum ADR 0004 D-1 and D-3, ADR 0006's applied-set gate). +- `docs/topics/prompt-audit-skills/PLAN.md` is graduated into the record and removed before the PR, so the contract-slice prune gate passes. +- The PR body carries the follow-up inventory verbatim from the record. + +### Captured assumptions + +- The bundled `claude-api` skill at Claude Code 2.1.258 is the current authority for prompt-audit; its guide and the Fable 5.1 migration sections are read from the session's bundled-skills directory. +- Local `skillUsage` counts from one machine are the usage signal; they rank session-flow, planning, and source-control first. +- Behavioral A/B across all 241 skills is not affordable; the record says so and routes behavior measurement to `claude-config:unhobble`. + +### Out-of-scope + +- Hooks prompt text, output styles, `.claude/rules`, `CLAUDE.md`, `AGENTS.md` as audit targets. +- Marketplace-level docs under `docs/` except the record, the new rule, the ADR, and conventions that tell skill bodies to carry archaeology. +- Pushing or opening the PR from a subagent. + +### Deferred questions + +- Q1 (arbiter: USER-RESERVED at PR time): whether the superseding ADR should also retire ADR 0005 and ADR 0008, decided once the audit shows what they blocked. + +## Follow-ups + +Inventoried here as they arise and shipped in the PR body verbatim. + +- F1. Write one superseding ADR covering every accepted ADR decision this audit contradicted (at minimum ADR 0004 D-1 and D-3, ADR 0006's applied-set gate); decide with the operator whether ADR 0005 and ADR 0008 are also retired. +- F2. Audit the out-of-scope prompt surfaces the same way: hooks prompt text, output styles, `.claude/rules`, `CLAUDE.md`, `AGENTS.md`, and the plugin-level `reference/` trees that skills load on invocation (`autonomy`, `architecture`, `performance`, `playbooks`, `rate-limit-guard`, `context-guard`); the performance auditor notes that `snapshot` and `verify` both mandate reading `plugins/performance/reference/harness-integrity.md`, which likely mirrors the archaeology the skill bodies shed. +- F3. Behavior measurement beyond the wave-1 spot-check: route to `claude-config:unhobble`. +- F4. Done before the PR: `docs/topics/prompt-audit-skills/PLAN.md` graduated into [Brief](#brief) and the slice was pruned (contract-slice prune gate); the PR body names the pre-prune commit. +- F5. `plugins/skill-quality/scripts/check-skill.sh` check 3 hard-fails any trigger phrase dropped versus the base ref. That blocks prompt-audit's documented fix for trigger-case enumeration (near-synonym lists become intent categories). Change check 3 to a warning, update its tests, and record the deliberately dropped phrases per skill in this record. Must land before the PR so the skill-quality CI gate passes. Landed in a694011bf; two out-of-scope surfaces still describe check 3 as a hard-FAIL gate and should follow: the comment at `plugins/docs-hygiene/skills/audit-noise/scripts/emit-findings.sh:220` and the eval fixture `plugins/docs-hygiene/skills/audit-noise/evals/fixtures/negation-trigger-fence.md:9` (the docs-hygiene commit corrected the same script's header comment and its eval case 12). +- F6. Verify and stamp the undated harness-behavior claims the audit flagged as `I12` items (session-flow: `/recap` trigger and the Skill-invocable allowlist, the usage-limit reset surface, `cleanupPeriodDays` default, `/clear` transcript and scheduled-task behavior). Each becomes a four-part upstream-drift record or a doc pointer. Collected per plugin as the waves run. source-control adds: GitHub `mergeStateStatus` precedence and `baseRefOid` staleness (freshness.md), the permission-mode and wrapper-strip claims in safety.md, and the ScheduleWakeup clamp, `/loop` expiry, Monitor-on-resume, and sandboxed-GraphQL claims across babysit-prs, babysit-loop, pull-request, and worktree. disk-hygiene adds four undated harness-version claims (`safety-model.md:262`, `:313`, `:315` on 2.1.207 and 2.1.218 `pluginConfigs` scope and PowerShell hook firing; `clean/SKILL.md:382` on the v2.1.211 auto-mode prompt). performance adds the undated benchstat `-delta-test` claim at `snapshot/SKILL.md:94-96`, and `plugins/performance/reference/harness-integrity.md` (out of audit scope, mandated reading for `snapshot` and `verify`) likely carries the run archaeology the four skill bodies shed (see F2). +- F7. `pull-request` hardcodes one vendor's review bot (login, emoji signalling, timing) in `reference/monitor.md` gotchas and `reference/readiness.md` Gate 5, against the file's own "discover actors, don't hardcode them" rule. Parameterize Gate 5 on the discovered reviewer login and move the vendor shapes into a dated reference-shapes note with a recheck trigger. +- F8. `source-control` cites sibling-plugin files by relative path (`../../../../autonomy/...`, `../../../../../prompts/...`) in `babysit-loop/reference/promotion-evidence-resolution.md` and `babysit-prs/reference/safety.md`. Those resolve only in the marketplace checkout, never in an installed plugin. Convert to the raw-URL form the plugin already uses at `babysit-loop/SKILL.md:40`. review adds: `agents/ecosystem-specialist.md:22`, `fanout/context/fix-pass-mode.md:7`, `quality-gate/context/close-out.md` (four sites), and `quality-gate/context/spec.md` (three sites) cite marketplace `docs/` paths or sibling-plugin files by relative path. review also adds two undated claims to F6: the bundled `/code-review` and managed Code Review service tiers in `quality-gate/context/pr.md` and `code.md`, and the "built-in `/security-review` is unusable in CI" claim in `security-review/SKILL.md`. The autonomy applier converted six of that plugin's own convention and sibling citations to marketplace URLs; those were reverted to the relative form before the PR because `scripts/validate-plugin-contracts.mjs` forbids the autonomy plugin naming the org or a vendor, so the autonomy sites stay under this follow-up. +- F9. `planning/skills/wayfind/SKILL.md` pre-compute silently coerces a non-string `container_label` to `work-map`, which `context/tracker-mechanics.md` says is a configuration error that must never proceed. Make the pre-compute fail loud or surface the raw value, matching the doc. +- F11. `work-items` carries the same 60-line lane-telemetry upsert as a fenced shell block in `work-loop/reference/telemetry-upsert.md` and `attend-queue/reference/telemetry-upsert.md`, transcribed by the model on every cycle, with a classifier-fallback section asking it to re-derive gate order by hand (prompt-audit Group 4, an LLM executor for a deterministic plan). Extract it into `plugins/work-items/scripts/lane-telemetry-upsert.sh` with a co-located test, taking lane, instance, repo, issue, and body-file arguments and exiting non-zero on each refusal branch; both references then invoke it. Deferred from the audit because it is a mechanism change, not a prose hunk. work-items also adds six undated harness and `gh` claims to F6 (classifier refusals of `permissions.allow` widening and of the `reclaim` call, the compound-shell block, sandboxed GraphQL 403). +- F12. `shell: bash` frontmatter selects the shell for `!`...`` injections. Skills whose pre-compute block became empty when the git lines moved into body calls still carry the key inert (debugging F5 found one). Sweep every SKILL.md: where no injection remains, drop the key; `check-skill.sh` check 19 stays green either way. +- F13. `playbooks:boris` presents Fable 5 as the current top model and its launch-era classifier behavior as current (`skills/boris/SKILL.md:58,133`); upstream has not published Fable 5.1 tips. Re-sync through `/playbooks:update` when it does, and until then qualify the Model row "as of the 2026-07-24 sync". +- F14. The `fable-5` playbook's own regeneration trigger ("a model-version change", `skills/update/SKILL.md:39`) has fired with Fable 5.1. The audit adds the guide-backed minimum, a `fable-5-1.md` adaptation chapter; regenerating the whole pack from Fable 5.1 is the maintainers' larger call. playbooks also adds to F8: `reference/model-adaptation/opus-5.md:207-208` cites a probe record (`thinking-off-probe-2026-07-26.md`) that exists nowhere in the repository. And to F6: the cache-pricing stamp at `skills/fable-5/context/orchestration.md:97` carries a date but no recheck trigger. +- F15. The statusline compose transform in `unwrap-before-compose.md` (synced between `context-guard` and `rate-limit-guard`) is a pure function of the effective `statusLine` string that the model hand-executes over roughly a hundred lines of prose, with eight eval cases checking the arithmetic (prompt-audit Group 4). Extract it into a synced `scripts/compose-statusline-wiring.sh` with the round-trip check inside, shrink the reference to the contract, and turn those eval cases into script tests. Deferred from the audit as a mechanism change. rate-limit-guard also adds to F6: the undated "Monitors is an experimental Claude Code component" claim in `reference/reader-contract.md:206-209`. +- F16. `claude-ops/skills/plugins/SKILL.md:268-276` records that its own probe's recheck trigger has fired (the CLI moved from 2.1.218 to 2.1.240 with the claim un-retested). Re-run the probe and refresh the stamp. claude-ops also adds nine undated harness and upstream-issue claims to F6 (bundled `doctor` gating, `audit-native-overlap` alias examples, `inventory` command aliases, the WebFetch truncation window, the `CLAUDE_PLUGIN_DATA` export claim, the `lanes` "verified on this machine" lines, the `observability` `session_id` and Stop-hook gotchas, upstream issue states in `read-routing.md` and `sync.md`, and the triggerless `surfaces.md` stamp) and two measured figures (`backups/` retention, the 97 percent and 50 MB figures in `observability`). `plugins/repo-fleet-hygiene/skills/audit/scripts/audit-fleet.test.sh` fails 5 of 180 cases on this host (the worktree-root-unconfigured placement and header cases, the symlink discovery-root case, the intermediate-symlink case, and the unreadable discovery-root case); the scripts are untouched by the repo-fleet-hygiene commit and the finding-kind table assertion passes. +- F17. `context-guard/skills/setup/SKILL.md` runs four fixed read-only probes (jq presence, installed shim versus shipped source, session snapshot, `zones.json`) as model-issued Bash calls where a `## Pre-computed context` block would run them before the body loads (prompt-audit Group 4). Adding one is a mechanism change: the block must pass `scripts/check-skill-precompute-compose.sh` and stay inside the worktree guard's rule that a composed block expands nothing but bare `$HOME`, so it is deferred from the audit. context-guard also adds to F6: the undated `disableAllHooks` / `allowManagedHooksOnly` claims in `skills/setup/SKILL.md:93-96` and `reference/reader-contract.md:503-507`, the undated PowerShell routing note in `statusline-edit.md:106-109`, and the folklore-number paragraph at `reader-contract.md:383-391`, which is dated but has no recheck trigger. +- F18. `autonomy/reference/autonomous-pipeline-reminder.md` (out of audit scope; cited only by the README and a hook) rewords the vendor's autonomy block under the repo's no-copy rule and omits the Fable 5.1 clause "Do not stop because the context or session is long"; the guide calls the opening sentence load-bearing as written. Weigh the no-copy rule against that claim and add the missing clause in the plugin's own words. autonomy also adds to F6: the undated `AGENTS.md`-reachability claim stated three times (`skills/setup/SKILL.md:267`, `context/prerequisite-resolution-slice.md:38-39`, `reference/prerequisite-resolution.md:86-88`), the undated empirical telemetry claims in `reference/telemetry.md`, and the "shipped first-party mechanisms today" claims in `reference/runner/escalation.md:140-152`. +- F19. `plugin-quality/skills/audit/SKILL.md:58-92` has the model resolve the context zone by hand from inlined band tables, a staleness window, a version floor, and a combination rule that `plugins/context-guard/scripts/context-zone.sh` already implements (prompt-audit Group 1b and Group 4). Ship a byte-identical synced copy at `plugins/plugin-quality/scripts/context-zone.sh` with its test, register it in `scripts/cross-plugin-source-registry.txt` with a `sync-context-zone.sh --check` entry, and have the gate and `setup/SKILL.md:28-30` call it. Deferred from the audit as a mechanism change. plugin-quality also adds to F6: two live doc-page titles quoted undated in `agents/auditor.md:117-119`, the `context: fork` and cloud-scoping claims in `references/component-types/skill.md:18-24`, and six dated stamps with no recheck trigger. skill-quality adds to F6: three undated harness claims outside the dated stamp in `check/SKILL.md:160-172`, and the `setup/SKILL.md:16-20` stamp that has no recheck trigger. instruction-placement adds to F6: the undated "other agents resolve nearest-wins" claim in `realign/context/apply-recipes.md:95-97`. context-budget adds to F6: the `v2.1.232` measurement at `audit/SKILL.md:226-228`, the `/doctor` availability and `disableModelInvocation` claim at `audit/SKILL.md:34-36`, the cited-but-undated mechanism claims in `audit/reference/engine.md:25-30` with the dangling "verified version" referent at `:52-53`, and the wall-clock range at `audit/SKILL.md:93`. computer-use adds to F6: the dated surface table in `diagnose/SKILL.md:62-63` and the dated basis in `diagnose/reference/windows-quirks.md:5-6`, both without a recheck trigger. overengineering adds to F6: the undated harness-behavior claim in the gather blocks of all three skills (`audit/SKILL.md:20-23`, `delta/SKILL.md:19-23`, `realign/SKILL.md:19-22`, covered by the one dated record the worktree skill will own) and the undated `/loop` capability claims in `delta/context/recurring-wiring.md:37-38,51-53`. improvement adds to F6: four undated GitHub REST and Claude Code CLI claims in `find/context/ci-health.md:32-41`, `find/SKILL.md:235-237`, and `find/context/unattended.md:74-75`. docs-hygiene adds to F6: the bundled `/batch` skill claim in `extract-ssot/actions/batch.md:35,281`, four undated external benchmark figures across `extract-ssot/SKILL.md:27`, `context/anti-patterns.md:129`, and `context/decision-framework.md:27-59`, and the undated upstream-publishing claim in `audit-encapsulation/context/public-surface-contract.md:5`. code-tidying adds to F6: the CodeScene agentic-refactoring figure in `tidy/reference/scope-budget.md` "Research lineage" has no resolvable source; the audit dropped the number and kept the qualitative claim until a publication URL and read date are recorded. repo-hygiene adds to F6: the sourced-but-undated `${CLAUDE_SKILL_DIR}` substitution-scope claim in `clean/reference/invocation-forms.md`. disk-hygiene adds to F6: four undated harness-version claims across `clean/SKILL.md` and `clean/reference/safety-model.md` (report F15). codebase-health adds to F6: the undated harness-capability claim at `audit/SKILL.md:25-28`, verified true by the auditor on 2026-09-04 and needing only its dated record. architecture adds to F6: the undated pre-compute execution claim at `improve/SKILL.md:25-28`. mcp-tools adds to F6: three cited-but-undated Claude Code client-behavior values in `audit/reference/checklist.md:38,105,106`. performance adds to F6: the undated benchstat flag-set claim in `snapshot/SKILL.md:94-96`. +- F20. `provenance/skills/audit` spells one tier two ways: `not-found` in `SKILL.md:2,82,227` and `source-not-identified` in `reference/rubric.md:297`, and `scripts/emit-findings.sh` with its test asserts both. Pick one spelling, change the script and `emit-findings.test.sh` with it, and align the markdown in the same commit. Deferred from the audit because the fix crosses into a script and its suite. +- F21. `mutation-testing/skills/setup/SKILL.md:80-89` has the model re-derive a suppression entry's `finding_id` hash from its constituents and check node-kind membership by hand (prompt-audit Group 1b and Group 4, the same shape as F19). Ship `plugins/mutation-testing/scripts/suppression-lint.sh` with a test implementing the two published derivations and the membership check, have setup call it, and retarget setup eval 5 and audit eval 3 from "the model re-derives" to the script. Deferred from the audit as a mechanism change. +- F22. `plugins/ai-briefing/skills/setup/evals/evals.json:33` prompts `/ai-briefing:setup --with-build-deps`, but the skill's contract is `apply install-build-deps`; the case exercises a flag the skill does not accept. Retarget the prompt to the contract form. Observed by the ai-briefing auditor outside the audit's markdown scope. +- F23. `plugins/dometrain/skills/sync/context/update.md` documents the maintainer-only `--refresh-baseline` command through `${CLAUDE_PLUGIN_ROOT}`, which resolves to the installed plugin cache in a normal session, while the next paragraph forbids running it anywhere but a working clone; the script writes next to itself either way. Give the command as a clone-relative path, or document that the flag is only safe under `--plugin-dir`. A script-safety contradiction, not a prose hunk; observed by the dometrain auditor. +- F24. Add a criteria row to `plugins/claude-config/skills/audit-instructions/reference/criteria.md` for each recurring shape in [Catalog gaps](#catalog-gaps): dated stamps with no recheck trigger, migration-relative phrasing inside reference and context files, routing text that names a skill absent from `plugins/`, sibling-file meta-commentary, and maintainer rationale inside model-facing YAML comments; the rest are one-offs and stay listed. +- F10. Not an audit finding, recorded so it is not mistaken for one: `.claude/hooks/cloud-bootstrap-plugins.test.sh` fails 15 of 32 assertions on this Windows host ("not installed at user scope") with `.claude/cloud-bootstrap.sh` and the suite byte-identical to `origin/main`. The failure is environmental or pre-existing; confirm on CI and file separately if it reproduces there. Same status for `plugins/docs-hygiene/skills/audit-noise/scripts/emit-findings.test.sh` ("tier is looked up as IMPORTANT", "Location is repo-relative") and `plugins/provenance/skills/audit/scripts/list-corpus.test.sh` and `emit-findings.test.sh` ("a directory target lists its markdown"), which fail on this host with their scripts and suites byte-identical to `origin/main`. Same again for `plugins/work-items/skills/onboard-adapter/scripts/generate-adapter.test.sh` case 116, and for the nine eval-case digest assertions in `plugins/planning/tests/interview-defenses.test.sh` (`interview/evals/evals.json` unchanged since the digests were pinned; local jq 1.8.2), and for four Windows temp-path cases in `plugins/instruction-placement/scripts/verify-load.test.sh` (selected by a basename collision on `typescript.md`; the probe and suite are unchanged on this branch), and for `plugins/claude-ops/skills/audit-install-state/scripts/install_state.test.sh` (a Windows filename-syntax error on a fixture path) and `plugins/claude-ops/skills/audit-skill-visibility/scripts/audit_skill_visibility.test.sh` (no `installed_plugins.json` in the temp config), both with scripts and suites byte-identical to HEAD, and for `plugins/claude-ops/skills/plugins/scripts/fleet-state.test.sh`, which fails a varying subset of its 74 cases on this host (six inside a check-skill run, two when run alone) with the scripts byte-identical to `origin/main`. Same again for `plugins/claude-config/skills/audit-instructions/scripts/restatement-scan.test.sh` (two I29 fixture cases, script and fixtures byte-identical to `origin/main`) and the one `emit-findings.test.sh` case downstream of it ("Action names a body cut"), which reads the same scanner's output. Same again for `plugins/claude-config/skills/audit-permission-grants/scripts/permission-rule-check.test.sh` case 6b ("vendored copies excluded, exactly one finding"), whose script and suite no branch commit touched (main has since tidied the suite in ac7eeeac8). The fleet gather block itself ("the harness runs a skill's whole pre-compute block as one shell invocation") is an undated harness claim in about 55 skills; one dated four-part record on the worktree skill, which owns the mechanism, with the copies pointing at it, clears every site at once. discovery adds six undated claim families across thirteen files (silent preload failure, `AskUserQuestion` and plan-mode tools filtered from non-fork subagents, the Workflow tool absent from subagents, background as the default execution mode, spawns permission-classified before launch); the fix is one dated record per claim in the plugin's `reference/parent-contract.md` with the skills pointing at it. claude-config adds the undated `pre-v2.1.211` boundary at six body sites (the dated owner is `audit-permission-state/reference/criteria.md`), dated-but-triggerless stamps across eight files, the `conflict-scan.sh` precision figures in `conflict-criteria.md`, and the "Fable 5 subpage" pointers in `audit-prompting-postures/reference/postures.md` that need a Fable 5.1 sibling once it exists. discipline adds five files of undated fork-mode harness claims (`sweep-all/SKILL.md`, its two references, `scrutinize-dont-coast/SKILL.md`, `use-your-skills/SKILL.md`). claude-memory adds the undated upstream-issue state at `audit/reference/official-guidance.md:168`. testing adds the xUnit v3 and .NET 10 framework-trap claims (`diagnose/SKILL.md:68`, `diagnose/context/investigate.md:16`, `write/SKILL.md:74`) and the `playwright-cli` version floor in `run-e2e/context/e2e.md:12`. planning also adds two undated harness claims to F6: the agent-teams "experimental, default-off" status in `plan/SKILL.md` and the "cannot read effort or advisor state" claim in `interview/context/session-config.md`. `plugins/ai-slop/skills/audit/scripts/detect.test.sh` fails its four "git absent" cases (4 of 202) on this Windows host because the test symlinks the shell builtin `printf` into a fake PATH directory (`ln: failed to create symbolic link`); the scripts are unchanged by the ai-slop commit. `plugins/disk-hygiene/skills/clean/scripts/guard_launch_monitor.test.sh` fails its two telemetry-sink cases and `hygiene.test.sh` fails `test_stash_must_exist_in_an_independent_checkout` and `test_preview_allows_root_children_os_managed_snapshot` on this host with the scripts byte-identical to HEAD; neither case reads markdown, and the frontmatter-belt assertions in `test_hygiene.py` that do read `clean/SKILL.md` pass after the disk-hygiene commit. `plugins/code-tidying/skills/audit-comment-residue/scripts/detect.test.sh` fails 4 of 53 cases on this host (embedded quote and backslash unescaping in the preview script, arrow-in-filename, tab-bearing path) with `detect.sh` and the suite byte-identical to HEAD; the code-tidying commit touches only prose the script does not read. `plugins/knowledge/skills/docpage-digest/scripts/check-fences-exact.test.sh` fails six cases on this host with a `UnicodeEncodeError` writing U+2265 to the cp1252 console, script and suite byte-identical to HEAD; the knowledge commit touches no fence, quote payload, or script. `plugins/education/skills/teach/scripts/list-workspaces.test.sh` fails "worktree lists the MAIN repo's workspace" on this worktree checkout with the script unchanged. diff --git a/plugins/actionlint/.claude-plugin/plugin.json b/plugins/actionlint/.claude-plugin/plugin.json index 75ba0f747e..1c255e6b03 100644 --- a/plugins/actionlint/.claude-plugin/plugin.json +++ b/plugins/actionlint/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "actionlint", - "version": "0.8.35", + "version": "0.8.36", "description": "Lint GitHub Actions workflow files on edit via actionlint, surfacing findings as advisory context.", "author": { "name": "Melodic Software", diff --git a/plugins/actionlint/CHANGELOG.md b/plugins/actionlint/CHANGELOG.md index 1cf73e2a08..2ecc116264 100644 --- a/plugins/actionlint/CHANGELOG.md +++ b/plugins/actionlint/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to the `actionlint` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.8.36] + +### Changed + +- **setup:** the `stdin_read_timeout` gotcha states the declare-it rule without naming the plugin + that declared it first. +- Applied from the 2026-09 prompt-audit against Claude Fable 5.1 + (docs/specs/prompt-audit-skills-2026-09.md). + ## [0.8.35] ### Changed diff --git a/plugins/actionlint/skills/setup/SKILL.md b/plugins/actionlint/skills/setup/SKILL.md index 2babc8dfeb..3ca32761db 100644 --- a/plugins/actionlint/skills/setup/SKILL.md +++ b/plugins/actionlint/skills/setup/SKILL.md @@ -91,7 +91,7 @@ Re-running `apply` after everything passes changes nothing and reports "already manifest". An undeclared key silently cannot be set through native config surfaces (a raw settings `env` block still works). That is why `stdin_read_timeout` is declared in this plugin's manifest even though the shared hook lib supplies its default; hook plugins reusing - the shared lib should declare it too (claude-ops set the precedent). + the shared lib should declare it too. - **`--config`'s post-install behavior is undocumented, so the guidance above rests on observation.** The official docs describe `--config` only as a `claude plugin install` flag and say nothing about an already-installed plugin. The verified-version record — which CLI diff --git a/plugins/adhd/.claude-plugin/plugin.json b/plugins/adhd/.claude-plugin/plugin.json index 5b52fbc339..473aaea4c4 100644 --- a/plugins/adhd/.claude-plugin/plugin.json +++ b/plugins/adhd/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "adhd", - "version": "0.4.6", + "version": "0.4.7", "description": "Shape and restructure the assistant's output for a reader with ADHD — action-first, low-friction, and digestible. adhd:shape is a standing session posture: lead with the concrete next action, number multi-step work, restate state across turns, cap and rank lists, give concrete time estimates, make wins visible, and cut preamble, recap, and closers. adhd:clarify is a one-shot reshape of a dense, decision-heavy artifact already on screen — chunk it one-decision-at-a-time, define the session's own jargon, and surface exactly what you must decide, faithfully (operative terms quoted verbatim, no altitude loss), rendered as an HTML decision table for big content. Reauthored in part from ayghri/i-have-adhd (MIT). Deliberately mutually exclusive with terse-for-tokens output shapers like caveman — opposite objectives.", "author": { "name": "Melodic Software", diff --git a/plugins/adhd/CHANGELOG.md b/plugins/adhd/CHANGELOG.md index fcc09a36e4..2780305d91 100644 --- a/plugins/adhd/CHANGELOG.md +++ b/plugins/adhd/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to the `adhd` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.4.7] + +### Changed + +- **shape:** the Gotchas section keeps the compaction note and drops the dated audit header and the + two bullets that restated the conflicting-shaper check and the rule 5 boundary test; rule 10 + states the no-preamble rule positively with one illustrative weak-versus-strong pair instead of + an exhaustive banned-phrase list. +- **clarify:** the scratchpad rule states its reason without narrating upstream's decision. +- Applied from the 2026-09 prompt-audit against Claude Fable 5.1 + (docs/specs/prompt-audit-skills-2026-09.md). + ## [0.4.6] ### Changed diff --git a/plugins/adhd/skills/clarify/SKILL.md b/plugins/adhd/skills/clarify/SKILL.md index 7c9be077a1..e824713721 100644 --- a/plugins/adhd/skills/clarify/SKILL.md +++ b/plugins/adhd/skills/clarify/SKILL.md @@ -146,8 +146,8 @@ this invocation, and nothing documented reclaims the OS temp tree on a schedule, so write one file per run and never an accumulating tree. Resolve that one path deterministically: never branch on whether the harness injected a scratchpad path or set -`CLAUDE_JOB_DIR`, and never depend on the session scratchpad, which is an -undocumented surface upstream has declined to support. Do not rely on a +`CLAUDE_JOB_DIR`, and never depend on the session scratchpad, which is +undocumented. Do not rely on a plugin-data substitution variable for this location either: skill-body substitution is documented only for a fixed set of variables, and an undocumented token can substitute unpredictably (including to the wrong diff --git a/plugins/adhd/skills/shape/SKILL.md b/plugins/adhd/skills/shape/SKILL.md index 22c79807f4..ee347eef37 100644 --- a/plugins/adhd/skills/shape/SKILL.md +++ b/plugins/adhd/skills/shape/SKILL.md @@ -137,16 +137,16 @@ over shaping. A 7-decision table renders all 7 rows. ### 10. No preamble, no recap, no closers - -- Forbidden openers: "Great question," "Let me…," "I'll…," "Sure!," "Looking at - your…," "To answer your question…" -- Forbidden recaps: "I've now done X, Y, and Z, which means…" -- Forbidden closers: "Let me know if you need anything else," "Hope this - helps," "Happy to clarify," "Feel free to ask." +Start with the answer. Stop when the answer is done. Do not open by announcing +what you are about to do, do not restate what you just finished, and do not +close with a pleasantry or an offer of further help. + + +- Weak: "Great question. Let me look at your project…" at the top, "Hope this + helps, let me know if you need anything else" at the bottom. +- Strong: the answer, then nothing. -Start with the answer. Stop when the answer is done. - ## When to override these defaults Drop the brevity rules, never the flat, preamble-free tone, when: @@ -177,22 +177,10 @@ Then check: reading only the first line and the last line, does the reader know ## Gotchas -Observed failures from a live audit of this skill (adhd@0.2.0, 2026-07-23): - -- **Applied silently alongside an active conflicting shaper.** With caveman's - hooks injecting terse-for-tokens instructions, invoking this skill produced - the exact "contradictory, unpredictable mix" the README warns about, with no - conflict flagged. The warning lived only in README/plugin.json, layers the - model never reads at invocation time. The conflicting-shaper check above is - the fix; it is advisory by necessity (no documented skill-to-hook detection - mechanism exists). - **The standing posture erodes across context compaction.** "Applies for the - rest of the session" is content-based persistence: when the conversation is - summarized/compacted, the rules can drop out of context. Re-invoke - `/adhd:shape` after a compaction if responses stop being shaped. -- **Rules 5 vs 10 read as contradictory without the boundary test.** "Restate - state every turn" vs "no recap". The explicit test now lives in rule 5 - (last-completed step + next step only; never a running done-list). + rest of the session" is content-based persistence, so a summarized or + compacted conversation can drop these rules out of context. Re-invoke + `/adhd:shape` if responses stop being shaped. ## Attribution diff --git a/plugins/ai-briefing/.claude-plugin/plugin.json b/plugins/ai-briefing/.claude-plugin/plugin.json index 12125b404b..a7c8b01861 100644 --- a/plugins/ai-briefing/.claude-plugin/plugin.json +++ b/plugins/ai-briefing/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "ai-briefing", - "version": "0.7.25", + "version": "0.7.26", "description": "Build source-backed AI-industry briefings from official vendor publications, configured RSS/Atom feeds, GitHub releases, reputable secondary reporting, and user-supplied URLs. Deduplicate, rank, and present results as markdown or optional HTML/PPTX decks, with repository-owned profile, audience, and brand configuration. Automated X/Twitter collection is disabled; Playwright is used only for deterministic local rendering.", "author": { "name": "Melodic Software", diff --git a/plugins/ai-briefing/CHANGELOG.md b/plugins/ai-briefing/CHANGELOG.md index d511374e39..9ea35b51ec 100644 --- a/plugins/ai-briefing/CHANGELOG.md +++ b/plugins/ai-briefing/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to the `ai-briefing` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.26] + +### Changed + +- **generate:** the build-pipeline and slide-generation references now describe the shipped + pipeline. Dropped the `flair` slide type the Zod schema has no case for, dropped the phantom + `lib/holidays.js` and `providers.md` pointers, added the build and `lib/` modules the pipeline + inventory never named, replaced the prev/next and swipe navigation description with the + sectioned-scroll behavior, pointed the validator gate list at the script's own header instead + of restating it, replaced the Node 20 requirement and its passed end-of-life trigger with a + pointer to the setup preflight, dropped step numbers that no longer match the skill, labelled + the in-repo prerequisites so consumers take the setup path, removed the stale-reference and + skill-inventory tables, and lowered all-caps emphasis to plain prose. +- **generate:** the audience-defaults reference now names the loading step in words rather than + by a step number the skill no longer uses. A second pass removed the last two `flair` mentions + and one `build/shots/` path the first pass left in `build-pipeline.md`. +- Applied from the 2026-09 prompt-audit against Claude Fable 5.1 + (docs/specs/prompt-audit-skills-2026-09.md). + ## [0.7.25] ### Changed diff --git a/plugins/ai-briefing/skills/generate/reference/audience-defaults.md b/plugins/ai-briefing/skills/generate/reference/audience-defaults.md index d35533124c..d474dd114b 100644 --- a/plugins/ai-briefing/skills/generate/reference/audience-defaults.md +++ b/plugins/ai-briefing/skills/generate/reference/audience-defaults.md @@ -1,8 +1,9 @@ # Audience defaults for /ai-briefing:generate The engine's **default** audience framing, pragmatic-use ranking lens, and apolitical -filter. Loaded by S4 categorize (ranking) and Step 4.5 enrichment (impact tag). These -are documented, **overridable** defaults: a consumer profile can refine or replace them +filter. Loaded at the categorize-and-rank step of `/ai-briefing:generate`, and again for the +optional per-item impact tag. These are documented, **overridable** defaults: a consumer +profile can refine or replace them (a profile's `audience.md` in `.claude/ai-briefing/[/]` may refine this file). ## Pragmatic-use filter (ranking lens) diff --git a/plugins/ai-briefing/skills/generate/reference/build-pipeline.md b/plugins/ai-briefing/skills/generate/reference/build-pipeline.md index 474db02e10..f5ce546224 100644 --- a/plugins/ai-briefing/skills/generate/reference/build-pipeline.md +++ b/plugins/ai-briefing/skills/generate/reference/build-pipeline.md @@ -3,7 +3,7 @@ ## Contents - [Pipeline files](#pipeline-files) -- [Prerequisites — one-time setup](#prerequisites--one-time-setup) +- [Prerequisites, one-time setup (in-repo maintainer form)](#prerequisites-one-time-setup-in-repo-maintainer-form) - [Per-meeting build sequence](#per-meeting-build-sequence) - [AI-in-loop checkpoints](#ai-in-loop-checkpoints) - [`slides-data.js` schema](#slides-datajs-schema) @@ -13,32 +13,44 @@ - [PDF output](#pdf-output) - [validate.js gates](#validatejs-gates) - [Drift / recheck triggers](#drift--recheck-triggers) -- [Slide/HTML/PDF generation (Step 5 detail)](#slidehtmlpdf-generation-step-5-detail) +- [Slide/HTML/PDF generation detail](#slidehtmlpdf-generation-detail) Canonical pipeline for `--format slides|html` reproducing the deck (brand tokens in `output/build/brand.js`). Lives at `output/build/` under the skill. -This file documents the working pipeline schema + commands. For brand spec / slide order / split rules / provider logos, see `slide-generation.md`. For provider buckets / query templates, see `providers.md`. +This file documents the working pipeline schema + commands. For brand spec, slide order, split rules, provider buckets, and provider logos, see `slide-generation.md`. ## Pipeline files | File | Role | Output | |---|---|---| | `run.js` | **Orchestrator** — chains emit → build (pptx+html+pdf) → validate. Single entrypoint | drives the chain | -| `emit-slides-data.js` | **Emitter** — reads briefing markdown + state, writes `slides-data.js`. Holiday-aware flair. Pre-flight provider-logo fetch. Zod schema validates before writing | `slides-data.js` | +| `emit-slides-data.js` | **Emitter** — reads briefing markdown + state, writes `slides-data.js`. Pre-flight provider-logo resolution. Zod schema validates before writing | `slides-data.js` | | `slides-data.js` | **Generated** — slide content per current meeting. Do NOT hand-edit; re-run emitter. | data module consumed by build-* scripts | | `lib/parse-briefing.js` | Markdown AST parser (remark + remark-gfm) — H2 buckets → H3 tiers → bullet items | — | | `lib/emit-slides.js` | Items → slide objects (canonical order, HIGH≤5 split, MED≤14 split, cross-provider clusters, patterns synthesis) | — | -| `lib/holidays.js` | Run-date → holiday theme (US federal via date-holidays + tech custom map) | — | | `lib/schema.js` | Zod discriminated union — 11 slide types, meta, theme, providerLogos | — | | `lib/provider-logos.js` | Resolves bundled provider SVGs; missing optional assets downgrade to text-only headers without network access | — | +| `lib/paths.js` | Resolves the build root and the per-profile state root every generated artifact is written under | — | +| `lib/brand-overlay.js` | Overlays a schema-validated profile `brand.json` on the neutral engine defaults | — | +| `lib/window.js` | Parses and renders the briefing header's `Window:` line | — | +| `lib/url-policy.js` | | — | +| `lib/url-display.js` | Shared URL display formatter used by the HTML build and the validator | — | | `build-pptx.js` | pptxgenjs ESM — provider-aware decorate(), 11 slide types | `../meetings/ai-meeting-{N}.pptx` | -| `build-html.js` | Single-file HTML emitter — inline base64 org logos + inline SVG provider logos via `currentColor`; keyboard nav, prev/next buttons, touch swipe, hash deep-link, `?print=1` flag | `../meetings/ai-meeting-{N}.html` | +| `build-html.js` | Single-file HTML emitter — inline base64 org logos + inline SVG provider logos via `currentColor`; keyboard section stepping, chip-strip navigation, hash deep-link, `?print=1` flag | `../meetings/ai-meeting-{N}.html` | +| `build-sections.js` | Section grouping and HTML fragment generation for the deck | consumed by `assemble-html.js` | +| `build-css.js` | CSS generation for the deck | consumed by `assemble-html.js` | +| `build-client-js.js` | Client-side JavaScript for the deck (keyboard nav, scroll-spy, print mode) | consumed by `assemble-html.js` | +| `assemble-html.js` | Assembles the single-file sectioned-scroll HTML deck from the build modules | consumed by `build-html.js` | | `build-pdf.js` | Playwright headless chromium prints `?print=1` HTML to Letter landscape, 0-margin, one slide per page | `../meetings/ai-meeting-{N}.pdf` | -| `validate.js` | 6-gate validator — Zod schema, URL/headline coverage, console errors, content-slide overflow, linkinator URL reach, PDF text coverage (unpdf), PPTX slide count match (node-pptx-parser). Screenshots all slides | `build/shots/*.png` + `build/shots/audit.json` | +| `validate.js` | Multi-gate validator. The gate list and which gates block live in the script's own header comment; read it rather than restating it here. Screenshots every section | `shots/section-*.png` + `shots/responsive-*.png` + `shots/audit.json` | | `assets/` | Bundled org logos (PNG) + provider logos (SVG) | — | | `package.json` | `playwright` + `pptxgenjs` + `remark-parse` + `remark-gfm` + `unified` + `unist-util-visit` + `zod` + `date-holidays` + `linkinator` + `unpdf` + `node-pptx-parser` | — | -## Prerequisites — one-time setup +## Prerequisites, one-time setup (in-repo maintainer form) + +As a consumer, skip this: run `/ai-briefing:setup apply install-build-deps` instead, and read +"Plugin form" below. The commands here are for a maintainer working in the repository, where +the build tree is writable. ```bash cd output/build @@ -51,8 +63,9 @@ The committed lockfile is authoritative for dependency versions; [`npm ci`](http fails instead of rewriting a mismatched lockfile. [Playwright couples each library release to compatible browser binaries](https://playwright.dev/docs/browsers), so rerun the browser install after a Playwright update. `--only-shell` is appropriate because this pipeline -launches Chromium headlessly without a browser channel. Node 20+ is required (ESM imports + -top-level await). On Windows / Git Bash, use `pwsh` for npx if `npx.cmd` resolution flakes. +launches Chromium headlessly without a browser channel. The supported Node versions are the +ones `/ai-briefing:setup` preflights; the plugin README carries the dated record. On Windows / +Git Bash, use `pwsh` for npx if `npx.cmd` resolution flakes. **Plugin form.** The plugin cache is read-only and the scripts are Node ESM (which ignores `NODE_PATH`), so `/ai-briefing:setup apply install-build-deps` **stages a runnable copy** of the build tree under `${CLAUDE_PLUGIN_DATA}/runtime/build/` with `node_modules` installed as a sibling. The skill resolves the rendered `${user_config.active_profile}` value (or a per-invocation override) and passes it explicitly when launching the build: `AI_BRIEFING_PROFILE="$PROFILE" node "${CLAUDE_PLUGIN_DATA}/runtime/build/run.js"`. Emitted `slides-data.js`, decks, and screenshots land under `${CLAUDE_PLUGIN_DATA}//output/`. Setup re-stages the optional build tree on a plugin-version bump when `apply install-build-deps` is invoked. @@ -69,15 +82,15 @@ node run.js ```bash node emit-slides-data.js # Step 1 — emit slides-data.js from briefing.md -# AI overseer reviews slides-data.js: tier assignments, headline phrasing, flair candidates, +# AI overseer reviews slides-data.js: tier assignments, headline phrasing, # patterns synthesis, cluster placement. Edit slides-data.js directly OR re-run emit with overrides. node build-pptx.js # Step 2a — pptx node build-html.js # Step 2b — html node build-pdf.js # Step 2c — pdf -node validate.js # Step 3 — quality gates (Zod, URLs, overflow, links, PDF, PPTX) -# AI overseer reviews build/shots/slide-*.png + build/shots/audit.json before ship. +node validate.js # Step 3 — quality gates +# AI overseer reviews shots/section-*.png + shots/audit.json before ship. ``` **Skip-emit** (rebuild from edited slides-data.js): @@ -92,7 +105,7 @@ node run.js --skip-emit node emit-slides-data.js --meeting-n 21 --briefing ../meetings/meeting-21.md --date 2026-05-22 ``` -`validate.js` exits non-zero on **blocking** issues only (schema violation, URL coverage gap, console errors, content-slide overflow). Warnings (broken external links, PDF URL coverage gap, PPTX slide-count drift) print but do not block. **Treat warnings as overseer-review items** — AI looks at the audit, decides whether to ship or iterate. +`validate.js` exits non-zero on blocking issues only and prints warnings without blocking. The script's `issues.blocking` and `issues.warnings` pushes are the authority for which is which; read them rather than assuming from this file. **Treat warnings as overseer-review items** — AI looks at the audit, decides whether to ship or iterate. ## AI-in-loop checkpoints @@ -101,14 +114,13 @@ Scripts make pipeline **efficient**, not autonomous. Overseer (Claude or human) | Gate | Script does | Overseer does | |---|---|---| | **Briefing → slides-data emit** | Parses markdown, partitions tiers, splits HIGH/MED, places clusters, fetches logos, validates schema | Reviews emitted `slides-data.js`: are tier assignments right? Are headline truncations preserving meaning? Should any item be promoted/demoted? Edit and re-run | -| **Flair candidates** | Picks holiday theme from run-date; emits placeholder `flair` slide with curate-your-own slot | Reviews `holiday.searchHooks`, runs Perplexity/WebSearch for candidates, vets each for apolitical filter (drop politician deepfakes, keep brand parodies/science weirdness), edits `slides-data.js` `FLAIR.items[]` | | **Patterns synthesis** | Emits stub `patterns` slide based on bucket presence | Reviews stub, replaces with curated cross-bucket themes the briefing actually surfaces — not a generic stub | | **Apolitical filter** | Doesn't filter — passes everything through | Drops partisan-only items at briefing-emit time AND re-validates at slides-emit (defense in depth) | | **Cross-provider clusters** | Routes "Legal", "Compute", "Real-world" H2 sections to dedicated slides | Decides if a sub-bullet inside another bucket should be promoted to a cluster slide (e.g., a Microsoft item that's actually a Musk-v-Altman co-defendant detail) | -| **Visual review** | Screenshots all 43 slides to `shots/slide-NN.png`, dumps `audit.json` | Reads screenshots, checks: text legibility, contrast, headline truncation natural, URL list density acceptable, no broken layouts, brand consistency | +| **Visual review** | Screenshots every section to `shots/section-NN.png` and every responsive combination to `shots/responsive-*.png`, dumps `audit.json` | Reads screenshots, checks: text legibility, contrast, headline truncation natural, URL list density acceptable, no broken layouts, brand consistency | | **Ship gate** | Prints "VALIDATION PASSED" on 0 blocking | Final go/no-go after visual + audit review. Iterate (edit briefing.md OR slides-data.js, re-run) until satisfied | -**Rule of thumb:** if a decision could embarrass the team in front of attendees (wrong tier, awkward headline, partisan flair, broken pattern claim), it's an overseer call. Scripts only handle decisions that have one mechanically-correct answer. +**Rule of thumb:** if a decision could embarrass the team in front of attendees (wrong tier, awkward headline, a partisan item that slipped the apolitical filter, broken pattern claim), it's an overseer call. Scripts only handle decisions that have one mechanically-correct answer. ## `slides-data.js` schema @@ -164,7 +176,6 @@ Each slide object has `type:` discriminating which renderer applies in `build-pp | `prompt` | `title`, `prompt`, `note` | — | Discussion prompt (Tools / Tips / Problems) | | `blank` | `title`, `placeholder` | — | Task Force Update placeholder | | `qa` | `title`, `subtitle` | — | Q & A closing | -| `flair` | `title`, `subtitle`, `items[{title,body,urls[]}]` | — | Holiday-themed / viral AI / curate-your-own slot — always include | ### `tier` values for `news`/`condensed` @@ -184,7 +195,7 @@ When `--format slides|html` runs: 1. Read briefing source `output/meetings/meeting-{N}.md` 2. Read state `context/seen-items.json` for `meeting_n` (or use `--meeting-n` override) -3. Parse markdown → bucket each item by provider (13-bucket schema per SKILL.md / providers.md) +3. Parse markdown and bucket each item by provider (the bucket order in `slide-generation.md` "Per-bucket slide ordering") 4. Within each bucket, partition by HIGH / MED / LOW 5. **Apolitical filter** — drop partisan-only items (already done at briefing-emit time per SKILL.md, but re-validate at slides-emit) 6. Emit slide objects in canonical order (see `slide-generation.md` "Canonical slide order") @@ -193,7 +204,6 @@ When `--format slides|html` runs: - LOW bucket → `condensed` slide — single-col - Cross-provider clusters → dedicated `news` slide (Legal/Compute/Real-world) - Patterns synthesis → `patterns` slide when ≥3 cross-bucket themes - - Flair → `flair` slide always (placeholder if no items) 7. Resolve provider logos from bundled `assets/logo-.svg` files; missing optional logos degrade to text-only headers 8. Write `slides-data.js` (overwriting prior meeting's data) 9. Run pipeline: `build-pptx.js → build-html.js → build-pdf.js → validate.js` @@ -206,11 +216,10 @@ profile-provided assets. Rendering performs no external requests. ### Navigation -- Keyboard: `←` / `→` / `Space` / `PgUp` / `PgDn` / `Home` / `End` -- Buttons: explicit prev/next in bottom-corners (visible) -- **NO click-to-advance** — clicks on URL links must not advance the deck (traps misclicks). Click event handler exits early when `event.target.closest("a")`. -- Touch: swipe left/right -- Deep-link: `#slide-N` jumps to slide N on page load +- Keyboard: `←` / `→` / `Space` / `n` / `p` step one section; `Home` / `End` / `Escape` jump to the ends +- Chip strip: clicking a chip smooth-scrolls to that section +- Scroll: the deck is a continuous scroll page, so ordinary scrolling works throughout +- Deep-link: `#` scrolls to that section on page load ### Print mode @@ -239,18 +248,13 @@ root, `document.fonts.ready`, and two animation frames before printing. ## validate.js gates -| Check | Failure mode | -|---|---| -| All `slides-data.js` `bullets[].urls[]` render as `.news-url` anchors in DOM | Reports per-slide missing URLs; do not ship deck until 0 missing | -| Headline coverage: every `bullets[].title` text appears in `.news-headline` / `.condensed-headline` / `.flair-headline` | Reports per-slide missing headlines | -| Console errors: pageerror + console.error captured | Reports any console error — investigate before shipping | -| Slide-overflow: `slide.scrollHeight > slide.clientHeight + 4` | Flags slides where content exceeds viewport — split per slide-generation.md "Split rules" | -| List-overflow: `.news-list.scrollHeight > .news-list.clientHeight + 4` | Same — bullet count too high | +The gate list, and which gates block versus warn, live in the header comment of +`output/build/validate.js`. Read it there; it changes with the script. Outputs: -- `build/shots/slide-NN.png` — per-slide screenshot for visual review -- `build/shots/audit.json` — structured audit (counts, mismatches, overflow) +- `shots/section-NN.png` and `shots/responsive-*.png` for visual review +- `shots/audit.json` — structured audit (counts, mismatches, overflow) ## Drift / recheck triggers @@ -261,13 +265,13 @@ Outputs: | bundled provider logo changes | Update the pinned SVG in `assets/` and re-run render validation | | New provider added (slug missing) | Append to `providerLogos`; add a reviewed asset to `assets/` or use text-only rendering | | Plugin-wide neutral default changes | Update `output/build/brand.js` `theme` + `brand` exports; update `slide-generation.md` "Default brand spec" | -| Node 20 EOL (April 2026) | Verify ESM + top-level await on Node 22+ | +| A supported Node major reaches end of life | Update the setup preflight's accepted majors and the README's dated matrix together | --- -## Slide/HTML/PDF generation (Step 5 detail) +## Slide/HTML/PDF generation detail -When SKILL.md Step 5 hits `--format slides|html`, the canonical path runs through this in-tree pipeline (Node ESM, pptxgenjs + playwright direct). The fallback skill paths are documented in `slide-generation.md`. +When the build step of `/ai-briefing:generate` hits `--format slides|html`, the canonical path runs through this in-tree pipeline (Node ESM, pptxgenjs + playwright direct). The fallback skill paths are documented in `slide-generation.md`. ### PPTX slides (`--format slides`) @@ -290,10 +294,10 @@ node emit-slides-data.js --meeting-n {N} --briefing ../meetings/meeting-{N}.md - # 3. Build all 3 artifacts (mechanical) node build-pptx.js && node build-html.js && node build-pdf.js -# 4. Validate (mechanical 6-gate audit) +# 4. Validate (mechanical multi-gate audit) node validate.js -# 5. AI REVIEW — read build/shots/slide-NN.png screenshots + build/shots/audit.json +# 5. AI review: read shots/section-NN.png screenshots + shots/audit.json # - text legibility / contrast / spacing # - headline truncations natural? # - broken-link warnings actionable? @@ -326,7 +330,7 @@ If `document-skills:pptx` is not available, follow the install steps in `slide-g ### HTML slides (`--format html`) -**Canonical pipeline:** `output/build/build-html.js` produces single-file HTML with inline CSS/JS, base64 org logos, inline SVG provider logos (white via `currentColor`), keyboard nav (←/→/space/PgUp/PgDn/Home/End), explicit prev/next buttons (NO click-to-advance — traps misclicks on URL links), touch swipe, hash deep-link, `?print=1` flag for print mode. +**Canonical pipeline:** `output/build/build-html.js` produces single-file HTML with inline CSS/JS, base64 org logos, inline SVG provider logos (white via `currentColor`), keyboard section stepping, a chip strip, hash deep-link, and the `?print=1` flag for print mode. **Summary:** Collect items → emit/update `output/build/slides-data.js` → run `node build-html.js` → output lands at `output/meetings/ai-meeting-{N}.html`. Schema and full slide-type list: see "`slides-data.js` schema" earlier in this file. diff --git a/plugins/ai-briefing/skills/generate/reference/slide-generation.md b/plugins/ai-briefing/skills/generate/reference/slide-generation.md index d0d8a8f162..1e4126a789 100644 --- a/plugins/ai-briefing/skills/generate/reference/slide-generation.md +++ b/plugins/ai-briefing/skills/generate/reference/slide-generation.md @@ -8,7 +8,7 @@ The `/document-skills:pptx` skill stack is documented as a **fallback path** at ## Default brand spec -These tokens are defined in `output/build/brand.js` (the neutral engine default) and embedded into the generated `slides-data.js` `theme` + `meta` exports by the emitter. Do NOT redefine per run; a consumer profile supplies a schema-validated `brand.json` to rebrand. +These tokens are defined in `output/build/brand.js` (the neutral engine default) and embedded into the generated `slides-data.js` `theme` + `meta` exports by the emitter. Do not redefine them per run; a consumer profile supplies a schema-validated `brand.json` to rebrand. ### Color palette (default) @@ -54,7 +54,7 @@ The neutral default ships **no** org logo (`brand.js` `logoColor` / `logoWhite` Logos are bundled at `output/build/assets/logo-.svg`. HTML inlines SVG with `fill: currentColor` so they render white-on-dark. Missing optional assets degrade to a -text-only header; runtime downloads are forbidden. PPTX SHOULD use bundled PNG variants +text-only header; runtime downloads are forbidden. PPTX should use bundled PNG variants when needed (pptxgenjs cannot inline SVG with `currentColor`) or skip the provider logo. **Bundled slug list:** @@ -100,7 +100,6 @@ Total typical: 35-50 slides. Order is fixed; sections may be empty (skip the sli | ... | `news` (Compute) | NVIDIA / AMD / hyperscaler / datacenter | when window has compute news | | ... | `news` (Real-world AI) | Tesla Robotaxi / Waymo / humanoid prod | when window has real-world news | | ... | `news` / `condensed` (EXTRAS) | Robotics HIGH → MED → LOW | when extras enabled | -| ... | `flair` | Holiday-themed + viral AI + curate-your-own slot | YES — always (placeholder OK) | | N-5 | `patterns` | "Notable patterns this window" — synthesis | YES when ≥3 cross-bucket themes | | N-4 | `prompt` | "AI Tools & Techniques" prompt + note | YES | | N-3 | `prompt` | "AI Tips & Tricks · Show and Tell" prompt + note | YES | @@ -125,12 +124,11 @@ For each bucket with items: HIGH first, then MED condensed, then LOW condensed. 11. Compute & Infrastructure 12. Real-world AI 13. EXTRAS — Robotics HIGH + MED + LOW -14. Flair (always-include placeholder slot) -15. Patterns synthesis (when ≥3 themes) +14. Patterns synthesis (when ≥3 themes) ### Split rules -- **HIGH news slides:** keep to **5-7 bullets max**. Overflow → split into "Provider — topic 1" + "Provider — topic 2" titled slides (see Anthropic Models & research / Reach & ecosystem in ai-meeting-20). +- **HIGH news slides:** keep to **5-7 bullets max**. Overflow splits into topic-titled slides for the same provider, for example "Provider: models and research" and "Provider: reach and ecosystem". - **MED condensed:** **>7 items → 2-col layout** (`condensed-grid` CSS). 8-12 typical. - **LOW condensed:** typically <5 items, single-col. @@ -158,11 +156,12 @@ Eyebrow text is small uppercase periwinkle — presenter sees the tier, audience | **Compute & Infrastructure** | `nvidia` (when dominant) or `null` | chip launches, hyperscaler GPU deals, datacenter capacity | | **Real-world AI — autonomous vehicles** | `tesla` (when dominant) or `null` | robotaxi launches, fleet expansions, humanoid production cadence | | **Patterns synthesis** | `null` | always when ≥3 cross-bucket themes detected | -| **Flair** | `null` | always — even with curate-your-own placeholder | -### Apolitical filter — flair gate +### Apolitical filter -Drop politician deepfakes, partisan campaign AI memes, partisan policy threads. KEEP brand parodies (PETA-style), fan-art trailers (Wes Anderson Star Wars), science weirdness (fly-brain emulation), real-world AI moments. Industry-controversy items go to **Legal cluster**, not Flair. See SKILL.md "Apolitical filter" for full heuristic. +Drop politician deepfakes, partisan campaign AI memes, and partisan policy threads. +Industry-controversy items go to the **Legal cluster**. See +`reference/audience-defaults.md` "Apolitical filter" for the full heuristic. ## Meeting number auto-increment @@ -171,10 +170,10 @@ Read `meeting_n` from `context/seen-items.json`. On `--format slides|html`: 1. Read current `meeting_n` (defaults to 0 if missing) 2. Increment by 1: `meeting_n += 1` 3. Use `meeting_n` for the title slide (`slides-data.js` `meta.meetingNumber`) -4. Write incremented value back to `seen-items.json` AFTER successful slide generation -5. If user passes `--meeting-n ` flag, override auto-increment with explicit number — do NOT increment state +4. Write the incremented value back to `seen-items.json` only after slide generation succeeds +5. `--meeting-n ` overrides the auto-increment with an explicit number and does not increment state -`slides-data.js` is rewritten per run (briefing markdown → emit data file → run pipeline). The hardcoded `meetingNumber: 20` in the existing file is the LAST run's value — overwritten on next emit. +`slides-data.js` is rewritten per run (briefing markdown → emit data file → run pipeline). ## In-tree build pipeline (canonical) @@ -183,7 +182,7 @@ Full schema, commands, and dependency setup: see `reference/build-pipeline.md`. ```bash cd output/build -# One-time setup +# One-time setup, in-repo maintainer form; consumers run `/ai-briefing:setup apply install-build-deps` npm ci # installs the committed dependency tree npx playwright install chromium --only-shell @@ -200,7 +199,7 @@ node validate.js # gate: all URLs render, 0 console errors ## Fallback skill paths (when in-tree pipeline unavailable) -These paths are documented for completeness — the in-tree `output/build/*.js` pipeline is canonical and reproduces org branding deterministically. Use a fallback skill ONLY when the in-tree pipeline cannot run (Node unavailable or build pipeline broken). All three are graceful fallbacks, not the critical path. +These paths are documented for completeness — the in-tree `output/build/*.js` pipeline is canonical and reproduces org branding deterministically. Use a fallback skill only when the in-tree pipeline cannot run (Node unavailable or build pipeline broken). All three are graceful fallbacks, not the critical path. ### PPTX fallback @@ -208,7 +207,7 @@ Invoke `/document-skills:pptx` via the Skill tool (marketplace `anthropic-agent- ### HTML fallback -Invoke `/frontend-design:frontend-design` via the Skill tool (marketplace `claude-plugins-official`) for `--format html` when in-tree `build-html.js` is unavailable, paired with `/ui-ux-pro-max:slides` (marketplace `claude-plugins-official`) for slide layout patterns. These do not include keyboard nav / `?print=1` flag / SVG provider logos out of the box — reproduce those from `build-html.js`. +Invoke `/frontend-design:frontend-design` via the Skill tool (marketplace `claude-plugins-official`) for `--format html` when in-tree `build-html.js` is unavailable, paired with `/ui-ux-pro-max:slides` for slide layout patterns. These do not include keyboard nav / `?print=1` flag / SVG provider logos out of the box — reproduce those from `build-html.js`. ### PDF fallback paths @@ -217,23 +216,10 @@ Invoke `/frontend-design:frontend-design` via the Skill tool (marketplace `claud ### Skill stack reference (only relevant for fallback) -| Skill | Source | Role | -|---|---|---| -| `document-skills:pptx` | `anthropic-agent-skills` | PPTX fallback | -| `document-skills:pdf` | same | PDF post-processing (merge cover/body, extract verification) | -| `document-skills:theme-factory` | same | 10 preset themes (use only as starting point — re-apply org brand tokens after) | -| `frontend-design:frontend-design` | `claude-plugins-official` | HTML fallback | -| `ui-ux-pro-max:slides` | `ui-ux-pro-max-skill` | layout patterns / emotion arcs (Team All-Hands closest to AI-meeting structure) | -| `ui-ux-pro-max:ui-ux-pro-max` | same | 161 palettes, 57 font pairings (do NOT use — org brand is canonical) | - -## Stale references — DO NOT use - -These tools are NOT installed and superseded by the in-tree pipeline: - -| Stale ref | Why removed | -|---|---| -| `tfriedel/claude-office-skills` | Third-party, unmaintained | -| `zarazhangrui/frontend-slides` | Third-party, single-author | +The fallback skills named above ship from other marketplaces and are not bundled with this +plugin. Confirm what is installed in the current session before routing to one, and reproduce +the brand tokens from `slides-data.js` `theme` afterwards, because none of them apply the +profile brand. ## Troubleshooting diff --git a/plugins/ai-slop/.claude-plugin/plugin.json b/plugins/ai-slop/.claude-plugin/plugin.json index 91d72e483b..4db7bb329c 100644 --- a/plugins/ai-slop/.claude-plugin/plugin.json +++ b/plugins/ai-slop/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "ai-slop", - "version": "0.5.9", + "version": "0.5.11", "description": "Detects and removes AI-writing tells (slop) in checked-in markdown prose: em dashes, emoji formatting, AI vocabulary, negative parallelisms, chatbot phrases, filler, stacked hedging, citation artifacts, model-era phrases, and the rest of a catalog distilled from Wikipedia's Signs of AI writing plus a repo-owned, evidence-graded inventory of current-generation model vocabulary. Read-only audit by default with a deterministic detector plus a judgment rubric; an explicit fix action rewrites findings behind a semantic-diff guard. Findings conform to the detector-findings convention so the review fanout fix relay can consume them.", "author": { "name": "Melodic Software", diff --git a/plugins/ai-slop/CHANGELOG.md b/plugins/ai-slop/CHANGELOG.md index 385bc9dd40..575b6d0795 100644 --- a/plugins/ai-slop/CHANGELOG.md +++ b/plugins/ai-slop/CHANGELOG.md @@ -1,5 +1,24 @@ # Changelog +## [0.5.11] + +### Changed + +- audit: the Purpose section keeps the two detection layers and leaves the relay-routing contract to audit step 6, which now also carries the rewrite-guide clause; the em-dash zero-tolerance rule is stated without the plan-approval provenance in SKILL.md and in the catalog entry, which carries the reason; the catalog's calibration record points at `detect.sh` for the shipped-rule count instead of a copied count, names the third pass without the pull-request number, and states the quotation exemption's input filter and tier rule as current facts; the rewrite guide drops the dogfood incident and the "now" from the quotation-exemption note. +- setup: the `thresholds` key table lists the two density rules `detect.sh` reads; `rule_of_three` left the density table when it moved to the judgment rubric. +- Applied from the 2026-09 prompt-audit against Claude Fable 5.1 (docs/specs/prompt-audit-skills-2026-09.md). + +## [0.5.10] + +### Fixed + +- **`audit`:** the git pre-compute lines moved out of `## Pre-computed context` into a "Repository + context. Gather first" body section of individual Bash calls, one command per call, each `head` + bound kept inside its command and a failure read as an unknown value. The harness composes a + skill's whole pre-compute block into one shell invocation, and a worktree-isolated session refuses + a git-bearing compound command, which blocked these skills from loading inside a worktree. Same + shape as the worktree skill's fix in #1619. Non-git pre-compute lines stay where they were. + ## [0.5.9] ### Changed diff --git a/plugins/ai-slop/skills/audit/SKILL.md b/plugins/ai-slop/skills/audit/SKILL.md index d2f56fda6c..ffbdc6be00 100644 --- a/plugins/ai-slop/skills/audit/SKILL.md +++ b/plugins/ai-slop/skills/audit/SKILL.md @@ -10,9 +10,20 @@ metadata: summary: Detect and remove AI-writing tells from markdown prose --- +## Repository context. Gather first + +Collect these with **individual** Bash calls, one command per call, never combined into a single +invocation: + +- Current branch, `git branch --show-current` + +Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as +separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute +block as one shell invocation, and a worktree-isolated session refuses a compound command that +contains git. + ## Pre-computed context -Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"` Effective config: !`"${CLAUDE_SKILL_DIR}/scripts/detect.sh" --show-config >/dev/null 2>&1 && { "${CLAUDE_SKILL_DIR}/scripts/detect.sh" --show-config 2>/dev/null | head -8; :; } || echo "detector unavailable"` ## Purpose @@ -25,13 +36,8 @@ vocabulary): 1. **Deterministic**: `${CLAUDE_SKILL_DIR}/scripts/detect.sh` runs the catalog's `v1: script` rules. Its findings carry argued severity tiers (the detector-findings convention's crosswalk) - and persist as a conforming findings file. **What the relay APPLIES is narrow; what it ROUTES - is not.** `rule-utm-params` alone is auto-applicable, and every other rule is - `/ai-slop:audit fix` work — but the crosswalk now declares that ownership, so the relay hands - those rows to this skill's `fix` action rather than to its cleanup route, which prefers - `/simplify`, a code-simplification skill, and applies the rows itself when `/simplify` is - absent. Neither branch loads this skill's rewrite guide. The findings file is how a consumer - *sees* them and how they reach the one surface that can rewrite them. + and persist as a conforming findings file, which is how a consumer sees them and how they + reach a surface that can rewrite them. Audit step 6 names which surface, and when. 2. **Judgment rubric**: the catalog's `v1: rubric` tells, applied by reading the prose. Rubric findings reach the human report only, never the findings file. @@ -73,13 +79,13 @@ removed, stay marker-free by construction. write when unreachable (report-only is then the outcome, and say so). Script findings only. 6. **Recommend**, never auto-run: the `fix` action for the findings, or `/ai-slop:setup` when the run tripped over deliberate house style (heavy declined counts or a flooded rule). - `review:fanout fix` is now a valid route for the whole file, not just one rule: it hands every - row but `rule-utm-params` to this skill's own `fix` action, which the crosswalk declares as - their remediation owner. `rule-utm-params` is the one row the relay is *capable* of applying + `review:fanout fix` routes the whole file: it hands every row but `rule-utm-params` to this + skill's own `fix` action, which the crosswalk declares as their remediation owner. `rule-utm-params` is the one row the relay is *capable* of applying meaning-preservingly — do not promise that it will. It takes its ordinary cleanup class and reaches the relay's cleanup route, which prefers `/simplify`, a code-simplification skill that - reads no findings file, and applies rows itself only when `/simplify` is absent. Recommend the - relay when the operator is already running a fix pass; recommend this skill's `fix` directly + reads no findings file, and applies rows itself only when `/simplify` is absent. Neither the + relay's own applier nor `/simplify` loads this skill's rewrite guide. Recommend the relay when + the operator is already running a fix pass; recommend this skill's `fix` directly when they are not, since it is the shorter path to the same rewrites. Name the condition that changes the answer — the relay can only hand the rows over when `/ai-slop:audit` is available in that session, and surfaces them otherwise. @@ -126,7 +132,8 @@ file survives its own remediation. Then report totals: fixed, suppressed, revert forms are documented in the plugin README and managed by `/ai-slop:setup`. The detector's `--show-config` names the layer supplying each effective value. When a whole document legitimately needs em dashes, the remedy is `em_dash_allowed_paths` or the file marker, never a -threshold: the em-dash rule is zero-tolerance by design (user decision at plan approval). +threshold. The em-dash rule is zero-tolerance by design; the catalog's `rule-em-dash` entry +carries the reason. ## What this skill does NOT do diff --git a/plugins/ai-slop/skills/audit/reference/catalog.md b/plugins/ai-slop/skills/audit/reference/catalog.md index f100ee46fc..564896fd92 100644 --- a/plugins/ai-slop/skills/audit/reference/catalog.md +++ b/plugins/ai-slop/skills/audit/reference/catalog.md @@ -123,8 +123,8 @@ minimal change" for quoted material (quotations are not the repo's own prose to detector implements it mechanically. Each rule carries a class: - **wording** — the rule judges prose the repo AUTHORS. It never scans quoted material: - blockquote lines and double-quoted spans are removed from its input, and inline code spans - were already exempt. Quote-exempt candidates are counted as declined, never silently dropped. + blockquote lines, double-quoted spans, and inline code spans are removed from its input. + Quote-exempt candidates are counted as declined, never silently dropped. This is also the use/mention boundary: a document that QUOTES a tell to document it (a style guide, a forbidden-phrase list, a changelog citing the phrase a fix removed) is mentioning, not using, and backticking or double-quoting the mention is the marker-free suppression. @@ -137,16 +137,16 @@ Known limitation: the double-quoted-span exemption is per-line. A quotation wrap line break escapes it; the closures are rewrapping the quote onto one line, the blockquote form, or the fenced marker. -The class assignments live in the detector's rule registry; the crosswalk rows are unchanged by -the exemption (it moves candidates from findings to declines, not between tiers). +The class assignments live in the detector's rule registry. The exemption moves candidates from +findings to declines and never changes a rule's crosswalk tier. ## Calibration record (V1) Calibrated 2026-08-17 against this marketplace's tracked markdown (1161 files) with neutral defaults. Outcomes: -- All 12 `v1: script` rules ship as of this pass; none demoted. (The roster is 15 after the - second pass below adds three, and 14 after the third pass demotes `rule-rule-of-three`.) +- All 12 `v1: script` rules measured in this pass ship; none demoted. `detect.sh` is the + authoritative list of shipped script rules. - Density rules gained a minimum-hits floor (3) after short files fired on a single normal-prose occurrence (one triad in a 201-word document hit 5.0/1000 words). - `rule-knowledge-cutoff-disclaimer` has a known false-positive class: prose ABOUT model @@ -178,8 +178,8 @@ Second pass, 2026-08-19, for the Cursor additions, against the same corpus: (3.0/1000 words, minimum 3 hits per file) kept the rule quiet on every file, so the shipped default stays neutral while saturated files still flag. -Third pass, 2026-08-25, from a full repo-wide `fix` dogfood of PR 3359 (82 findings across 45 -files) plus a plugin-quality audit and a verified prior-art survey: +Third pass, 2026-08-25, over a full repo-wide `fix` run (82 findings across 45 files), a +plugin-quality audit, and a verified prior-art survey: - `rule-rule-of-three` demoted to rubric per its own calibration clause: 18 of 18 residual findings after the fix pass sat on load-bearing enumerations, the ERE matched only @@ -391,10 +391,10 @@ then-current 1,361-file tracked-markdown corpus: - detectability: mechanical - applicability: general-prose - v1: script -- The `—` character (`\xE2\x80\x94`) in prose. **Zero-tolerance by default** (user decision at - plan approval): any occurrence outside code fences and inline code flags. Documents that - require em dashes opt out per-document via config path-lists or the in-file marker; the rule is - never threshold-calibrated and is excluded from the `recorded-only` demotion path. +- The `—` character (`\xE2\x80\x94`) in prose. **Zero-tolerance by default**: any occurrence + outside code fences and inline code flags. Documents that require em dashes opt out + per-document via config path-lists or the in-file marker; the rule is never + threshold-calibrated and is excluded from the `recorded-only` demotion path. - The source page's Style section (catalog pin and the 2026-08-21 recheck) treats this as a **valid sign**, not an ineffective one. The same section carries the qualifier *"This sign is most useful when taken in combination with other indicators, not by itself."* That is a diff --git a/plugins/ai-slop/skills/audit/reference/rewrite-guide.md b/plugins/ai-slop/skills/audit/reference/rewrite-guide.md index 5867678779..872d8118af 100644 --- a/plugins/ai-slop/skills/audit/reference/rewrite-guide.md +++ b/plugins/ai-slop/skills/audit/reference/rewrite-guide.md @@ -58,17 +58,16 @@ classes adversarially: - **Negative parallelism** ("not just X but Y", "not only X, but also Y"): the construction is ambiguous between "X alone is insufficient (X still counts)" and "X is excluded". A positive - restatement must pick one, and picking wrong inverts a criterion — a dogfood pass turned - "(not just facilitator)" into a blanket exclusion that external review caught. Resolve the - intended reading from surrounding context first; when the context does not settle it, keep - the original and flag the ambiguity to the author instead of guessing. + restatement must pick one, and picking wrong inverts the criterion. Resolve the intended + reading from surrounding context first; when the context does not settle it, keep the original + and flag the ambiguity to the author instead of guessing. - **Triad collapse**: keep the single strongest item ONLY when the surviving text still entails every deleted item. An enumeration whose items are independent claims ("no endpoint tables, no scope lists, no prices") loses assertions when collapsed; restate without the cadence ("no endpoint tables, scope lists, or prices") rather than dropping items. - **Quoted operative phrases**: a hedge, discriminator, or trigger phrase inside quotation marks is load-bearing verbatim text ("what could possibly happen" as one arm of a - read-vs-run discriminator). Never edit inside the quotes; the quotation exemption now keeps + read-vs-run discriminator). Never edit inside the quotes; the quotation exemption keeps wording rules out of them. ## Substitution guardrails diff --git a/plugins/ai-slop/skills/setup/SKILL.md b/plugins/ai-slop/skills/setup/SKILL.md index 27e39e54e1..44aaae290b 100644 --- a/plugins/ai-slop/skills/setup/SKILL.md +++ b/plugins/ai-slop/skills/setup/SKILL.md @@ -23,7 +23,7 @@ tuning in `.claude/ai-slop.json`, resolved per the config-cascade convention: us | `phrase_add` | ERE fragment list | Additions to the model-era phrase roster (`rule-model-era-phrases`); whole fragments, spaces allowed, apostrophes spelled `.` | | `phrase_remove` | ERE fragment list | Removals from the shipped phrase roster, matched verbatim against the shipped fragments | | `disabled_rules` | rule slugs | Rules the audit skips entirely (reported as disabled) | -| `thresholds` | map | Per-rule density thresholds: `ai_vocabulary`, `copulative_avoidance`, `rule_of_three` (matches per 1000 words; density rules also need at least 3 matches) | +| `thresholds` | map | Per-rule density thresholds: `ai_vocabulary`, `copulative_avoidance` (matches per 1000 words; density rules also need at least 3 matches) | | `_comment` | string | Free-text rationale for the choices in this file. Read by nobody; JSON has no comment syntax, and a config that disables a rule without recording why is the drift this skill exists to catch. Not drift — do not flag it as an unknown key | ## check (default — read-only) diff --git a/plugins/architecture/.claude-plugin/plugin.json b/plugins/architecture/.claude-plugin/plugin.json index f8ec5f26d4..d1591ec10c 100644 --- a/plugins/architecture/.claude-plugin/plugin.json +++ b/plugins/architecture/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "architecture", - "version": "0.6.8", + "version": "0.6.10", "description": "Scans an existing codebase for module-level architecture friction — shallow modules, seam leaks, and locality gaps — using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and runs an interview loop on the selected candidate before handing off for planning.", "author": { "name": "Melodic Software", diff --git a/plugins/architecture/CHANGELOG.md b/plugins/architecture/CHANGELOG.md index 7bf2829dd8..ec0869eca7 100644 --- a/plugins/architecture/CHANGELOG.md +++ b/plugins/architecture/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to the `architecture` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.10] + +### Changed + +- improve: the Phase 1.5 reproduction rule is stated without the anecdote of the run that motivated it, in SKILL.md and `actions/deepening.md`; the Gotchas preamble frames the entries as rules, not an incident log; the hot-spot step names the repository-context list this skill gathers instead of a pre-computed block it no longer has; the scan briefing drops the prior-audit finding id and the "instead of Phase 2" contrast; the description drops two phrases that restate 'improve architecture'. +- improve: `research/deepening/html-report.md` describes badge colours, the files list, band shapes, module labels, and the accent palette in the terms the scaffold's own `