plan-verify-fix
Skill0 starsChanged 57 days agoMITView on GitHub
Run a feature or bug fix end to end with the Plan → Verify → Fix loop. Interviews you, sends subagents to research, writes a spec and a plan of small verifiable tasks, then builds, verifies and commits each task on its own, stopping for your approval at the gates. Coaches the habits along the way.
In this repository10 other files it gives its agents.
- feature-slicingSkill
- mermaid-diagramsSkill
- modern-cssSkill
- piv-commitSkill
- piv-create-prSkill
- piv-fix-review-findingsSkill
- semver-releaseSkill
- slack-block-kitSkill
- slack-mrkdwnSkill
- verify-setupSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
The one rule: every task ends in a check that returns pass/fail, and a commit.
- Very specific: line 34
Keep all state in files so any step can continue after /clear or in a new session:
- Very specific: line 47
Read CLAUDE.md and .claude/references/conventions.md if present.
- Very specific: line 51
If on the default branch, create feature/<slug> or fix/<issue>-<slug>.
- Distinctive: line 56
Use the AskUserQuestion tool (plain numbered questions if it isn't available).
- Distinctive: line 60
Always settle: what "done" looks like (the end-to-end check), what's out of scope, and constraints (versions, dependencies you may not add, …
- Very specific: line 70
Keep their conclusions, not their file dumps.
- Distinctive: line 74
Write SPEC.md: goal, decisions (with the reason for each), research findings, out of scope, risks, and the
- Distinctive: line 99
Write or update the test first, where practical, and watch it fail.
- Distinctive: line 101
Run the task's check, then the full verify command.
- Distinctive: line 108
Stop and ask the user: when: the same failure survives two different fixes.
- Very specific: line 113
Keep context clean: after every few tasks, make sure PLAN.md is up to date.
- Very specific: line 122
When all tasks are ticked, get a review from a fresh context: run the code-review skill on the branch, or send a general-purpose subagent …
- Distinctive: line 133
Close the work folder: before the PR, so the PR carries its final state.
- Distinctive: line 139
Delete the folder: when the PR description is record enough.
- Distinctive: line 148
Add lessons to CLAUDE.md (only rules Claude kept getting wrong, one line each).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plan → Verify → Fix
Input: $ARGUMENTS
You run the whole loop and do the work. The user approves at the gates and learns the habits as you go.
The one rule: every task ends in a check that returns pass/fail, and a commit. If it can't be verified, it isn't done. Show evidence (the command and its output, a screenshot), never just "it works".
Modes
Decide from the input and say which one you chose:
| Mode | When | Path |
| Small | The whole change fits in one sentence and one commit | Skip the interview and spec: one task, then verify and commit |
| Feature | Anything bigger | Interview → research → SPEC → PLAN → loop → review |
| Bug | An issue URL or number, an error, or "X is broken" | Same, but reproduce before fixing: BUGS.md |
| Resume | resume <slug> | Read the work folder and continue from the first unfinished step |
Coaching (see COACHING.md): by default, add one short Habit line at each gate
saying what just happened and why it matters. --coach explains more, including what the user would press or type
to do it themselves, and ends with a short retro. --quiet leaves the habit lines out.
Where the work lives
Keep all state in files so any step can continue after /clear or in a new session:
docs/work/<slug>/SPEC.md what and why, decisions, research, end-to-end check (or DIAGNOSIS for bugs)
docs/work/<slug>/PLAN.md small tasks, each with files, out-of-scope, check, status and evidence
docs/work/<slug>/LOG.md decisions, failures, recoveries and lessons, one dated line eachTemplates: DOCUMENTS.md. A ## work section in .claude/references/conventions.md
overrides the location. Update the files as you go; they are the source of truth, not the chat.
Phase 0: Get ready
- Read
CLAUDE.mdand.claude/references/conventions.mdif present. Find the verify command (lint, type-check, tests, build). If the project has none, stop and offer/verify-setup(recommended), or agree on a verify command for this run and note it in SPEC.md. git status: if there are uncommitted changes, ask whether to commit or stash first. Don't mix them into this work.- If on the default branch, create
feature/<slug>orfix/<issue>-<slug>. - Pick the mode.
Phase 1: Interview
Use the AskUserQuestion tool (plain numbered questions if it isn't available). Ask only what the input and code don't already answer: at most 4 questions per round and 3 rounds. Offer concrete options with a recommended one first. Question sets: INTERVIEW.md.
Always settle: what "done" looks like (the end-to-end check), what's out of scope, and constraints (versions, dependencies you may not add, data you must not touch).
Phase 2: Research with subagents
Split the unknowns into 2–4 independent questions and send one subagent per question, in parallel. Use the
read-only Explore type for the codebase and general-purpose for external docs or APIs. Brief each one with the
template in SUBAGENTS.md: the question, where to look, what's out of bounds, and the exact
shape of the answer. Subagents research; they don't edit files.
Keep their conclusions, not their file dumps. Write the findings (with file:line references) into SPEC.md.
Phase 3: Spec, then Gate 1
Write SPEC.md: goal, decisions (with the reason for each), research findings, out of scope, risks, and the end-to-end check. For bugs, first reproduce it and write the diagnosis (BUGS.md).
Gate 1: show a short summary and the path to SPEC.md. Wait for approval or edits. Tell the user they may
/clear now and continue with /plan-verify-fix resume <slug>; a fresh context builds better than a long one.
Phase 4: Plan, then Gate 2
Break the spec into tasks in PLAN.md. Every task is:
- Small: one commit. If you can't describe its diff in two sentences, split it.
- Specified: files to touch, what's out of scope.
- Verifiable: the exact check (a test command, the verify command, or a screenshot compared with a mockup), runnable in about a minute.
Order tasks so each leaves the project working. Then send one subagent with fresh context to critique the plan ("what's missing or wrong? correctness and requirements only") and fix what it finds.
Gate 2: show the task list. Wait for approval. The user may edit PLAN.md directly.
Phase 5: Build loop (runs on its own)
For each unchecked task in PLAN.md:
- Mark it in progress. Read only the files it needs.
- Write or update the test first, where practical, and watch it fail.
- Implement.
- Run the task's check, then the full verify command. Iterate until both pass. Fix root causes; never skip, weaken or delete a test to get green.
- UI work: screenshot and compare with the mockup if you have a browser tool; otherwise stop at a visual gate and ask the user to look.
- Paste the evidence (command + the last lines of output) into the task in PLAN.md, tick it, and commit it with
piv-commit: one commit per task.
Stop and ask the user when: the same failure survives two different fixes; the approach turns out wrong; the task needs something outside the plan (new dependency, scope change, schema change on shared data); a step is destructive or outward-facing (pushing, migrations on real data, messages to other people); or you need a human to look at something. Recovery choices: RECOVERY.md. Log every failure and recovery in LOG.md.
Keep context clean: after every few tasks, make sure PLAN.md is up to date. If the session is getting long,
suggest /compact keep PLAN.md status and the verify command or /clear plus resume.
Parallel work (optional): tasks that touch completely separate files can go to general-purpose subagents with
isolation: worktree, one task each, briefed like research agents plus the task's check. Only when the user
agrees; review and merge each result before starting dependent tasks.
Phase 6: Independent review
When all tasks are ticked, get a review from a fresh context: run the code-review skill on the branch, or send a
general-purpose subagent with the reviewer brief in SUBAGENTS.md (diff against SPEC.md
and PLAN.md; missing requirements, untested edge cases and out-of-scope changes only). Handle the findings with
piv-fix-review-findings: the user decides what to fix now. Run the end-to-end check from SPEC.md and the full
verify command again.
Phase 7: Gate 3 and wrap-up
Show: tasks done with their evidence, the end-to-end check result, review findings and how each was handled, and anything deferred.
Close the work folder before the PR, so the PR carries its final state. Ask what to keep (see "After the work" in DOCUMENTS.md):
- Keep only SPEC.md (recommended): it records why the change was made this way. PLAN.md and LOG.md are removed; their evidence lives on in the commits and the PR.
- Keep all three: for when the full story, failures included, is worth having in the repository.
- Delete the folder: when the PR description is record enough.
For anything kept, set SPEC.md to Status: done (<date>). Commit the result with piv-commit. If a PR is opened
next, add its link to SPEC.md afterwards in a small follow-up commit on the same branch.
Then offer, and do only on a yes:
- Open a PR with
piv-create-pr(link the issue:Fixes #N). - For a bug, comment on the issue with the root cause and the fix.
- Add lessons to
CLAUDE.md(only rules Claude kept getting wrong, one line each).
With --coach, finish with a three-line retro: what went well, one failure and how it was recovered, one habit to
practise next time.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

