feat: self-improve routes artifact-first, CLAUDE.md last

[bborbe]

Summary

• Rewrites /coding:self-improve Step 5 routing: artifact-first, CLAUDE.md last resort
• Routing table now leads with existing-artifact rows (command/agent/skill repair-or-extend, runbooks, guides); memory files demoted to the bottom two rows
• CLAUDE.md proposals must name which artifacts were checked and why none fit
• Adds Step 3 scoring signal: routes-to-CLAUDE.md-though-artifact-could-own-it = −1

Why

Observed bias: every self-improve run proposes new CLAUDE.md bullets (both proposals in the triggering session routed there and were rejected). Memory files must stay short and precise — fixes belong in the artifact that is loaded when the mistake happens.

🤖 Generated with Claude Code

[ben-s-pull-request-reviewer]

Now I have all the information needed. Let me produce the final report.

Analysis Summary:

Step 0c diff: 2 files changed (CHANGELOG.md, commands/self-improve.md) — 22 insertions, 3 deletions

Step 4b-i candidates (judgment rules triggered by changed files):

• changelog/conventional-prefix-required (agent-auditor) — CHANGELOG.md modified
• changelog/preamble-frozen (agent-auditor) — CHANGELOG.md modified
• agent-cmd/command-frontmatter (slash-command-auditor) — skipped: applies to file creation, not modification
• agent-cmd/command-thin (slash-command-auditor) — commands/self-improve.md substantially changed

Step 4c-sel CLASSIFY:

• changelog/conventional-prefix-required → applicable (CHANGELOG.md modified, check bullet prefix)
• changelog/preamble-frozen → applicable (CHANGELOG.md modified, check Unreleased placement)
• agent-cmd/command-frontmatter → skipped — "applies_when: any commands/*.md file is created" — modification, not creation
• agent-cmd/command-thin → applicable (substantial change to commands/*.md)

Step 4d-sel ADJUDICATE:

1. changelog/conventional-prefix-required — PASS: new bullet feat: rewrite /coding:self-improve Step 5 routing... starts with feat: ✓
2. changelog/preamble-frozen — PASS: ## Unreleased placed correctly after the preamble block (MAJOR/MINOR/PATCH bullets), not inside it ✓
3. agent-cmd/command-thin — PASS: changes add a new routing-table row and a scoring signal (+1 row, -1 signal), all within documentation prose. No inline Bash/Task/agent spawning added. The command remains a documentation-only workflow guide (thin wrapper) ✓

Concerns from Plan:

• Concern 1 (subjective scoring for "could own") — acknowledged design trade-off, not a code defect
• Concern 2 (no enforcement for "which artifacts were checked") — acknowledged documentation-only constraint, not a code defect
• Concern 3 (routing table reorder vs Step 3 repair scoring) — no conflict; Step 3 rates candidates, Step 5 routes fixes, they operate at different phases
• Concern 4 (no test coverage) — correct; this is a documentation-only change, no executable code to test

Step 3a: LICENSE file exists at repo root ✓

---

{
  "verdict": "approve",
  "summary": "The routing-table rewrite and new scoring signal in self-improve.md are well-reasoned documentation changes. CHANGELOG.md follows all conventions (correct preamble placement, feat: prefix). No violations found in applicable rules.",
  "comments": [],
  "concerns_addressed": [
    "correctness: routing table reorder verified not to conflict with Step 3 scoring — different phases, no overlap",
    "correctness: \"which artifacts were checked\" requirement is acknowledged as documentation-only constraint, not a code defect",
    "correctness: subjective scoring risk for \"could own\" is an accepted design trade-off documented in the rule itself",
    "tests: behavioral changes are to a documentation-only command guide; no executable code to test"
  ]
}

superseded by new automated review

[ben-s-pull-request-reviewer]

Now I have the full picture. Let me compile my review findings based on the diff.

Step 0c diff summary: CHANGELOG.md (+5 lines), commands/self-improve.md (+30/−12 lines) — 2 files, both .md.

Step 4 early-exit check: Changed files are .md only (no .go/.py). They match CHANGELOG.md and commands/**/*.md triggers → judgment rules fire. Proceeding.

Step 4a (mechanical funnel): Changed files are markdown only — no Go/Python ast-grep rules apply. ast-grep/sg is in PATH but the runner would produce zero mechanical findings for .md inputs. Noted as not-applicable.

Step 4b (judgment rules): Active rules triggered by the diff:

• changelog/conventional-prefix-required → CHANGELOG.md
• changelog/preamble-frozen → CHANGELOG.md
• agent-cmd/command-thin → commands/self-improve.md
• agent-cmd/command-frontmatter → commands/self-improve.md

Manual review of the diff:

commands/self-improve.md changes:

1. allowed-tools: Read, Edit, Glob, Grep — correctly declares Phase 2 (Apply) capabilities. Read for Phase 1 reading; Edit/Glob/Grep for Phase 2 artifact edits.
2. Worth-it score −1 signal — "Routes to a CLAUDE.md though an existing artifact could own it (judged after Step 5 routing)" — correctly annotated as post-routing.
3. Step 5 routing table — reordered artifact-first (Misfire OR gap in existing command/agent/skill → that artifact) with CLAUDE.md as last resort (Project convention no artifact can enforce → project's CLAUDE.md, Global habit no artifact could ever own → global CLAUDE.md). Directly addresses the bias toward always proposing new memory rules.
4. Artifacts checked: mandatory output line — correctly placed in Step 6 output template, mandatory when targeting CLAUDE.md.
5. Phase 2 convention matching — generalized beyond CLAUDE.md to all artifact types with their respective formats.

CHANGELOG.md changes:

• ## Unreleased added with feat: and fix: bullets — both conventional prefixes correct; section placed after (not inside) the preamble ✓

No issues found.

{
  "verdict": "approve",
  "summary": "The artifact-first routing rewrite and audit follow-ups are well-reasoned. The routing table now explicitly prioritizes existing artifacts (command/agent/skill repair, runbook, guide) before CLAUDE.md, with a −1 scoring signal for proposals that route to CLAUDE.md when an existing artifact could own the fix. The mandatory 'Artifacts checked:' output line and generalized Phase 2 convention matching are correct. The CHANGELOG entries follow the conventional-prefix format and the preamble is untouched.",
  "comments": [],
  "concerns_addressed": [
    "correctness: new Step 5 routing table artifact-first priority is implemented — misfire/gap in existing artifact routes to that artifact first, CLAUDE.md is last resort with no routing around without external constraint",
    "correctness: -1 scoring signal annotated 'judged after Step 5 routing' — applied in Step 3 worth-it scoring after routing decision",
    "correctness: mandatory 'Artifacts checked:' line added to Step 6 output template, mandatory when targeting CLAUDE.md",
    "correctness: allowed-tools frontmatter (Read, Edit, Glob, Grep) matches Phase 1/2 capabilities — Read for Phase 1, Edit+Glob+Grep for Phase 2 artifact edits",
    "tests: no test files changed — plugin-only repo, no Go/Python test suite; testing concern not applicable"
  ]
}