AGENT SKILL

debug

Signal-driven production debugging via shared RCA core. Use when triaging production errors, crashes, or regressions before fixing. Diagnoses and routes; does not implement patches or merge.

License 许可
MIT
最近更新
2026-11-03
Stars
★ 2
Forks
0

01 前言 Front Matter

name
debug
description
Signal-driven production debugging via shared RCA core. Use when triaging production errors, crashes, or regressions before fixing. Diagnoses and routes; does not implement patches or merge.

02 资源文件 1

03 SKILL.md 正文

Debug workflow

Post-ship production signals and dev-time test/build failures (R22). Shares skills/rca-core with stabilize (R35). Diagnoses + proposes; does not implement or merge — routing hands off to implementation (003) or documentation (002).

Model tier: build — resolve via python3 scripts/sw_bootstrap.py resolve-model-tier.py -- --skill debug. When using the Task tool for subagent dispatch, resolve concrete model IDs from models.tiers in config (never semantic tier names in subagent model: frontmatter).

Orchestrator plan-policy (PRD 024)

Single-tier orchestrator-step plan proposal, validation, and capability selection are owned by core/commands/sw-debug.md + skills/conductor/SKILL.md — this skill maps phases to step IDs (triage, normalize, enrich, rca, route-confirm-halt, route, rca-human-decision-halt, record).

Under proposed, Sentry bodies MUST be redacted via python3 scripts/sw_bootstrap.py memory-redact.py before any persist or handoff (including DBG-A2 concurrent enrich + preflight). Fail-closed on redaction error.

Under proposed, R21 surfacing writes chosenPlan, capabilitySet, and planRejections to .cursor/sw-debug-runs/<runId>/episodic-run-summary.json (fixture: debug-r21-surfacing). Driver-enforced budget/no-progress trips after repeated plan rejections (fixture: debug-budget-trip).

Phase 0 — Triage

Parse the inbound signal:

Input pattern Normalized type RCA entry
Sentry issue URL/ID sentry debug
Deploy log excerpt / CI deploy failure deploy_log debug
User-described broken behavior user_report debug
Failing test output / assertion test_failure dev-time
Build/typecheck/lint failure build_failure dev-time
/sw-verify failure + log excerpt verify_failure dev-time

Dev-time path: when type is test_failure, build_failure, or verify_failure, skip production-signal enrichment and invoke skills/rca-core dev-time entry (strict reproduction-first + failing-regression-test gate). See Dev-time gates below.

Trivial fast-path: cause obvious from signal alone (single-line config typo visible in stack, known missing env var in deploy log). Present diagnosis + proposed one-line fix; offer Route to scoped phase / Diagnosis only — never edit on bare main. If the user chooses scoped phase, skip to Phase 3 routing with the one-line fix as the proposal. Diagnosis-only → skip to Phase 4.

Otherwise → Phase 1.

Phase 1 — Enrich + memory preflight

  1. Normalize to skills/rca-core/references/debug-inputs.md shape.
  2. Redact all text: python3 scripts/sw_bootstrap.py memory-redact.py.

Sentry expansion reader (R9/R10)

When expanding a bare Sentry ref via MCP (skills/debug/references/sentry.md), delegate a reader Task at boundary debug-sentry-expansion (role: reader, readonly: true). The reader fetches and redacts the Sentry body; the acting debug agent receives only the redacted enveloped excerpt.

python3 scripts/dispatch-check.py --agent generalPurpose --command sw-debug --skill debug   --parent-model <concrete-parent-id> --role reader --boundary debug-sentry-expansion   --dispatch-id <id> --prompt "$RUN_DIR/sentry-reader-prompt.md"
  1. If type == sentry → skills/debug/references/sentry.md (MCP enrich or degrade).
  2. memory-preflight search: category debug, relatedFiles, tags for failing area.
  3. Attach priorDebugMemoryIds to the signal context.

Phase 1.5 — Repro-first gate (R16–R21)

Before RCA hypothesis generation, run the mechanical repro-first gate:

python3 scripts/debug_repro_gate.py run \
  --signal "$RUN_DIR/normalized-signal.json" \
  --state "$RUN_DIR/repro-gate-state.json" \
  --out "$RUN_DIR/repro-gate.status.json"

Gate verdicts: pass (repro confirmed or production evidence bundle complete), blocked (pending checklist items — exit 20), exhausted (bounded acquisition exhausted — exit 20). Typed halts include resumeCommand and checklist state (R21).

Mechanical reproduction path (dev-time, R17)

For test_failure, build_failure, and verify_failure:

  1. Repro command (red) — run the narrowest repro command; record exact command + output digest in repro-gate-state.json under repro.reproCommand / repro.reproConfirmed.
  2. Minimize — shrink surface area until failure remains (mechanicalRepro.repro_minimize).
  3. Instrument — add temporary logging or trace hooks on the failing path (mechanicalRepro.repro_instrument).

Checklist metadata: python3 scripts/debug_repro_gate.py checklist-metadata --signal-class dev-time.

Evidence acquisition path (production, R18–R20)

When local repro is impossible for sentry, deploy_log, or user_report:

  1. Fetch logs (evidenceAcquisition.logs).
  2. Fetch traces/spans (evidenceAcquisition.traces).
  3. Collect replay bundle when available (evidenceAcquisition.replay_bundle).
  4. Sentry MCP enrich read-only (evidenceAcquisition.sentry_enrich).

Before hypothesis unlock, persist production evidence bundle metadata in gate state:

  • signalClass, checklistState, redacted artifactPaths, and complete: true when required items finish.

Checklist metadata: python3 scripts/debug_repro_gate.py checklist-metadata --signal-class production.

Hypothesis gate (R19)

Do not emit or dispatch RCA hypotheses while gate verdict is blocked. If hypotheses are present during evaluation, the gate returns hypothesisGate: refused with cause hypothesis-before-gate.

On pass, proceed to Phase 2. On blocked or exhausted, halt with resumeCommand and surface checklist state — no speculative fix or hypothesis fan-out.

Phase 2 — RCA

Invoke skills/rca-core:

  • Production signals (sentry, deploy_log, user_report) → debug entry procedure
  • Dev-time signals (test_failure, build_failure, verify_failure) → dev-time entry procedure

Fan-out entry (opt-in): when rca.fanout.enabled is true, evaluate D5 gating via python3 scripts/rca_fanout.py should-fanout --signal <normalized-signal.json>. On useFanout: true, follow skills/rca-core/references/fan-out.md (partitioned generators → synthesize → per-survivor refuters). On useFanout: false, use single-context shared discipline below.

Shared across entries:

  • Rank hypotheses with evidence
  • Causal-chain gate before fix proposal (refuter panel when fan-out active)
  • Invalidate rejected hypotheses explicitly
  • Hard stops: max 5 iterations, no-progress, rule-of-three, human-decision (R29)
  • Production debug: attempt repro-from-context; local repro optional
  • Dev-time: reproduction-first (strict) and failing-regression-test gate (see below)

Dev-time gates

Apply when Phase 0 classifies a dev-time signal:

  1. Reproduction-first — run the narrowest repro command; record exact command + output. If repro cannot be established, log attempts and stop at R29 human-decision — no speculative fix.
  2. Failing-regression-test-before-fix — identify or write a test that fails on current HEAD; cite its path. The fix is not proposed until this test is red. After fix, the same test must pass without weakening assertions.
  3. Optional git-bisect-for-regressions — when the failure is a regression with unclear introducer, offer bisect with a determinism-forcing wrapper (exit 0/1/125-skip per rca-core dev-time entry).
  4. Rule-of-three — three identical failed fix attempts (same hypothesis + evidence signature) triggers R29 circuit breaker → escalate to architecture review; do not retry variants.

Phase 3 — Fix-size classification + routing (R24)

After root cause + proposed fix, classify small vs substantial using skills/triage/SKILL.md rubrics on the proposed fix scope (estimated file count, risk triggers, workaround detection):

Outcome Route Handoff
Small — Quick or Standard tier (≤5 files, no risk-floor triggers), no architectural mismatch, not workaround-only Scoped implementation /sw-worktree provision debug-<slug> → /sw-start with RCA output as phase brief
Substantial — Full tier, wrong interface/requirements, risk-floor triggers, or every fix is a workaround Documentation /sw-brainstorm (new) or /sw-amend + freeze for frozen PRD scope changes

Never patch in place on main without worktree + phase loop.

Workaround detection (bias → substantial)

  • Fix only masks symptom (retry loop, broader catch, silent swallow)
  • Root cause is missing requirement or wrong abstraction
  • Proposed fix contradicts frozen PRD without amendment path

Routing record (compounding)

After routing decision, memory-preflight write (redacted):

{
  "category": "debug",
  "tags": ["surface:debug-route", "route:<scoped|brainstorm|amendment>"],
  "relatedFiles": [],
  "summary": "root cause one-liner",
  "originatingSignal": "<type + redacted ref>"
}

Feeds /sw-compound and future debug preflight.

Phase 4 — Handoff summary

## Signal
[type + redacted ref]

## Root cause
…

## Proposed fix
…

## Route
<scoped phase | brainstorm | amendment> — rationale

## Next command
/sw-worktree … + /sw-start  OR  /sw-brainstorm / amendment path

Guardrails

  • Production path is signal-driven (R22); dev-time path is repro-driven with strict gates.
  • All Sentry/log text redacted before prompts/memory (R41).
  • Bounded RCA loop (R29) — same hard stops as stabilize, including rule-of-three escalation.
  • No auto-merge, no silent in-place patches on default branch.
  • Sentry MCP read-only; degrade when unavailable.

Small-fix → deliver handoff (PRD 067 R10–R14)

When route classification is small:

  1. Materialize a thin one-phase frozen pack via scripts/debug_deliver_handoff.py materialize (tasks-debug-<slug>; virtual body under docs/prds/debug-<slug>/).
  2. Print /sw-deliver run --unit-id tasks-debug-<slug> and optionally confirm same-turn handoff.
  3. Confirm → invoke /sw-deliver run inline in-turn; decline → end debug. Never Task-spawn deliver.
  4. Pre-confirm: debug_deliver_handoff.py pre-confirm-guard --step <step> fails closed on execute/ship (R12).
  5. Post-handoff legitimate halts are the deliver/ship set only (R13).

Substantial routes still go to /sw-brainstorm or /sw-amend and bypass the thin debug pack (R14). Debug never auto-merges to main.

04 同仓库更多 Skills