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
- 参考文档references/sentry.md1.9 KB
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
- Normalize to
skills/rca-core/references/debug-inputs.mdshape. - 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"
- If
type == sentry→skills/debug/references/sentry.md(MCP enrich or degrade). memory-preflightsearch: categorydebug,relatedFiles, tags for failing area.- Attach
priorDebugMemoryIdsto 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:
- Repro command (red) — run the narrowest repro command; record exact command + output digest in
repro-gate-state.jsonunderrepro.reproCommand/repro.reproConfirmed. - Minimize — shrink surface area until failure remains (
mechanicalRepro.repro_minimize). - 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:
- Fetch logs (
evidenceAcquisition.logs). - Fetch traces/spans (
evidenceAcquisition.traces). - Collect replay bundle when available (
evidenceAcquisition.replay_bundle). - Sentry MCP enrich read-only (
evidenceAcquisition.sentry_enrich).
Before hypothesis unlock, persist production evidence bundle metadata in gate state:
signalClass,checklistState, redactedartifactPaths, andcomplete: truewhen 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:
- 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.
- 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. - 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 perrca-coredev-time entry). - 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:
- Materialize a thin one-phase frozen pack via
scripts/debug_deliver_handoff.py materialize(tasks-debug-<slug>; virtual body underdocs/prds/debug-<slug>/). - Print
/sw-deliver run --unit-id tasks-debug-<slug>and optionally confirm same-turn handoff. - Confirm → invoke
/sw-deliver runinline in-turn; decline → end debug. Never Task-spawn deliver. - Pre-confirm:
debug_deliver_handoff.py pre-confirm-guard --step <step>fails closed on execute/ship (R12). - 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
wrong-name
Missing use when phrase and wrong directory name for critical lint failure.
demo-skill
Demo workflow pack skill fixture. Use when validating workflow-pack-sdk golden paths in CI.
good-skill
Validates Agent Skills spec conformance for fixture trees. Use when testing skills-spec-guard pass paths across core and dist mirrors. Does not ship production skills.
wrong-name
Fixture with name/dir mismatch for guard failure tests. Use when verifying skills-spec-guard rejects invalid identity. Does not ship production skills.
bad-description
Missing the required when trigger phrase in this fixture skill.
dropin-demo
暂无简介