canary-run-debug

name	canary-run-debug
description	Use this skill when running Canary tests or workflows, inspecting failures, querying job/session state, reproducing a job, or debugging resource and dependency problems.

Running and debugging Canary jobs

What this skill is for

Use this skill when you need to execute Canary jobs, inspect status, debug failures, or query persisted job/session state.

First action: query execution and query capabilities

For running behavior:

canary query -c execution.local

For result inspection:

canary query -c query
canary query -c results

For resource failures:

canary query -c resources

For dependency failures:

canary query -c dependencies

Basic execution workflow

1. Run jobs from a path, tag, or ID.

canary run PATH
canary run TAG
canary run JOBID

2. Inspect status.

canary status

3. Inspect logs for a job.

canary log JOBID

4. Query structured state.

canary query -j JOBID
canary query -j JOBID status
canary query -j JOBID measurements.data
canary query -s latest

5. Reproduce a single job if needed.

canary exec JOBID

Use query instead of scraping when possible

Canary persists JSON-like state in job and session lock files. Prefer:

canary query -j JOBID measurements.data
canary query -s latest measurements

over parsing canary-out.txt.

Query syntax is lightweight, not jq. For details:

canary query -c query

Debugging failures

Use this order:

1. Check overall status.

canary status

2. Open the failing job log.

canary log JOBID

3. Query the job status reason.

canary query -j JOBID status.reason

4. Query measurements.

canary query -j JOBID measurements.data

5. Locate the working directory.

canary location JOBID

6. Re-run the single job if appropriate.

canary exec JOBID

Debugging dependency problems

If a job did not run, inspect whether it was blocked:

canary query -j JOBID status
canary query -c dependencies

A blocked job often means an upstream dependency completed but did not satisfy the dependency condition.

Debugging resource problems

If jobs do not run or are masked due to resource capacity, inspect the resource pool and requirements:

canary config show resource_pool
canary query -c resources

Common issues:

• The resource type is not defined in the resource pool.
• A job requests more slots than exist.
• A multi-node job cannot be accommodated.
• Oversubscription or slot counts are configured incorrectly.

Rerun strategies

For rerunning selected jobs, query:

canary query -c commands.run
canary query -c workflows.common_patterns

Common patterns:

canary run TAG --only failed
canary run TAG --only not_pass
canary run TAG --only changed

Common mistakes

• Running from the wrong workspace.
• Assuming the latest visible results are the only persisted state.
• Forgetting that TestResults is a view, not the entire workspace.
• Debugging only logs and ignoring testcase.lock.
• Querying -c all when -c query, -c results, or -c resources is enough.

Related skills

• Use canary-test-authoring to modify tests.
• Use canary-workflows-results for workflow-level result analysis.
• Use canary-extension-development for hook or plugin changes.