feat(claude-ops): bake the explain-usage route phrase into observability's description

[kyle-sexton]

No related issue: sweep unit 3 of the native-reference description-phrase sweep approved in the 2026-09-29 native-surfaces interview (Q4).

Summary

The native-surface store records a route verdict for the bundled explain-usage skill against claude-ops:observability, but the routing lived only in the skill's Boundary section, which the model reads after it has picked a skill. Four Boundary bullets in claude-ops also said the native surface "Ships with Claude Code", an availability assertion the native-references convention forbids.

Fix

• Description phrase: observability opens with one presence-gated clause that restates its Boundary routing in full (the lesson from feat(source-control): bake native route phrases into commit and pull-request descriptions #5503's review).

  Native surface	Skill	New description clause	Boundary routing sentence
  bundled explain-usage	observability	"When the bundled explain-usage skill resolves in this session, prefer it for a quick plain-language breakdown of this session's tokens; this skill for cross-session trends, cost, hooks, and anything the local telemetry stores hold."	"When the bundled explain-usage skill resolves in this session, prefer it for a quick plain-language breakdown of this session's tokens. Prefer this skill for cross-session trends, cost, hooks, and anything the local telemetry stores hold."

• Presence wording: the doctor bullets in audit-install-state, audit-performance and audit-skill-visibility, and the explain-usage bullet in observability, drop "Ships with Claude Code rather than as a marketplace plugin" for the template form (<provenance class>)**: what it does. Every behavioral statement in those bullets is kept.

• Store: baked.description_phrase is set on the explain-usage → claude-ops:observability row (complementary, route, extraction against Claude Code 2.1.284), and docs/native-surfaces.md is regenerated.

• Not baked: the doctor and /skill-doctor rows are suggest rows on user-only surfaces, which take no description phrase.

• claude-ops 0.71.2; native-references CHANGELOG 3.3.4 and the Adopters table record the phrase.

Verification

• overlap.py self-check: degraded, on the 2 documented advisories only (extraction versions older than the local 2.1.285 build; upstream SHA not supplied). generate --check: in sync. test_overlap.py: OK.
• overlap.py detect against a 2.1.285 inventory: 0 new, 0 resurfaced, 76 suppressed.
• check-changed-skills.sh origin/main: 4 checked, 0 failed.
• validate-plugin-contracts.mjs: 0 warnings. generate-catalog.mjs --check: in sync.
• check-changelog-parity.sh: --check, --check-order, --check-bump, --check-preserved all pass. check-spoke-plugin-root.sh --check: clean.
• typos and markdownlint on the changed files: clean.
• observability description: about 720 of 1536 characters.

Related

• feat(source-control): bake native route phrases into commit and pull-request descriptions #5503 (source-control) and feat(claude-config): bake native route phrases and presence-gate the Boundary bullets #5509 (claude-config) were the earlier sweep units.
• Sweep contract: one plugin per PR, each merged before the next unit starts (audit-native-overlap/SKILL.md).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-30T04:03:26.815408Z	fc94cd8	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

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

---

Code review complete

• Gather context (PR body, changed files, diff via gh pr diff 5556)
• Review changed files for correctness/maintainability
• Post findings

Scope: all 10 changed files (native-references convention docs, docs/native-surfaces.md + records.json, claude-ops plugin manifest/changelog, and the four SKILL.md Boundary-section edits).

Findings: none that clear the high-signal bar for this lane.

What I checked and ruled out:

• The new observability description clause (plugins/claude-ops/skills/observability/SKILL.md:2) matches the Boundary routing sentence's intent and the PR body's stated table exactly; no drift between the two.
• Cross-file consistency: docs/native-surfaces/records.json's explain-usage → claude-ops:observability row (baked.description_phrase: true), docs/native-surfaces.md's prose ("Baked: description phrase yes"), and docs/conventions/native-references/README.md's Adopters row all agree with each other and with the CHANGELOG (3.3.4, patch/clarification per the doc's own major/minor/patch rule).
• The four Boundary-bullet rewrites (audit-install-state, audit-performance, audit-skill-visibility, observability) drop "Ships with Claude Code rather than as a marketplace plugin" for the **<name> (<provenance class>)**: what it does template defined at docs/conventions/native-references/README.md#L146 — verified each rewritten bullet still reads as one coherent sentence once the markdown line-wrap is resolved (no dropped words/duplicated text at the hunk boundaries).
• Independently recomputed the observability description length (grep '^description:' … | wc -c, minus the description: " prefix and trailing ") → 721 chars, matching the PR's claimed "about 720 of 1536." (The 1536 budget figure itself is author-claimed and not independently re-derived here.)
• plugins/claude-ops/.claude-plugin/plugin.json version bump (0.71.1 → 0.71.2) matches the new plugins/claude-ops/CHANGELOG.md entry; .claude-plugin/marketplace.json doesn't duplicate plugin versions, so nothing there needed updating.
• The doctor//skill-doctor rows correctly keep their old bullet wording, consistent with the PR's claim that those are suggest rows on user-only surfaces and take no description phrase.

All other verification claims in the PR body (script output, lint/typos runs) are author-claimed and not independently re-run in this pass.

[claude]

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

---

Security review — no issues found

• Gather context (PR diff, changed files)
• Invoke /review:security-review skill
• Post findings/results

Scope: All 10 changed files are documentation/metadata — two SKILL.md frontmatter descriptions plus Boundary-section prose (audit-install-state, audit-performance, audit-skill-visibility, observability), two CHANGELOG.md files, docs/native-surfaces.md, docs/native-surfaces/records.json, docs/conventions/native-references/README.md, and a version bump in plugins/claude-ops/.claude-plugin/plugin.json. No executable code, workflow, hook, or permission logic changed.

Instruction-surface check: The diff removes "Ships with Claude Code rather than as a marketplace plugin" from four Boundary bullets (audit-install-state, audit-performance, audit-skill-visibility, observability — e.g. observability/SKILL.md#L155). Checked against docs/conventions/instruction-exception-register/README.md's six protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority): this is a provenance/availability assertion, not a rule in any protected class, and every behavioral statement in the same bullets (what the surface does, how it's invoked) is preserved. No guardrail is being removed — this doesn't qualify as a finding under the instruction-surface lens.

No CRITICAL / IMPORTANT / SUGGESTION findings. No injection surfaces, auth/access-control logic, secret handling, or Actions workflow changes are present in this diff.