| name | builder-loop |
| description | Run a substantial coding task as an evidence-driven closed loop: inspect the repository, define the decision and acceptance evidence, implement the smallest useful change, verify real behavior, expose deviations and debt, and finish with one explicit recommendation. |
| argument-hint | <feature, bug, experiment, review, or ship task> |
| disable-model-invocation | true |
| effort | high |
Builder Loop
Task
$ARGUMENTS
Objective
Complete the task while optimizing for verified outcomes and decision quality, not code volume.
Do not stop after producing a plan unless a genuine approval gate is reached. After the execution contract, proceed through implementation and verification in the same session whenever the work is reversible and sufficiently specified.
Do not commit, push, deploy, delete data, alter production configuration, or make irreversible changes unless the invocation explicitly requests it or the user later approves it.
1. Classify the task
Choose one primary mode:
- Implement — add or change behavior.
- Debug — reproduce and fix a failure.
- Experiment — test a product or technical hypothesis.
- Review — inspect work and recommend a decision.
- Ship — establish readiness and perform an explicitly requested release action.
- Explore — reduce uncertainty before choosing an implementation.
If the task text is empty, ask for the task and stop.
2. Inspect before changing anything
Read the minimum repository context needed to avoid guessing:
CLAUDE.md files that apply to the target area.- Current git status and relevant recent changes.
- Relevant implementation, tests, types, configuration, and documentation.
- Existing conventions and nearby analogous code.
- For bugs, available logs, screenshots, traces, and production/local differences.
State what was actually inspected. Do not imply knowledge of files or behavior that were not read or run.
3. Publish a concise execution contract
Before editing, show this block:
Execution contract
- Mode: one mode.
- Decision unlocked: what this work will allow the user to decide or safely do.
- Desired outcome: observable user or system behavior.
- Current evidence: facts already verified.
- In scope: smallest change capable of producing the outcome.
- Out of scope: attractive adjacent work that will not be done.
- Invariants: behavior, interfaces, safety properties, and tests that must remain true.
- Verification: exact evidence required before claiming completion.
- Risk level: low, medium, or high, with one-sentence rationale.
Avoid ceremonial detail. Keep the contract proportionate to the task.
Approval gate
Proceed immediately for low- and medium-risk reversible work when requirements are clear.
Pause before editing only when a material choice is unresolved in one of these areas:
- authentication or authorization;
- user identity, tenant isolation, consent, privacy, or other sensitive-data logic;
- destructive migration or data deletion;
- secrets, billing, production deployment, or production configuration;
- breaking public APIs or persisted schemas;
- weakening, deleting, or redefining tests or acceptance criteria;
- a change whose likely blast radius cannot be bounded from repository evidence.
At an approval gate, present the recommended choice, the main alternative, the consequence of each, and the exact evidence still missing. Ask one focused question.
4. Execute the smallest decision-producing solution
During execution:
- Preserve the stated scope and invariants.
- Prefer a narrow vertical slice over a generic framework.
- Follow repository conventions before introducing abstractions.
- Add or update tests for changed behavior.
- Never make a test weaker merely to obtain green checks.
- If a test must change because the intended invariant changed, explain that change explicitly before treating it as valid.
- Separate extracted facts, repository evidence, assumptions, and recommendations.
- Record meaningful deviations, unexpected findings, temporary shortcuts, and unverified assumptions.
- Do not silently broaden scope when discovering adjacent defects. Report them separately unless they block the requested outcome.
- Do not claim production, security, compliance, performance, or user-value results without direct evidence at that level.
5. Mode-specific requirements
Debug
Establish or reconstruct:
- environment and affected version;
- exact starting state;
- reproduction steps;
- expected behavior;
- actual behavior;
- frequency and scope;
- local versus production behavior;
- relevant logs or recent changes.
Reproduce before fixing whenever feasible. After the fix, run the same path that originally failed and at least one nearby failure case.
Experiment
State:
- hypothesis;
- cheapest credible test;
- success threshold;
- falsifying result;
- data or observations to collect;
- decision for each likely outcome.
Do not turn an experiment into platform work. Implement only what is needed to obtain the evidence.
Review
Do not edit files unless the user explicitly asked for fixes. Rank findings by severity, cite concrete files and behavior, distinguish confirmed defects from risks, and finish with one recommendation.
Ship
Verify the exact artifact and environment that will ship. A green unit test suite alone is insufficient. Check configuration, migrations, rollback or recovery, observability, and a representative running path. Never push or deploy unless explicitly requested.
Explore
End with a recommendation, not an unranked menu. Name the decisive uncertainty and the smallest next experiment or implementation.
6. Verify in layers
Use the highest relevant evidence level:
- Static: diff inspection, types, lint, build, schema checks.
- Behavioral: targeted tests, end-to-end path, logs, screenshots, failure cases.
- Environment: production-like configuration, real dependencies, migration behavior, deployed path when authorized.
- Value: observed user behavior, repeated use, measurable improvement, commercial commitment.
Do not substitute a lower level for a required higher level. Clearly label any level that was not reached.
Before completion:
- inspect the final diff;
- confirm no unrelated files changed;
- list all changed tests and why;
- search for hardcoded values, fixtures, debug bypasses, TODOs, and temporary flags introduced by the task;
- run the most relevant available checks;
- exercise the user-visible or system-visible behavior when feasible;
- compare the result against every invariant and acceptance condition.
7. Completion report
Never finish with only “implemented,” “tests pass,” or a list of files.
Use this exact structure:
Completion report
Outcome
- What now works or what was learned.
Changed
- Material behavior, interfaces, configuration, and files changed.
Evidence produced
- Commands run, tests executed, paths observed, logs, screenshots, benchmark results, or user evidence.
Not verified
- Environments, inputs, failure modes, or claims not directly tested.
Plan deviations
- Every meaningful departure from the execution contract, or
None.
Test integrity
- Tests added, modified, removed, skipped, or made more permissive, with reasons.
Debt and shortcuts
- Hardcoded values, fixtures, temporary flags, deferred cleanup, or
None.
Remaining risks
- What could still make the result wrong, unsafe, or incomplete.
Decision
Choose exactly one:
- Approve and merge
- Revise before merging
- Run another experiment
- Stop or abandon
Give the reason in one or two sentences.
Next action
- One concrete action only.
If commit, push, or deployment was requested, also report the exact branch, commit, target, and observed result. Never state that one occurred unless the command was actually executed successfully.
8. High-risk overlay
When the work touches sensitive data, identity, tenancy, authorization, consent, destructive
data operations, or externally published claims, also apply
references/high-risk-changes.md.
9. Standard of truth
Use these labels consistently:
- Verified: directly inspected, executed, or observed.
- Inferred: supported by evidence but not directly observed.
- Assumed: required to proceed but not verified.
- Unknown: missing information that could materially change the result.
The goal is not to make the work look complete. The goal is to make the true state of the work impossible to misunderstand.
