LoopX Self Repair
Use this skill to turn a surprising LoopX behavior into a durable fix,
not only an apology or a one-off explanation.
Repair Loop
- Pause delivery selection. Do not spend quota or continue adapter work
until the control-plane facts explain why that work is valid.
- Reuse evidence before collecting more. Start with the current failed
command's structured response, error code and operation identity. An already
loaded packet is evidence for that observation, not permission for a later
write. Fetch fresh authority when required by its admission/lease contract.
Read targeted diagnostics when deciding
which missing fact to collect or investigating slow commands. Do not run
diagnose, status, quota and history as a fixed preflight: diagnose already
composes status and quota work. Recording an already-understood repair Todo
does not require rediscovering the incident.
- Look up the symptom. Run
python3 scripts/find_pattern.py --query '<error code or symptom terms>' from this skill directory, or invoke its
absolute path. Use --id <returned-id> to read the relevant full guidance.
Search instructions explain pagination and
fallback. Do not load the complete catalog, paginate it into context, or
reread unchanged references already available in this task. If no pattern
fits, diagnose from current facts and add one after the fix.
- Assign the responsible layer. Separate:
- agent behavior mistake;
- state projection or quota payload bug;
- active-state authoring gap;
- benchmark harness mismatch;
- docs/process hygiene gap.
- Repair at the lowest durable layer.
- If it is a one-off agent mistake, write back the correct state/todo and
size the next scoped effort to its verifiable result, evidence and risk.
- If the machine projection misled the agent, fix CLI/status/quota
projection and add a focused smoke.
- If a direct user correction changes what counts as success, first update
the matching durable outcome requirements through
outcome refinement.
Read back and reconcile affected work before dependent execution. Preserve
unaffected requirements; change the Goal objective only when its purpose
changes. Chat, a peer message, a report or Vision alone cannot update
acceptance. Do not invent a new approval, goal or text classifier.
- If the corrected requirements also change the execution route, the agent
missed the intended loop, or a product bottleneck is invisible in
quota/status, write a bounded
goal_vision_replan_contract_v0 packet with
replan_trigger_summary through normal loopx refresh-state --vision-*
fields, using the same --agent-id as the current lane, or
--agent-vision-json for generated multi-field patches, before returning
to delivery. If the next executable step is already known, also add or
link the concrete successor todo; do not leave the correction only in chat
or an incident note.
- If a design rule is missing, update the interaction model or todo list
before implementing broad behavior.
- If benchmark evidence is not attributable, add posthoc trace/parity
checks before claiming uplift or regression.
- Validate before resuming. Run the smallest smoke or CLI check that would
have caught the issue, plus
loopx check on changed public surfaces
when docs/contracts changed.
- Write back the lesson. Update active goal state, docs, contributor
tasks, or this skill so the same failure mode is visible next time.
When work repeatedly enters a receipt-owned retry, first check the caller's
typed outcome against the selected Todo. Rejecting a candidate with new,
validated evidence can advance an evaluation Todo while leaving the broader
stage open; it is not automatically an execution blocker. Pure reuse or setup
does not qualify as progress. Use blocked only when the Todo's actual next
step cannot execute, preserve genuine retry clocks, and replan finite answered
questions through the existing Todo/vision. Finishing one question or submitting
its PR does not close an ongoing user objective. Use the retained requirements
and already authorized sources to select the next useful independent slice;
source discovery does not need a new human assignment. Missing cost,
comprehension, adoption or review evidence limits the corresponding claim or
dependent operation, not all research or implementation. Do not retire an
ongoing vision merely to suppress replan. If an earlier authoring mistake did
so, repair the original Todo/vision, keep genuine dependency waits scoped, and
verify that the public entrypoint admits independent work before continuing it.
Preserve actual authority, budget and stop conditions; when no useful authorized
work remains, retain the evidenced wait rather than inventing activity. Never
erase receipts or fabricate progress to escape a wait. See
settlement classification.
Upstream Issue Escalation
A public GitHub issue is an optional final escalation, not a default side
effect of self-repair. Consider it only when the responsible layer is a
reusable LoopX product, CLI, skill, installer, or control-plane gap and durable
upstream tracking adds value beyond the local repair or PR.
Read references/upstream-issue-escalation.md before publishing anything.
Invoking this skill never grants publication permission. The guarded path must:
- reject private, project-specific, support-only, and security-sensitive
reports;
- reduce the evidence to a minimal public-safe reproduction and scan the
draft with
loopx check;
- search open and closed issues by a stable fingerprint before creating one;
- auto-submit only under explicit current-turn approval or durable owner
opt-in; otherwise show the exact draft and ask once for confirmation;
- create at most one issue per repair turn, then record the existing or new
issue URL in the relevant LoopX todo/evidence writeback.
If qualification, authority, authentication, boundary scanning, or duplicate
search is uncertain, preserve the draft and stop before publication. Prefer a
direct fix or PR when no separate issue is needed for coordination.
Vision / Replan Writeback
Use the bounded vision contract when self-repair discovers that LoopX did not
notice a missing outcome, route, or acceptance condition by itself. Persist a
changed user acceptance requirement through its owner first; Vision records the
execution response, not a replacement acceptance contract. The packet is the
bridge from human or agent insight to quota-visible replan state:
{
"schema_version": "goal_vision_replan_contract_v0",
"state": "vision_drift_detected",
"vision_patch": {
"vision_summary": "Name the corrected route or acceptance target.",
"acceptance_summary": "Name the machine-visible condition that must hold.",
"replan_trigger_summary": "Name why the current frontier is insufficient."
},
"todo_delta": ["create_successor"]
}
Record it with normal inline refresh-state --vision-summary --vision-acceptance --vision-replan-trigger fields using the same --agent-id
that ran the repair. Use --agent-vision-json when a generated patch is clearer
than a command line. Replan closes only through a typed semantic observation or
an atomic Todo transition bound with --replan-obligation-id, a typed
--action-kind, and a stable --target-key or Explore node ref; do not append
a second --autonomous-replan-recorded repair ACK. A vision patch without a
runnable Todo is still useful: quota should-run can promote its
replan_trigger_summary into goal_frontier_projection.acceptance_gaps[] when
the advancement frontier is empty.
If the repair concludes that the existing per-agent vision is still correct,
close the required checkpoint with --vision-unchanged-reason instead of
writing a fake patch. If a material refresh-state lacks both a patch and an
unchanged/no-follow-up decision, LoopX should preserve a per-agent
vision_checkpoint_v0 with decision=missing_required so the same agent's
next quota check can enter replan. A scheduler wake alone is not a material
vision boundary: when quota explicitly projects a normally admitted open
advancement Todo as delivery_boundary=in_flight_continuation, use the
projected settlement command and do not invent a vision patch. The next
heartbeat keeps that same Todo selected only after accountable
outcome_progress; Todo completion, blocker/gap, durable Next Action change,
replan, or terminal closeout must return to the strict semantic checkpoint.
Evidence Discipline
- Do not read or commit raw private logs, trajectories, verifier output,
credentials, internal links, or production material.
- Do not solve contradictory payloads by guessing. If
recommended_action,
goal_boundary.write_scope, todos, and interaction contract disagree, treat
that as a projection bug or state authoring bug first.
- Separate priority advice from authority. Use the planning horizon and current
user direction to choose useful in-scope work; do not treat P0/P1 order as a
permission gate or relabel every task to escape it. Before explaining a
refusal as recovery protection, check whether a settlement identity is
actually bound. Priority-only rejection of an eligible explicit choice is a
control-plane defect. Preserve real gates and record the changed route in
existing Todo/vision state. A committed Turn may finish with progress while
its Todo stays open; settle and release before switching, rather than treating
the binding as an obligation to finish that entire Todo first.
- Do not let fallback work hide the primary blocker. When a higher-priority
path is gated but safe fallback is valid, report both the concrete gate and
the fallback progress.
- Do not equate bounded work with a small operation. If turns repeatedly stop
after setup or surface-only edits, check whether a verifiable result could
have been reached within scope and budget. Repair the premature stop, not by
imposing a minimum number of calls/files or ignoring explicit stop conditions.
Reference Routes
- For known symptom-to-repair mappings, search with
scripts/find_pattern.py;
references/pattern-lookup.md explains the lookup, not a required full read.
- For missing facts, slow commands and response truncation, read
references/targeted-diagnostics.md.
- For guarded public GitHub issue escalation, read
references/upstream-issue-escalation.md.
- For user/agent/state channel semantics, read
../../docs/state-interaction-model.md and
../../docs/concepts/interaction-pattern-catalog.md.
- For quota and heartbeat decisions, read
../../docs/quota-allocation.md and
../../docs/heartbeat-automation-prompt.md.
- For commit/PR hygiene failures, read
../../AGENTS.md.
1---2name: loopx-self-repair3description: Diagnose and repair LoopX control-plane drift or agent behavior drift. Use when a LoopX task makes unexpectedly small progress, follows a stale or contradictory recommended_action, ignores a higher-priority blocked item while doing fallback work, reports vague owner/user gates, loses todo projection, misaligns benchmark treatment with the real product path, mixes temporary artifacts into commits, or when the user asks for root-cause analysis, self-repair, or why the harness/agent behaved unexpectedly.4metadata:5 source: https://skillmd.com/skills/tuyv/loopx-self-repair6---78# LoopX Self Repair910Use this skill to turn a surprising LoopX behavior into a durable fix,11not only an apology or a one-off explanation.1213## Repair Loop14151. **Pause delivery selection.** Do not spend quota or continue adapter work16 until the control-plane facts explain why that work is valid.172. **Reuse evidence before collecting more.** Start with the current failed18 command's structured response, error code and operation identity. An already19 loaded packet is evidence for that observation, not permission for a later20 write. Fetch fresh authority when required by its admission/lease contract.21 Read [targeted diagnostics](references/targeted-diagnostics.md) when deciding22 which missing fact to collect or investigating slow commands. Do not run23 diagnose, status, quota and history as a fixed preflight: diagnose already24 composes status and quota work. Recording an already-understood repair Todo25 does not require rediscovering the incident.263. **Look up the symptom.** Run `python3 scripts/find_pattern.py --query27 '<error code or symptom terms>'` from this skill directory, or invoke its28 absolute path. Use `--id <returned-id>` to read the relevant full guidance.29 [Search instructions](references/pattern-lookup.md) explain pagination and30 fallback. Do not load the complete catalog, paginate it into context, or31 reread unchanged references already available in this task. If no pattern32 fits, diagnose from current facts and add one after the fix.334. **Assign the responsible layer.** Separate:34 - agent behavior mistake;35 - state projection or quota payload bug;36 - active-state authoring gap;37 - benchmark harness mismatch;38 - docs/process hygiene gap.395. **Repair at the lowest durable layer.**40 - If it is a one-off agent mistake, write back the correct state/todo and41 size the next scoped effort to its verifiable result, evidence and risk.42 - If the machine projection misled the agent, fix CLI/status/quota43 projection and add a focused smoke.44 - If a direct user correction changes what counts as success, first update45 the matching durable outcome requirements through46 [outcome refinement](../loopx-project/references/outcome-refinement.md).47 Read back and reconcile affected work before dependent execution. Preserve48 unaffected requirements; change the Goal objective only when its purpose49 changes. Chat, a peer message, a report or Vision alone cannot update50 acceptance. Do not invent a new approval, goal or text classifier.51 - If the corrected requirements also change the execution route, the agent52 missed the intended loop, or a product bottleneck is invisible in53 quota/status, write a bounded `goal_vision_replan_contract_v0` packet with54 `replan_trigger_summary` through normal `loopx refresh-state --vision-*`55 fields, using the same `--agent-id` as the current lane, or56 `--agent-vision-json` for generated multi-field patches, before returning57 to delivery. If the next executable step is already known, also add or58 link the concrete successor todo; do not leave the correction only in chat59 or an incident note.60 - If a design rule is missing, update the interaction model or todo list61 before implementing broad behavior.62 - If benchmark evidence is not attributable, add posthoc trace/parity63 checks before claiming uplift or regression.646. **Validate before resuming.** Run the smallest smoke or CLI check that would65 have caught the issue, plus `loopx check` on changed public surfaces66 when docs/contracts changed.677. **Write back the lesson.** Update active goal state, docs, contributor68 tasks, or this skill so the same failure mode is visible next time.6970When work repeatedly enters a receipt-owned retry, first check the caller's71typed outcome against the selected Todo. Rejecting a candidate with new,72validated evidence can advance an evaluation Todo while leaving the broader73stage open; it is not automatically an execution blocker. Pure reuse or setup74does not qualify as progress. Use `blocked` only when the Todo's actual next75step cannot execute, preserve genuine retry clocks, and replan finite answered76questions through the existing Todo/vision. Finishing one question or submitting77its PR does not close an ongoing user objective. Use the retained requirements78and already authorized sources to select the next useful independent slice;79source discovery does not need a new human assignment. Missing cost,80comprehension, adoption or review evidence limits the corresponding claim or81dependent operation, not all research or implementation. Do not retire an82ongoing vision merely to suppress replan. If an earlier authoring mistake did83so, repair the original Todo/vision, keep genuine dependency waits scoped, and84verify that the public entrypoint admits independent work before continuing it.85Preserve actual authority, budget and stop conditions; when no useful authorized86work remains, retain the evidenced wait rather than inventing activity. Never87erase receipts or fabricate progress to escape a wait. See88[settlement classification](../../docs/quota-allocation.md#allocation-contract).8990## Upstream Issue Escalation9192A public GitHub issue is an optional final escalation, not a default side93effect of self-repair. Consider it only when the responsible layer is a94reusable LoopX product, CLI, skill, installer, or control-plane gap and durable95upstream tracking adds value beyond the local repair or PR.9697Read `references/upstream-issue-escalation.md` before publishing anything.98Invoking this skill never grants publication permission. The guarded path must:991001. reject private, project-specific, support-only, and security-sensitive101 reports;1022. reduce the evidence to a minimal public-safe reproduction and scan the103 draft with `loopx check`;1043. search open and closed issues by a stable fingerprint before creating one;1054. auto-submit only under explicit current-turn approval or durable owner106 opt-in; otherwise show the exact draft and ask once for confirmation;1075. create at most one issue per repair turn, then record the existing or new108 issue URL in the relevant LoopX todo/evidence writeback.109110If qualification, authority, authentication, boundary scanning, or duplicate111search is uncertain, preserve the draft and stop before publication. Prefer a112direct fix or PR when no separate issue is needed for coordination.113114## Vision / Replan Writeback115116Use the bounded vision contract when self-repair discovers that LoopX did not117notice a missing outcome, route, or acceptance condition by itself. Persist a118changed user acceptance requirement through its owner first; Vision records the119execution response, not a replacement acceptance contract. The packet is the120bridge from human or agent insight to quota-visible replan state:121122```json123{124 "schema_version": "goal_vision_replan_contract_v0",125 "state": "vision_drift_detected",126 "vision_patch": {127 "vision_summary": "Name the corrected route or acceptance target.",128 "acceptance_summary": "Name the machine-visible condition that must hold.",129 "replan_trigger_summary": "Name why the current frontier is insufficient."130 },131 "todo_delta": ["create_successor"]132}133```134135Record it with normal inline `refresh-state --vision-summary136--vision-acceptance --vision-replan-trigger` fields using the same `--agent-id`137that ran the repair. Use `--agent-vision-json` when a generated patch is clearer138than a command line. Replan closes only through a typed semantic observation or139an atomic Todo transition bound with `--replan-obligation-id`, a typed140`--action-kind`, and a stable `--target-key` or Explore node ref; do not append141a second `--autonomous-replan-recorded` repair ACK. A vision patch without a142runnable Todo is still useful: `quota should-run` can promote its143`replan_trigger_summary` into `goal_frontier_projection.acceptance_gaps[]` when144the advancement frontier is empty.145146If the repair concludes that the existing per-agent vision is still correct,147close the required checkpoint with `--vision-unchanged-reason` instead of148writing a fake patch. If a material `refresh-state` lacks both a patch and an149unchanged/no-follow-up decision, LoopX should preserve a per-agent150`vision_checkpoint_v0` with `decision=missing_required` so the same agent's151next quota check can enter replan. A scheduler wake alone is not a material152vision boundary: when quota explicitly projects a normally admitted open153advancement Todo as `delivery_boundary=in_flight_continuation`, use the154projected settlement command and do not invent a vision patch. The next155heartbeat keeps that same Todo selected only after accountable156`outcome_progress`; Todo completion, blocker/gap, durable Next Action change,157replan, or terminal closeout must return to the strict semantic checkpoint.158159## Evidence Discipline160161- Do not read or commit raw private logs, trajectories, verifier output,162 credentials, internal links, or production material.163- Do not solve contradictory payloads by guessing. If `recommended_action`,164 `goal_boundary.write_scope`, todos, and interaction contract disagree, treat165 that as a projection bug or state authoring bug first.166- Separate priority advice from authority. Use the planning horizon and current167 user direction to choose useful in-scope work; do not treat P0/P1 order as a168 permission gate or relabel every task to escape it. Before explaining a169 refusal as recovery protection, check whether a settlement identity is170 actually bound. Priority-only rejection of an eligible explicit choice is a171 control-plane defect. Preserve real gates and record the changed route in172 existing Todo/vision state. A committed Turn may finish with progress while173 its Todo stays open; settle and release before switching, rather than treating174 the binding as an obligation to finish that entire Todo first.175- Do not let fallback work hide the primary blocker. When a higher-priority176 path is gated but safe fallback is valid, report both the concrete gate and177 the fallback progress.178- Do not equate bounded work with a small operation. If turns repeatedly stop179 after setup or surface-only edits, check whether a verifiable result could180 have been reached within scope and budget. Repair the premature stop, not by181 imposing a minimum number of calls/files or ignoring explicit stop conditions.182183## Reference Routes184185- For known symptom-to-repair mappings, search with `scripts/find_pattern.py`;186 `references/pattern-lookup.md` explains the lookup, not a required full read.187- For missing facts, slow commands and response truncation, read188 `references/targeted-diagnostics.md`.189- For guarded public GitHub issue escalation, read190 `references/upstream-issue-escalation.md`.191- For user/agent/state channel semantics, read192 `../../docs/state-interaction-model.md` and193 `../../docs/concepts/interaction-pattern-catalog.md`.194- For quota and heartbeat decisions, read195 `../../docs/quota-allocation.md` and196 `../../docs/heartbeat-automation-prompt.md`.197- For commit/PR hygiene failures, read `../../AGENTS.md`.