orchestrate-repair-loop

Skill: Run fix loop (review + test + fix)

Purpose

By running multiple iteration loops converge the codebase or change set to "clean":

Review(find issues early and prevent regressions),
Test(obtain executable signals),
Fix(apply the minimal correct patch),
Repeat untilno blocking issues remainorstop conditions。

Core Objective

Primary objective: use a bounded, evidence-driven review-test-fix loop to converge the repository to a "clean" state—all tests pass and there are no "critical"/"major" review findings.

Success criteria(all requirements must be met):

✅ Complete and parsed definition: confirm pre-flight selections (scope, test mode, max iterations, allowed actions) before the loop starts
✅ Evidence first in every iteration: each iteration produces at least one of the following: new test results, new review signals, or concrete code changes
✅ Re-run tests after fixes: a failed test command (or target subset) is always re-run in the same iteration after the fix is applied
✅ Bounded loop: the loop terminates due to convergence or an explicit stop condition - no infinite retries
✅ Structured final report: the output includes a fix loop report (Appendix: Output Contract), containing commands run, failures, patches, and remaining risks

AcceptanceTest: does the final report show (a) tests pass with no blocking review findings, or (b) an explicit stop condition, and provide the user with clear remaining issues and options?

Scope Boundaries

This skill is responsible for：

Multiple iteration review→test→fix loop
Diff-scoped and codebase-scoped review using "review-diff" and "orchestrate-code-review"
Test execution via "run-automated-tests" (fast/ci/full modes)
Minimal targeted patches that preserve API contracts
Stop condition detection (no progress, environment blockers, flaky tests, iteration limit)
Structured fix loop report output

This skill is not responsible for：

Installing dependencies, using the network, or starting Docker/services without explicit confirmation
Large refactors without explicit user approval
Modifying unrelated sibling repositories
Disabling tests, weakening assertions, or deleting coverage without explicit user approval

Handoff point: when the loop converges or reaches a stop condition, present the fix loop report to the user. For risky changes (architecture migrations, authentication changes, broad refactors), pause and request explicit approval before proceeding.

Usage Scenarios (Use Cases)

"Keep fixing until the tests pass."
"Run a review-test-fix loop and make the repository green."
"Stabilize this PR/changeset through iterative testing and targeted fixes."
"Run CI-like tests, fix failures, repeat until stable."

Behavior (Behavior)

1. Pre-flight (must be resolved once)

If CLAUDE.md or .ai-cortex/config.yamlexists, prioritize reading the test_command etc. within it; otherwise obtain it according to the discovery logic. See docs/guides/project-config.md。

Confirm or default the following:

Target: repository path (default ".") and scope:
- diff(default): focus on current changes, prioritizereview-diff。
- codebase: review the specified path set, viaorchestrate-code-reviewprioritizereview-codebase/language skills.
Definition of done：
- Tests: the selected test plan passes (quick/ci/full).
- Review: no retained "critical"/"major" review findings.
- If only "minor"/"suggestion" findings remain, list them and ask whether to resolve them.
Loop bounds：
- max_iterations default:5。
- time_budget default: "best effort"; if the user provides a time limit, strictly adhere to it.
Allowed actions(ask when unclear; default to the safer choice):
- Modify repository files:Yes(this skill is for fixing), but keep changes minimal.
- Install dependencies:Confirm before executing(reasonable action, but beyond the implicit authorization scope of "changing code").
- Network access:Confirm before executing(only for what is needed for test execution; do not initiate proactively when idle).
- Docker/services (DB/Redis/etc.):Confirm before executing(start on demand, stop after testing ends).
- Large refactoring:No, without confirmation.

2. Iteration loop

For "i = 1..max_iterations":

Collect current signals (evidence first)
- If scope = diff: run/execute on the current diff/untracked additions review-diff pass.
- If scope = "codebase" or the user wants a deeper review: run "review code" (or the relevant atomic review skill).
- If test failures occurred in the previous iteration, prioritize resolving those failures first.
Run tests
- Use "run-automated-tests" in the selected mode to discover and run the best-matching test command:
  - fast(default): unit tests only, minimal setup.
  - ci: mirror the CI steps as closely as possible.
  - full: include integration/e2e (explicit confirmation only for dependencies/services).
- Capture:
  - The first failing command + exit code
  - The most relevant error excerpt (do not dump large logs unless requested)
Synthesize a fix plan (minimal correct patch)
- Choose the first to resolveoneprimary issue:
  - The first failing test/command usually wins (highest signal).
  - If the review finds a "critical" safety/correctness issue, fix that issue before or alongside testing.
- Prefer fixes that:
  - Change minimal surface area
  - Preserve API/contract unless explicitly approved
  - Add or adjust tests when fixing bugs (if feasible)
Apply fixes
- Implement the patch.
- Avoid unrelated formatting or churn.
- If the fix requires risky changes (architecture migration, authentication changes, broad refactoring), pause and ask.
Re-run minimal verification
- If the framework supports it, re-run the most relevant subset of failing tests; otherwise re-run the same test command.
- If fixed, proceed to the next remaining failure/finding within the same iteration only if it is trivial; otherwise proceed to the next loop iteration.
Stop early when converged
- If tests pass and there are no "critical"/"major" review findings, stop.

3. Stop conditions (must not loop forever)

If any of the following occurs, stop and ask the user for direction:

No progress: the same failure repeats for 2 iterations with no new information.
Environment blocker: missing toolchain, missing secrets, or unavailable dependencies (DB/Docker) and the user has not approved the required setup.
Flaky tests: suspected nondeterministic failures (e.g., retry without changes).
Iteration limit reached：max_iterations exhausted, with remaining failures.

When stopping, provide shortest-path options:

Run a different test mode (fast -> ci -> full）
Allow install/network/Docker
Narrow scope (fix only the first failing test)
Increase iteration limit

Report persistence

By default, do not write a standalone report file. If the user explicitly requests persistence, write to the path resolved from the project specification, or default to "docs/calibration/repair-loop.md" and overwrite the specification file, unless a snapshot is explicitly requested.

Input & Output

Input

Target path (default.）
Scope: "diff" (default) or "codebase" (+ path)
Test mode:fast(default),ci、full
Constraints: allow install/network/Docker/services (yes/no)
max_iterations(defaults to5）
Optional: time budget

Output

Repair loop report：
- Definition of done used
- Evidence sources (which files/CI configuration informed the test plan)
- For each iteration:
  - Test commands run and results
  - First failure excerpt (if any)
  - Changes made (files touched + intent)
  - Remaining failures/findings
- Final state:
  - Tests pass (which command)
  - Remaining review items (if any) and whether they are blocked

Limits

Hard Boundaries

Operations beyond the scope of code modifications (installing dependencies, network requests, starting Docker/services) require explicit confirmation before execution—these are reasonable repair operations, but require the user's informed consent; do not execute them without notice.
Do not ask users to paste secrets into chat. Prefer local environment files or documented development workflows.
Do not "fix" by disabling tests, weakening assertions, or removing coverage, unless the user explicitly approves and the trade-offs are documented.
Avoid large refactors by default; prioritize the minimal patch that unlocks correctness.
Keep changes scoped to the target repository; do not modify unrelated sibling repositories.

Skill Boundaries (avoid overlap)

Do not do these (other skills can handle them)：

Test execution only(no review or fix loop): use "run-automated-tests"
Test quality assessment(coverage, structure, edge case adequacy): use "review tests"
Comprehensive code review(no test fix iteration): use "orchestrate-code-review"
Diff-only review(no test execution or fix iteration): use review-diff
Writing new tests from scratch(without fixing existing failures): use development skills

When to stop and hand off：

Loop convergence (tests pass, no blocking findings) → report the current fix loop and stop
A stop condition is encountered (no progress, environment obstruction, flaky tests, iteration limit) → show options and wait for user instruction
User requests a one-off code review without fixing → hand off to "orchestrate-code-review" or "review-diff"
User requests running tests only without fixing → hand off to "run-automated-tests"

Self-Check

Core success criteria

Definition of done resolved: confirm preflight choices before the loop starts (scope, test mode, maximum iterations, allowed operations)
Evidence first each iteration: each iteration produces at least one of the following: new test results, new review signals, or concrete code changes
Rerun tests after fixes: after applying a fix in the same iteration, the failed test command (or target subset) is always rerun
Bounded loop: the loop terminates due to convergence or an explicit stop condition—no infinite retries
Structured final report: the output includes a fix loop report (Appendix: Output Contract), including commands run, failures, patches, and remaining risks

Process quality checks

Minimal patch surface: each fix touches only the files needed to resolve the identified issue—no unrelated formatting or changes.
Flaky test awareness: detect nondeterministic failures (e.g., passes on retry without code changes) and flag them instead of blindly "fixing" them.
Risky changes paused: architecture migrations, authentication changes, or broad refactors trigger explicit user confirmation before continuing.
Progress tracked per iteration: Each iteration log shows a clear increment (new signal or new fix) - no empty iterations.

Acceptance Test

Does the final report show either (a) tests passing with no blocking review findings, or (b) a clear stop condition with explicit remaining issues and options for the user?

Examples (Illustrative)

Example 1: Fix failing unit tests in a Node repo

User: "Get tests passing. Keep fixing until green."

Agent:

Preflight: scope=diff, test mode=fast, max_iterations=5; confirm installs allowed (npm ci) and network allowed.
Iteration 1: run npm test, fix the first failing test, rerun npm test。
Iteration 2: run review-diff to catch edge cases introduced by the fix; rerunnpm test。
Stop when "npm test" passes and there are no major review findings.

Example 2 (edge case): integration tests require Docker and secrets

User: "Mirror CI and fix failures."