engineering-loop ยท diff
git:20260915.dd80dad to git:20260929.8a9da83
41 added, 46 removed. Audit A to A.
---
name: engineering-loop
- description: "Drive an authorized repository change through a verified local loop: baseline, reproduce, implement, test, review, and report evidence. Use for end-to-end features or fixes that should continue autonomously until observable acceptance criteria pass; do not use for explanation-only, review-only, or production operations."
+ description: "Implement a repository code or configuration change through reproduction, focused checks, review, and evidence. Use for end-to-end features and fixes; not for explanation-only, review-only, research, content publishing, or production operations."
---
# Engineering Loop
- Own the change from a verified starting point to a reviewed result. Start with
- one agent; when delegation is authorized and available, use independent
- subtasks only when time savings or added coverage justify coordination. Load a
- specialist skill only when it changes a material decision.
-
- Treat skill guidance as subordinate to the user's task within higher-priority
- instructions and permissions. Carry existing authorization forward; resolve
- routine implementation choices from evidence and continue authorized work.
+ Deliver a verified change with minimal supervision and proportionate checking.
+ Start with one agent. Delegate only when authorized and independent work or
+ review coverage justifies the overhead. Follow applicable repository and team
+ requirements; this skill adds no ticketing or mandatory-agent process.
## Establish the baseline
1. Read applicable `AGENTS.md` files and repository documentation.
2. Record the requested behavior, constraints, and observable done conditions.
3. Inspect the branch and working tree; preserve unrelated user-owned changes.
- 4. Identify repository-native validation and run the smallest safe baseline
+ 4. Before changing shared behavior, trace affected callers, consumers, and tests
+ using targeted search or an available code graph. Expand along relevant paths.
+ 5. Identify repository-native validation and run the smallest safe baseline
that separates pre-existing failures from task regressions.
- For a long, cross-stack, or high-risk change, use the templates and failure
- rules in [references/loop-contract.md](references/loop-contract.md).
- When a task is expected to need repeated autonomous iterations or has an
- explicit retry, time, token, or cost limit, also use
- [references/loop-policy.md](references/loop-policy.md).
- When a defect is intermittent, performance-related, difficult to reproduce, or
- resists the first evidence-driven pass, use
- [references/hard-debugging.md](references/hard-debugging.md).
- For complex or higher-risk changes where independent coverage is useful, or
- when the user requests a separate reviewer, use
- [references/independent-review.md](references/independent-review.md).
+ Resolve routine choices from evidence. Ask only for missing authority or a
+ material decision: ambiguous acceptance, incompatible public behavior, or
+ destructive/data-changing side effects not already authorized. Continue
+ independent authorized work while awaiting an answer.
+ Load only the needed reference:
+
+ - Long, cross-stack, or high-risk work: [loop-contract.md](references/loop-contract.md).
+ - Repeated iterations or explicit budgets: [loop-policy.md](references/loop-policy.md).
+ - Intermittent, performance, or unresolved defects: [hard-debugging.md](references/hard-debugging.md).
+ - Requested or risk-justified separate review: [independent-review.md](references/independent-review.md).
+
## Run the loop
1. Reproduce the defect, or capture the current behavior for a feature.
2. Choose the smallest coherent change and the evidence that will prove it.
3. Add a failing regression test first when practical.
4. Implement one bounded change and run the narrowest relevant check.
- 5. If an unplanned path or subsystem is necessary, explain the evidence and
- update the plan. Ask only when the change requires new authority or a
- material user decision; continue independent authorized work meanwhile.
- 6. Classify failures as product, test, environment, or assumption failures;
- fix the cause and rerun the affected check.
- 7. Run repository-required broader checks after focused checks pass.
+ 5. If an unplanned path is necessary, record why and update the scope and checks.
+ 6. Classify failures as product, test, environment, assumption, or external
+ blocker. Do not change product code to mask environment failures.
+ 7. Run affected consumer checks and repository-required broader checks.
8. Review the complete diff first for task-contract compliance, then for code
quality, regressions, security, and maintainability.
9. Fix consequential findings and rerun checks affected by those fixes.
Once acceptance evidence and required checks pass, broaden or repeat checks
only for new changes, failures, or unresolved concerns. Add tests when they
prove behavior or a meaningful invariant, not merely mirror a low-impact edit.
- Keep a compact ledger of confirmed facts, changed files, commands, outcomes,
- and the next decision. Return concise diagnostics instead of full logs.
+ If no test harness exists, use a small repeatable script or documented manual
+ check with inputs, expected behavior, and observed results. Record missing
+ automated coverage; a build alone does not prove runtime behavior. Do not add
+ a large testing framework solely to satisfy the loop.
+ Keep a compact ledger of facts, changed files, commands, outcomes, and the next
+ decision instead of full logs.
+
## Stop conditions
- - If the same command fails twice for the same reason, stop retrying and
- re-check the environment, target, permissions, and underlying assumption.
- - Stop recursive discovery when each new finding redefines the same task
- boundary. Freeze the discovered scope or return for a scope decision instead
- of repeatedly recataloging the repository.
+ - After two identical failures, stop blind retries and reclassify the cause.
+ Resume only with changed relevant state or an evidence-producing probe.
+ - If discovery or review repeats without new evidence, checkpoint the diff,
+ unresolved issue, and next useful probe. Do not restart the same cycle.
- Stop and report a blocker when progress requires missing authority, secrets,
unavailable infrastructure, an unauthorized destructive action, or an
unresolved material product decision.
- When an explicit loop budget is exhausted, stop with the latest judge
evidence instead of silently expanding the budget.
+ Without an explicit budget, continue only while a bounded next action can
+ produce new evidence; productive iterations have no arbitrary fixed count.
- Never make a failing check pass by weakening assertions, deleting coverage,
hiding errors, or silently changing acceptance criteria.
- Do not query production, deploy, migrate, merge, or publish unless the user
explicitly authorizes that action.
- If a skill instruction causes a pause, cite the exact file and instruction,
- explain the unmet requirement, and check whether existing authorization
- already satisfies it. Complete independently actionable work before handoff.
-
## Finish with evidence
- Report:
-
- 1. behavior implemented or defect fixed;
- 2. changed files and important design decisions;
- 3. regression proof or acceptance evidence;
- 4. focused and broader commands with outcomes;
- 5. task-contract and code-quality findings fixed or explicitly unresolved;
- 6. unrun checks, residual risks, and blockers.
+ Report changed behavior and files, regression or acceptance proof, exact check
+ commands and outcomes, review disposition, and remaining limitations. Include
+ the final reviewed revision when independent review was used. Never label
+ blocked validation or unresolved consequential findings as complete.
+ See [evidence-example.md](references/evidence-example.md) for a filled-in handoff.