execution-loop

name	execution-loop
description	This skill should be used for authorized multi-step coding implementation work, including applying a plan, finishing a feature, implementing review feedback, or turning a specification into working code. It guides the agent through reading requirements and files, planning ordered units, making minimal edits, reviewing diffs, fixing findings, verifying with targeted and final checks, and committing only when explicitly authorized. Do not use it for trivial one-line edits or pure explanations.
compatibility	Designed for Claude Code and Agent Skills-compatible coding agents with file, shell, test, and git access.
license	MIT

Execution Loop

Use this skill when the user asks you to build, implement, finish, apply a plan, execute a spec, or complete several code changes. The purpose is to make implementation reliable: read the source of truth, choose the correct order, make minimal changes, review them, fix what review finds, and only then finalize.

Do not use this skill for a trivial one-line edit, a pure explanation, or a command-only request. If the task becomes multi-step while working, switch into this loop and say so briefly.

Core model

Read        collect requirements, constraints, context, and relevant code before editing
Plan        split work into ordered units with success checks
Execute     implement one unit at a time with minimal, scoped edits
Review      compare diff against the request and look for defects or drift
Fix         address review findings or verification failures, then review again
Verify      run targeted checks per unit; for multiple units, run final full checks
Commit      commit only when explicitly authorized by the user
Handoff     report what changed, what passed, and what remains

This skill is selected for implementation integrity, not speed, token economy, response brevity, or the appearance of quick completion. Do not optimize for token cost or response length by compressing away reading, planning, review, targeted verification, or the fix loop. If the task is small, use the lightweight mode below; do not silently skip the safeguards that keep the implementation aligned with the request.

Depth control

Choose the lightest loop that still protects correctness:

• Lightweight inline: Use for one small implementation unit touching one or two files. State the target, one-line plan, one check, then implement and do a short diff-vs-request review. The full Unit / Reason / Depends on / Check block is optional.
• Standard loop: Use for most feature work, bug fixes, review feedback, or changes spanning several files. Use ordered units with Unit / Reason / Depends on / Check, targeted checks, and per-unit review.
• Persistent execution log: Use for long tasks, many independent units, risky migrations, or work likely to be handed off. Keep a todo list or state notes with completed units, checks, review findings, and open items.

Do not let the format become the work. Scale the ceremony down for small tasks, but keep the sequence: read before edit, plan before execution, review before done, verify before final report.

Preconditions

• Read relevant instructions first: user request, existing plan/spec, CONTEXT.md if present in the project root, README, contributing notes, and nearby code.
• Read files before editing them.
• Do not refactor adjacent code unless required by the plan or a confirmed fix.
• Do not broaden scope silently. If the plan uncovers a larger design decision, pause and ask.
• Commit only when the invoking user explicitly asked for or authorized commits. Never treat this skill itself as commit authorization.

Workflow

1. Read

Extract and restate the working contract:

• requested outcome
• files or systems likely involved
• explicit constraints and non-goals
• required ordering or dependencies
• expected verification commands
• whether commit is authorized

If the request references an existing plan, issue, PR comment, review, or pasted checklist, treat that as the source of truth. Preserve its order unless code evidence shows a dependency requires reordering; if you reorder, say why.

2. Plan

Create a short ordered checklist. Each unit should include:

Unit: what will change
Reason: which requirement it satisfies
Depends on: prior unit or context, if any
Check: targeted verification for this unit

In lightweight mode, the plan may be a single sentence: "Change X because Y; check with Z." In standard or persistent mode, use the full unit format. For larger tasks, use the todo list if available and keep exactly one item in progress.

Default commit strategy when commits are authorized:

• Small to medium tasks: one final commit after verification.
• Large multi-part tasks: commit per coherent unit only if each unit can stand alone and the user authorized that style.
• If unsure, ask before committing.

3. Execute

Work one unit at a time:

1. Mark or note the current unit.
2. Re-read the relevant requirement for that unit.
3. Make the smallest implementation that satisfies it.
4. Avoid drive-by cleanup, renames, formatting churn, or unrelated dependency changes.
5. Run the unit's targeted check when practical.

After each unit, ask: "Am I still doing exactly what was requested?" If not, stop and correct course before continuing.

4. Review

Before declaring a unit done, review the actual diff. Always run the universal checks, then add the review lens that matches the unit type.

Universal checks:

• Does every changed line map to a requirement, dependency, or confirmed fix?
• Did the implementation preserve existing behavior not mentioned by the task?
• Is there any accidental secret, credential, generated artifact, or local-only file?

Review lens by unit type:

• New feature or behavior: check requirements coverage, user-visible states, errors/empty states, integration points, and tests or docs for the new behavior.
• Existing behavior fix: check reproduction path, regression risk, edge cases around the failing path, and whether the targeted test would fail without the fix.
• Refactor or internal change: check behavior preservation, public API compatibility, typing, imports/exports, and whether the diff avoids unrelated cleanup.
• Test-only change: check that the test asserts behavior rather than implementation trivia, fails for the original bug when practical, and is not flaky or over-broad.
• Documentation/config/build change: check command names, paths, environment assumptions, ordering, and whether generated or local-only files were avoided.
• Risky system change: for security, database, concurrency, external API, migrations, or flaky tests, escalate to evidence-gated review/debug instead of relying on this checklist alone.

For risky, multi-file, security-sensitive, database, concurrency, external API, flaky test, or unclear bug work, invoke the evidence-gated-review skill or a review/debug specialist rather than relying only on a quick self-review.

5. Fix loop

If review or verification finds an issue:

Finding: concrete defect or mismatch
Cause: why it happened, if known
Fix: smallest correction
Re-check: targeted verification to rerun

Apply the fix, rerun the relevant check, and review the new diff. If the same class of issue repeats or two fix attempts fail, stop and hand off with evidence instead of looping indefinitely.

6. Verify

Verification is layered:

• Targeted checks: run after the unit they cover.
• Integration checks: run when multiple touched pieces interact.
• Final full gate: if multiple units/files/features were changed, run the project's full or conventional test/build/lint suite when feasible.
• Light final review: after the full gate, do one last diff-vs-request review to catch drift.

If a check cannot be run, say why and name the best substitute or next command.

7. Commit

Only commit when explicitly authorized. Before committing:

• inspect status, diff, and recent commit style
• stage only relevant files
• use a message that explains the purpose of the change
• do not include secrets or unrelated local files
• do not push unless the user explicitly asked for push/publication

If pre-commit hooks modify files or fail, follow the repository's safe git rules: inspect the result, fix issues, and avoid amend/force operations unless explicitly allowed and safe.

8. Handoff

End with a concise report:

Implemented
- ...

Verification
- targeted check: pass/fail/not run
- final full gate: pass/fail/not run
- light review: pass/fail/notes

Commit
- hash/message, or "not committed because ..."

Open items
- remaining risk or next step, if any

Failure modes to avoid

• Editing from memory without reading the file.
• Treating the plan as complete after implementation but before review.
• Running only broad tests while skipping the targeted check that proves the changed behavior.
• Continuing to patch after repeated inconclusive failures.
• Committing untracked files just because they exist.
• Compressing multiple independent tasks into one unreviewed blob.