Keystone · evolve — lessons become project rules
fix plans (Root cause, Prevention) + verify FAIL/Found + Implementation notes + review/security findings + docs/notes
↓
analyze recurring problems, tech-specific pitfalls, project conventions
↓
propose rules → diff → explicit yes → .claude/rules/
Output rendering. Report and summary templates in code blocks below show structure only. Render them as Markdown —
headings, tables, bold labels, bullet lists — never wrapped in a code block (it shows as a monospace wall); keep paths
and commands in inline code. The closing Blocked on me: / Changed: / Found: lines become three bullets with bold labels.
Next step (mandatory). End the answer with a Next: line that names the step in a few words, then put the exact
command on its own, on the following line(s), inside a fenced code block with no language tag — the app shows a
copy button on a code block. Never tag it ```bash: a /keystone:* command is not a shell command, and the bash tag
adds a Run button that would fail. When nothing runs now, write Next: nothing now — waiting for <event> and put the
later command in that fenced block. Never end on a caveat or an open-ended question. A path in that command must open
from the session's working directory, because the next session (after /clear) starts there: a file inside it →
its path relative to it; a file you wrote in another repository or folder (after cd) → its absolute path.
Choice at the end (menu). When the stage leaves more than one sensible next step, end with one AskUserQuestion
menu instead of a single command, as AI Factory does: 2–4 options, the recommended one first with (Recommended),
and Stop here last. Print the report and the summary first, then ask. On a pick, carry it out: an option that
continues in this session runs now — for another Keystone skill, read ${CLAUDE_SKILL_DIR}/../<skill>/SKILL.md and
follow it with the chosen arguments; an option that needs a clean session (/clear first), an irreversible external
step (push, deploy, production) or a human action outside the chat is not run — it becomes the Next: command. With
one sensible next step, or when AskUserQuestion is unavailable (claude -p, CI), skip the menu. The Next: line
always closes the answer.
Status colors. In the chat (not in files other tools parse) mark statuses so they scan at a glance: ✅ ok / done · ⚠️ not proven / warn / partial · ❌ missing / wrong / fail · ⏸️ BLOCKED · 🔄 in progress · ⏳ pending; verdicts and gates 🟢 PASS / pass · 🟡 PASS-UNPROVEN / warn / not proven · 🔴 FAIL / fail · ⚪ n/a; severity and risk 🔴 critical / High · 🟠 high · 🟡 medium / Medium · 🟢 low / Low. The marker goes before the word; the word stays.
File links. Every file you write or point the user to lives inside the session's working directory
(the folder Claude Code runs in — in a worktree, the worktree, never the main checkout), and its link is relative to
that directory: [intent.md](wordpress-plugin/x/docs/keystone/<task>/intent.md), not relative to a nested repo or a
subproject. Check the link before showing it: the app opens links only from the working directory. A file outside
it (Claude's memory under ~/.claude, another repository, a temp folder) is never a link — the app cannot open
it and shows "file not found", and a path in code becomes such a link too: give its absolute path as plain
text, without backticks. Link only a file you checked exists.
Claude Code loads .claude/rules/*.md by itself, so a lesson written there reaches every later session with no extra
layer. Keystone has no per-skill override layer and its skills are never edited — a plugin's files are replaced on
update. Everything evolve learns becomes a project rule.
Arguments: $ARGUMENTS — all or empty (every source and topic), a Keystone stage (plan, implement, fix,
verify, check, review) to look only at lessons for that stage, or any other word as a rules topic filter.
The first word add switches to Mode add below; the rest of the argument is the rule text.
Mode add — one rule you dictate (/keystone:evolve add <rule text>)
No sources, no registry, no 8-proposal cap: the human's words are the evidence. Steps 1–3 are skipped.
- Text.
addwith no text → ask for the rule (AskUserQuestion, or plain text and wait). Several rules at once (one per line, or split by;) → each is handled as its own rule below. - Context. Step 0 — the loaded rules are the baseline for dedupe.
- Wording. One short imperative line in English, the user's meaning kept, a concrete format, name or command kept
verbatim. The user says always / never / must →
MUST/MUST NOT(only those lines are checked by/keystone:review rulesand the verifier's Rules gate); a preference → a plain imperative, and say it will not be gated. Evidence comment:<!-- evolve add: user, <YYYY-MM-DD> -->. - Target. Use the table in "Where a rule goes": an existing
.claude/rules/<topic>.mdwhose topic fits, else a new<topic>.md(kebab-case). The rule names files, folders or a language →paths:globs; Glob each one and drop or fix a glob that matches nothing. A whole-project rule gets nopaths:. - Dedupe as in Step 2, against every loaded rule including
CLAUDE.md: Covered → quote the existing rule withfile:line, write nothing; Partial → propose the strengthened rule as a diff; Conflict → show both and let the human choose. - Show, then write only after "yes". Show the exact diff (new file content or the added line), then ask once:
Write/Change topic or paths/Cancel. Only onWritefollow the Writing rules of Step 4.Change→ ask what, show the new diff, ask again. - Log. Append to
docs/keystone/evolve-log.mdan entry## <date> — evolve addwith anAdded:line (orRejected:on Cancel) and noSources:line. Then Step 6.
Where a rule goes
| Lesson applies to | Target |
|---|---|
| Specific files or folders (a module, a test layout, a config) | .claude/rules/<topic>.md with paths: frontmatter listing the globs |
| The whole project (a convention, a pitfall of the stack) | .claude/rules/<topic>.md, no paths: |
| How a Keystone stage should be run in this project | .claude/rules/keystone.md under the heading ## plan, ## implement, ## fix, ## verify, ## check, ## review |
Rules are short imperative lines in English (agents read them), one rule = one bullet, each with its evidence in a
trailing comment, for example - MUST guard nullable relations before reading nested fields. <!-- evolve: docs/keystone/2026-09-02-x/plan.md -->.
Never write to CLAUDE.md from here; never touch anything under the plugin folder.
Step 0: context
Read what exists: CLAUDE.md, .claude/CLAUDE.md, docs/architecture.md, every .claude/rules/**/*.md (note their
paths:), AGENTS.md.
From them take the stack and the existing rules — the baseline for dedupe.
Read docs/keystone/evolve-log.md if it exists (format in Step 5). Its listed sources are already processed.
Task folders: docs/keystone/<date>-<slug>/.
Step 1: collect intelligence
1.1 Sources. Glob the task folders and read, newest first, skipping sources listed in evolve-log.md:
plan.mdwithMode: fix—## Root causeand## Prevention(the richest source).verify.md— theFAILverdict, everywrong/missing/unrequestedline and theFound:lines, especially from a FAIL that a later fix plan or re-verify resolved.plan.md## Implementation notes— decisions that deviated from the plan and "unexplained deviation" entries.- Review and security findings saved in a task folder (
review.md,security.md,qa/results). docs/notes/*.md(memlab notes), when the folder exists.### Suggested rule updatesfrom a/keystone:review rulesrun earlier in this session — in the conversation, not a file; each line becomes a prevention point (sourcereview rules <date>), and they are not added to the log'sSources:line.
Re-run guard. Never re-analyze a source listed in the log, unless the user asks for a full rescan (then ignore the
log for this run and say so). Sources not in the log are the "new" set. To limit the chance of skipping a point on one
pass, also re-read the 5 newest processed sources and mark them "overlap": they can produce proposals but are not
added to the log's Sources: line again.
1.2 Prevention Point Registry. Read every source. For each, extract:
Problem category (null-check, async, validation, types, API, DB, migration, test flakiness, …)
Root-cause pattern (the class of mistake)
Prevention points — each independent actionable rule from Prevention / Found / the notes. A source often holds several independent points aimed at different stages. Extract EACH separately with its target (a rules topic or a Keystone stage). Do NOT treat a source as a single unit.
Verdict — what the record shows the point's action actually did, judged from execution evidence (a test, a re-verify, a later task), never from the source's own claim:
helped— the record isolates it: a regression test that failed before and passes after, a re-verify that turned the FAIL into PASS on exactly this point, or the same defect absent in later tasks that followed the action.hurt— the action was later reverted, broke something, or a later source names it as a cause.no observed effect— applied, and the defect or its class came back anyway.confounded— prefer it whenever the fix changed several things at once and nothing isolates this one, or a single occurrence is all that stands behind it. A## Preventionline, a passing build or an approved plan alone is intent, not evidence: it isconfoundeduntil something isolates it.
Build one flat registry:
| # | Source (path) | Prevention point (specific action) | Target | Verdict — evidence |
|---|---------------|------------------------------------|--------|--------------------|
| 1 | docs/keystone/2026-09-02-x/plan.md | <concrete action to enforce> | .claude/rules/db.md | helped — test_x red→green in fix commit |
| 2 | docs/keystone/2026-09-02-x/plan.md | <different action, same source> | keystone.md ## fix | confounded — fix also changed y, z |
A patch with 5 prevention points produces 5 rows, not 1. The same holds for a plan, a verify.md or a note. A confounded row is a useful record; an invented attribution poisons every later session that loads the rule.
1.3 Aggregate patterns. Group by category. Identify:
- Recurring problems — the same category 3 or more times is systemic. Fewer than 3 stays a candidate, labelled so.
- Tech-specific pitfalls — problems tied to the stack (React re-renders, ORM N+1, timezone handling, …).
- Missing guards — what check, test or convention would have prevented the defect.
1.4 Read codebase conventions (focus on the target stage or topic when one was given): linter configs, test layout and assertions, error-handling style, logging, import and file-structure conventions. They show which rules the code already follows and which a lesson would newly demand.
Step 2: gap analysis against existing rules
A gap exists only if no existing rule covers it. For each (prevention point × target) pair, check the loaded
rules (.claude/rules/**, CLAUDE.md, fallback files) for a rule that addresses the specific action described.
Source reference ≠ full coverage. A rule that cites a source's path covers one point of that source, not all of its points. Verify the content of the existing rule against each prevention point individually.
Classify each existing rule that touches a point:
- Covered — equal or more complete → no proposal.
- Partial — the existing rule covers part → propose a strengthened version as a diff, never a silent rewrite.
- Conflict — a proposal contradicts an existing rule → show both, let the human choose; do not pick.
- Stale — an existing rule cites files, tools or a stack the project no longer has → list it under "Stale rules" with the evidence; propose removal only as a diff that needs its own yes.
After the scan print the count: Prevention points: <total>, covered <a>, partial <b>, uncovered <c>.
Uncovered and partial points become inputs for Step 3.
Stack gaps. Compare the stack with the rules: a framework the project uses but no rule mentions, an error-handling or logging convention the code follows consistently but nobody wrote down. These are proposals too, with the code location as evidence.
Step 3: generate proposals
Quality rules (these are what the human reviews):
- One prevention point = one rule. Do not merge independent points into a vague summary.
- Preserve concrete formats and patterns from the source (an exact command, a header, a field name) verbatim.
- Every proposal is traceable: evidence = a source path (and the line or heading), a convention's file path, or a stack fact. No evidence, no proposal. No generic advice ("write clean code") — project-specific only.
- Minimal and additive: do not rewrite whole rule files. A new file only when no existing one fits the topic.
- Use MUST / MUST NOT only when the source shows a defect already happened; otherwise a plain imperative.
- Verdicts decide. A rule rests on
helpedrows, or on a recurring pattern (3+) whatever the verdicts. A rule that rests only onconfoundedrows is a guess: narrow it to what the record does show, or decline it. Ahurtrow becomes a rule only as its opposite (MUST NOT <the action>), and ano observed effectrow never becomes a rule as written. - Cue and confidence. Each proposal names its
Cue— the shape of situation it applies to, so it fires on a different task (not this task's facts: "an optional relation read in a template", not "order.customer in invoice.php") — and itsConfidence(high / medium / low, with the reason: which verdicts, how many occurrences). Too generic ("be careful with nulls") changes nothing; too specific never fires again. - NO_ENTRY is a real answer. When no point is backed by
helpedrows or a recurring pattern, propose nothing and say so:NO_ENTRY — <why: only confounded rows / single occurrences / all covered>. The registry is still shown. A rule the evidence does not argue for is a regression: it is loaded on every session and buys nothing. - Cap a run at 8 proposals; if more qualify, show the 8 with the most evidence and say how many were left.
Step 4: present, then write only after "yes"
Show the report:
## Evolution report
Sources: <n new> new, <m overlap> overlap, <k skipped by the log>
Prevention points: <total>, covered <a>, partial <b>, uncovered <c> · recurring patterns: <list> · stack insights: <n>
Verdicts: helped <h>, hurt <x>, no observed effect <n>, confounded <c>
### Proposed rules <or the single line NO_ENTRY — <why>>
1. [new] .claude/rules/db.md (paths: src/db/**)
Rule: MUST guard optional relations before reading nested fields.
Cue: a template or serializer reads a field through an optional relation.
Evidence: docs/keystone/2026-09-02-x/plan.md ## Prevention (helped — test_invoice_no_customer red→green);
docs/keystone/2026-09-20-y/verify.md Found (confounded)
Confidence: high — 3 fixes in 6 weeks, one isolated by a regression test.
2. [strengthen] .claude/rules/keystone.md ## fix
<unified diff of the change>
### Declined <points left out on verdicts: # — why (confounded only / no observed effect / hurt) | none>
### Stale rules <list with evidence | none>
With NO_ENTRY skip the question below and go to Step 5 (log) with nothing added.
Then ask with AskUserQuestion (one question, up to 4 options per call; batch if more): one option per proposed
rule with its target and first words, plus None — save nothing. If AskUserQuestion is unavailable, ask in plain text
and wait. For each chosen rule show the exact diff (new file content or changed lines) before writing, unless the
human already saw it in the report and chose it explicitly.
Writing rules:
- Only chosen rules are written. No yes → nothing is written in
.claude/rules/. - An existing rule is never rewritten silently: a change is a diff with its own yes.
- Create
.claude/rules/if absent. Keeppaths:frontmatter valid YAML (a list of globs). - Do not commit; end with
git status --shortof the touched files and suggest committing them (rules are project files and deserve a review in git).
Step 5: log (append-only)
Append to docs/keystone/evolve-log.md (create it with the header # Evolve log if missing). Never edit or delete
earlier entries. One entry per run:
## 2026-10-12 — evolve [all]
Sources: docs/keystone/2026-09-02-x/plan.md, docs/keystone/2026-09-20-y/verify.md, … (<n>)
Added: .claude/rules/db.md — "guard optional relations" (evidence: …)
Rejected: "<rule text>" — <why: not evidence-backed / confounded only / human said no / conflicts with …>
Rules after: <n rules in .claude/rules/>
The Sources: line lists every source read as new (not the overlap), whether or not it produced a rule: a source
that gave nothing is still processed. If the human chose "None", ask once whether to log the sources anyway;
recommended: no — keep them for a re-run, since one pass can miss points. Log when at least one rule was added or
the human says to. /keystone:transfer writes to the same log (a transfer from <project> entry); those entries are
not sources of this project's lessons.
Step 6: next steps
## Evolution complete
Rules added: <n> · strengthened: <n> · rejected: <n> · stale found: <n>
Next: commit .claude/rules and docs/keystone/evolve-log.md; run /keystone:evolve again after 5–10 more fixes;
/keystone:review on recent code to see the new rules at work
Context is heavy after reading many sources — suggest /clear or /compact.
Rules
- Traceable — every proposal links to a source path, a convention file or a tech fact (in Mode add, the user).
- Minimal — add short rules; do not rewrite rule files or
CLAUDE.md. - Reversible — the human approves each rule after seeing the diff; nothing is auto-applied.
- Cumulative — each run builds on the log and the existing rules.
- No hallucination — only what the sources and the code show; a rule rests on an isolated execution contrast or a recurring pattern, never on a fix having been accepted.
- Plugin files are never edited; Keystone has no per-skill override files.
- English only for rule text; the report may follow the user's language.
- No new skills — a pattern that keeps recurring and needs a procedure is a candidate for
/keystone:distill. - Read-only towards sources: plans, verify.md and notes are never changed by evolve.
- Ownership — evolve writes only
.claude/rules/**anddocs/keystone/evolve-log.md.