feat: add /coding:self-improve command

[bborbe]

What

Adds /coding:self-improve — an inline, session-scoped command that reviews the current conversation and proposes at most two durable, evidence-backed improvements to the Claude Code environment (memory/CLAUDE.md rules, commands, agents, skills).

Design

• Two-phase: Report (read-only, ≤2 ranked proposals, each routed by scope) → Apply (only after explicit approval). No edits in the report phase.
• Opinionated: default outcome is Nothing worth keeping this session. — optimizes for one or two keepers, not idea volume.
• Prefer edit over create: bias toward tightening existing artifacts over adding new ones (anti-bloat).
• Stays inline: analyzes the parent conversation, so it cannot be delegated to a sub-agent (same constraint as reflect/session-close). Documented in the command.

Files

• commands/self-improve.md — the command (self-contained; no personal paths)
• README.md — commands table row
• CHANGELOG.md — ## Unreleased feat bullet

Sibling to the audit-* commands, on the friction-removal side.

[ben-s-pull-request-reviewer]

PR Review Report

PR: feat: add /coding:self-improve command (#64)
Branch: feature/self-improve → master
Diff: 3 files, +99 lines

---

Selector Mode Traceability

• Candidates: 9 rules matched by Step 4b-i glob filter
• Applicable: 5 rules selected by Step 4c-sel
• Skipped:
  • changelog/conventional-prefix-required → bullet uses valid feat: prefix
  • changelog/preamble-frozen → ## Unreleased placed after preamble, not inside it
  • readme/user-facing-not-agent-context → single terse operational line, not user-facing duplication
  • agent-cmd/scripts-in-claude-dir → no scripts used

Ast-grep funnel: Toolchain unavailable — ast-grep present at /usr/bin/ast-grep, but /tmp/pr-review-findings.json could not be written (worktree access restriction). Step 4a skipped.

---

Must Fix (Critical)

None — no security vulnerabilities, no concurrency bugs, no context violations in the diff.

---

Should Fix (Important)

1. agent-cmd/command-frontmatter (MUST) — Missing required frontmatter fields

   • commands/self-improve.md:1-2
   • The frontmatter has description but is missing allowed-tools and argument-hint, which are required per docs/agent-command-development-guide.md §Required frontmatter.
   • Fix: Add allowed-tools (listing the tools the command may invoke) and argument-hint (e.g., "" for a no-arg command).

2. agent-cmd/command-thin (MUST) — Inline analysis logic in command body

   • commands/self-improve.md
   • The command does substantive Phase 1 analysis (steps 1–6: session review, repetition detection, keep-forever test, routing logic) rather than delegating to an agent. Per the guide: "Business logic: None" belongs in the agent, not the command.
   • Acknowledged: The command documents why inline is necessary ("sub-agent runs in a fresh context that cannot see this session"), but the business logic is still present. Consider extracting the analysis into agents/self-improve-assistant.md and having the command invoke it, or explicitly documenting this as a documented exception to the rule with a <!-- @exception --> marker.

3. agent-cmd/gap-driven-feedback (SHOULD) — No gap reporting

   • commands/self-improve.md
   • The command depends on external documentation (CLAUDE.md, agents, skills, commands) that may be incomplete, but does not surface gaps as feedback to the user. Per the rule, incomplete documentation should produce a gap report pointing to the missing source.
   • Fix: If any referenced artifact (e.g., a skill path, an agent name) is not found during Phase 1, include a "⚠️ DOCUMENTATION GAPS" section in the output.

---

Nice to Have (Optional)

4. agent-cmd/no-user-prompts (MUST) — Phase 2 approval gate
   • commands/self-improve.md Phase 2
   • Phase 2 says "On approval:" and waits for the user to select proposals before editing. This technically triggers the no-user-prompts rule.
   • Context: This is the Pattern 2 "Analyze + apply" shape from the guide (§Command structure templates), which explicitly includes "Ask for confirmation before commit." The two-phase design (report then apply) and the "at most two proposals" cap provide meaningful blast-radius control. This is an intentional pattern, not an oversight.
   • Recommendation: Accept as-is given the architectural justification, or add <!-- @exception: two-phase design requires approval gate --> if the audit rule is strict.

---

Concerns from Plan

Concern	Status
security: blast radius of proposed changes scoped	Addressed — command limits to "at most two" proposals, edits are smallest-change, Phase 2 is explicit-approval-only
security: two-phase design validates proposals before execution	Addressed — Phase 1 is read-only; Phase 2 requires explicit user selection before any edit
correctness: "stays inline" cannot be delegated	Addressed — command explicitly prevents delegation ("do not delegate it to an agent")
correctness: "at most two" and "nothing worth keeping" default enforced	Addressed — explicitly stated in command documentation

---

{
  "verdict": "request-changes",
  "summary": "The self-improve command is well-scoped with solid blast-radius controls (two-phase, at-most-two cap, inline-only), but has two must-fix violations: missing required frontmatter fields (allowed-tools, argument-hint) and inline analysis logic that should live in an agent per the command-agent separation principle.",
  "comments": [
    {
      "file": "commands/self-improve.md",
      "line": 1,
      "severity": "critical",
      "message": "agent-cmd/command-frontmatter (MUST): Missing required frontmatter fields `allowed-tools` and `argument-hint`. Only `description` is present. Add both per docs/agent-command-development-guide.md §Required frontmatter."
    },
    {
      "file": "commands/self-improve.md",
      "line": 1,
      "severity": "major",
      "message": "agent-cmd/command-thin (MUST): Command body contains substantive Phase 1 analysis logic (session review, repetition detection, keep-forever test, routing) rather than delegating to an agent. Per the guide: 'Business logic: None' belongs in the agent. The inline justification is documented but the logic is still present. Consider extracting to agents/self-improve-assistant.md or adding an explicit exception marker."
    },
    {
      "file": "commands/self-improve.md",
      "line": 1,
      "severity": "major",
      "message": "agent-cmd/gap-driven-feedback (SHOULD): Command depends on external artifacts (CLAUDE.md, agents, skills, commands) that may be incomplete but does not report gaps. If a referenced artifact is not found, include a '⚠️ DOCUMENTATION GAPS' section pointing to the missing source per the rule's feedback loop pattern."
    },
    {
      "file": "commands/self-improve.md",
      "line": 67,
      "severity": "nit",
      "message": "agent-cmd/no-user-prompts (MUST): Phase 2 says 'On approval:' and waits for user selection before editing, which technically triggers the no-user-prompts rule. Context: this is the Pattern 2 'Analyze + apply' shape from the guide which explicitly includes a confirmation gate. The two-phase design and at-most-two cap provide meaningful blast-radius control. Consider adding an exception marker if accepting as-is."
    }
  ],
  "concerns_addressed": [
    "security: blast radius of proposed changes scoped — addressed by 'at most two' cap and explicit Phase 2 approval",
    "security: two-phase design validates proposals before execution — Phase 1 is read-only; Phase 2 requires explicit selection",
    "correctness: 'stays inline' cannot be delegated — explicitly documented in command",
    "correctness: 'at most two' and 'nothing worth keeping' default enforced — explicitly documented"
  ]
}