stuck

name	Stuck
description	Bounded auto-debug loop for failing build/test commands with evidence-first diagnosis.
requires	{"bins":[],"env":[]}

Stuck

Run a bounded diagnostic loop when a build or test is failing repeatedly. This skill is for "reproduce -> inspect -> isolate -> propose fix", not for open-ended retries.

Use when

• User reports a failing cargo build or cargo test.
• The failure can be reproduced from a concrete command or recent log.
• You need structured diagnosis before applying code changes.

Do not use when

• There is no runnable command and no usable failure output.
• The issue is infrastructure-only (network outage, registry down, host disk full) and not actionable from the repo.
• The task is a one-off explanation without debugging.

Input contract

• failing_command (required): command to reproduce the failure.
• max_rounds (optional): default 3, clamp to [1, 5].
• focus_pattern (optional): regex/error token to prioritize while scanning output.
• failure_context (optional): pasted stderr/stdout snippet for first-pass triage.

Parsing rules (priority order)

1. If structured args are provided, use them directly.
2. Else infer from user text:
   • first explicit command-like phrase -> failing_command
   • "2 rounds", "max 4 attempts", "repeat 3x" -> max_rounds
   • "focus on E0425", "grep unresolved import" -> focus_pattern
3. Defaults:
   • max_rounds = 3
4. If failing_command is still missing, ask for one concrete reproducible command.

Canonical workflow

1. Reproduce baseline
   • Run failing_command as-is.
   • Capture exit code + shortest error excerpt that identifies the failure.
2. Increase observability
   • Build-style command: add verbosity (-vv) when safe.
   • Test-style command: add -- --nocapture when safe.
3. Isolate blast radius
   • Prefer targeted reruns (-p <crate>, single test path, or narrowed filter) once the failing unit is known.
4. Classify likely root cause
   • compile/type/import mismatch
   • feature-flag/config mismatch
   • flaky test/runtime ordering
   • environment/toolchain mismatch
5. Propose one fix candidate per round
   • Keep the fix minimal and directly tied to captured evidence.
6. Verify
   • Re-run the narrow check first, then the original failing_command.
7. Stop when:
   • failure is fixed (status=fixed), or
   • root cause is clear but fix needs user decision (status=diagnosed), or
   • rounds exhausted (status=max_rounds_reached).

Guardrails

• Never run unbounded loops.
• Never execute destructive commands (git reset --hard, rm -rf, force-push).
• Do not broaden task scope while debugging; stay on the current failure.
• Keep evidence concise (error-focused snippets, not full logs).
• If command hangs, use bounded execution and report timeout explicitly.

Output format

Always return:

• status: fixed | diagnosed | max_rounds_reached | needs_user_input
• rounds_run: number of rounds executed
• failing_command: normalized command used for reproduction
• focus_pattern: normalized pattern or none
• root_cause_hypothesis: strongest current diagnosis
• evidence: per-round bullets (command, exit code, key error line)
• fix_candidate: concrete minimal patch idea (or applied change summary)
• verification: narrow check result + full command result
• next_action: required unless status=fixed

Examples

• failing_command="cargo build -p nexo-core" max_rounds=3 focus_pattern="E0[0-9]{3}"
• failing_command="cargo test -p nexo-core agent::skills::tests" max_rounds=4
• failing_command="cargo test" failure_context="thread 'x' panicked at ..."