Skip to content

docs(docs-hygiene): unify audit-derivability fork-mechanism wording - #1311

Merged
kyle-sexton merged 1 commit into
mainfrom
docs/1082-audit-derivability-fork-wording
Jul 25, 2026
Merged

docs(docs-hygiene): unify audit-derivability fork-mechanism wording#1311
kyle-sexton merged 1 commit into
mainfrom
docs/1082-audit-derivability-fork-wording

Conversation

@kyle-sexton

@kyle-sexton kyle-sexton commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

Closes #1082

Summary

The audit-derivability skill warns against confirming a deletion with a contaminated context, and
names the fork mechanism at three sites in SKILL.md. Those three sites had drifted apart: two gave
the same fact in two different voices, and the third named none of it.

  • Hard Rules bullet (was line 111): is unrelatedis the opposite. The spot-test bullet
    (line 56), context/rubric.md:134, and evals/evals.json:84 already used "the opposite," so this
    bullet was the sole outlier of four sites — aligning it required no change to the other three.
  • Gotchas self-grade bullet (was line ~119): previously the one bare non-fork subagent
    mention. It now names the Agent tool's fork subagent type as the forbidden mechanism, which
    evals/evals.json:88 already grades on. It does not repeat the context: fork explanation —
    a Gotchas summary restating the full disambiguation a third time would be duplication on an
    agent-facing surface, exactly what this plugin exists to remove.

"Opposite" is also the more accurate word, verified against current official docs this session:

  • Agent-tool fork — "A fork inherits the full parent conversation instead of starting fresh"
    (tools reference)
  • Skill context: fork — "It won't have access to your conversation history"
    (skills)

Same word, inverse context behavior. "Unrelated" understated precisely the trap the disambiguation
exists to prevent.

docs-hygiene bumped 0.8.6 → 0.8.7 with the matching CHANGELOG entry.

Test plan

Run from the PR worktree against origin/main:

  • scripts/check-changed-skills.sh origin/main — PASS, 0 errors, 0 warnings; confirms all 8
    base-ref trigger phrases preserved (the frontmatter description is untouched) and SKILL.md at
    142/500 lines.
  • scripts/check-skill-portability.sh origin/main — no unexcused coupling tokens.
  • scripts/check-changelog-parity.sh --check-bump origin/main — the version bump has its
    ## [0.8.7] entry.
  • scripts/validate-plugins.sh — all plugin manifests and the catalog validate.
  • markdownlint-cli2 --config .markdownlint-cli2.jsonc "plugins/docs-hygiene/**/*.md" — 36 files,
    0 errors.
  • scripts/check-silent-skips.sh, scripts/check-skill-leaf-names.sh — clean.

No behavioral surface changes: prose only, plus the version/CHANGELOG pair.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01NE8W4XPPVfZVCGBW2GYgyH

Closes #1082

The `audit-derivability` skill names the fork hazard at three sites in
SKILL.md, and they had drifted into two voices plus one bare mention.

- Hard Rules bullet: "is unrelated" -> "is the opposite", matching the
  spot-test bullet, `context/rubric.md`, and `evals/evals.json`, which
  all already used that phrasing. This was the sole outlier of four.
- Gotchas self-grade bullet: names the Agent tool's `fork` subagent type
  as the forbidden mechanism, which `evals/evals.json` already grades
  on, without repeating the full `context: fork` explanation.

"Opposite" is the accurate word: the Agent tool's fork "inherits the
full parent conversation instead of starting fresh" (tools reference),
while a skill's `context: fork` "won't have access to your conversation
history" (skills doc) — same word, inverse context behavior, which is
exactly the trap the disambiguation exists to prevent.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@claude

claude Bot commented Jul 25, 2026

Copy link
Copy Markdown

Claude encountered an error after 1s —— View job


I'll analyze this and get back to you.

@claude

claude Bot commented Jul 25, 2026

Copy link
Copy Markdown

Claude encountered an error after 1s —— View job


I'll analyze this and get back to you.

@github-actions

github-actions Bot commented Jul 25, 2026

Copy link
Copy Markdown

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

Re-running the job, or pushing a new commit, will retry the review.

@github-actions

github-actions Bot commented Jul 25, 2026

Copy link
Copy Markdown

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

Re-running the job, or pushing a new commit, will retry the review.

@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: bc2b43fede

ℹ️ 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/docs-hygiene/skills/audit-derivability/SKILL.md
@claude

claude Bot commented Jul 25, 2026

Copy link
Copy Markdown

Claude encountered an error after 1s —— View job


I'll analyze this and get back to you.

@claude

claude Bot commented Jul 25, 2026

Copy link
Copy Markdown

Claude encountered an error after 0s —— View job


I'll analyze this and get back to you.

@kyle-sexton

Copy link
Copy Markdown
Contributor Author

🤖 Autonomous lane note (AI-generated) — read before merging.

CI is green (26/26 SUCCESS, MERGEABLE), but the AI review verdict on this PR is absent, not clean.

claude-review and claude-security-review both failed inside the SDK (is_error: true, 1s and 0s), and the repo's own infra-status gate posted its warning: "Treat any Claude comment on this PR ... as incomplete, not 'no findings.'" I re-ran both workflows (runs 30160800194, 30160800163); both failed identically on the retry, so this is not a transient blip.

It is not branch-owned. 4 of the 5 most recent open PRs (#1323, #1322, #1320, #1319) carry the same warning, so this is an environment/credential-level failure across the repo, not something this diff caused or can fix. Filed separately rather than papered over here.

Note that the surrounding job reports review / review pass — the workflow succeeds while the review inside it errors, so a green check row is not evidence a review ran. Worth knowing for any lane that gates on check status alone.

What did review this PR: Codex posted one P2 finding, which was validated against the actual sources and classified VALID (defer) → #1317, with a threaded reply and the reasoning recorded there. So this PR is not unreviewed — but it has had no Claude-side review, and the merger should weigh that.

@kyle-sexton
kyle-sexton merged commit b81a251 into main Jul 25, 2026
31 checks passed
@kyle-sexton
kyle-sexton deleted the docs/1082-audit-derivability-fork-wording branch July 25, 2026 16:27
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.

docs(docs-hygiene): audit-derivability fork-mechanism wording drift (line 56 vs 111) + Gotchas line ~119 still undisambiguated

1 participant