agentleFS
radiovisualradiovisual/claude-skills/skills/plan-verify-fix/SKILL.md

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.

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
  1. Distinctive:

    The one rule: every task ends in a check that returns pass/fail, and a commit.

    line 14
  2. Very specific:

    Keep all state in files so any step can continue after /clear or in a new session:

    line 34
  3. Very specific:

    Read CLAUDE.md and .claude/references/conventions.md if present.

    line 47
  4. Very specific:

    If on the default branch, create feature/<slug> or fix/<issue>-<slug>.

    line 51
  5. Distinctive:

    Use the AskUserQuestion tool (plain numbered questions if it isn't available).

    line 56
  6. Distinctive:

    Always settle: what "done" looks like (the end-to-end check), what's out of scope, and constraints (versions, dependencies you may not add, …

    line 60
  7. Very specific:

    Keep their conclusions, not their file dumps.

    line 70
  8. Distinctive:

    Write SPEC.md: goal, decisions (with the reason for each), research findings, out of scope, risks, and the

    line 74
  9. Distinctive:

    Write or update the test first, where practical, and watch it fail.

    line 99
  10. Distinctive:

    Run the task's check, then the full verify command.

    line 101
  11. Distinctive:

    Stop and ask the user: when: the same failure survives two different fixes.

    line 108
  12. Very specific:

    Keep context clean: after every few tasks, make sure PLAN.md is up to date.

    line 113
  13. Very specific:

    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 …

    line 122
  14. Distinctive:

    Close the work folder: before the PR, so the PR carries its final state.

    line 133
  15. Distinctive:

    Delete the folder: when the PR description is record enough.

    line 139
  16. Distinctive:

    Add lessons to CLAUDE.md (only rules Claude kept getting wrong, one line each).

    line 148

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

ModeWhenPath
SmallThe whole change fits in one sentence and one commitSkip the interview and spec: one task, then verify and commit
FeatureAnything biggerInterview → research → SPEC → PLAN → loop → review
BugAn issue URL or number, an error, or "X is broken"Same, but reproduce before fixing: BUGS.md
Resumeresume <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 each

Templates: 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

  1. Read CLAUDE.md and .claude/references/conventions.md if 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.
  2. git status: if there are uncommitted changes, ask whether to commit or stash first. Don't mix them into this work.
  3. If on the default branch, create feature/<slug> or fix/<issue>-<slug>.
  4. 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:

  1. Mark it in progress. Read only the files it needs.
  2. Write or update the test first, where practical, and watch it fail.
  3. Implement.
  4. 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.
  5. 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.
  6. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.