builder-loop

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:

1. CLAUDE.md files that apply to the target area.
2. Current git status and relevant recent changes.
3. Relevant implementation, tests, types, configuration, and documentation.
4. Existing conventions and nearby analogous code.
5. 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:

1. Static: diff inspection, types, lint, build, schema checks.
2. Behavioral: targeted tests, end-to-end path, logs, screenshots, failure cases.
3. Environment: production-like configuration, real dependencies, migration behavior, deployed path when authorized.
4. 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.