Keystone · fix — bug fix workflow, regression-first
Fix a specific bug or problem in the codebase. Two modes: fix now (level S, a short plan created directly in
implementing) or plan first (level M, a draft plan in the /keystone:plan format, then Approve and
/keystone:implement). The default workflow is regression-first whenever a regression check is needed: reproduce the
problem, confirm the reported behavior, implement the fix, then verify the same check passes.
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.
Workflow
Keep going without asking while the next step needs no human decision; stop only before a destructive action, an irreversible external action, or an action outside the repository — and say which.
Canonical Regression-First Policy
A regression check is the smallest useful test, command, fixture, API call, browser scenario, script, or documented manual/runtime reproduction that proves the reported bug or validates the expected behavior.
When a bug needs regression coverage, every workflow path (fix-now, plan-first, and existing-plan execution) follows this policy:
- Identify the minimal regression check that should reproduce the issue or encode the expected behavior.
- Execute the check before implementation and confirm it fails or reproduces the reported problem.
- Implement the smallest fix addressing the root cause.
- Re-run the exact same check and confirm it passes.
- Only after that, run related existing checks when practical and suggest broader coverage if useful.
Fallback behavior:
- If no automated/executable check is available, document the narrowest manual/runtime reproduction and why no executable check exists. Treat that documented reproduction as the regression check for Step 4 when it can be rerun.
- If no useful regression check exists at all, record the reason before implementation. Ask whether to proceed with the likely fix, adjust reproduction, or investigate further.
- If the pre-fix regression check passes unexpectedly, treat it as a reproduction mismatch: record the command/check, inputs, environment assumptions, and observed result. Then use the fallback above.
Do not duplicate or weaken this policy in later workflow sections. Later steps should reference this section and add only local execution details.
Test files are never edited (the gate enforces it)
The regression test is written as a NEW file. Your own new test (not yet committed in HEAD) may be edited freely;
test files that exist in HEAD are not edited — while a fix plan is implementing the Keystone hook denies any change to
them, including overwriting with Write. If an existing test
is itself wrong, STOP and ask the human; they decide (and set Status: abandoned in the plan header or
KEYSTONE_GATES=off themselves). Never route around the gate (Bash, renaming, copying over).
Step 0: Existing fix plan and project context
- Active plan. It is the plan.md of the newest task folder under docs/keystone/ — newest by the date prefix of the folder name, ties broken by the plan.md modification time — whose Status is draft, approved or implementing. A plan elsewhere (an older task folder outside docs/keystone) is used only when its path is given explicitly as the argument.
$ARGUMENTSempty and the active plan hasMode: fix→ "Found existing fix plan. Executing the fix based on the plan." Skip Step 1; ifdraft, STOP ("Approve it in/keystone:planfirst"); otherwisetakeit (see "One session per plan") and only then, ifapproved, setStatus: implementing. Go to Step 2 using the plan as a guide, still applying the Regression-First Policy.$ARGUMENTSempty and no fix plan → "No fix plan and no problem description. Run/keystone:fix <description>." STOP.$ARGUMENTSisverifyorverify critical→takethe active plan, then Verify findings mode below; it works inside the active plan, no question.$ARGUMENTSgiven while another plan is active → say which one and ask: finish it, or mark itabandoned; after settingabandoned, runrelease --any <that plan>(see "One session per plan").
- Project context. Read, in this order, what exists:
CLAUDE.mdand.claude/CLAUDE.md;docs/architecture.md;.claude/rules/**/*.md(a rule withpaths:applies only to matching files);AGENTS.md. Use them to avoid fixes that violate project structure or conventions; MUST / MUST NOT lines there are project rules. Infer the Settings (tests: a runner or test files exist; logging: an existing logger; docs:docs/or a README with usage sections) — they are written into the plan, never asked. - Past lessons — before any code change. Load what earlier fixes taught about this area (it does not count
against the Step 2 budget):
- memlab, when its tools are available:
search_decisionson the error text and on the affected module or files (in a git worktree passroot= the worktree); read the notes it returns at theirpath:line; - the
.claude/rules/**/*.mdfiles/keystone:evolvewrote whosepaths:match the files you will touch (already read in 2 — look again at those); - no memlab → the
## Root cause/## Preventionsections of the 10 newestMode: fixplans under docs/keystone/ (newest by the folder's date prefix). Prefer recurring Root cause / Prevention patterns. Name what applies in one line —Lessons: <note or rule> — <how it shapes this fix> | none found— and write that line into task 1's evidence in the plan.
- memlab, when its tools are available:
Verify findings mode — /keystone:fix verify
verify critical narrows the list to the critical findings: every wrong line and an Architecture or Security gate
fail. The rest (rule-only findings, Settings: violated) are listed as left open in the report — they keep the
verdict FAIL until fixed or until their rule changes.
Read verify.md next to the active plan. Its verdict is not FAIL → say so and STOP. not proven, BLOCKED and
Unconfirmed items, Advisory: and Minor: lines and the ## Carried rows are not defects — leave them out of the
list and do not fix them. Otherwise fix all of them in one pass inside the active plan — every finding and every place
of its class: no new plan, no mode question. The task files are the files: list in ## Checks of that verify.md
plus the files changed since its commit. In this order:
- The list. Each
rule … — failline with all itsfile:line, the places aftersites to cover:and itsClass:— minus the places underaccepted violations:in## Checks; everywrongline with itsClass:andRepro:; everyDecision:line; everyUnrequested:item;Settings: violated; anArchitecture gate: fail. AnUnrequested:item is fixed by tracing it: a change inside the scope of an existing task (the same class of fix, a neighbour its rule asked to walk) → write it into that task's text in the plan (a drift edit, not only a note); a change no task covers → revert it; a change worth keeping that no task covers → new work (item 2). A## Reportthat isnot judged — … failed: eachbuild:/test:line of## Checkswith→ failis a finding, and its output is the regression check. Print the list numbered. Before each finding of this list runbeat(see "One session per plan"). - New work is not a fix. A finding whose fix needs a function, task, endpoint, screen or behaviour that no task,
row or
I-nasks for is not fixed here:not fixed — new work: <what> → /keystone:plan <plan path>, and then that command is theNext:line. - The whole class. The verifier's
Class:is a hint: widen it and grep every task file for the same call, guard, pattern, missing step and the neighbouring places. Print each asClass <name>: <file:line>; …. Fix at the shared point where there is one (one guard in the function every call goes through, one reset for the whole module); otherwise fix every place in this same pass. - Repro and a test for the class. Before the change run the
Repro:of everywrongline and quote the failure (Regression-First Policy); after it, the sameRepro:and its passing line. One NEW test file per class that walks every place or checks the shared point; run it on the code before the fix (revert the fix, run, restore) and quote the red line —red on revert. Decision:. Read the named earlier intent whole and find everyI-nand confirmed decision the diff or this plan contradicts, not only the named one. Ask once (AskUserQuestion):Supersede <path> I-a, I-b, I-c? (<why, one line>)— Yes / No. Yes → one line in this task's intent## Decisions log(the only intent edit fix ever makes, by the rule of/keystone:intent):- <YYYY-MM-DD> Q: <path> conflicts with this change → A: supersedes <path> I-a, I-b, I-c (<why>). No →not fixed — the decision stands; change the code or the intent with /keystone:intent.- The same class again. The past run is the newest earlier commit of
git log --format=%H -- <verify.md>that is a run (its text withoutAccepted … by …lines differs from the commit before it) and was judged (its## Report, past blank lines and a ``` fence, does not start withnot judged); never judge a commit by its message. A class of the same nature as one of itsClass:(even named differently) is a repeat: the class test of item 4 is then required for a rule finding too (a guard script that greps the task files and fails on any new place will do), and ask (AskUserQuestion)Add a rule via /keystone:evolve: "<MUST … line>"?— Yes → read${CLAUDE_SKILL_DIR}/../evolve/SKILL.mdand follow itsaddpath with that line (it shows the diff and asks itself); No → a line in the notes. No rule is written without that yes. - Rules before the commit. Check every MUST / MUST NOT line of the project rules (Step 0, item 2) against fix's
own diff (
git diffand new files) — red on revert for new tests, walking the neighbours — and fix a break before committing. Re-check each failing rule against all changed files of the plan (not only the cited lines) and fix other lines this task added or changed that break it too. - Notes and the commit. In
## Implementation notes, one line per finding:- <YYYY-MM-DD> fix verify — <finding id> — Class: <name> — sites: <file:line; …> — fixed at <shared point | each site> — Repro before: <line> → after: <line> — test: <file> (red on revert: <output line>); and one line- <YYYY-MM-DD> fix verify — rules self-check: <r> rules — pass <p>, n/a <n>; fixed before commit: <rule — file:line> | none. Runbeat, then commit code, plan (and intent after item 5) together, thenrelease.
Report each finding as fixed — <file:line> or not fixed — <why>, and the line Владелец: <remote>; <warning>.
Next: /keystone:verify <plan>.
Step 1: Understand the problem and choose the mode
From $ARGUMENTS, identify the error message or unexpected behavior, where it occurs (file, function, endpoint) and
the steps to reproduce (if provided). If unclear, ask: expected vs actual behavior, the error message/stack trace, and
when it started.
Then ask once (AskUserQuestion, recommended first): Fix now — investigate and fix immediately (level S) — or
Plan first — write a plan for review, fix later (level M). A bug that touches data/schema, security/auth/payments or
a module owned by others is L: say so and use /keystone:start instead.
- Fix now (S) → create
docs/keystone/<YYYY-MM-DD>-fix-<slug>/plan.md(slug from the problem) in the short format below, withStatus: implementing,takeit right away (see "One session per plan"), then go to Step 2. - Plan first (M) → Step 1.1. It takes no plan:
/keystone:implementtakes it.
# Plan: fix — <short name>
Level: S · Mode: fix · Status: implementing
Settings: tests — <yes|no> (<why, from repo>) · logging — <minimal|standard|verbose> (<why>) · docs — <yes|no> (<why>)
## Original Request
<the user's words, verbatim>
## Problem
<what is broken; expected vs actual; error text>
## Root cause
<filled in Step 6>
## Tasks
- [ ] 1. Regression check: add or identify the minimal check; run it and confirm it fails — files: <new test file> — check: fails before the fix
- [ ] 2. Fix the root cause with the smallest change — files: <…> — check: <the same regression check> passes
- [ ] 3. Run the closest related existing checks — check: <command>
## Prevention
<filled in Step 6>
Step 1.1: Plan first (M)
Investigate with Step 2 (budget below), then write plan.md in the same folder with Level: M · Mode: fix · Status: draft in exactly the /keystone:plan format (Original Request, ## Requirements Reconciliation with header
| Decision | Source | Verification evidence |, Project rules check: line, ## Risks with Could break / Riskiest step /
Rejected alternatives, ## Tasks as - [ ] N. <task> — files: … — check: …). The tasks follow the Fix Checklist:
regression check first, run it and confirm it reproduces the problem (or record the fallback), smallest fix, rerun the
same check, closest related checks. Add ## Root cause (suspected) and ## Prevention (filled after the fix).
Show the plan. STOP here. Do NOT apply the fix. Immediately offer Approve: "Approve with
/keystone:plan <path to plan.md>" (it takes an existing draft straight to Approve), then /keystone:implement
executes it.
Step 2: Investigate the codebase
Budget (same as /keystone:start): level S — at most 2 searches or reads before acting; level M — one Explore sweep.
Use the Task tool with subagent_type: Explore to keep the main context clean; run up to 3 in parallel only when the
bug is M:
- Agent 1 — locate the problem area: find code related to the error location, read the relevant functions, trace the data flow.
- Agent 2 — related code and side effects: find all callers/consumers of the affected function or module; what else might break.
- Agent 3 — similar patterns: search for similar error patterns;
git logfor recent changes to the affected files.
Synthesize: the root cause (not just symptoms), related code that might be affected, existing error handling. If Task
is unavailable, investigate directly with Glob/Grep, read the code around the issue and trace the data flow. Grep every
caller of the function you are about to change; fix once where all callers route through.
Step 2.5: Capture a regression check
Apply the Canonical Regression-First Policy before changing implementation code. Prefer a regression check for behavior bugs, parsing/validation bugs, API/data bugs, crashes, and regressions. If the change is a non-bug cleanup, purely static correction, or investigation-only request, record why the policy does not apply and continue with the normal fix workflow.
Anti-gaming rule: Do not tailor the test to the implementation you plan to write. The test must describe the externally expected behavior or the reported failure condition. If the test passes before any fix, either the reproduction is wrong, the bug is stale, or the environment differs; handle that mismatch through the fallback behavior in the Canonical Regression-First Policy before changing implementation code.
Write the test as a NEW file (see above), run it, and quote the failing output. Record the selected regression check, pre-fix result and any fallback decision in the plan (task 1 evidence) so Step 4 can rerun the same check.
Step 3: Implement the fix
Make the smallest change that fixes the root cause; tick each task [x] in plan.md right after it is done. A task whose mandatory check did not run stays [ ] with BLOCKED: <reason> at the end of its line (as in implement), never [x] with "NOT RUN". Add
logging only as the Settings logging level says: for standard / verbose log the fix's inputs, success and error
context with the prefix [FIX] (or [FIX:<issue-id>]) so it can be filtered, configurable through LOG_LEVEL if the
project has it; for minimal add none. Do not refactor unrelated code or add features while fixing.
Step 4: Verify the fix
- Check the code compiles/runs.
- Rerun or revisit the same regression check from Step 2.5 and confirm the fixed behavior; quote the passing output.
- Verify the logic is correct and no regressions were introduced; run the closest existing related test suite.
Step 5: Suggest more coverage
Output the fix summary, then one line: Suggested extra coverage: <the edge case that caused the bug, as a test name>, and ask with AskUserQuestion: Write this test now (new file) (Recommended when the regression check was
manual) · Skip. On yes, write it as a new test file, run it, and include it in the fix commit.
✅ Fix applied (or ⚠️ Fix applied, regression check manual · ❌ Not fixed — <why>)
**Issue:** [what was broken]
**Cause:** [why it was broken]
**Fix:** [what was changed]
**Regression check:** [command/check and result, manual/runtime reproduction result, or "not available: <reason>"]
**Files modified:** path/to/file.ts (line X)
**Logging added:** [prefix `[FIX]` | none (minimal)]
**Владелец:** <remote>; <warning>
Step 6: Root cause and prevention — in plan.md
Fill the plan's ## Root cause and ## Prevention sections (no separate patch file). Root cause is the most valuable
part — not "what was wrong" but "why it was wrong": a logic error (why was the logic incorrect?), a missing check (why
was it missing?), a wrong assumption (what was assumed?), a race (what sequence caused it?). Prevention: what pattern or
practice prevents this class of problem, what to check in code review, what test would catch it. Level S: once the
regression check is green in this session, set Status: verified yourself (an allowed transition for S-fix) BEFORE
the single commit of code and plan (git diff --cached --stat; the plan must be staged). Level M: commit code and plan
together and recommend /keystone:verify <plan> in a new session. Run beat right before the commit (taken → STOP
without it) and release right after it.
Commit scope. If the project has commitlint (.commitlintrc*, commitlint.config.*, or a commitlint key in
package.json) with a scope-enum rule, use only a scope from that list — the closest one (e.g. docs), or no scope
if the rule allows it; never a scope the hook rejects. No scope list → keep the Keystone scope (fix(<area>)).
Suggest /clear to free context if needed.
End the report with a fixed three-heading summary, short, on top of the line-by-line report (not instead of it). It is
followed only by the Next: line (see Next step): decisions for a human go inside Blocked on me:, the command to run
is the Next: line, nothing else after it.
Blocked on me: <what needs a human decision or action, incl. next step | none>
Changed: <files / commits / status set | none>
Found: <defects, surprises, open questions | none>
One session per plan
fix takes its plan so that a second session cannot run it at the same time; the record lives on the service branch
keystone/owners, the work tree and the plan folder are not touched. Script:
node "${CLAUDE_SKILL_DIR}/../implement/scripts/owner.mjs" take|beat|release <plan> [--stage fix] [--force] [--any] — one
JSON line; exit 0 = go on, 3 = stop, 1 = error (say it in one line and go on). Run every call as a command of its own
and read its exit code before the next step — never chained with the fix's work (;, &&).
node "${CLAUDE_SKILL_DIR}/../implement/scripts/owner.mjs" take <plan> --stage fix— as soon as the plan path is known (Step 0: an existing fix plan, Verify findings mode; Step 1: Fix now, right after writingplan.md) and before any edit, the Status line included. Exit 3 → printПлан <folder> ведёт <place> · ветка <branch> · <stage> с <since>, последний признак жизни <beat>and ask (AskUserQuestion): a live owner →Стоп (Recommended)·Забрать план; a stale one (stale: true, no beat for 2 h) →Забрать план (Recommended)·Стоп.Забрать план→take --force;Стоп→ STOP with the same command asNext:. No AskUserQuestion → STOP for a live and a stale owner alike, no--force.node "${CLAUDE_SKILL_DIR}/../implement/scripts/owner.mjs" beat <plan> --stage fixbefore each finding of Verify findings mode and before every commit; exit 3 (taken) → STOP:План забрала <place> в <since> — эта сессия останавливается, no commit.release <plan>right after the fix commit.remote: "local"+warning→ say it once and go on.KEYSTONE_GATES=off→ nothing is guarded.
Important rules
- Plan first = plan only — when the user chooses "Plan first", write the plan and STOP. Do NOT fix.
- Execute mode = follow the plan — when an active fix plan exists, follow it step by step.
- NO reports — no summary documents; the plan is the record.
- Log as Settings say —
[FIX]prefix, never hardcoded noise. - Regression-first when checks are needed — follow the Canonical Regression-First Policy before changing implementation code, confirm the problem when reproducible, then verify the same check after the fix.
- Do not fit tests to implementation — regression tests encode the reported/expected behavior, not the internal shape.
- Tests in HEAD are untouchable — the regression test is a new file (your own uncommitted one is editable); a wrong existing test is the human's call.
- Root cause — fix the actual problem, not symptoms. Minimal changes; one fix at a time, no scope creep —
except
/keystone:fix verify, which fixes every finding of the FAILverify.mdin one pass — every finding and every place of its class.
DO NOT: apply a fix when the user chose "Plan first"; skip the active-plan check; refactor unrelated code; add
features; edit test files that exist in HEAD; claim pass for a check that did not run in this session.
Project memory (memlab, optional)
After the fix is committed, if memlab's add_note is available, record the lesson: one-line summary, body with
## Root cause and ## Prevention (copied from the plan) and the plan path; list a superseded note in supersedes.
Commit the new docs/notes file together with the plan header update. No memlab — the plan's sections are the record.