Keystone · check — refine the plan with fresh eyes
The plan was written by one context; this skill re-checks it with two other contexts (an analyzer and a validator) and shows the human only what survives. It is read-only for code: it never edits source files, only the plan, and only after an explicit answer.
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.
Core idea
(Cost: two Opus agents. The validator is mandatory here; in upstream AI Factory it was the optional +check.)
keystone:analyzerre-reads the codebase deeper than the planner did and lists findings.keystone:validator(always, fresh context) re-reads the plan and the cited files and keeps, modifies or drops each.- You show the report and
Coverage: … · verdict, ask, and only then edit the plan.
Step 1 — resolve the inputs
$ARGUMENTS = <intent path> <plan path>, or <plan path> only, or nothing — then, optionally, a free-text
request: what the user wants changed in the plan (/keystone:check <plan> add a migration rollback task). The
leading words that are existing files or folders are the paths; everything from the first word that is not one is the
request. No such text → Request: none.
- Two paths: use them. A path may be a task folder — then
intent.md/plan.mdinside it. - One path (plan): take the intent from the plan's
Authority:line, if there is one. No Authority line → no intent; say so, skipintent-gapand the I-n lines (Coverage then readsn/a). Decisions instead of an intent file: when Authority or## Original Requestpoints to a numbered grill decision list (D1…) rather than a file, check that list as the intent (D1 covered — …), and head the reportIntent: reconstructed from the plan's D-list, not a signed intent.md— the verdict is then advisory, and recommend/keystone:intentto record it. - Nothing: the 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. Its intent from Authority.
- No plan found: print
FAIL: plan not foundand stop. - On an approved plan the report only reports: changes to the plan are applied after the user's answer (Step 4), never directly.
Read the plan completely. Note what is done (- [x], never touched), the ## Original Request (the scope anchor,
never touched), the Settings line, the Requirements Reconciliation table, the Risks, the Tasks and the Commit Plan.
Project rules (those that exist): CLAUDE.md, .claude/CLAUDE.md, docs/architecture.md, .claude/rules/**/*.md
(paths: rules apply only to matching files), AGENTS.md. Intent
status not accepted, or intent.md changed after the plan's first commit (git log) → remember it for the Notes line.
Step 2 — analyze
Launch one agent: subagent_type: "keystone:analyzer". Its prompt names, as absolute paths: the plan, the intent (or
"none"), the rule files, the request (or "none"), whether memlab MCP tools are available in this session, and the instructions ${CLAUDE_SKILL_DIR}/references/ANALYZE.md ("read it completely and
follow it"). It returns findings F1… (groups missing, improvements, removals, out_of_scope, intent-gap,
goal-drift, rule-violation), dependency lines D1…, and the I-n status: lines.
If the analyzer fails or returns nothing: print FAIL: analyzer failed (<reason>) and stop — a check with no analysis
is not a PASS.
Step 3 — validate (always)
Number the findings Item 1… in group order (goal-drift, missing, improvements, removals, out_of_scope,
intent-gap, rule-violation), keeping the F-id and the group in each heading. If the list is empty, skip the validator: hidden = 0,
adjusted = 0.
Launch a fresh agent: subagent_type: "keystone:validator". Pass the plan path, the intent path, the rule files, the request,
${CLAUDE_SKILL_DIR}/references/VALIDATOR.md and the items — not the analyzer's reasoning. Parse by ### Item N
headings. The group is always the original one; a differing Group: makes the block malformed.
keep→ unchanged.modify→ replace the text withModified-text, adjusted += 1.drop→ remove, hidden += 1.
Failure modes:
- a block is malformed (no heading, no
Verdict, unknown token,modifywithoutModified-text, group changed) → treat it askeep; end the report withWARN [validator]: validator response for item N was malformed, kept as-is; - the whole call failed (empty, error, timeout, refusal) → all items
keep, no Hidden/Adjusted rows, end the report withWARN [validator]: validator failed (<reason>), all items kept as-is.
Then recompute the dependency fixes yourself, against the post-validation plan state: start from the plan's tasks, add
tasks from missing keep/modify, remove tasks targeted by removals and out_of_scope keep/modify (a dropped removal
keeps its task, which stays a valid target); improvements never change the graph. Discard every D that points at a
task absent from that state. Dependencies are not sent to the validator.
A validator drop of a missing/partial gap on an I-n means the validator found the delivering task: that I-n is
covered. Otherwise the analyzer's I-n status: lines stand, adjusted by kept/modified intent-gap findings.
Step 4 — present
Report shape (structure fixed; wording in the user's language):
## Plan Check Report
Plan: <path> · Intent: <path | none> · Request: <text | none>
Tasks analyzed: N
### Findings
#### 🆕 Missing Tasks (N found)
#### 📝 Task Improvements (N found)
#### 🔗 Dependency Fixes (N found)
#### 🗑️ Removals (N found)
#### 💡 Out of scope — for later (N found)
#### 🎯 Intent gaps (N found)
#### ⛔ Rule violations (N found)
#### 📋 Summary
- Missing tasks: N · Tasks to improve: N · Dependencies to fix: N · Tasks to remove: N · Out of scope: N
- Intent gaps: N · Rule violations: N
- Hidden by validator: N · Adjusted by validator: M
I-1 covered — Task 2 · check: <the proving check>
I-2 partial — <what is missing>
I-3 missing
Notes: <intent not accepted / rework signal / numbering> | none
Coverage: <covered>/<total> = <p>% (partial counts 0.5) · verdict: PASS | FAIL
Items in the first five groups are prose with no labelled fields: (1) behavioural impact — what breaks or gets harder if
the plan stays as is; (2) optional note — a short code citation path:line; (3) plan anchor — Task #X ("after Task #X"
for new tasks); (4) suggested edit — concrete. Dependencies use the short form
Task #X should depend on Task #Y. Reason: …. Omit empty groups. verdict is PASS only with no missing I-n, no
kept rule violation, no kept goal-drift and Coverage ≥ 90 %; otherwise FAIL. A kept goal-drift is shown first:
"The plan delivers , you asked for " — the fix is /keystone:intent, not a plan edit. With no intent: drop the I-n lines and write
Coverage: n/a · verdict: by the other two conditions.
No findings at all: Plan looks solid — no significant gaps. plus the I-n lines and the Coverage line.
Then AskUserQuestion: Apply all · Let me pick which ones · Nothing — keep the plan as it is. "Let me pick"
→ one question per item. "Nothing" → no edit, but the Coverage line is still written (Step 5, last paragraph).
Step 5 — apply (only after the answer)
Edit the plan with Edit, surgically — never regenerate it:
- improvements: reword the task line, keep
— files: … — check: …, add the missing path or check; - missing: add
- [ ] N. …in the right place, renumber the following tasks and the references to them; - removals / out_of_scope: delete the task, renumber, fix the references;
- dependencies: move the dependency before its dependent, or write
after task Nin the line; - intent-gap: add the delivering task or the proving check, and a row in
## Requirements Reconciliation(| Decision | Source | Verification evidence |, Source =intent — I-n); - rule-violation: change the step so it obeys the rule; update the
Project rules check:line; - keep Reconciliation, Risks and Commit Plan in step with the tasks (≥5 tasks → a Commit Plan must exist).
Finally write — or replace — the line Coverage: <covered>/<total> = <p>% (partial counts 0.5) · verdict: <PASS|FAIL> · <date> directly after the Project rules check: line. After edits, recount the I-n against the edited plan. Close with the
refinement summary, counted from the edits you just made (not from the findings list):
Plan refined: <a> added / <c> changed / <r> removed — added = new tasks (missing, intent-gap), changed = reworded
tasks, moved dependencies, rule-violation and check-only intent-gap edits, removed = removals and out_of_scope; the
answer "Nothing" → Plan refined: none — kept as is. Under it, git diff --stat for the plan. Nothing is committed
here.
Only check writes the Coverage: line; no other skill recomputes it. If the plan was edited by hand after check,
append · not re-checked to that line.
Important rules
- Don't rewrite from scratch — improve the existing plan, don't replace it.
- Preserve completed work — never modify or remove
- [x]completed tasks. - Traceable improvements — every change must be justified by codebase analysis or user input.
- Respect settings — if Settings say tests "no", don't add test tasks. If logging is "minimal", don't add verbose logging tasks.
- No gold-plating — don't propose adding tasks outside the feature scope unless critical. When you find a task already in the plan that drifts outside scope, route it to the "Out of scope" report section, not to "Removals" — the user should see useful-but-not-here ideas separately from dead-weight duplicates.
- Minimal viable improvements — suggest only what matters, not every possible enhancement.
- User approves first — never apply changes without user confirmation.
- Keep plan file in sync — the plan file MUST match the task list after improvements.
- Original Request is immutable — use
## Original Requestto judge scope and preserve it verbatim on every plan edit. - Requirements remain external evidence — never rewrite requirement, intent, rules or architecture artifacts to make the plan look consistent; refine the plan or report the conflict.
- Code is never edited here. A checked box is not evidence — judge by the plan text and the code, not by the marks.
After the report
PASS and the human agrees → Approve plan, then /keystone:implement. FAIL → apply the fixes (or edit the plan by
hand) and run /keystone:check again. The gate on code edits stays until the plan is approved (lift: Status: abandoned
in the plan header, or env KEYSTONE_GATES=off).