debug-program

Name: debug-program
Author: sendaifun

162stars45forks

How to install debug-program?

sendaifun/solana-new/debug-program

$npx -y skills add sendaifun/solana-new --skill debug-program

Installs into the current project.

Summary

Help a developer debug a failing Solana program or transaction. Use when a user says "debug my program", "program error", "transaction failed", "stuck", "help me fix", "why is this failing", "error code", or "instruction failed". Reads build-context.md if available.

Files · 1

View on GitHub

SKILL.md

1	## Preamble (run first)
2
3	```bash
4	_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null \| grep -o '"telemetryTier": "[^"]"' \| head -1 \| sed 's/."telemetryTier": "//;s/"$//' \|\| echo "anonymous")
5	_TEL_TIER="${_TEL_TIER:-anonymous}"
6	_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" \|\| echo "no")
7	_TEL_START=$(date +%s)
8	_SESSION_ID="$$-$(date +%s)"
9	mkdir -p ~/.superstack
10	echo "TELEMETRY: $_TEL_TIER"
11	echo "TEL_PROMPTED: $_TEL_PROMPTED"
12	if [ "$_TEL_TIER" != "off" ]; then
13	_TEL_EVENT='{"skill":"debug-program","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
14	echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null \|\| true
15	_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null \| grep -o '"convexUrl":"[^"]*"' \| head -1 \| cut -d'"' -f4 \|\| echo "")
16	[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"debug-program","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
17	true
18	fi
19	```
20
21	If `TEL_PROMPTED` is `no`: Before starting the skill workflow, ask the user about telemetry.
22	Use AskUserQuestion:
23
24	> Help superstack get better! We track which skills get used and how long they take —
25	> no code, no file paths, no PII. Change anytime in `~/.superstack/config.json`.
26
27	Options:
28	- A) Sure, help superstack improve (anonymous)
29	- B) No thanks
30
31	If A: run this bash:
32	```bash
33	echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
34	_TEL_TIER="anonymous"
35	touch ~/.superstack/.telemetry-prompted
36	```
37
38	If B: run this bash:
39	```bash
40	echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
41	_TEL_TIER="off"
42	touch ~/.superstack/.telemetry-prompted
43	```
44
45	This only happens once. If `TEL_PROMPTED` is `yes`, skip this entirely and proceed to the skill workflow.
46
47	> Wrong skill? See [SKILL_ROUTER.md](../../SKILL_ROUTER.md) for all available skills.
48
49	# Debug Program
50
51	## Overview
52
53	Systematically diagnose and fix Solana program errors and transaction failures. Instead of guessing, follow a structured debugging workflow: read the error, simulate the transaction, inspect program logs, check account state, and trace CPI chains. Covers the top 20 most common Solana dev mistakes and their fixes.
54
55	## Workflow
56
57	1. Check for `.superstack/build-context.md` for context on what the user is building. If not found, gather context from the user and write `.superstack/build-context.md` so future skills can use it.
58	2. Get the error: ask for the exact error message, transaction signature, or program logs.
59	3. Read [references/debug-workflow.md](references/debug-workflow.md) and follow the systematic debugging process.
60	4. If the error matches a known pattern, check [references/common-pitfalls.md](references/common-pitfalls.md) for the exact cause and fix.
61	5. Debug steps:
62	a. Parse the error message — identify error code, program, instruction index
63	b. Simulate the transaction to get full logs: `connection.simulateTransaction(tx)`
64	c. Inspect account state: check existence, ownership, balance, data
65	d. If CPI involved, trace the call chain to find which program failed
66	e. Apply the fix, test on devnet, confirm resolution
67	6. If stuck after 3 attempts, suggest a different approach or escalate to a community resource.
68
69	## Non-Negotiables
70
71	- Always get the exact error message or transaction signature first. Do not guess without data.
72	- Simulate transactions before sending — the simulation logs contain the actual error.
73	- Check the basics first: is the account initialized? Is the signer correct? Is there enough SOL?
74	- Never suggest "just retry" without understanding why the transaction failed.
75	- When debugging CPI errors, identify which program in the chain actually failed.
76	- Use Surfpool for reproducible debugging — fork the state, replay the transaction, inspect.
77
78	## Phase Handoff
79
80	This skill is Phase 2 (Build) in the Idea → Build → Launch journey.
81
82	Reads: `.superstack/build-context.md`
83	Writes/Updates: `.superstack/build-context.md` (creates if missing) with:
84	- `debug.issues_resolved`: array of { error, cause, fix }
85	- `debug.last_debug_session`: ISO timestamp
86
87	When updating, deep-merge — don't overwrite existing fields.
88
89	See `../../data/specs/phase-handoff.md` for the full JSON contract.
90
91	## Quick Start
92
93	```bash
94	# Step 1: Get the error from transaction signature
95	solana confirm -v <TX_SIGNATURE>
96
97	# Step 2: Check program logs for the failing transaction
98	solana logs <PROGRAM_ID> # Stream real-time logs (run before reproducing the error)
99
100	# Step 3: Check account state
101	solana account <ACCOUNT_ADDRESS>

People who liked this also viewed

6 picks

Type

debug-program

162stars45forks

View on GitHub

How to install debug-program?

sendaifun/solana-new/debug-program

$npx -y skills add sendaifun/solana-new --skill debug-program

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	## Preamble (run first)
2
3	```bash
4	_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null \| grep -o '"telemetryTier": "[^"]"' \| head -1 \| sed 's/."telemetryTier": "//;s/"$//' \|\| echo "anonymous")
5	_TEL_TIER="${_TEL_TIER:-anonymous}"
6	_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" \|\| echo "no")
7	_TEL_START=$(date +%s)
8	_SESSION_ID="$$-$(date +%s)"
9	mkdir -p ~/.superstack
10	echo "TELEMETRY: $_TEL_TIER"
11	echo "TEL_PROMPTED: $_TEL_PROMPTED"
12	if [ "$_TEL_TIER" != "off" ]; then
13	_TEL_EVENT='{"skill":"debug-program","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
14	echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null \|\| true
15	_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null \| grep -o '"convexUrl":"[^"]*"' \| head -1 \| cut -d'"' -f4 \|\| echo "")
16	[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"debug-program","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
17	true
18	fi
19	```
20
21	If `TEL_PROMPTED` is `no`: Before starting the skill workflow, ask the user about telemetry.
22	Use AskUserQuestion:
23
24	> Help superstack get better! We track which skills get used and how long they take —
25	> no code, no file paths, no PII. Change anytime in `~/.superstack/config.json`.
26
27	Options:
28	- A) Sure, help superstack improve (anonymous)
29	- B) No thanks
30
31	If A: run this bash:
32	```bash
33	echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
34	_TEL_TIER="anonymous"
35	touch ~/.superstack/.telemetry-prompted
36	```
37
38	If B: run this bash:
39	```bash
40	echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
41	_TEL_TIER="off"
42	touch ~/.superstack/.telemetry-prompted
43	```
44
45	This only happens once. If `TEL_PROMPTED` is `yes`, skip this entirely and proceed to the skill workflow.
46
47	> Wrong skill? See [SKILL_ROUTER.md](../../SKILL_ROUTER.md) for all available skills.
48
49	# Debug Program
50
51	## Overview
52
53	Systematically diagnose and fix Solana program errors and transaction failures. Instead of guessing, follow a structured debugging workflow: read the error, simulate the transaction, inspect program logs, check account state, and trace CPI chains. Covers the top 20 most common Solana dev mistakes and their fixes.
54
55	## Workflow
56
57	1. Check for `.superstack/build-context.md` for context on what the user is building. If not found, gather context from the user and write `.superstack/build-context.md` so future skills can use it.
58	2. Get the error: ask for the exact error message, transaction signature, or program logs.
59	3. Read [references/debug-workflow.md](references/debug-workflow.md) and follow the systematic debugging process.
60	4. If the error matches a known pattern, check [references/common-pitfalls.md](references/common-pitfalls.md) for the exact cause and fix.
61	5. Debug steps:
62	a. Parse the error message — identify error code, program, instruction index
63	b. Simulate the transaction to get full logs: `connection.simulateTransaction(tx)`
64	c. Inspect account state: check existence, ownership, balance, data
65	d. If CPI involved, trace the call chain to find which program failed
66	e. Apply the fix, test on devnet, confirm resolution
67	6. If stuck after 3 attempts, suggest a different approach or escalate to a community resource.
68
69	## Non-Negotiables
70
71	- Always get the exact error message or transaction signature first. Do not guess without data.
72	- Simulate transactions before sending — the simulation logs contain the actual error.
73	- Check the basics first: is the account initialized? Is the signer correct? Is there enough SOL?
74	- Never suggest "just retry" without understanding why the transaction failed.
75	- When debugging CPI errors, identify which program in the chain actually failed.
76	- Use Surfpool for reproducible debugging — fork the state, replay the transaction, inspect.
77
78	## Phase Handoff
79
80	This skill is Phase 2 (Build) in the Idea → Build → Launch journey.
81
82	Reads: `.superstack/build-context.md`
83	Writes/Updates: `.superstack/build-context.md` (creates if missing) with:
84	- `debug.issues_resolved`: array of { error, cause, fix }
85	- `debug.last_debug_session`: ISO timestamp
86
87	When updating, deep-merge — don't overwrite existing fields.
88
89	See `../../data/specs/phase-handoff.md` for the full JSON contract.
90
91	## Quick Start
92
93	```bash
94	# Step 1: Get the error from transaction signature
95	solana confirm -v <TX_SIGNATURE>
96
97	# Step 2: Check program logs for the failing transaction
98	solana logs <PROGRAM_ID> # Stream real-time logs (run before reproducing the error)
99
100	# Step 3: Check account state
101	solana account <ACCOUNT_ADDRESS>

People who liked this also viewed

6 picks

Type