Systematic Debugging

Indexed Reference Map

• @[SKILL.md#L1-L109] Frontmatter, trigger rules, SOP, output contract.
• @[references/INDEX.md#L1-L29] Reading order and reference inventory.
• @[references/QUICK_REFERENCE.md#L1-L50] Fast triage loop, stop conditions, and anti-patterns.
• @[references/classification-matrix.md#L1-L30] Failure classification matrix by symptom/layer.
• @[references/evidence-checklist.md#L1-L40] Evidence collection order and minimum proof set.
• @[references/practical-lane.md#L1-L53] Practical debugging lane: minimal repro, first failure, fallback, mutation discipline.
• @[references/retest-and-rollback.md#L1-L24] Verification, smoke checks, PARTIAL/PASS gate, and rollback discipline.
• @[references/escalation-map.md#L1-L37] Handoff map to specialist internal skills.

Scope

• In-scope:
  • Runtime errors, test failures, unexpected behavior, regressions, integration mismatches.
  • OpenClaw-Module Android issues involving shell/service/plugin/config/python/runtime layers.
  • Local reproduction, evidence collection, hypothesis testing, minimal patch planning.
  • Practical failure handling where the visible error may be downstream from the true first failing layer.
• Out-of-scope:
  • Blind trial-and-error patching without reproduction or evidence.
  • Large architectural rewrites disguised as debugging.
  • Destructive/system-level actions outside approved workspace/runtime safety boundary.

KB Mode Notes

• Reading order:
  1. references/INDEX.md
  2. references/QUICK_REFERENCE.md
  3. references/classification-matrix.md
  4. references/evidence-checklist.md
  5. references/practical-lane.md
  6. references/retest-and-rollback.md
  7. references/escalation-map.md
• Coverage Matrix:
  • Symptom triage -> QUICK_REFERENCE.md, classification-matrix.md
  • Evidence discipline -> evidence-checklist.md
  • Practical incident handling -> practical-lane.md
  • Verify/report/rollback -> retest-and-rollback.md
  • Specialist handoff -> escalation-map.md
• Portability note:
  • Workflow is local-first and does not depend on external docs. Absolute runtime paths, when mentioned, are verify targets/examples rather than mandatory hard dependencies.

Trigger Rules

• Positive:
  • User reports bug, failure, regression, broken behavior, flaky result, mismatch, command fail, service/app not running, or asks why something is broken.
  • Logs/output show an error and the next step is root-cause isolation rather than immediate patching.
  • Prompt contains intent like: debug, diagnose, triage, investigate, root cause, inspect failure, find why, why broken, what error.
  • A task needs disciplined reproduce -> inspect -> isolate -> verify flow.
• Negative:
  • User already requested a very specific, low-risk edit with clear root cause and no debugging needed.
  • Pure feature implementation, planning, refactor, scaffolding, or skill authoring with no failure diagnosis aspect.
  • User asks directly for a known mechanical action without symptom analysis.
  • Cases already clearly inside a specialist skill with a dominant signature.
• Escalation:
  • If the strongest signature matches a specialist internal skill, hand off early after minimal evidence capture.
  • If the next step requires actions outside workspace/network write/sensitive mutation, stop and request approval checkpoint.

SOP

1. Stabilize the symptom statement
   • Rewrite the problem as: expected behavior, actual behavior, scope, first known bad point.
   • Reject vague labels like "broken" without observable evidence.
2. Build the smallest safe repro
   • Use the minimum command/request/path that reproduces the issue.
   • Prefer a repro matrix when schema/validation/input shape may be involved.
3. Separate first failure from downstream symptom
   • Identify the earliest layer that violates contract.
   • Do not assume the last error message is the root cause.
4. Classify the failure layer
   • Use references/classification-matrix.md to place the issue into likely layers.
   • For wrapper/core/executor style incidents, explicitly separate caller payload, bridge/wrapper normalization, core validation, and execution/runtime effects.
5. Collect evidence in order
   • Follow references/evidence-checklist.md.
   • Prefer raw command output, logs, file state, version info, and recent diffs over intuition.
6. Form bounded hypotheses
   • Generate 1-3 hypotheses maximum.
   • Each hypothesis must predict what evidence should appear if true.
7. Test one variable at a time
   • Change only the minimum variable needed to confirm or reject a hypothesis.
   • Avoid parallel patching that destroys causality.
8. Patch minimally and at the correct layer
   • Fix the first failing layer, not the loudest downstream symptom.
   • If the failing tool itself becomes unreliable for the repair path, switch to a safer fallback path.
9. Verify explicitly
   • Re-run the original repro.
   • Run adjacent smoke checks.
   • Keep rollback path for every mutation cluster.
10. Report with confidence and state gate

• Use PARTIAL when mutation happened but verification is incomplete.
• Use PASS only when repro rerun and adjacent smoke checks support the claim.

11. Escalate or hand off when appropriate

• Use references/escalation-map.md for specialist skill mapping.

Error Handling

• Reproduction unavailable:
  • Return UNREPRODUCED status, list missing evidence, and avoid claiming root cause.
• Multiple plausible layers:
  • Narrow by cheapest discriminator test first; do not branch into many speculative fixes.
• Logs too noisy/large:
  • Extract only the minimal failing segment plus surrounding context needed for causality.
• Tool-under-repair is itself failing:
  • stop retrying the same broken lane
  • choose fallback (read+write, script patcher, alternate probe) that preserves causality and rollback
• Potential specialist-skill case:
  • Capture initial evidence, then hand off instead of duplicating a more specialized SOP.
• Sensitive/destructive step required:
  • Stop and request approval with exact command/scope.

Output Contract

• Deliverable:
  • Symptom: concise expected vs actual.
  • Repro: minimal path or repro matrix.
  • Classification: likely layer + reason.
  • First Failure: earliest violating layer + why.
  • Evidence: commands/logs/files used.
  • Hypotheses Tested: accepted/rejected.
  • Action: fix applied, proposed patch, fallback, or handoff.
  • Verification: repro re-check + adjacent smoke checks.
  • Rollback: backup path or recovery path.
  • Confidence: LOW|MEDIUM|HIGH.
• Validation:
  • PASS = reproduced or strongly evidenced, first failing layer isolated, fix/handoff verified.
  • PARTIAL = some evidence or mutation exists, but root cause or verification incomplete.
  • UNREPRODUCED = symptom not reproduced and evidence insufficient.
  • FAIL = debugging attempt blocked, contradicted, or made unsafe by constraints.
• Compliance Verdict:
  • PASS|PARTIAL|UNREPRODUCED|FAIL + short reason, never vague success claims.