debug-a0

name: debug-a0 description: This skill should be used when the user asks to "debug an A0 program", "fix A0 error", "understand A0 error", "A0 diagnostic", "A0 exit code", "read A0 trace", "why does my A0 program fail", "A0 parse error", "A0 capability denied", "A0 runtime error", or needs to diagnose, understand, or fix issues in existing A0 source code.

Debugging A0 Programs

Guide for diagnosing and fixing errors in A0 programs. A0 uses structured diagnostics with stable error codes, machine-readable trace output, and deterministic exit codes.

Diagnostic Format

A0 errors follow this format:

error[E_CODE]: Human-readable message
  --> file.a0:3:5
  hint: Suggested fix (when available)

Each diagnostic has:

• code — Stable string identifier (e.g., E_PARSE)
• message — What went wrong
• span — File, line, and column
• hint — Optional fix suggestion

In JSON mode (non-pretty), diagnostics are { code, message, span?, hint? }.

Exit Codes

Map exit codes to error categories:

Quick Diagnostic Reference

Compile-Time Errors (exit 2)

Runtime Errors (exit 3, 4, 5)

For detailed repair strategies per error code, see references/diagnostics-guide.md.

Debugging Workflow

Step 1: Run a0 check

Start with static validation — catches most errors without executing anything:

a0 check file.a0

This catches: E_LEX, E_PARSE, E_AST, E_NO_RETURN, E_RETURN_NOT_LAST, E_UNKNOWN_CAP, E_DUP_BINDING, E_UNBOUND, E_CALL_EFFECT, E_UNDECLARED_CAP, E_UNKNOWN_BUDGET, E_FN_DUP.

Step 2: Read the Diagnostic

Parse the error output:

1. Note the error code — look it up in the table above
2. Note the line:col — go to exact location
3. Read the hint if present — it often gives the fix directly

Step 3: Apply the Fix

Common fix patterns:

• Missing return: Add return <expr> at end
• Wrong tool keyword: Swap do ↔ call? based on tool mode
• Unbound variable: Ensure the variable is bound with let x = ... or expr -> x before use
• Duplicate binding: Rename one variable (A0 has no reassignment)
• Capability denied: Add the capability to the cap { ... } block

Step 3b: Use try/catch for Recoverable Errors

If the error is a runtime failure that should not halt the program (e.g., a missing file, invalid JSON, network error), wrap the failing code in try/catch instead of fixing the root cause:

let result = try {
  call? fs.read { path: "optional.json" } -> raw
  let data = parse.json { in: raw }
  return { ok: true, data: data }
} catch { e } {
  # e is { code: "E_TOOL", message: "..." } or similar
  return { ok: false, error: e.code }
}

The catch binding { e } receives a record with code (e.g., E_TOOL, E_FN, E_TYPE) and message fields. Use this for graceful degradation when failures are expected and recoverable.

Note: E_ASSERT (fatal assertion) is NOT catchable -- it always halts the program. E_CHECK is non-fatal and does not throw, so it cannot be caught either.

Step 4: Use Trace for Runtime Issues

For errors that only appear at runtime, use trace mode:

a0 run file.a0 --trace trace.jsonl --unsafe-allow-all

The trace JSONL file contains step-by-step execution events. Examine the last events before the error to identify the failing operation.

Step 5: Use a0 fmt to Normalize

After fixing, format for consistency:

a0 fmt file.a0 --write

Reading A0 Code

When understanding existing A0 programs:

1. Start at cap {} — identifies what side effects the program uses
2. Follow the data flow — let and -> bindings create the variable chain
3. Identify tool calls — call? (reads data) vs do (has effects)
4. Check return — the program's output is always the return value (can be any expression, not just a record)
5. Note assert/check — assert is fatal (halts on failure), check is non-fatal (records evidence, continues)

Capability Policy

A0 uses deny-by-default. Capabilities must be:

1. Declared in the program's cap { ... } block
2. Allowed by the host policy

Policy files load in order (first match wins):

1. .a0policy.json in the project directory
2. ~/.a0/policy.json (user-level)
3. Deny-all default

Override for development: --unsafe-allow-all

Common Debugging Scenarios

"Nothing happens" (exit 3)

Capability denied. Check cap {} matches the tools used, then check policy files.

"Parse error on valid-looking code"

A0 is line-oriented. Check for:

• Multi-line expressions that aren't supported
• Missing commas in records/lists
• Unclosed braces or brackets
• Using a keyword as a variable name

"Tool returned unexpected data"

Use trace to see the raw tool return value. Common issues:

• http.get returns body as a string — must parse.json before dot access
• fs.read returns a string — must parse.json if the file is JSON
• sh.exec returns { exitCode, stdout, stderr } — check exitCode

"E_TYPE on + operator"

The + operator works on numbers and strings, but both operands must be the same type. Common issues:

• "count: " + 42 -- mixed string + number produces E_TYPE. Convert to string first, or use str.template.
• { ...x, key: 1 } where x is not a record -- spread of non-record produces E_TYPE.

"E_TYPE on loop times"

The loop construct requires times: to be a non-negative integer. Common issues:

• loop { in: 0, times: 2.5, as: "x" } -- float produces E_TYPE
• loop { in: 0, times: -1, as: "x" } -- negative produces E_TYPE
• loop { in: 0, times: count, as: "x" } where count is a string -- non-number produces E_TYPE

"E_BUDGET on filter/loop"

Both filter blocks and loop count against maxIterations budget (shared with for, map, reduce). If multiple iterations in the same program, their counts are cumulative.

"Unrecoverable error that should be recoverable"

If a tool call or stdlib function throws and you want the program to continue, wrap it in try/catch:

let result = try {
  call? fs.read { path: "missing.txt" } -> raw
  return { data: raw }
} catch { e } {
  return { data: null, error: e.code }
}

The catch binding e has { code, message }. Note that E_ASSERT cannot be caught -- it always halts.

Additional Resources

Reference Files

• references/diagnostics-guide.md — Detailed repair strategies for every error code with before/after examples