diff --git a/CHANGELOG.md b/CHANGELOG.md index 87ae82a..6e7ebad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Please choose versions by [Semantic Versioning](http://semver.org/). * MINOR version when you add functionality in a backwards-compatible manner, and * PATCH version when you make backwards-compatible bug fixes. +## Unreleased + +- feat: `/coding:self-improve` Step 5 becomes an adversarial placement procedure — (5a) mandatory discovery (semantic search + Glob/Grep) that must name 2–3 concrete candidate homes before any routing, with query discipline (search the workflow/domain name, not the rule text; guides often live outside the repo) and a no-forfeit rule (empty discovery never routes to a CLAUDE.md — a memory target must beat a named alternative), (5b) a 5-rung placement ladder (repair misfiring artifact → extend point-of-mistake artifact → point-of-use guide/runbook → project CLAUDE.md → global CLAUDE.md) where descending requires naming the rung's STRONGEST discovery candidate — quoting a heading from the guide/runbook candidate to prove it was opened — and why it can't own the fix, and (5c) a 4-part global-CLAUDE.md admission argument (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 of a misroute) with auto-demotion to the best discovered home when any argument fails; Step 2 records candidates as incidents and forbids drafting rule wording before placement; output's `Artifacts checked:` line replaced by a `Placement:` ladder trace; adds `mcp__semantic-search__search_related` to allowed-tools. Hardens the v0.30.0 artifact-first routing after a session where a PR-workflow rule was still proposed for global CLAUDE.md despite a domain guide with exact neighboring bullets being one search away. + ## v0.30.2 - fix: migrate MacPorts paths to Homebrew across `shellcheck-assistant` (`/opt/local/bin/shellcheck` → `/opt/homebrew/bin/shellcheck` in allowed-tools + docs, drop `port install`), `license-assistant` (`gdate` for current year), and the toolchain-preflight/scaling/findings scenarios (`ast-grep` → `/opt/homebrew/bin/ast-grep`) — MacPorts was removed in the local MacPorts→Homebrew migration. diff --git a/commands/self-improve.md b/commands/self-improve.md index 0bc6f49..f6a2397 100644 --- a/commands/self-improve.md +++ b/commands/self-improve.md @@ -1,6 +1,6 @@ --- description: Review THIS session and propose at most two durable improvements to the Claude Code environment (commands, agents, skills, guides, runbooks, memory/CLAUDE.md rules). Default outcome is "nothing worth keeping." -allowed-tools: Read, Edit, Glob, Grep +allowed-tools: Read, Edit, Glob, Grep, mcp__semantic-search__search_related --- # Self Improve @@ -35,6 +35,11 @@ Scan the transcript for: Ignore anything that happened once with no cost. One-offs never graduate. +Record each candidate as an **incident** — what happened, what it cost — not +as a rule. Do NOT draft rule wording or a diff sketch until Step 5 has chosen +the home: wording drafted early comes out CLAUDE.md-shaped (a terse imperative +bullet) and biases placement toward memory files. + ### 3. Rate each candidate Gate first, then grade — the same shape as `/vault-cli:reflect`'s significance filter. @@ -50,7 +55,7 @@ Passers get a **worth-it score**: | Generality — the fix applies beyond this one task / project / file | +1 | | Repair — fixes a tool that misfired, not a new rule bolted on | +1 | | Obvious-anyway — the "fix" is just doing the naturally obvious thing | −2 | -| Routes to a `CLAUDE.md` though an existing artifact could own it (judged after Step 5 routing) | −1 | +| Routes to a `CLAUDE.md` though an existing artifact could own it (judged after Step 5 placement) | −1 | Tier by score: - **≥ 3 → propose** (ranked, max two) @@ -65,31 +70,81 @@ Does an existing rule / command / agent / skill almost cover this? If yes, propose a small edit to it. Only propose a NEW artifact when nothing existing is close. -### 5. Route the fix — artifact first, CLAUDE.md last - -Before routing anything to a `CLAUDE.md`, check whether an existing artifact -could own the fix: slash command, skill, agent, guide, runbook. The fix belongs -in the artifact that is already loaded when the mistake happens. - -| The fix is a… | It belongs in… | -|---|---| -| Misfire OR gap in an existing command / agent / skill | that artifact (repair / extend it) | -| Step missing from an operational procedure | the runbook that documents it | -| Knowledge gap in a documented system | the guide that owns the topic | -| The exact same prompt, retyped | a slash command | -| An independent responsibility | an agent | -| Reusable multi-step capability with scripts/state | a skill | -| Project convention no artifact can enforce | that project's `CLAUDE.md` | -| Global habit no artifact could ever own | global `CLAUDE.md` (last resort) | - -**CLAUDE.md is the last resort, not the default.** Memory files must stay short -and precise — every rule added there is prompt overhead in every future session. -A proposal targeting a `CLAUDE.md` must name which artifacts were checked and -why none could own the fix (the `Artifacts checked:` output line). A rule that -merely restates what an artifact should enforce itself, or tells the operator to -work around a broken tool, is a symptom patch — repair the tool instead; fall -back to a `CLAUDE.md` rule only when the tool genuinely can't be changed -(external constraint). +### 5. Place the fix — discover, walk the ladder, argue the exception + +Placement is a search problem, not a routing decision. The reasoning that +generated a proposal is biased toward memory files (always loaded, zero +discovery cost) — counter that bias with mandatory discovery and a burden of +proof on the CLAUDE.md target. + +**5a. Discovery (mandatory, before any routing).** Search for existing homes: +semantic search over the vault(s) when available +(`mcp__semantic-search__search_related ""`), plus Glob/Grep over +`commands/`, `skills/`, `agents/`, and the project's guide/runbook dirs. List +the top 2–3 candidate homes found, as file paths. No named candidates means +you haven't searched — do not route yet. + +Query discipline: search the **workflow/domain name** ("development guide PR +workflow", "deploy runbook"), not the rule text you have in mind — rule-text +queries return junk and fake an empty result. Minimum two queries. Note that +guides and runbooks often live OUTSIDE the repo (e.g. an Obsidian vault), so +semantic search is the primary channel and Glob/Grep over the cwd alone is +insufficient evidence that no home exists. + +**Empty discovery never routes to a CLAUDE.md.** If no home is found, propose +creating/extending a guide in the domain's knowledge dir, or output "no home +found — operator decides". A CLAUDE.md target must BEAT a named alternative; +it never wins by forfeit. + +**5b. The ladder.** Work down the rungs. To descend past a rung you must NAME +the concrete candidate at that rung and give a one-line reason it cannot own +the fix. "Nothing fits" without a filename is not a reason. The candidate you +name must be the STRONGEST discovery hit for that rung — not a straw man you +can safely reject — and for the guide/runbook rung you must quote one heading +or line from the candidate file to prove it was actually opened. + +1. The artifact that misfired → repair it. +2. The artifact already loaded at the moment of the mistake (command / skill / + agent step) → extend it. +3. The guide or runbook read at point-of-use for that workflow → add the rule + where it is read in context. +4. Project `CLAUDE.md` → only for a project convention no artifact can enforce. +5. Global `CLAUDE.md` → the exception. Requires the admission argument below. + +New artifacts (slash command for a retyped prompt, agent for an independent +responsibility, skill for a multi-step capability with scripts/state) sit on +rungs 2–3: create one only when discovery proves nothing existing is close. + +**5c. Global CLAUDE.md admission argument.** A proposal may target the global +memory only if ALL FOUR hold, argued one line each in the output: + +- **Always-on:** matters in sessions unrelated to its domain. Counter-test: + name one plausible session type where the line is dead weight — if you can + name one, it fails. +- **Unowned:** name the closest artifact/guide from discovery and why it is + not (and cannot be) loaded at the moment the rule applies. +- **Behavioral, not procedural:** shapes conduct everywhere ("be terse", + "English only") — not a step in any workflow. Workflow steps always have a + point-of-use home. +- **One stable line:** expressible as one terse imperative bullet that will + not churn when tools change. + +**De-generalization test** (apply before grading Always-on): state the rule +with its workflow named — "when opening a PR, run X"; "when deploying, check +Y". If the un-generalized version names a workflow step, the rule is +procedural and belongs at that step's point-of-use home. Generalizing the +wording until it sounds behavioral is the tell of a misroute, not a pass — +gates test the incident, not the phrasing. + +Any argument missing or hand-wavy → auto-demote the proposal to the best named +home from discovery. If the target memory file already feels long, also +nominate one existing line to demote to a guide (soft one-in-one-out). + +Memory files are prompt overhead in every future session. A rule that merely +restates what an artifact should enforce itself, or tells the operator to work +around a broken tool, is a symptom patch — repair the tool instead; fall back +to a `CLAUDE.md` rule only when the tool genuinely can't be changed (external +constraint). ### 6. Output Short. Max two proposals, ranked. @@ -100,7 +155,7 @@ Per proposal: - **Change:** what, and where (exact target file / artifact) - **Worth-it:** (e.g. recurrence +2, cost +1) - **Evidence:** verbatim quote(s) + how often -- **Artifacts checked:** which existing artifacts were considered; mandatory when targeting a `CLAUDE.md` (name why none could own the fix) +- **Placement:** discovery hits (top candidate homes as file paths) + the ladder walk (rung → named candidate → one-line why-not), ending at the chosen home; global-`CLAUDE.md` targets append the four admission-argument lines - **Edit or new:** if new, why nothing existing fit - **Diff sketch:** the concrete line(s) to add or change @@ -128,5 +183,6 @@ Never edit beyond the approved proposals. Never expand scope while applying. - Default to zero. Two is the ceiling. - Edit existing before creating new. - No quote, no proposal. +- Placement is discovered, not assumed — a `CLAUDE.md` target must survive the admission argument. - Fix the cause (missing rule/tool), not the symptom (one bad turn). - Every permanent rule you add, someone maintains forever.