debug

Name: debug
Author: Borda

23stars3forks

How to install debug?

borda/ai-rig/debug

$npx -y skills add Borda/AI-Rig --skill debug

Installs into the current project.

Summary

Investigation-first debugging — gather evidence, form confirmed root-cause hypothesis, hand off to fix mode with diagnosis file. TRIGGER when: user reports a symptom or failing test with Python traceback, or asks to investigate a runtime/CI failure with reproducible evidence; phr

Files · 1

View on GitHub

SKILL.md

1	<objective>
2
3	Investigation-first debugging. Gather evidence, trace data flow, form confirmed root-cause hypothesis, hand off to fix mode.
4
5	NOT for: production incidents without any CI run ID or local traceback (use `/foundry:investigate` (requires foundry plugin) for triage); `.claude/` config issues (use `/foundry:audit` (requires foundry plugin)); non-Python projects (JS/TS/Go/Rust) — toolchain assumes pytest; use language-native toolchain instead. CI-only failures ARE supported — pass `--ci-run <run-id or URL>` to use GitHub Actions logs as evidence source.
6
7	Issue ID routing note: issue mode selected when `--issue` flag present, or when argument (after other flags stripped) is a pure run of digits with an optional `#` prefix (e.g. `123` or `#123`). No numeric threshold. Pass `--issue <N>` to force issue mode for any argument.
8
9	</objective>
10
11	<compaction>
12
13	Key boundary: after Steps 1+2 — evidence gathered and pattern analysis complete, before hypothesis gate (Step 3).
14	Preserve: debug mode, CI run ID if set, evidence signals (issue body, test path), tried-hypotheses ledger (candidate causes + verdicts — refuted/ruled-out/open), --keep items.
15	Refresh also after any Step 3 probe that rules out a hypothesis — so post-compact gate does not re-test refuted causes (loop guard).
16
17	</compaction>
18
19	<workflow>
20
21	<!-- Agent resolution: see _DEV_SHARED/agent-resolution.md (mounted by develop plugin init) -->
22
23	## Agent Resolution
24
25	```bash
26	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
27	# loads: compaction-contract.md
28	cat "$_DEV_SHARED/agent-resolution.md"
29	```
30
31	Contains: foundry check + fallback table. If foundry not installed: substitute each `foundry:X` with `general-purpose` per table. Agents this skill uses: `foundry:sw-engineer`, `foundry:challenger`.
32
33	```bash
34	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
35	cat "$_DEV_SHARED/task-hygiene.md"
36	```
37
38	## Project Detection
39
40	```bash
41	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
42	cat "$_DEV_SHARED/runner-detection.md"
43	```
44	Sets `$TEST_CMD` (full suite) and `$PYTEST_CMD` (pytest flags). Run at skill start.
45
46	Language preflight gate: detect project language; adjust test runner accordingly.
47
48	```bash
49	# timeout: 5000
50	LANG_HINT="python"
51	if [ ! -f "pyproject.toml" ] && [ ! -f "setup.py" ] && [ ! -f "setup.cfg" ] && [ ! -f "Pipfile" ]; then
52	if [ -f "package.json" ]; then LANG_HINT="node"
53	elif [ -f "go.mod" ]; then LANG_HINT="go"
54	elif [ -f "Cargo.toml" ]; then LANG_HINT="rust"
55	fi
56	fi
57	```
58
59	If `LANG_HINT` not `python`: invoke `AskUserQuestion` — "Non-Python project detected (`$LANG_HINT`). Toolchain assumes pytest. How to proceed?" · (a) Abort — use language-native runner · (b) Continue — repo also has Python sources. On Abort: stop.
60
61	Checkpoint: debug = investigation only — no code changes. `.plans/active/debug_<slug>.md` (written in Step 4) serves as implicit session state. No `.developments/` checkpoint needed.
62
63	## Flag parsing
64
65	Parse flags into actual shell variables (not prose) so downstream blocks see correct values:
66
67	```bash
68	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
69	KEEP_ITEMS=""
70	if [[ "$ARGUMENTS" =~ --keep[[:space:]]\"([^\"]+)\" ]]; then
71	KEEP_ITEMS="${BASH_REMATCH[1]}"
72	fi
73	echo "$KEEP_ITEMS" > "${TMPDIR:-/tmp}/dev-debug-keep-items-${CSID}"
74	rm -f .temp/state/skill-contract.md ${TMPDIR:-/tmp}/dev-debug-hypotheses-${CSID} # timeout: 5000
75	```
76
77	```bash
78	# timeout: 10000
79	python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_parse_args.py" \
80	--skill debug --write-files "$ARGUMENTS"
81	# URL normalization + log fetching: §URL Normalization in ci-log-extract.md
82	```
83
84	Codemap resolve — `CODEMAP_RAW` already written to `${TMPDIR:-/tmp}/dev-debug-codemap-${CSID}` (per-skill) and `${TMPDIR:-/tmp}/dev-codemap-raw-${CSID}` (legacy) by flag-parsing block above (via `dev_

People who liked this also viewed

6 picks

Type

debug

23stars3forks

View on GitHub

How to install debug?

borda/ai-rig/debug

$npx -y skills add Borda/AI-Rig --skill debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<objective>
2
3	Investigation-first debugging. Gather evidence, trace data flow, form confirmed root-cause hypothesis, hand off to fix mode.
4
5	NOT for: production incidents without any CI run ID or local traceback (use `/foundry:investigate` (requires foundry plugin) for triage); `.claude/` config issues (use `/foundry:audit` (requires foundry plugin)); non-Python projects (JS/TS/Go/Rust) — toolchain assumes pytest; use language-native toolchain instead. CI-only failures ARE supported — pass `--ci-run <run-id or URL>` to use GitHub Actions logs as evidence source.
6
7	Issue ID routing note: issue mode selected when `--issue` flag present, or when argument (after other flags stripped) is a pure run of digits with an optional `#` prefix (e.g. `123` or `#123`). No numeric threshold. Pass `--issue <N>` to force issue mode for any argument.
8
9	</objective>
10
11	<compaction>
12
13	Key boundary: after Steps 1+2 — evidence gathered and pattern analysis complete, before hypothesis gate (Step 3).
14	Preserve: debug mode, CI run ID if set, evidence signals (issue body, test path), tried-hypotheses ledger (candidate causes + verdicts — refuted/ruled-out/open), --keep items.
15	Refresh also after any Step 3 probe that rules out a hypothesis — so post-compact gate does not re-test refuted causes (loop guard).
16
17	</compaction>
18
19	<workflow>
20
21	<!-- Agent resolution: see _DEV_SHARED/agent-resolution.md (mounted by develop plugin init) -->
22
23	## Agent Resolution
24
25	```bash
26	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
27	# loads: compaction-contract.md
28	cat "$_DEV_SHARED/agent-resolution.md"
29	```
30
31	Contains: foundry check + fallback table. If foundry not installed: substitute each `foundry:X` with `general-purpose` per table. Agents this skill uses: `foundry:sw-engineer`, `foundry:challenger`.
32
33	```bash
34	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
35	cat "$_DEV_SHARED/task-hygiene.md"
36	```
37
38	## Project Detection
39
40	```bash
41	_DEV_SHARED=$(python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_shared_resolve.py" 2>/dev/null) # timeout: 5000
42	cat "$_DEV_SHARED/runner-detection.md"
43	```
44	Sets `$TEST_CMD` (full suite) and `$PYTEST_CMD` (pytest flags). Run at skill start.
45
46	Language preflight gate: detect project language; adjust test runner accordingly.
47
48	```bash
49	# timeout: 5000
50	LANG_HINT="python"
51	if [ ! -f "pyproject.toml" ] && [ ! -f "setup.py" ] && [ ! -f "setup.cfg" ] && [ ! -f "Pipfile" ]; then
52	if [ -f "package.json" ]; then LANG_HINT="node"
53	elif [ -f "go.mod" ]; then LANG_HINT="go"
54	elif [ -f "Cargo.toml" ]; then LANG_HINT="rust"
55	fi
56	fi
57	```
58
59	If `LANG_HINT` not `python`: invoke `AskUserQuestion` — "Non-Python project detected (`$LANG_HINT`). Toolchain assumes pytest. How to proceed?" · (a) Abort — use language-native runner · (b) Continue — repo also has Python sources. On Abort: stop.
60
61	Checkpoint: debug = investigation only — no code changes. `.plans/active/debug_<slug>.md` (written in Step 4) serves as implicit session state. No `.developments/` checkpoint needed.
62
63	## Flag parsing
64
65	Parse flags into actual shell variables (not prose) so downstream blocks see correct values:
66
67	```bash
68	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
69	KEEP_ITEMS=""
70	if [[ "$ARGUMENTS" =~ --keep[[:space:]]\"([^\"]+)\" ]]; then
71	KEEP_ITEMS="${BASH_REMATCH[1]}"
72	fi
73	echo "$KEEP_ITEMS" > "${TMPDIR:-/tmp}/dev-debug-keep-items-${CSID}"
74	rm -f .temp/state/skill-contract.md ${TMPDIR:-/tmp}/dev-debug-hypotheses-${CSID} # timeout: 5000
75	```
76
77	```bash
78	# timeout: 10000
79	python "${CLAUDE_PLUGIN_ROOT:-plugins/cc_develop}/bin/dev_parse_args.py" \
80	--skill debug --write-files "$ARGUMENTS"
81	# URL normalization + log fetching: §URL Normalization in ci-log-extract.md
82	```
83
84	Codemap resolve — `CODEMAP_RAW` already written to `${TMPDIR:-/tmp}/dev-debug-codemap-${CSID}` (per-skill) and `${TMPDIR:-/tmp}/dev-codemap-raw-${CSID}` (legacy) by flag-parsing block above (via `dev_

People who liked this also viewed

6 picks

Type