Debugger

GTM-OS Debugger

Systematic diagnostic skill that activates when any GTM-OS command fails. Runs a 5-layer funnel from cheapest checks (file reads) to most expensive (live API calls), identifies the root cause, and offers auto-fixes with user approval.

When This Skill Applies

• Any pnpm cli -- command outputs an error or stack trace
• User says "debug" / "fix" / "not working" / "broken" / "troubleshoot"
• User says "help me fix [error]" / "what went wrong" / "why is this failing"
• User pastes an error message or stack trace from GTM-OS

What This Skill Does NOT Do

• Fix bugs in user's custom code outside GTM-OS
• Debug network/firewall issues beyond basic connectivity checks
• Modify GTM-OS source code (only configuration, env vars, and database state)

CRITICAL RULES

1. Never skip layers. Always start at Layer 1 even if you think you know the issue. Cheap checks catch 80% of problems.
2. Never auto-fix without approval. Always show the proposed change and ask before applying.
3. Never expose secrets. When reading .env.local or api_connections, mask all API keys (e.g., sk-...redacted).
4. Short-circuit on first finding. When a layer finds the root cause, stop and offer the fix. Don't keep checking.
5. Re-run the original command after fixing. The debug session isn't done until the command succeeds.

Base Context: GTM-OS Architecture

GTM-OS is a CLI-first TypeScript system for AI-native go-to-market automation.

Entry point: src/cli/index.ts via npx tsx Env loading: .env.local via loadEnv() at CLI startup Config files: ~/.gtm-os/config.yaml (user prefs) + gtm-os.yaml (GTM framework) Database: SQLite via @libsql/client + Drizzle ORM. Default path: file:./gtm-os.db

Three-Layer Architecture

Provider Dependency Matrix

Critical Files Map

Diagnostic Workflow

Step 0: Capture Error Context

Before starting the funnel, capture:

1. The exact error message and stack trace
2. Which CLI command was run (e.g., campaign:track, leads:qualify)
3. Which provider is involved (extract from error message or command)

Store this context — you'll reference it throughout the funnel.

Step 1: Layer 1 — Environment Validation (FREE)

Check .env.local existence and content. No API calls needed.

# Check .env.local exists
test -f .env.local && echo "OK: .env.local exists" || echo "FAIL: .env.local missing"

# Check required vars are set (mask values)
for var in ANTHROPIC_API_KEY DATABASE_URL ENCRYPTION_KEY; do
  if grep -q "^${var}=" .env.local 2>/dev/null; then
    echo "OK: $var is set"
  else
    echo "FAIL: $var is missing"
  fi
done

# Check provider-specific vars for the failing provider
# (run only the relevant check based on Step 0 context)

# Unipile check:
grep -q "^UNIPILE_API_KEY=" .env.local && echo "OK: UNIPILE_API_KEY set" || echo "FAIL: UNIPILE_API_KEY missing"
grep -q "^UNIPILE_DSN=" .env.local && echo "OK: UNIPILE_DSN set" || echo "FAIL: UNIPILE_DSN missing"

# Validate UNIPILE_DSN format (must be https://api{N}.unipile.com:{PORT})
grep "^UNIPILE_DSN=" .env.local | grep -qE "^UNIPILE_DSN=https://api[0-9]+\.unipile\.com:[0-9]+" && echo "OK: DSN format valid" || echo "FAIL: DSN format invalid"

# Check for common env var mistakes
# Trailing whitespace:
grep -n ' $' .env.local && echo "WARNING: Trailing whitespace found" || echo "OK: No trailing whitespace"
# Quoted values (should NOT be quoted):
grep -nE '^[A-Z_]+=".+"' .env.local && echo "WARNING: Quoted values found — remove quotes" || echo "OK: No quoted values"

If any FAIL found: Stop here. Explain the issue and offer to fix it.

Auto-fix actions:

• Missing .env.local → "I'll copy .env.example to .env.local. You'll need to fill in your API keys."
• Missing env var → "I'll add {VAR}= to your .env.local. Please paste your key value."
• Invalid DSN format → Show the correct format: UNIPILE_DSN=https://api{N}.unipile.com:{PORT}
• Quoted values → "I'll remove the quotes around the value."
• Trailing whitespace → "I'll trim the whitespace."

Step 2: Layer 2 — Database Validation (FREE)

Check database file and schema state. Local queries only.

# Extract DB path from .env.local (default: ./gtm-os.db)
DB_URL=$(grep "^DATABASE_URL=" .env.local 2>/dev/null | cut -d= -f2-)
DB_PATH="${DB_URL:-file:./gtm-os.db}"
DB_PATH="${DB_PATH#file:}"
echo "Database path: $DB_PATH"
test -f "$DB_PATH" && echo "OK: Database file exists" || echo "FAIL: Database file missing"

# Check core tables exist (need at least these)
sqlite3 "$DB_PATH" "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;" 2>&1

Expected tables (minimum): conversations, messages, workflows, workflow_steps, result_sets, result_rows, knowledge_items, api_connections, frameworks, rate_limit_buckets, campaigns, campaign_leads, campaign_variants, campaign_messages

# Check FTS5 virtual table
sqlite3 "$DB_PATH" "SELECT name FROM sqlite_master WHERE type='table' AND name='knowledge_fts';" 2>&1

# Check pragmas
sqlite3 "$DB_PATH" "PRAGMA journal_mode;" 2>&1
sqlite3 "$DB_PATH" "PRAGMA foreign_keys;" 2>&1

If any FAIL found: Stop here.

Auto-fix actions:

• Database file missing → "I'll run pnpm db:push to create the database and tables. Approve?"
• Missing tables → "Tables are missing. I'll run pnpm db:push to apply the schema. Approve?"
• FTS5 missing → "The full-text search index is missing. This usually self-heals on next startup. Try re-running your command."
• WAL mode off → "I'll enable WAL mode: sqlite3 gtm-os.db 'PRAGMA journal_mode=WAL;'. Approve?"

Step 3: Layer 3 — Configuration Validation (FREE)

Check YAML config files exist and parse correctly.

# Check gtm-os.yaml
test -f gtm-os.yaml && echo "OK: gtm-os.yaml exists" || echo "FAIL: gtm-os.yaml missing"

# Validate YAML syntax
node -e "
try {
  require('js-yaml').load(require('fs').readFileSync('gtm-os.yaml','utf8'));
  console.log('OK: Valid YAML');
} catch(e) {
  console.log('FAIL: Invalid YAML -', e.message);
}
" 2>&1

# Check onboarding status
node -e "
const y = require('js-yaml').load(require('fs').readFileSync('gtm-os.yaml','utf8'));
console.log('onboarding_complete:', y.onboarding_complete || false);
" 2>&1

# Check user config
test -f ~/.gtm-os/config.yaml && echo "OK: User config exists" || echo "FAIL: User config missing at ~/.gtm-os/config.yaml"

Auto-fix actions:

• Missing gtm-os.yaml → "Run yalc-gtm onboard to create your GTM framework. This asks 5 questions about your business."
• Invalid YAML → Show the syntax error location and offer to fix it
• onboarding_complete: false → "Run yalc-gtm onboard to complete setup."
• Missing user config → "I'll create ~/.gtm-os/config.yaml with defaults. Approve?"