diagnostics

name	diagnostics
description	Use when troubleshooting build failures, test failures, daemon connectivity issues, or integration errors in Auto-Tundra.
allowed_tools	["Bash","Read"]
references	["/Users/studio/rust-harness/docs/PROJECT_HANDBOOK.md","/Users/studio/rust-harness/AGENTS.md"]

Diagnostics

Trigger

Use this skill when something is broken: build errors, test failures, daemon won't start, API returns errors, or integrations fail.

Diagnostic Ladder (follow in order)

Step 1: Environment check

# All-in-one health check
at doctor -p /Users/studio/rust-harness -j

# Manual checks
rustc --version                    # Must be 1.91+
env | grep -E 'API_KEY|TOKEN'      # Check credentials
curl -sf http://localhost:9090/api/status | jq .  # Daemon alive?

Step 2: Build diagnostics

# Full workspace check (fast, no codegen)
cargo check 2>&1 | head -50

# Single crate
cargo check -p at-<crate> 2>&1 | head -50

# If linker errors on macOS:
xcode-select --install

Step 3: Test diagnostics

# Run with output visible
cargo nextest run -p at-<crate> --no-capture 2>&1 | tail -80

# Run a single test
cargo nextest run -p at-<crate> -E 'test(test_name)' --no-capture

# Run with debug logging
RUST_LOG=debug cargo nextest run -p at-<crate> --no-capture

Step 4: Daemon diagnostics

# Start daemon with debug logging
RUST_LOG=debug cargo run --bin at-daemon 2>&1 | tee /tmp/daemon.log

# Check if ports are in use (API: 9090, UI: 3001)
lsof -i :9090 -i :3001

# Kill stale daemon processes
pkill -f at-daemon
kill -9 $(lsof -t -i:9090 -i:3001) 2>/dev/null || true

Step 5: Integration diagnostics

# GitLab
curl -sf http://localhost:9090/api/gitlab/issues 2>&1 | jq .
# Expected 503 with {"error":"...","env_var":"GITLAB_TOKEN"} if token missing

# Linear
curl -sf http://localhost:9090/api/linear/issues?team_id=X 2>&1 | jq .

# GitHub
curl -sf http://localhost:9090/api/github/issues 2>&1 | jq .

Step 6: Dependency/security diagnostics

# Check for vulnerable dependencies
cargo deny check 2>&1 | head -30

# Check for outdated dependencies
cargo outdated -R 2>&1 | head -30

Common Failure Patterns

Symptom	Likely Cause	Fix
Connection refused :9090	Daemon not running	cargo run --bin at-daemon
503 + env_var in response	Missing credential	Ensure variables like GITLAB_TOKEN are exported in the shell before starting the daemon, or modify ~/.config/auto-tundra/settings.toml.
linking with cc failed	Missing Xcode tools	xcode-select --install
cannot find crate	Missing workspace member	Check Cargo.toml members
Test timeout	Network-dependent test	Check #[ignore] gate or mock
port already in use	Stale process	lsof -i :9090 -i :3001 then kill

Rules

1. Always start at Step 1 and work down — don't jump to Step 5.
2. Capture output with 2>&1 | head -N to avoid flooding context.
3. When reporting errors, include the exact error message and the command that produced it.
4. Never blindly cargo clean — it wastes 5-10 min of rebuild time. Only use if genuinely corrupt.