feat: harden /coding:self-improve placement — discovery, ladder, admission argument

[bborbe]

Problem

/coding:self-improve v0.30.0 made routing artifact-first in principle, but the gate is self-graded prose — a live session still proposed a PR-workflow rule for global CLAUDE.md while the Development Guide (with two exactly-adjacent anti-pattern bullets) was one semantic search away. Self-assessed gates get satisfied shallowly: "Artifacts checked: none fit" costs one line and no work.

Change

Step 5 becomes an adversarial placement procedure:

• 5a Discovery (mandatory) — semantic search + Glob/Grep must produce 2–3 named candidate homes before routing; query discipline (search the workflow/domain name, not the rule text; guides often live outside the repo); no-forfeit rule — empty discovery never routes to a CLAUDE.md.
• 5b Ladder — 5 rungs (repair misfiring artifact → extend point-of-mistake artifact → point-of-use guide/runbook → project CLAUDE.md → global CLAUDE.md); descending requires naming the rung's strongest discovery candidate + why-not, quoting a heading from the guide/runbook candidate to prove it was opened.
• 5c Admission argument — global CLAUDE.md requires all four: always-on (with dead-weight counter-test), unowned, behavioral-not-procedural, one stable line; plus a de-generalization test (a rule whose un-generalized wording names a workflow step is procedural — rewording it to sound behavioral is the tell); auto-demote to the best discovered home on any failure.
• Step 2 records candidates as incidents and forbids drafting rule wording before placement (early wording comes out CLAUDE.md-shaped).
• Output Artifacts checked: → auditable Placement: ladder trace; mcp__semantic-search__search_related added to allowed-tools (optional, graceful when absent).

[ben-s-pull-request-reviewer]

I have all the information needed. I cannot run bash to get the diff, but I have read both changed files directly. Let me conduct the full review.

---

PR Review: feat: harden /coding:self-improve placement

Files changed: CHANGELOG.md, commands/self-improve.md
Mode: selector (default)
Reviewer: pr-reviewer-agent

---

Step 3a: LICENSE check

LICENSE* not in changed files — skip.

Step 3b: make precommit

Selector mode — skipped, noted.

Step 4 — Mechanical Funnel + Selector Adjudication

Changed files: CHANGELOG.md, commands/self-improve.md

Relevant candidate rules from glob:

Rule	Owner	Applies?
agent-cmd/command-frontmatter	slash-command-auditor	Applicable — command file modified; trigger commands/**/*.md
agent-cmd/command-thin	slash-command-auditor	Applicable — command file modified; trigger commands/**/*.md
changelog/preamble-frozen	agent-auditor	Applicable — CHANGELOG.md modified
changelog/conventional-prefix	agent-auditor	Skipped — applies_when: "a CHANGELOG.md entry does not use a conventional prefix (feat:, fix:, docs:, chore:, refactor:, test:, ci:)" — the single bullet uses feat: correctly
git-workflow/no-ai-attribution-in-commits	agent-auditor	Skipped — trigger on .git/COMMIT_EDITMSG, not in diff

Mechanical findings: No ast-grep binary accessible to run; skip 4a runner.

Step 4c-sel / 4d-sel — Adjudicate applicable rules:

Rule: agent-cmd/command-frontmatter (MUST)

• Doc: docs/agent-command-development-guide.md
• Findings: ✅ commands/self-improve.md has description: and allowed-tools: in frontmatter (lines 1–4). Satisfies the MUST.
• Verdict: No violation.

Rule: agent-cmd/command-thin (MUST)

• Doc: docs/agent-command-development-guide.md
• Findings: ✅ The command is a thin wrapper — it delegates entirely to the agent's own read-only analysis. "This command must stay inline — it analyzes the parent conversation, and a sub-agent runs in a fresh context that cannot see this session. Do not delegate it to an agent." — correctly flags it cannot be delegated. No tool execution, no inline rules, no heavy procedural steps in the command body itself. Phase 1 is read-only report, Phase 2 applies only after explicit approval. The command correctly delegates only to the parent session for analysis.
• Verdict: No violation.

Rule: changelog/preamble-frozen (MUST)

• Doc: docs/changelog-guide.md
• Findings: ✅ CHANGELOG.md preamble (lines 1–10) is unmodified. ## Unreleased (line 11) is placed after the preamble, not inside it. SemVer bullet structure intact.
• Verdict: No violation.

Plan concern verification

Concern	File	Status
Step 5 adversarial placement — discovery (2–3 candidates), ladder (5 rungs), admission argument (4 criteria)	commands/self-improve.md	✅ Correctly implemented in Step 5a/5b/5c
No-forfeit rule — empty discovery must not route to CLAUDE.md	commands/self-improve.md	✅ Step 5a: "Empty discovery never routes to a CLAUDE.md"
Step 2 incident recording, no rule wording before placement	commands/self-improve.md	✅ Step 2: "Record each candidate as an incident — what happened, what it cost — not as a rule. Do NOT draft rule wording..."
Auto-demotion on admission argument failure	commands/self-improve.md	✅ Step 5c: "Any argument missing or hand-wavy → auto-demote the proposal..."
mcp__semantic-search__search_related added to allowed-tools	commands/self-improve.md	✅ Line 3
Artifacts checked: replaced by Placement: ladder trace	commands/self-improve.md	✅ Phase 1 §6: Placement: replaces the old Artifacts checked:
Principles section	commands/self-improve.md	✅ Phase 3 added at end of command

---

Step 5: Consolidated Report

Must Fix (Critical): None.
Should Fix (Important): None.
Nice to Have (Optional): None.

Selector Mode Traceability:

• Candidates: 5 rules matched by glob
• Applicable: 3 rules adjudicated
• Skipped: changelog/conventional-prefix → bullet uses correct feat: prefix; git-workflow/no-ai-attribution-in-commits → trigger .git/COMMIT_EDITMSG, not in diff

Step 6: Next Steps

No test coverage gaps found in this diff.

Step 7: Manual Review

Reviewed commands/self-improve.md against agent-command-development-guide.md and changelog-guide.md. Implementation is faithful to the v0.30.2 CHANGELOG bullet description — all four sub-features (5a discovery, 5b ladder, 5c admission argument, Step 2 incident recording) are correctly implemented. No stale-forfeit routing, no early rule drafting, auto-demotion logic is present.

---

{
  "verdict": "approve",
  "summary": "The self-improve command correctly hardens Step 5 placement with mandatory discovery, a 5-rung ladder, a 4-part admission argument for global CLAUDE.md targets, auto-demotion on failure, and incident-before-wording discipline in Step 2. CHANGELOG entry uses correct `feat:` prefix and preserves the frozen preamble. No violations of command-thin, command-frontmatter, or changelog/preamble-frozen rules.",
  "comments": [],
  "concerns_addressed": [
    "correctness: Step 5a discovery — 2-3 named candidates required before routing, enforced",
    "correctness: Step 5b ladder — 5 rungs with strongest-candidate naming, enforced",
    "correctness: Step 5c admission argument — 4 criteria + de-generalization test, enforced",
    "correctness: no-forfeit rule — empty discovery never routes to CLAUDE.md, enforced",
    "correctness: Step 2 incident tracking — candidates recorded as incidents, no rule wording drafted before placement",
    "correctness: auto-demotion on admission argument failure — implemented"
  ]
}