claude-config: audit-instructions — evaluate pre-computed !-injected surface inventory (absorb candidate from audit-model-fit)

[kyle-sexton]

Context

Absorb candidate recorded in PR #870 (which shipped claude-config:audit-instructions and superseded audit-model-fit, issue #800). The superseded skill pre-computed an instruction-surface inventory at invocation time via !-injection in its SKILL.md (shell: bash frontmatter + !-backtick call to its scan script), so the model started with the surface list already in context. audit-instructions deliberately shipped without shell: bash and without !-injection — its Phase A inventory is model-driven. Leaving this unevaluated means the absorb decision from the supersede is silently dropped; the candidate needs an honest cost/benefit design read, then implement or close-as-rejected with rationale here.

Cost side to weigh honestly: !-injection runs on every invocation (including model-invoked runs), adds shell: bash to a skill that currently needs no shell frontmatter, executes before scope-filter parsing (inventory may cover surfaces the requested scope excludes), and couples the SKILL.md to the scan script's output shape. Benefit side: Phase A becomes deterministic and cheaper, and the existing scripts/instruction-scan.sh spine already exists to build on.

Proposed work

• Design read: weigh pre-computed !-injected inventory against the current model-driven Phase A (invocation cost, scope-filter interaction, frontmatter surface, drift coupling).
• Decision: implement (add shell: bash + injection block + inventory mode on the scan spine) OR close this item as rejected with the rationale recorded in the closing comment.
• If implemented: patch/minor-bump claude-config with CHANGELOG entry; check-skill, validate-plugin-contracts, changelog-parity green.

Acceptance criteria

• A written cost/benefit read exists (issue comment or PR body) covering invocation cost, scope interaction, and coupling.
• Either the injection ships (gates green) or the item is closed-as-rejected with rationale — no silent drop.

References

• PR feat(claude-config): add audit-instructions skill, superseding audit-model-fit (0.9.0) #870 (supersede rationale; absorb candidates noted)
• claude-config: add model-upgrade unhobbling audit — sweep instruction surfaces for constraints newer models no longer need #800 (originating issue), feat(claude-config): add audit-model-fit unhobbling audit #809 (superseded audit-model-fit PR)
• Source material: git show 9533a14^:plugins/claude-config/skills/audit-model-fit/SKILL.md (frontmatter + "Pre-computed context" block)
• plugins/claude-config/skills/audit-instructions/SKILL.md, scripts/instruction-scan.sh

Metadata

Field	Value
Category	unspecified
Area	unspecified
Ecosystem	unspecified

[kyle-sexton]

[kyle-sexton]

Design read — cost/benefit for the !-injected surface inventory

Decision: close as rejected (with a re-open trigger below). The read was drafted, then adversarially reviewed by a fresh-context critic instructed to refute it; two initially-claimed costs did not survive and are excluded from the grounds. Recorded per the no-silent-drops rule from PR #870's absorb-candidate note.

Grounds that survived adversarial review

1. The injection pre-computes the cheap part. Phase A's expensive work is ownership classification — plugin-cache exclusion, managed vs locally-owned against the consuming repo's sync manifest, upstream routing, recording skipped surfaces for tier transparency (SKILL.md Phase A + Scope boundary). A raw injected listing (what audit-model-fit's scan produced) replaces only the globbing, roughly 8–15 tool round trips in an audit that already dispatches ~20 subagents across Phases B/C — a small fraction of wall time on a rare, human-triggered run.
2. The fallback path must remain regardless. Under disableSkillShellExecution: true (managed settings; plugin skills ARE affected — the command renders as a policy placeholder), the model-driven Phase A has to stay correct. Injection adds a second path to keep in sync for that marginal benefit.
3. New surface and coupling: shell: frontmatter (the skill-quality gate FAILs bash-only injection syntax without it, WARNs portable-looking forms), an inventory mode on the scan script or a second script, tests, and SKILL.md coupling to the script's output shape.
4. Sibling precedent: claude-memory:audit's seven injections are all scalars (counts, yes/no) — token-cheap by design. A full inventory is a different cost class.

Claims tested and dropped (for the record)

• "Injection is scope-blind" — false, verified empirically on Claude Code 2.1.216: $ARGUMENTS/$0 substitute into injection commands before execution, so a scope-aware scan.sh $ARGUMENTS injection is feasible.
• "Inventory tokens are a pure per-invocation add" — overstated: the model-driven Phase A pays a comparable listing into context as tool results anyway (injection mostly moves tokens), and since v2.1.202 an identical re-render dedups to an "already loaded" note.

Re-open trigger

If Phase A's tool-call overhead proves material in practice (observed slow audits, user friction), revisit — the feasible design space is wider than scalar counts: a scope-aware injected inventory ($ARGUMENTS reaches the injection) or claude-memory-style per-surface scalar counts. Either still pays grounds 2–3, so adoption needs observed pain, not anticipation.

Refs: PR #870 (absorb-candidate note), #800, #809.

[kyle-sexton]

Closed as rejected per the design read above — acceptance criteria met: written cost/benefit read exists (adversarially reviewed), decision recorded with re-open trigger, no silent drop.