debug-program

name	debug-program
description	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.

Preamble (run first)

_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//'  || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"debug-program","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' 
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -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 &
true
fi

If TEL_PROMPTED is no: Before starting the skill workflow, ask the user about telemetry. Use AskUserQuestion:

Help superstack get better! We track which skills get used and how long they take — no code, no file paths, no PII. Change anytime in ~/.superstack/config.json.

Options:

• A) Sure, help superstack improve (anonymous)
• B) No thanks

If A: run this bash:

echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted

If B: run this bash:

echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely and proceed to the skill workflow.

Wrong skill? See SKILL_ROUTER.md for all available skills.

Debug Program

Overview

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.

Workflow

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.
2. Get the error: ask for the exact error message, transaction signature, or program logs.
3. Read references/debug-workflow.md and follow the systematic debugging process.
4. If the error matches a known pattern, check references/common-pitfalls.md for the exact cause and fix.
5. Debug steps: a. Parse the error message — identify error code, program, instruction index b. Simulate the transaction to get full logs: connection.simulateTransaction(tx) c. Inspect account state: check existence, ownership, balance, data d. If CPI involved, trace the call chain to find which program failed e. Apply the fix, test on devnet, confirm resolution
6. If stuck after 3 attempts, suggest a different approach or escalate to a community resource.

Non-Negotiables

• Always get the exact error message or transaction signature first. Do not guess without data.
• Simulate transactions before sending — the simulation logs contain the actual error.
• Check the basics first: is the account initialized? Is the signer correct? Is there enough SOL?
• Never suggest "just retry" without understanding why the transaction failed.
• When debugging CPI errors, identify which program in the chain actually failed.
• Use Surfpool for reproducible debugging — fork the state, replay the transaction, inspect.

Phase Handoff

This skill is Phase 2 (Build) in the Idea → Build → Launch journey.

Reads: .superstack/build-context.md Writes/Updates: .superstack/build-context.md (creates if missing) with:

• debug.issues_resolved: array of { error, cause, fix }
• debug.last_debug_session: ISO timestamp

When updating, deep-merge — don't overwrite existing fields.

See ../../data/specs/phase-handoff.md for the full JSON contract.

Quick Start

# Step 1: Get the error from transaction signature
solana confirm -v <TX_SIGNATURE>

# Step 2: Check program logs for the failing transaction
solana logs <PROGRAM_ID>  # Stream real-time logs (run before reproducing the error)

# Step 3: Check account state
solana account <ACCOUNT_ADDRESS> --output json

# Step 4: Read program logs
solana logs <PROGRAM_ID>  # Live stream

# Step 5: Check common issues
anchor idl fetch <PROGRAM_ID>  # Verify IDL matches

Decision Points

• Which RPC for debugging? Use Surfpool with surfpool start --network mainnet to replay mainnet transactions locally. For a custom upstream RPC, use surfpool start --rpc-url <RPC_URL>.
• Can't read error code? Check Anchor error codes: 6000+ are custom program errors. 0x1 = insufficient funds. 0x0 = success.
• CPI error from another program? Check the inner instructions in transaction logs. The error comes from the CPI'd program, not yours.

Resources

references/

• references/debug-workflow.md
• references/common-pitfalls.md

Telemetry (run last)

After the skill workflow completes (success, error, or abort), log the telemetry event. Determine the outcome from the workflow result: success if completed normally, error if it failed, abort if the user interrupted.

Run this bash:

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"debug-program","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi

Replace OUTCOME with success/error/abort based on the workflow result.