Loop Spec Card Reference

Use this after loop-discovery.md proves a loop candidate, or when a report needs a compact example of the loop contract. This file shapes the card; it does not decide the owner, create a Skill, wire automation, or replace the evidence gate.

Return to loop-discovery.md when repeated intent, stable input, verification, stop condition, safety boundary, state, observability, or evaluation evidence is still missing.

Core Card

Every small loop should fit this shape:

WHEN -> SEE -> DO -> CHECK -> STOP -> LEAVE

• When: bounded trigger, cadence, event, report row, prompt cluster, CI signal, review signal, or costly repeated demand.
• See: concrete evidence the agent must inspect before acting.
• Do: smallest allowed action, including what must stay out of scope.
• Check: validation signal that proves whether the action helped.
• Stop: success, failure, needs more evidence, or human-decision boundary.
• Leave: durable artifact, state, patch, report, run log, or unresolved risk note that makes the next run replayable.

Add Owner only after Loop Discovery has selected one primary owner. Add Primitives only when loop-primitives.md is needed and the supporting primitive is backed by provided or opened evidence; otherwise omit it.

Evidence Rules

• When names a real trigger or recurrence signal. Do not use a topic name alone.
• See cites exact files, commands, sessions, reports, logs, scan output, CI, review comments, external records, or user-provided artifacts.
• Do not cite paths, workflows, tools, test commands, or external records that were not provided in the evidence pack or opened during the current task.
• Do is bounded enough that a reviewer can tell whether the loop stayed in scope. Sensitive edits, shell commands, external writes, broad refactors, and policy decisions need a human gate where relevant.
• Check names the command, review result, report field, fixture, smoke test, human confirmation, or comparison criterion. Do not claim success without it.
• If the evidence pack does not provide a validation command or acceptance signal, write Check: missing validation evidence instead of inventing an ecosystem-default command such as npm test, mvn test, or phpunit.
• Stop includes both a pass condition and at least one non-pass boundary such as unreproducible input, missing credentials, product decision, risk too broad, or repeated attempts without new evidence.
• Leave records what changed and what remains uncertain. Purely stateless loops should say why no replayable state is needed.
• Static release notes, configured scripts, dependency manifests, badges, or README claims are context only. They do not prove recurrence or a new owner unless paired with an active advisory, user request, prompt cluster, CI/review record, scan output, or observed repeated repair/setup/validation work.

If the evidence is static only, write an unpromoted candidate card with Owner: needs more evidence or cite the existing covered surface.

Compact Format

# <Loop Name>

When: ...
See: ...
Do: ...
Check: ...
Stop: ...
Leave: ...
Owner: ...
Primitives: primary=<owner>; support=<none|...>; why=...

If the candidate cannot fit this shape, it is probably too broad or missing evidence. Split it or return needs more evidence.

Complete Example

# Test-Driven Repair Loop

When: CI, local test output, or review feedback shows a reproducible failing
test.

See: The failing command, raw error output, related test file, implementation
file, and recent related diff.

Do: Reproduce the failure, form one small hypothesis, make the smallest safe
fix, and add or update regression coverage only when behavior was wrong. Do not
rewrite unrelated modules or broaden the fix from naming similarity alone.

Check: Rerun the original failing test. If it passes and code changed in a
shared path, run one related targeted check.

Stop: Stop when targeted validation passes. Stop with `needs more evidence`
when the failure cannot be reproduced, the fix requires a product decision, or
two attempts fail without new evidence.

Leave: Patch, changed-file list, validation command and result, and residual
risk note.

Owner: Skill for the repeatable repair playbook; script for deterministic test
selection or execution; report for the repair summary. Choose hook or automation
only after Loop Discovery proves an event or cadence owner.

Example input:

Trigger: CI failed on `pnpm test checkout-tax.test.ts`
Error: expected 8.25 but received 0
Changed files: src/checkout/tax.ts, src/checkout/summary.ts

Acceptable result:

# Repair Summary

Fixed checkout tax amount propagation from `calculateTax()` into the checkout
summary.

Validation:
- `pnpm test checkout-tax.test.ts` passed.

Changed:
- `src/checkout/summary.ts`
- `src/checkout/checkout-tax.test.ts`

Risk:
- Low. The change is scoped to checkout summary tax mapping.

Unacceptable result:

I improved the checkout module and cleaned up related files.

This is not acceptable because it lacks the failing command, validation evidence, scope boundary, stop rule, and changed-artifact summary.

Operating Pattern Catalog

Scenario sketches are owned by the operating pattern catalog, which groups them as scheduled inspection, event response, goal completion, proactive discovery, and system improvement. This file remains the canonical owner of the card syntax and the complete example above.

Use the catalog only after loop-discovery.md proves the loop and selects an owner. Return here when a chosen pattern needs a compact WHEN -> SEE -> DO -> CHECK -> STOP -> LEAVE card.