Skill

skill-system-debug

Coder-only debugging lifecycle for AI agents. Open isolated debug sessions, record hypothesis steps, capture tool friction, and close with a structured lesson written to memory.

Install

npx claudepluginhub arthur0824hao/skills --plugin document-skills

Tool Access

This skill uses the workspace's default tool permissions.

Preview

This skill is coder-only. The public contract is a lifecycle:

Supporting Assets

SKILL.behavior.yamlSKILL.meta.yamlSKILL.spec.yamlscripts/debug_tool.pyscripts/test_debug_tool.pytone.md

SKILL.md

Similar Skills

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

168.3k

subagent-driven-development

3 files

Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.

superpowers

168.3k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

168.3k

Stats

Stars4

Forks0

Last CommitApr 11, 2026

Actions

View Source View Plugin View on GitHub View README

skill-system-debug

This skill is coder-only. The public contract is a lifecycle:

start opens a debug session with its own scratch dir and time budget
step records hypothesis progression, evidence, and optional tool friction
close writes a structured lesson with root-cause and verification fields back into memory

Reviewer surfaces should consume the resulting lesson or friction artifacts, not run sk debug directly.

Operations

The preferred public entrypoint is the unified CLI:

python3 ../skill-system-cli/scripts/sk.py debug start --title "FD entry path bug" --symptom "entry.json env paths failed from arbitrary cwd"
python3 ../skill-system-cli/scripts/sk.py debug step --debug-id dbg_123 --hypothesis "paths are cwd-relative" --action "inspect entry rewrite"
python3 ../skill-system-cli/scripts/sk.py debug close --debug-id dbg_123 --root-cause-file path/to/file.py --root-cause-line 42 --hypothesis-chain "..." --counter-evidence "..." --fix "..." --verification "..."

Direct debug_tool.py invocation remains the underlying runtime surface.

start

python3 scripts/debug_tool.py start --title "FD entry path bug" --symptom "entry.json relative path fails in runtime"

step

python3 scripts/debug_tool.py step --debug-id dbg_123 --hypothesis "entry path resolved relative to cwd" --action "inspect loader path join" --evidence "loader joins cwd + entry.json"

close

python3 scripts/debug_tool.py close \
  --debug-id dbg_123 \
  --root-cause-file skills/skill-system-memory/scripts/mem.py \
  --root-cause-line 2162 \
  --hypothesis-chain "cwd-relative path hypothesis -> reproduction -> fix confirmed" \
  --counter-evidence "absolute paths worked, proving parser was fine" \
  --fix "normalize to artifact-relative path resolution" \
  --verification "reproduced bug, applied fix, reran loader successfully"

Lifecycle Rules

Canonical session state lives under .tkt/debug/<debug_id>.yaml
Scratch artifacts live under .sisyphus/tmp/debug/<debug_id>/
Default time budget is 30 minutes; step/close must warn when elapsed time exceeds budget
close is fail-closed if required lesson fields are missing
Tool-unfriendly moments should emit an inbox/friction artifact through the comms helper instead of silently disappearing

Required Lesson Fields

Every successful close must capture:

root_cause.file
root_cause.line
hypothesis_chain
counter_evidence
fix
verification

Integration Notes

Memory writeback should use the existing skill-system-memory surface rather than raw SQL
Friction logging should use the existing skill-system-comms inbox helper path
Existing low-level debug helpers (diagnose/trace/bisect/compare) may remain as internals, but the public lifecycle is start / step / close

Example: real bug workflow

This lifecycle was exercised against the real FD entry.json relative-path bug in:

/share/nas165/arthur0824hao/Work/Study/GNN/FraudDetect/Experiment/scripts/regenerate_fd_absolute_entries.py:54

The resulting close lesson recorded:

root cause file:line
hypothesis chain
counter-evidence
fix
verification

and wrote a debug-lesson memory row after the close path was corrected to respect procedural-memory importance rules.

{
  "schema_version": "2.0",
  "id": "skill-system-debug",
  "version": "0.2.0",
  "capabilities": ["debug-start", "debug-step", "debug-close"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.write"],
  "operations": {
    "start": {
      "description": "Open a coder-only debug session with isolated scratch state and budget tracking.",
      "input": {
        "title": { "type": "string", "required": true },
        "symptom": { "type": "string", "required": true },
        "workdir": { "type": "string", "required": false },
        "time_budget_minutes": { "type": "integer", "required": false }
      },
      "output": {
        "description": "Debug session metadata",
        "fields": { "debug_id": "string", "state_path": "string", "scratch_dir": "string", "time_budget_minutes": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "start", "--title", "{title}", "--symptom", "{symptom}"],
        "windows": ["python", "scripts/debug_tool.py", "start", "--title", "{title}", "--symptom", "{symptom}"]
      }
    },
    "step": {
      "description": "Record one debug step with hypothesis, evidence, and optional tool friction.",
      "input": {
        "debug_id": { "type": "string", "required": true },
        "hypothesis": { "type": "string", "required": true },
        "action": { "type": "string", "required": true },
        "evidence": { "type": "string", "required": false },
        "counter_evidence": { "type": "string", "required": false },
        "tool_unfriendly": { "type": "boolean", "required": false },
        "friction_note": { "type": "string", "required": false }
      },
      "output": {
        "description": "Step progression result",
        "fields": { "debug_id": "string", "step_index": "integer", "budget_warning": "boolean", "friction_logged": "boolean" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "step", "--debug-id", "{debug_id}", "--hypothesis", "{hypothesis}", "--action", "{action}"],
        "windows": ["python", "scripts/debug_tool.py", "step", "--debug-id", "{debug_id}", "--hypothesis", "{hypothesis}", "--action", "{action}"]
      }
    },
    "close": {
      "description": "Close a debug session and write a structured lesson into memory.",
      "input": {
        "debug_id": { "type": "string", "required": true },
        "root_cause_file": { "type": "string", "required": true },
        "root_cause_line": { "type": "integer", "required": true },
        "hypothesis_chain": { "type": "string", "required": true },
        "counter_evidence": { "type": "string", "required": true },
        "fix": { "type": "string", "required": true },
        "verification": { "type": "string", "required": true }
      },
      "output": {
        "description": "Debug closure result",
        "fields": { "debug_id": "string", "closed": "boolean", "lesson_path": "string", "memory_write_status": "string", "friction_count": "integer" }
      },
      "entrypoints": {
        "unix": ["python3", "scripts/debug_tool.py", "close", "--debug-id", "{debug_id}", "--root-cause-file", "{root_cause_file}", "--root-cause-line", "{root_cause_line}", "--hypothesis-chain", "{hypothesis_chain}", "--counter-evidence", "{counter_evidence}", "--fix", "{fix}", "--verification", "{verification}"],
        "windows": ["python", "scripts/debug_tool.py", "close", "--debug-id", "{debug_id}", "--root-cause-file", "{root_cause_file}", "--root-cause-line", "{root_cause_line}", "--hypothesis-chain", "{hypothesis_chain}", "--counter-evidence", "{counter_evidence}", "--fix", "{fix}", "--verification", "{verification}"]
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true
  }
}