Skip to content

feat(claude-config): add the unhobble skill and codify instruction economy - #2005

Merged
kyle-sexton merged 7 commits into
mainfrom
feat/unhobbling-alignment
Aug 8, 2026
Merged

feat(claude-config): add the unhobble skill and codify instruction economy#2005
kyle-sexton merged 7 commits into
mainfrom
feat/unhobbling-alignment

Conversation

@kyle-sexton

Copy link
Copy Markdown
Contributor

Summary

Alignment change set from the full /knowledge:youtube-digest of Boris Cherny: "We Cut 80% of Claude Code's Prompt" (YC Startup School, 2026-07-25). Research record + prioritized menu live in melodic-software/knowledge-corpus PR #10 (slice boris-cherny-we-cut-80-of-claude-code-s-qyPCVqFUyDo).

Repo alignment (menu P0 items):

  • docs/PLUGIN-PHILOSOPHY.md — new Instruction economy section: per-session-tax framing, evidence-gated additions ("stumble twice" before any new standing instruction), generation-triggered ablation, evals-outlive-instructions, the official durable-tier carve-outs (deterministic policy hooks, team conventions in git), explicit security non-relaxation (injection-resistance claims are hedged in primary sources), and the note that verification-first task design is already encoded by the verification/planning/tdd/testing plugins.

Downstream-consumer capability (menu #2):

  • New claude-config:unhobble skill (0.22.0) — the empirical bare-baseline experiment consumers run on their own repos: snapshot + policy-vs-behavioral classification → reversible strip on a dedicated branch → stumble ledger across fresh sessions → evidence-gated re-add citing ledger rows. Managed settings and policy hooks are never stripped; CLAUDE_CODE_SIMPLE explicitly out of contract (undocumented). 8 evals; check-skill.sh PASS (0 errors, 0 warnings, description 641/1536); audit-instructions gains the reciprocal route-out.

Verification: two fresh-context reviewer agents (skill-quality contract; research-fidelity vs the slice's RESEARCH.md) — all findings fixed (skill count phrasing, blog citation + "coding evaluations" qualifier, reciprocal routing, description trim).

Deliberately deferred (tracked in the slice's recommendations/): skill-authoring playbook echoes of the evidence gate (avoids doc duplication — the instruction-economy rule itself argues against second copies), listing-budget program (menu #4, needs operator decision), hook-surface policy-vs-behavioral classification sweep (menu #5), marketplace self-maintenance routines (menu #9), recurring work-item wiring for the ablation cadence (menu #1 second half).

No linked issue

Related

🤖 Generated with Claude Code

…onomy

Digest-driven alignment with Boris Cherny's YC Startup School talk ("We Cut
80% of Claude Code's Prompt") and the official best-practices doctrine it
matches. Two deliverables:

- docs/PLUGIN-PHILOSOPHY.md gains an "Instruction economy" section: standing
  instructions are a per-session tax; additions are evidence-gated (repeated
  observed stumbles, never anticipation); ablation is generation-triggered;
  evals outlive instructions; deterministic policy hooks and team conventions
  are the officially carved-out durable tier; model-capability claims never
  relax the security posture.
- New claude-config:unhobble skill (0.22.0): the empirical bare-baseline
  experiment — snapshot/classify, reversibly strip behavioral surfaces on a
  dedicated branch, observe real stumbles in fresh sessions via a ledger,
  re-add only what two-plus same-cause rows earn back, each restore citing
  its evidence. audit-instructions gains the reciprocal route-out.

Verified by two fresh-context reviewers (skill-quality contract + research
fidelity); check-skill.sh PASS, markdownlint clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@cursor

cursor Bot commented Aug 8, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 3m 44s —— View job


Code review complete

  • Gather context (diff, changed files, CLAUDE.md/REVIEW.md guidelines)
  • Understand the request (code-review lane, correctness/architecture/error-handling/tests/maintainability; security findings deferred to the security lane per REVIEW.md)
  • Review docs/PLUGIN-PHILOSOPHY.md changes
  • Review plugins/claude-config/skills/unhobble/SKILL.md (new skill)
  • Review plugins/claude-config/skills/unhobble/evals/evals.json
  • Review plugins/claude-config/skills/audit-instructions/SKILL.md diff
  • Review plugin.json / CHANGELOG.md / README.md updates
  • Post findings as inline comments + summary

Scope: the 7 files changed in this PR (git diff origin/main..HEAD — used two-dot since the shallow checkout has no merge-base with origin/main; filtered to the PR's own files, ignoring unrelated context-guard drift that showed up from main having moved on since this branch forked).

Findings (posted inline)

  1. [Important] plugins/claude-config/skills/unhobble/SKILL.md#L73 — Phase 1's classification step only classifies "each hook and each rule," but Phase 2 treats CLAUDE.md/.claude/skills//.claude/agents/ as blanket git rm targets and disables project-enabled plugins "classified behavioral" — a classification that never happens for either. Concretely, this repo's own CLAUDE.md mixes checked-in convention content (the "Branching & PRs" section) with behavioral instructions in one file; running unhobble bare here would delete the convention content wholesale, contradicting the "durable tier is exempt" principle this same PR adds to docs/PLUGIN-PHILOSOPHY.md. Worth extending the classification step to cover single-file surfaces and plugins before Phase 2 relies on it.
  2. [Nit] docs/PLUGIN-PHILOSOPHY.md#L472-L474 — the "over 80%" system-prompt-reduction claim cites "Anthropic blog… claude.com/blog" without a URL, unlike the adjacent best-practices link.

Otherwise

  • New unhobble skill's phase structure (snapshot → bare → observe → readd), state layout, and safety rails (managed settings excluded, human-gated mutations, fresh-session requirement for observation) are internally coherent apart from finding chore: initialize marketplace scaffold #1.
  • Version bump (0.21.9 → 0.22.0), CHANGELOG.md, README.md skill table/count, and plugin.json description are all mutually consistent (6 skills + setup, matches the actual skills directory).
  • audit-instructions/SKILL.md's reciprocal route-out to unhobble reads naturally in context and doesn't duplicate the new skill's contract.
  • evals.json structure/field names match the sibling audit-instructions evals file; 8 evals present as claimed.
  • Did not independently run check-skill.sh or any eval harness — the PR body's "PASS (0 errors, 0 warnings)" and description-length figures are author-claimed and unverified by this review.
  • No security-relevant findings identified in this diff; none reported here per the REVIEW.md lane split (this repo has a claude-security-review workflow, so vulnerabilities/authZ/secrets/injection are exclusively the security lane's scope).

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 1m 14s —— View job


Security review complete ✅

  • Gather context (PR diff, changed files)
  • Review docs/PLUGIN-PHILOSOPHY.md changes
  • Review plugin.json / CHANGELOG.md / README.md changes
  • Review skills/audit-instructions/SKILL.md changes
  • Review new skills/unhobble/SKILL.md
  • Review new skills/unhobble/evals/evals.json
  • Post final security review

Scope: all 7 files changed in this PR (commit 3185e23), per git show --stat 3185e23, matching the PR's file list. No .github/workflows/* files, hooks, or executable scripts are touched by this PR — every changed file is Markdown documentation, a plugin manifest description/version bump, or a new prose SKILL.md + its evals.json.

Findings: none.

This PR has no security-relevant surface to flag:

  • No code execution added. unhobble/SKILL.md (permalink) is a natural-language procedure the agent follows interactively (via its own Bash-tool permission prompts) — there is no new shell script, hook, or workflow file that could carry a command/argument-injection surface.
  • No GitHub Actions changes. No workflow files are touched, so pull_request_target/workflow_run/permissions/pin questions don't apply here.
  • No permission widening. plugin.json (diff) only bumps version and rewords description; no allowedTools, permissions, or trust boundaries change.
  • The new skill's own safety rails read as security-positive, not just neutral:
    • Managed settings and org-managed policy files are explicitly never touched, "regardless of operator request" (SKILL.md#L41), and this is backed by a dedicated eval (managed-settings-never-touched, evals.json#L28-L39).
    • Policy-classified hooks (secrets gates, PR-body contracts, permission guards) are excluded from the default strip and require an explicit, named operator override that's recorded in the manifest (SKILL.md#L47-L50), also eval-covered (policy-hooks-survive-the-strip).
    • Every mutating phase is explicitly human-gated with a presented change set before acting (SKILL.md#L45-L46).
    • Deletions are git rm-based (reversible via git history) rather than in-place disabling, which the CHANGELOG entry explicitly frames as a deliberate choice to avoid a "renamed-but-present" file that could still be read.
  • docs/PLUGIN-PHILOSOPHY.md (diff) is prose only, and it explicitly states model-capability claims never relax the security posture, and that the plugin-acceptance deny-by-default stance on egress/trust delegation stays regardless of model generation — consistent with, not a weakening of, the existing security review process.

No CRITICAL, IMPORTANT, or SUGGESTION findings to report.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3185e23c6b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread plugins/claude-config/skills/unhobble/SKILL.md Outdated
Comment thread plugins/claude-config/skills/unhobble/SKILL.md Outdated
Comment thread docs/PLUGIN-PHILOSOPHY.md Outdated
@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

Main released its own 0.22.0 (#2004) while this branch was in flight; the
unhobble release moves to 0.23.0 with both changelog sections preserved.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 2m 38s —— View job


Security review complete

  • Gather context (git diff origin/main...HEAD, confirmed the 7 changed files match the PR's stated list — no drift since the last review)
  • Review docs/PLUGIN-PHILOSOPHY.md changes
  • Review plugins/claude-config/.claude-plugin/plugin.json / CHANGELOG.md / README.md changes
  • Review plugins/claude-config/skills/audit-instructions/SKILL.md diff
  • Review new plugins/claude-config/skills/unhobble/SKILL.md
  • Review new plugins/claude-config/skills/unhobble/evals/evals.json
  • Post findings

Scope: all 7 files changed in this PR (git diff origin/main...HEAD, HEAD eb2bc5a). Confirmed identical to the file set already reviewed at 3185e23 — the merge commit only pulls in an unrelated guardrails fix (#2007) from main, no new content in this PR's own files.

Findings

1. [IMPORTANT] Plugin-level strip granularity can silently disable a policy hook the skill itself promises to protect — confidence: high

unhobble/SKILL.md explicitly names "PR-body contracts" as an example policy hook that must survive the strip by default (L47-50). But the classification step (Phase 1, step 3) only classifies "each hook and each rule" as loose settings-level entries (L73-75) and Phase 2's mutation for "project-settings hook entries" operates per-entry, backed up individually (L85-86). Project-enabled plugins, by contrast, are stripped at whole-plugin granularity: "disable the ones classified behavioral" (L87-88) — with no defined classification step for plugins at all, and critically no mechanism to split a mixed plugin's policy-hook component from its behavioral-skill component.

This repo has a concrete instance of exactly that mixed plugin: source-control ships hooks/pr-body-linkage-gate.sh and hooks/pr-linkage-mcp-gate.sh — the very PR-body-linkage policy contract this repo's own CLAUDE.md requires — bundled via hooks/hooks.json alongside purely behavioral convenience skills (commit, pull-request, babysit-prs, worktree, resolve-conflicts). If an operator or the agent following this skill judges source-control "behavioral" (a reasonable read, since 5 of its 6 skills are workflow convenience) and disables it wholesale during Phase 2, the PR-linkage policy gate goes down with it — with no per-hook carve-out to catch that, and no eval in evals.json exercising a mixed plugin (eval #2, policy-hooks-survive-the-strip, only tests project-settings hooks, not plugin-shipped ones). This directly contradicts the skill's own "Security posture is out of scope... policy gates are not model-era workarounds" guarantee (L47-50) for exactly the class of hook (PR-body contracts) it names as the intended protection target.

Recommend extending Phase 1's classification to per-hook granularity inside each project-enabled plugin (not just project-settings hooks), so a mixed plugin's policy hooks are individually preserved even when its behavioral skills are stripped.

2. [IMPORTANT] Experiment state keyed by repo basename + model + date collides across checkouts sharing a basename — confidence: high (independently confirmed, not just plausible)

Already flagged by @chatgpt-codex-connector on SKILL.md:55; confirming independently because the mechanism checks out. ${CLAUDE_PLUGIN_DATA} is documented as a machine-global, per-plugin-ID directory — ~/.claude/plugins/data/<id>/ (docs/MIGRATION-PLAYBOOK.md:179, link), not scoped by working-tree path. unhobble's experiment-id is <repo-basename>-<model-version>-<YYYYMMDD> (SKILL.md#L54-55) — basename only, no path or repo-identity disambiguator. Two clones/forks/worktrees sharing a basename, run against the same model on the same day, resolve to the same manifest/backup directory; the later snapshot's non-git backups can overwrite the earlier one's, so readd can restore hook/settings backups into the wrong checkout. Given finding #1's mixed-plugin risk, a cross-checkout mixup compounds it: a policy-relevant settings backup from checkout A could be silently applied to checkout B's readd. Recommend keying the experiment id off a canonical repo identity (e.g. remote URL or absolute path hash) plus a run nonce, per the existing suggestion.

Otherwise

  • No code execution, hook, or workflow files are touched by this PR — every file is Markdown/prose (docs/PLUGIN-PHILOSOPHY.md, README.md, CHANGELOG.md), a manifest description/version bump (plugin.json), or a new natural-language SKILL.md + evals.json. No injection surface, no permission widening, no secrets handling introduced.
  • docs/PLUGIN-PHILOSOPHY.md's new "Instruction economy" section explicitly states model-capability claims never relax the security posture and the plugin-acceptance deny-by-default stance on egress/trust delegation stays regardless of model generation — consistent with, not a weakening of, the existing security review process.
  • Both findings above are about the skill's own contract (as documentation an agent follows) failing to hold under its own stated guarantees for security-relevant scope boundaries — not vulnerabilities in executable code, since none is added by this PR.
  • Deferred: general classification-scope quality gaps (single-file CLAUDE.md convention/behavioral mixing) are already covered by the code-review lane's finding on this same PR; not re-reported here except where they compound a security-relevant policy-hook bypass (finding chore: initialize marketplace scaffold #1).

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 1m 33s —— View job


Code review (re-run after synchronize)

  • Gather context (diff vs origin/main at new HEAD eb2bc5a, changed files)
  • Check whether prior review findings (classification scope, missing citation) were addressed
  • Review any new/changed content since last review
  • Post findings + summary

What changed since the last review

This synchronize is a merge of origin/main into the branch (eb2bc5a), resolving a version
collision: main had independently released claude-config 0.22.0 (#2004) while this PR was in
flight, so unhobble's release was bumped to 0.23.0 with both changelog sections preserved in
order (plugins/claude-config/CHANGELOG.md). Verified with git diff origin/main...HEAD --numstat
that the 7-file, +344/-5 diff is otherwise identical to what was reviewed at 3185e23 — no
content in unhobble/SKILL.md, unhobble/evals/evals.json, PLUGIN-PHILOSOPHY.md, README.md, or
audit-instructions/SKILL.md changed. plugin.json's description was also correctly updated to
"Six configuration-health skills... unhobble (...)".

Sanity-checked the merge itself:

  • CHANGELOG.md: both the new [0.23.0] and existing [0.22.0] sections are present, correctly
    ordered, uncorrupted.
  • evals/evals.json: still valid JSON, 8 evals present as claimed (checked with jq).
  • No unrelated files leaked into this PR's diff from the merge (three-dot diff correctly excludes
    the other plugins' changes — context-guard, guardrails, markdown-format — that came in via
    origin/main).

Prior findings — still open (unaddressed by this synchronize)

Since the reviewed content didn't change, the two substantive findings from the earlier pass on
3185e23 still stand and are not re-posted as duplicate inline comments:

  1. [Important] unhobble/SKILL.md#L73 — Phase 1 step 3 classifies "each hook and each rule" into policy/behavioral/convention, but Phase 2 (L83-88) treats CLAUDE.md/.claude/skills//.claude/agents/ as blanket git rm targets and disables project-enabled plugins "classified behavioral" — a classification neither surface ever receives. This repo's own CLAUDE.md mixes checked-in convention content with behavioral instructions in one file, so running unhobble bare here would git rm the convention content too, contradicting the durable-tier carve-out this same PR adds to docs/PLUGIN-PHILOSOPHY.md.
  2. [Nit] docs/PLUGIN-PHILOSOPHY.md#L474 — the "over 80%" system-prompt-reduction figure cites "Anthropic blog, claude.com/blog" without a URL, unlike the adjacent linked best-practices citation.

Otherwise

No new issues introduced by this synchronize. Version/changelog/description bump to 0.23.0 is
internally consistent and correctly resolves the collision with #2004.

…ption

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 48s —— View job


Security review complete

  • Gather context (git diff origin/main...HEAD, HEAD 378196f)
  • Confirm delta since last security review (eb2bc5a)
  • Review docs/CATALOG.md change
  • Re-confirm no other file content changed
  • Post findings

Scope: git diff eb2bc5a..378196f --stat shows this synchronize touched exactly one file, docs/CATALOG.md (+1/-1) — a regenerated catalog-index line reflecting the "Six configuration-health skills (plus setup)" description already reviewed in plugin.json. Every other file in the PR (docs/PLUGIN-PHILOSOPHY.md, plugin.json, CHANGELOG.md, README.md, audit-instructions/SKILL.md, unhobble/SKILL.md, unhobble/evals/evals.json) is byte-identical to what was already reviewed at eb2bc5a in the prior security review pass (job 31268866645).

Findings: none.

  • The docs/CATALOG.md change is a one-line prose edit (diff) — the claude-config catalog entry's skill count/description, mechanically regenerated to match the plugin manifest's already-reviewed description bump. No code, no links, no paths, no permissions — nothing with a security-relevant surface.
  • No workflow files, hooks, or executable scripts are touched by this synchronize.
  • The two prior IMPORTANT findings on this PR (Phase 1/Phase 2 classification-scope gap in unhobble/SKILL.md re: mixed-plugin policy hooks; experiment-ID collision risk from repo-basename-only keying) are unaddressed but unchanged by this commit — not re-posted here to avoid duplication; they still stand from the eb2bc5a review.

No CRITICAL, IMPORTANT, or SUGGESTION findings to report for this synchronize.
· branch feat/unhobbling-alignment

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 48s —— View job


Code review (re-run after synchronize)

  • Gather context (git diff origin/main...HEAD at new HEAD 378196f, changed files)
  • Check what changed since HEAD eb2bc5a (last reviewed) → 378196f
  • Review the new content
  • Confirm prior findings status
  • Post summary

What changed since the last review

This synchronize adds one commit, 378196f, which regenerates docs/CATALOG.md
(+1/-1) to reflect the claude-config plugin's new description string ("Six
configuration-health skills (plus setup)... and unhobble (...)"). Confirmed via
git diff eb2bc5a 378196f that this is the only content change — no other file
in the 8-file, +345/-6 diff changed.

Checked that this regeneration is correct and mechanical, not hand-authored:

  • docs/CATALOG.md's own header states the block is CI-generated from plugin
    manifests and "never hand-edit it."
  • Diffed the new claude-config line against plugins/claude-config/.claude-plugin/plugin.json's
    description field on HEAD — they match verbatim.

No new findings from this delta.

Prior findings — still open (unaddressed by this synchronize)

Content in unhobble/SKILL.md and docs/PLUGIN-PHILOSOPHY.md didn't change in this
synchronize, so the two substantive findings from the earlier passes (3185e23,
re-confirmed at eb2bc5a) still stand and are not re-posted as duplicate inline
comments:

  1. [Important] unhobble/SKILL.md#L73 — Phase 1 step 3 classifies "each hook and each rule" into policy/behavioral/convention, but Phase 2 (L83-88) treats CLAUDE.md/.claude/skills//.claude/agents/ as blanket git rm targets and disables project-enabled plugins "classified behavioral" — a classification neither surface ever receives. This repo's own CLAUDE.md mixes checked-in convention content with behavioral instructions in one file, so running unhobble bare here would git rm the convention content too, contradicting the durable-tier carve-out this same PR adds to docs/PLUGIN-PHILOSOPHY.md. (The security lane's re-review additionally found this compounds with mixed-content plugins like source-control, whose policy hooks could be disabled along with its behavioral skills.)
  2. [Nit] docs/PLUGIN-PHILOSOPHY.md#L474 — the "over 80%" system-prompt-reduction figure cites "Anthropic blog, claude.com/blog" without a URL, unlike the adjacent linked best-practices citation.

Otherwise

No new issues introduced by this synchronize. The docs/CATALOG.md regeneration is
correct and consistent with the plugin manifest.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 33s —— View job


Security review complete

  • Gather context (git diff 378196f..39d3cf9, new HEAD 39d3cf9)
  • Review the delta
  • Confirm status of prior open findings
  • Post final summary

Scope: this synchronize adds exactly one commit, 39d3cf9, touching a single file: docs/SKILL-CHEAT-SHEET.md (+1/-0). Every other file in the PR's 9-file diff is byte-identical to what was already reviewed at 378196f (job 31269248263).

Findings: none.

  • The change is a single new table row registering /claude-config:unhobble in the generated skill cheat-sheet (diff), mirroring the skill's already-reviewed name and one-line description. No code, no links to unreviewed content, no permissions, no executable surface.
  • No workflow files, hooks, or scripts are touched by this synchronize.
  • The two prior IMPORTANT findings on this PR are unchanged by this commit and still stand from the eb2bc5a review (job 31268866645), not re-posted here to avoid duplication:
    1. unhobble/SKILL.md's Phase 1 classification step doesn't cover project-enabled plugins at per-hook granularity, so a mixed plugin bundling both policy hooks (e.g. PR-body-linkage gates) and behavioral skills could have its policy hook disabled if the whole plugin is judged "behavioral" during Phase 2's strip.
    2. Experiment state is keyed by repo basename + model + date only (${CLAUDE_PLUGIN_DATA} is machine-global, not path-scoped), so two checkouts sharing a basename can collide and cross-contaminate backups/manifests on readd.

No CRITICAL, IMPORTANT, or SUGGESTION findings to report for this synchronize.
· branch feat/unhobbling-alignment

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 40s —— View job


Code review (re-run after synchronize)

  • Gather context (diff since last review, new HEAD 39d3cf9)
  • Review what changed since last reviewed commit (378196f)
  • Confirm status of prior open findings
  • Post summary

What changed since the last review

git diff 378196f 39d3cf9 --stat shows this synchronize touched exactly one file,
docs/SKILL-CHEAT-SHEET.md
(+1/-0) — a regenerated cheat-sheet row for the new unhobble skill:

| [`/claude-config:unhobble`](../plugins/claude-config/skills/unhobble/SKILL.md) | `claude-config` | Strip instructions to a bare baseline, log real stumbles, re-add only what evidence earns |

Checked this is mechanical, not hand-authored content requiring independent review:

  • The row text matches unhobble/SKILL.md's own metadata.summary frontmatter field
    verbatim ("Strip instructions to a bare baseline, log real stumbles, re-add only what
    evidence earns").
  • The row is correctly alphabetically ordered within the claude-config block (after
    audit-permission-grants, before the claude-memory plugin's rows).
  • This follows the same pattern as the already-reviewed docs/CATALOG.md regeneration
    from the prior synchronize (378196f) — a generated index catching up to the plugin's
    new skill, no new prose or logic.

Every other file in the PR (docs/PLUGIN-PHILOSOPHY.md, plugin.json, CHANGELOG.md,
README.md, CATALOG.md, audit-instructions/SKILL.md, unhobble/SKILL.md,
unhobble/evals/evals.json) is unchanged from what was already reviewed at 378196f.

Prior findings — still open (unaddressed by this synchronize)

Content in unhobble/SKILL.md and docs/PLUGIN-PHILOSOPHY.md didn't change, so the two
substantive findings from the earlier passes still stand and are not re-posted as duplicate
inline comments:

  1. [Important] unhobble/SKILL.md#L73 — Phase 1 step 3 classifies "each hook and each rule" into policy/behavioral/convention, but Phase 2 (L83-88) treats CLAUDE.md/.claude/skills//.claude/agents/ as blanket git rm targets and disables project-enabled plugins "classified behavioral" — a classification neither surface ever receives. This repo's own CLAUDE.md mixes checked-in convention content with behavioral instructions in one file, so running unhobble bare here would git rm the convention content too, contradicting the durable-tier carve-out this same PR adds to docs/PLUGIN-PHILOSOPHY.md. (The security lane additionally found this compounds with mixed-content plugins like source-control, whose policy hooks could be disabled along with its behavioral skills.)
  2. [Nit] docs/PLUGIN-PHILOSOPHY.md#L474 — the "over 80%" system-prompt-reduction figure cites "Anthropic blog, claude.com/blog" without a URL, unlike the adjacent linked best-practices citation.

Otherwise

No new issues introduced by this synchronize. The docs/SKILL-CHEAT-SHEET.md regeneration
is correct and consistent with the new skill's own frontmatter.
· branch feat/unhobbling-alignment

Three review findings on #2005:

- Experiment state now keys on canonical checkout identity: the id gains a
  run nonce, the manifest records the resolved worktree path and origin URL,
  later phases verify the match and abort on mismatch, and snapshot never
  reuses an existing experiment directory — two same-basename checkouts can
  no longer cross-restore each other's settings.
- Phase 1 classification now covers every surface Phase 2 acts on
  (instruction files and project-enabled plugins included), and mixed
  instruction files are split at section granularity so the convention
  carve-out survives a strip instead of being deleted with the file.
- The 80%-cut citation in PLUGIN-PHILOSOPHY.md is now a clickable URL to the
  Anthropic blog post, matching the neighboring best-practices citation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 2m 37s —— View job


Code review (re-run after synchronize)

  • Gather context (diff since last reviewed commit 39d3cf9 → new HEAD cb99a75)
  • Check whether prior open findings (classification scope, missing citation) were addressed
  • Review any new/changed content since last review
  • Post findings + summary

What changed since the last review

New commit cb99a75 ("fix(claude-config): address review findings on the unhobble contract")
touches exactly two files — docs/PLUGIN-PHILOSOPHY.md (+3/-2) and
plugins/claude-config/skills/unhobble/SKILL.md (+23/-7) — addressing three review findings raised
on this PR:

  1. Experiment-id collision (codex P1 / security lane finding fix: correct plugin-system inaccuracies and harden references #2) — fixed. The id now gains a
    random nonce, the manifest records the canonical checkout identity (resolved absolute path +
    origin URL when present), and every phase verifies the match before acting, aborting on
    mismatch. This closes the cross-checkout backup-collision risk.
  2. Classification scope gap (code-review finding chore: initialize marketplace scaffold #1) — substantially addressed for
    instruction files: Phase 1 step 3 now classifies CLAUDE.md/skills/agents explicitly, and a
    mixed instruction file is split at section granularity in Phase 2 rather than git rm'd
    whole, so the convention carve-out actually survives for a file like this repo's own CLAUDE.md.
    Good fix. Not addressed for plugins, though — see inline finding below; this is effectively
    the security lane's mixed-plugin finding (source-control bundling a PR-linkage policy hook
    with behavioral skills) reappearing, since the fix gave files section-level granularity but left
    plugins as a single classification unit.
  3. Missing citation (nit) — fixed. The 80%-reduction claim is now a clickable link to the
    Anthropic blog post, matching the neighboring best-practices citation. (Author-claimed URL,
    not independently fetched by this review — no WebFetch tool available in this lane's session.)

New findings (posted inline)

  1. [Important] unhobble/SKILL.md#L105-106 — the plugin-strip bullet still disables a whole plugin classified behavioral, with no per-hook split analogous to the new mixed-file handling. A plugin bundling a policy hook with behavioral skills (this repo's own source-control, with its PR-linkage gate alongside five convenience skills) would still have its policy hook silently disabled if the plugin as a whole reads "mostly behavioral" — contradicting the skill's own "security posture is out of scope" guarantee for exactly the hook class it names as protected.
  2. [Nit] unhobble/evals/evals.json — none of the three behaviors this fix commit introduced (checkout-identity guard, mixed-file section splitting, plugin classification) gained eval coverage, so a future edit could silently regress any of them.

Otherwise

  • No regressions introduced by this synchronize; the two fixed items are correct and don't disturb anything else in the file.
  • The remaining gap (finding 1) is a narrower re-statement of an already-reported issue, not a new architectural concern — flagging so it isn't lost now that the file-level half of the same problem is resolved.
    · branch feat/unhobbling-alignment

@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 1m 20s —— View job


Security review complete

  • Gather context (git diff 39d3cf9..cb99a75, new HEAD cb99a75)
  • Review the delta for security-relevant content
  • Confirm status of prior open findings
  • Post final summary

Scope: this synchronize (cb99a75, "fix(claude-config): address review findings on the unhobble contract") touches exactly two files versus the last-reviewed commit (39d3cf9): docs/PLUGIN-PHILOSOPHY.md (+3/-2, citation URL only) and plugins/claude-config/skills/unhobble/SKILL.md (+27/-8). evals/evals.json and every other PR file are byte-identical to what was already reviewed.

Prior findings — resolution status

1. Experiment-ID collision (previously IMPORTANT, confidence: high) — now fixed. unhobble/SKILL.md#L52-L64 adds a random nonce to the experiment id (<repo-basename>-<model-version>-<YYYYMMDD>-<nonce>) and, more importantly, now records the canonical checkout identity (resolved absolute worktree path + origin URL when present) in the manifest, with every later phase verifying the current checkout matches before acting — a mismatch aborts and names the conflicting path. That closes the cross-checkout backup/manifest contamination path this and Codex's review both flagged. snapshot also no longer reuses an existing experiment directory. This directly addresses the finding as raised.

2. Mixed-plugin policy-hook bypass (previously IMPORTANT, confidence: high) — still open. unhobble/SKILL.md#L81-L90 extends Phase 1 classification to instruction files and plugins, and adds genuine per-section splitting for mixed instruction files (CLAUDE.md) — "a mixed instruction file... is not classified whole: split it in the strip plan... so the convention carve-out holds at section granularity rather than being deleted wholesale." That's a real fix for the CLAUDE.md-mixing case from the code-review lane's finding.

But the same section still lists "a plugin" as a single atomic classification unit alongside "a hook entry, a rule file, a skill, an agent" (line 86) — it does not extend the mixed/split treatment to a plugin's internal components. Phase 2's plugin handling (L105-106) is unchanged from the version already flagged: "disable the ones classified behavioral" still operates at whole-plugin granularity. evals.json is unchanged by this commit and still has no eval exercising a plugin that bundles a policy hook with behavioral skills — policy-hooks-survive-the-strip (evals.json:18-25) only covers project-settings hooks, not plugin-shipped ones.

Concretely, this repo's own source-control plugin still bundles hooks/pr-body-linkage-gate.sh (the PR-body-linkage policy this repo's CLAUDE.md requires) alongside five behavioral convenience skills (commit, pull-request, babysit-prs, worktree, resolve-conflicts). Judging that plugin "behavioral" as a whole and disabling it during Phase 2 still takes the policy hook down with it — the exact scenario the skill's own "policy gates are not model-era workarounds" guarantee (L47-50) is meant to protect. Recommend extending the same per-unit splitting logic already applied to instruction files to a plugin's constituent hooks, so a mixed plugin's policy hooks survive even when its behavioral skills are stripped. — [IMPORTANT], confidence: high.

Otherwise

  • docs/PLUGIN-PHILOSOPHY.md's change in this delta is a citation URL addition only — no security surface.
  • No workflow files, hooks, or executable scripts are touched by this synchronize; nothing here changes trust boundaries, permissions, or execution surface beyond the prose contract of unhobble/SKILL.md itself.

Summary: 1 IMPORTANT finding remains open (mixed-plugin policy-hook bypass); the previously-open experiment-ID collision finding is resolved by this commit.
· branch feat/unhobbling-alignment

Comment thread plugins/claude-config/skills/unhobble/SKILL.md
Comment thread plugins/claude-config/skills/unhobble/evals/evals.json
kyle-sexton and others added 2 commits August 8, 2026 13:50
…with evals

Second review round on #2005:

- A plugin bundling any policy-classified surface is kept whole (plugins
  toggle whole; no partial disable), its behavioral components recorded as
  unstripped-mixed-plugin and flagged as observe-phase confounds — the
  policy gate never goes down with the plugin.
- Three new evals lock the recent rails: mixed-plugin-kept-whole,
  checkout-identity-mismatch-aborts, mixed-claude-md-split-not-deleted-whole.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@claude

claude Bot commented Aug 8, 2026

Copy link
Copy Markdown

Claude finished @kyle-sexton's task in 1m 21s —— View job


Security review complete

  • Gather context (git diff cb99a75..HEAD filtered to this PR's own files; confirmed via git diff origin/main...HEAD --stat that the PR is still exactly the same 9 files, +406/-6, HEAD bad3b85)
  • Review the delta for security-relevant content
  • Confirm status of prior open findings (mixed-plugin policy-hook bypass)
  • Post final summary

Scope: since the last security-lane review (cb99a75), the only content changes to this PR's files are in plugins/claude-config/skills/unhobble/SKILL.md (+5 lines), plugins/claude-config/skills/unhobble/evals/evals.json (+36 lines, 3 new evals), and plugins/claude-config/CHANGELOG.md/audit-instructions/SKILL.md (unrelated audit-instructions precision-fix prose, no security surface). docs/PLUGIN-PHILOSOPHY.md, plugin.json (still 0.23.0, no collision), README.md, docs/CATALOG.md, docs/SKILL-CHEAT-SHEET.md are byte-identical to what was already reviewed. The merge commits (eb2bc5a, bad3b85) pull in unrelated main changes (context-guard, discovery, planning, playbooks, dependency bumps) that are correctly excluded from the three-dot diff — not part of this PR.

Prior finding — now resolved

Mixed-plugin policy-hook bypass (previously IMPORTANT, confidence: high) — fixed. Commit 8edc0e8 ("keep mixed plugins whole and cover the new rails with evals") closes this. unhobble/SKILL.md#L105-111 now states plugins "toggle whole — project settings offer no partial disable" and explicitly requires that a mixed plugin bundling any policy-classified surface (the source-control-shaped case: a PR-linkage hook alongside behavioral convenience skills) is kept whole rather than disabled, with its behavioral components recorded as unstripped-mixed-plugin and surfaced to the observe phase as confounds. This is the correct fix — erring toward not stripping when a policy hook can't be isolated, rather than the previous silent whole-plugin-disable path that could take a policy gate down with it.

This also picks up the companion nit from the last pass: evals.json gained eval #9 (mixed-plugin-kept-whole, L99-109) exercising exactly this scenario, plus #10 (checkout-identity-mismatch-aborts) and #11 (mixed-claude-md-split-not-deleted-whole) covering the two other fixes from cb99a75. Confirmed evals.json is still valid JSON with 11 evals (jq empty + jq '.evals | length').

Findings: none. No new security-relevant content was introduced by this synchronize, and the previously open finding is resolved as described. No workflow files, hooks, or executable scripts are touched by this PR at any point — every file remains Markdown/prose, a manifest version/description bump, or a natural-language SKILL.md + evals.json.

Summary: 0 open findings. Both IMPORTANT findings raised across this PR's review history (experiment-ID collision, mixed-plugin policy-hook bypass) are now resolved.
· branch feat/unhobbling-alignment

@kyle-sexton
kyle-sexton merged commit cd81923 into main Aug 8, 2026
33 checks passed
@kyle-sexton
kyle-sexton deleted the feat/unhobbling-alignment branch August 8, 2026 18:01
kyle-sexton added a commit that referenced this pull request Aug 8, 2026
Third integration. Main added claude-config's unhobble skill (#2005),
which rewrote the manifest description to name six skills.

Resolution keeps this branch's version (0.23.0, the higher bump) and
main's description, since mine carried only the stale five-skill text.
Both 0.23.0 changelog entries sit under the one Added heading — they
describe different additions to the same release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NNmc2T3y81efZTaDZHerWo
kyle-sexton added a commit that referenced this pull request Aug 8, 2026
…alignment

Main's #2000/#2005 landed their own I23 (context-budget, fable-5), catalog
1.17.0, claude-config 0.23.0, session-flow 0.19.0, work-items 0.33.0 —
colliding with this branch's identically-numbered additions. Resolution:

- claude-config 0.24.0, catalog 1.18.0; this branch's rows renumbered
  I23/I24/I25 -> I24/I25/I26 with cross-references updated; partition and
  SKILL.md ranges to I26; Sources merged (Opus 4.8 guide +
  whats-new-sonnet-5 added alongside main's entries); I8-b/I8-d/I8-e
  edits re-applied onto main's revisions of those rows.
- session-flow 0.20.0, work-items 0.34.0; both CHANGELOG entries
  reinserted above main's same-numbered releases.
- New rows checked against main's ADR 0008 (present-text anchoring): all
  four anchor to present passages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HTJ15VxULScgiYFWFRSV8G
kyle-sexton added a commit that referenced this pull request Aug 8, 2026
…2015)

No linked issue

## Summary

Aligns this repo — and its consumer-facing audit machinery — with the
[Sonnet 5 prompting
guide](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5).
The guide was read in full from the raw-`.md` channel (MD5
`6d23959f0ed226feb06bf20c314029e3`, byte-identical to the repo's
recorded 2026-08-04 snapshot), broken down into a 13-concern inventory,
and applied in both directions the guide binds: this repo's own
instruction surfaces, and the `audit-instructions` catalog downstream
consumers run against their repos (`/claude-config:audit-instructions
--target-model sonnet-5`).

## Fix

**Consumer-facing catalog (`claude-config` 0.24.0, catalog 1.18.0)** —
every row verified 2026-08-08 against raw-`.md` fetches with recorded
byte sizes + MD5s (rows renumbered after merging main's Fable 5
alignment, which took I23 and catalog 1.17.0):

- New **I24** instruction relying on silent generalization (unscoped —
Sonnet 5 and Opus 4.8 guides state the literalism claim
verbatim-identically).
- New **I25** sampling parameter prescribed where the model rejects it
(unscoped; Detect range Opus 4.7+, Sonnet 5, Fable 5, Mythos 5;
400-class `error` like I17/I20).
- New **I26** generic negative steering on open-ended design briefs
(unscoped — both guides converge; propose-options is the documented
variety mechanism now that `temperature` is rejected).
- New **I17-d** tool reliance with thinking disabled and no explicit
tool nudge (`sonnet-5`-scoped; the coupling is stated only in that guide
— Opus 4.8's differing default recorded as the scope negative).
- **I8-e unscoped**: its own recheck trigger fired — the Opus 4.8 guide
now states the forced-interim-status-cadence claim, meeting the
promotion gate. I8-d cedes the cadence shape (one finding per line).
I8-b corroboration extended; Sources gain the Opus 4.8 guide and
whats-new-sonnet-5.

**Repo self-alignment** (guide § "Code review harnesses", "More literal
instruction following", "Design and frontend defaults"):

- `review` 0.17.0 — fanout gains a dispatch contract (finder leaves told
coverage is the job; the 5-stage normalization pipeline stays the
filter); per-slice template reports coverage-first with a Confidence
column; three agents now enumerate **every** `REVIEW.md` code-span
citation instead of "a citation"; security-reviewer gains a stated floor
for unlisted ecosystems; ecosystem-specialist reports UNVERIFIED instead
of silently skipping ecosystems with no bundled default; untracked-files
read line added to the two agents missing it.
- `session-flow` 0.20.0 — retro quick mode's findings bar is a decidable
test, not "significant"/"minor".
- `work-items` 0.34.0 — `work` Step 4 staleness pre-check checks every
concrete referent; bullets labeled as examples.
- `prototype` 0.4.0 — explore-directions makes the visual axis additive:
mockup variants declare background/accent/typeface + rationale;
structure stays the floor; eval 3 no longer treats color variety as out
of scope.

Audit lanes that came back clean (no drift found): sampling params,
thinking-disable prescriptions, cadence scaffolding, token budgets,
effort frontmatter (all `high` = model default), stale Sonnet model
facts (severity.md already cites and follows the guide), design steering
outside prototype, repo-root surfaces.

## Test plan

- `markdownlint-cli2` clean over every edited markdown file.
- `jq` validation of all bumped `plugin.json` files and the edited
`evals.json`.
- Fresh-context verification agents: implicit-scope and design-variety
audit findings verified against files before fixes were applied; an
independent branch-diff verifier script-checked quote fidelity of every
upstream citation against the raw-`.md` snapshots across three passes
(16 defects raised, all fixed; final verdict CLEAN). The Opus 5 and
Fable 5 guides were additionally fetched to close the verifier's
disclosed snapshot gaps.
- Merge with main's Fable 5 alignment (#2000) and unhobble (#2005) PRs
resolved semantically: rows renumbered around main's I23, versions
advanced past main's, re-applied edits re-linted; new rows checked
against main's ADR 0008 present-text admission rule.
- CI: pr-title, pr-issue-linkage, and repo lint workflows on this PR.

## Verification

Guide + adjacent pages (whats-new-sonnet-5, migration guide § Sonnet 5,
effort, thinking § effort, Opus 4.8 guide) fetched via the raw-`.md`
channel on 2026-08-08; all quoted spans in catalog rows carry
verification stamps with byte sizes + MD5s. The Sonnet 5 guide is
byte-identical to the 2026-07-29/2026-08-04 captures recorded in
`playbooks/reference/model-adaptation/sonnet-5.md`, which therefore
needed no delta.

## Related

- `plugins/playbooks/reference/model-adaptation/sonnet-5.md` —
session-arming counterpart (already current; hash-verified this
session).
- Prior guide-driven work: review 0.16.0/0.16.1 severity.md
decidable-test rewrite (already aligned).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HTJ15VxULScgiYFWFRSV8G

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton added a commit that referenced this pull request Aug 8, 2026
…#2020)

No linked issue

## Summary

Adds the first row to `.github/recurring-schedule.json`,
operationalizing the instruction-economy doctrine's generation-triggered
ablation (merged in #2005): on each frontier model release, run
`/claude-config:audit-instructions` + `/claude-config:unhobble` over
this repository's session surfaces. Until now the practice existed only
as doctrine prose — nothing prompted it when a release actually lands.

## Fix

One schedule row, `frontier-release-instruction-ablation`: primary
trigger `frontier-model-release` (the release event, not the date, per
docs/PLUGIN-PHILOSOPHY.md "Instruction economy"), quarterly cadence as
backstop only, `next_due` 2026-11-06. Scope note pins the pass to
session surfaces, never the shipped plugin components. Backed by tracker
issue #2019 (`[Maintenance]`-prefixed, `recurring` label) so
`/work-items:track due`/`recheck` and the `/work-items:work`
due-recurring tier can see and reconcile it.

## Verification

- `jq . .github/recurring-schedule.json` parses clean; row matches the
schema used by the work-items `add`/`recheck` actions (id, cadence,
triggers, last_checked, next_due, close_previous).
- Issue #2019 created through the work-item-tracker seam with exact
`[Maintenance] {title}` match to the schedule row title, as `recheck`
requires for close-matching.

## Related

- Refs #2019 — the recurring tracker issue this schedule row backs (not
closed; it is the recurring instance)
- Refs #2005 — the merged instruction-economy doctrine + unhobble skill
this cadence operationalizes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton added a commit that referenced this pull request Aug 8, 2026
…, alias-abort UX, chapter discoverability) (#2017)

Closes #1996

## Summary

Executes the interview outcomes over #1996's six deferred Opus 5 design
candidates: decisions (b) effort-misconception audit row, (d) opus-5
chapter discoverability, and (e) family-alias abort UX are accepted and
shipped here; (a) generic prior-model-workaround row and (c)
vision-workaround row stay deferred-with-trigger; (f) the additive
chapter-payload omissions are ratified as decided-not-missed. All six
outcomes are recorded in a comment on the issue.

## Fix

- **claude-config 0.25.0** (criteria 1.18.0 → 1.19.0):
- New catalog row **I27 — effort lowered to shorten the response**
(renumbered twice from I23 as main's #2000 and #2015 landed I23–I26
concurrently), `Model scope: opus-5` (both source statements are
model-qualified; promotion gate unmet, unscope trigger on the row), with
cost/latency-ground, length-instruction-only, audience-test, and
config-value fences.
- New `instruction-scan.sh` **I27 family**: effort-lowering directive +
brevity token ANDed on one line, word-boundary conventions applied,
doubled-consonant `dropp?` stem per review; header/usage docs updated;
11 I27 regression assertions (57 checks total).
- **Family-alias abort UX**: the fail-loud abort on a version-ambiguous
target now also names the normalized token the alias currently resolves
to as a suggested `--target-model` value the user confirms — still never
proceeds on a guess.
- Stale `evals/evals.json` check-range fixed (I6-I16 → I6-I27;
`--opinion` set corrected to I16, I19, I22).
- **playbooks 0.7.1**: `fable-5` description now names the per-model
adaptation chapters (Opus 5, Opus 4.8, Sonnet 5) with Opus 5 trigger
phrases — the opus-5 chapter was previously unreachable from the skill
listing.

## Verification

- Both guide quotes verified against the LIVE Opus 5 prompting guide
this session: raw `.md` 11,225 bytes, MD5
`8579d63fc9f793784b8c56320fd74e71`, byte-identical to the 2026-07-25
knowledge-corpus capture; the effort page's Opus 5 section corroborates
the claim unhedged. A sibling fresh-context verifier independently
re-fetched the page and reproduced every quote and both hashes.
- `instruction-scan.test.sh`: 57/57 checks pass.
- `check-changelog-parity.sh --check`, `--check-bump origin/main`,
`--check-order`: all pass after each rebase (branch rebased over #2005,
#2000, #2015; versions re-slotted each time).
- `check-changed-skills.sh origin/main`: 2 skills checked, 0 failed;
fable-5 description 828 chars (cap 1,536); aggregate listing budget
1,801/8,000.
- Fresh-context reviewer pass applied: prose-grammar fix in the seeding
list, word-boundary consistency on the brevity ERE, brevity-token
test-matrix completion, doubled-p stem fix, evals range fix.

## Related

- Refs #1699 (the workstream that shipped the built Opus 5 audit set)
- Refs #1997 (the repo-alignment PR; carried the chapter half of
decision c)
- ADR-0006 / ADR-0007 (model-scoping promotion gate; doctrine hosting
seam)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01E5qiaLiGqP6fUTHkRYS19R

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
kyle-sexton added a commit that referenced this pull request Aug 9, 2026
…guide and add the posture-audit lane (#2018)

## Summary

Aligns the marketplace's prompt-bearing surfaces with the current
official prompting guide
(best-practices page + the Fable 5 / Sonnet 5 / Opus 5 / Opus 4.8
subpages, all fetched
2026-08-08), and ships the tooling downstream consumers need to run the
same alignment on their
own repos. Rebased over — and reconciled with — the parallel alignment
PRs #2000 (Fable 5) and
#2015 (Sonnet 5): where those landed the same catalog change first (Opus
4.8 in Sources, I8-e
unscoping, a sampling-parameter row), this PR keeps main's version and
contributes only what
remained novel.

**Repo alignment (audit → adversarial verification → fix):** every
plugin's instruction surfaces
were audited against a 30-item checklist distilled from a verified
451-item inventory of the
guide; every finding was re-adjudicated by independent fresh-context
verifiers before any edit.
~55 verified fixes across 21 plugins (each with a version bump and
CHANGELOG entry), including:

- machine-health: three high-severity internal contradictions — two
reference files still
described the pre-`approvals.json` approval model (checkbox-driven
TODO.md, writes into the
plugin install directory); plus a broken markdown fence-nesting bug in
the report template and a
  wrong-schema pointer in setup
- songwriting: "Pat's seven title types" stated three mutually
inconsistent taxonomies across
  four files — reconciled to `hook.md`'s canonical list
- playbooks (boris): stale model/effort rows (`/model` → `/effort`,
missing `xhigh`, superseded
model recommendations) corrected per the pack's own supersession-note
conventions, verified
  against live docs
- implementation + testing: the repo's two code-editing loops
(implement's TDD cadence, diagnose's
fix step) gained anti-test-gaming guards (guide: "Avoid focusing on
passing tests and
  hardcoding")
- ~30 instruction-style fixes (emphasis-language, missing rationale,
example/structure hygiene,
scope explicitness) and removals of forced status-cadence and fabricated
context-percentage
  triggers

**Downstream capability:**

- `claude-config:audit-instructions` criteria 1.18.0 → 1.19.0: new row
**I27** (over-aggressive
trigger emphasis / blanket tool defaults — the one guide concern no
parallel PR had covered);
**I8 base promoted to unscoped** via the model-agnostic
prefer-general-instructions statement,
with the delegation-throttle worked instance kept `fable-5`-scoped (the
Opus guides recommend
the opposite shape); **I21** gains the
calibration-staleness-vs-level-adequacy distinction.
`instruction-scan.sh` now seeds I27 (both arms) and the existing I25
sampling-parameter row.
- New skill `claude-config:audit-prompting-postures` — the additive
lane: detects posture guidance
(delegation criteria, minimal-scope/anti-test-gaming guardrails,
grounding, autonomy/destructive
postures, etc.) that the guide says a component's purpose needs but the
component does not
carry; report-only, applicability-predicated, wording fetched live
(pointer-not-copy)
- `docs/OFFICIAL-DOCS.md`: new "Prompting doctrine (platform docs)"
section indexing the guide
pages + Thinking page, composed with #2014's evaluation-guidance section

**Follow-ups worked to completion in this PR** (originally filed as
issues, then implemented here
on approval instead of being left parked):

- Closes #2026 — `claude-config:audit` Phase 1 now reads machine-scope
managed settings
(OS-resolved path + `managed-settings.d/` drop-in, structure-only,
no-secrets posture); the
  checklist tick is restored, now truthful
- Closes #2027 — `audit-pass`'s 892-line `run-contract.md` split into
five per-topic reference
files behind a routing index, §-numbering preserved, inbound links
repointed, last
  history-narration clause reframed
- Closes #2028 — `course-digest`'s two inconsistent self-estimated
context-percentage handoff
triggers replaced with one qualitative signal set (long/degraded
session, compaction, module
  boundary); resume protocol untouched
- #2029 closed separately as already-covered: `lib/hook-utils.sh` is the
canonical source and CI's
  `hook-utils-sync` required check already gates every plugin copy

Also swept: the `rhyme` skill's latent skill-relative
`context/pat-pattison/` mention (same defect
the CI gate caught on its seven edited siblings) is now
plugin-root-relative.

## Related

- Prompting best practices:
<https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices>
- Model subpages: prompting-claude-fable-5, prompting-claude-sonnet-5,
prompting-claude-opus-5, prompting-claude-opus-4-8 (same section)
- Thinking page (sampling-param 400 set, disable-rejection set):
<https://platform.claude.com/docs/en/build-with-claude/thinking>
- Parallel alignment PRs reconciled with: #2000, #2015, #2005, #2014

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01LYm1iCn68WiKKsWbP994Co

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant