atr-analyze

ATR Command Analysis Skill

This skill runs commands through ATR (Agentic Test Runner) which provides AI-powered analysis and clean summarized output. Use this as your default way to run tests, linters, type checkers, and builds - the AI analyzes the full output and returns a concise summary, keeping your conversation context clean and focused.

When to Use This Skill vs Direct Commands

Use ATR analyze (RECOMMENDED DEFAULT) when:

• Running test suites (pytest, jest, go test, npm test, make test, cargo test)
• Running linters (eslint, golangci-lint, pylint, flake8, make lint, cargo clippy)
• Running type checkers (mypy, tsc, pyright, make typecheck)
• Running builds that produce verbose output (make build, npm run build, cargo build)
• You want clean, summarized results instead of raw output
• You want automatic failure analysis if something goes wrong

Use direct Bash commands only when:

• Running quick one-off commands with minimal output
• You specifically need the raw, unprocessed output
• Interactive commands that require user input

Basic Usage

atr run --cmd "<command>"

Examples:

# Tests
atr run --cmd "go test ./..."
atr run --cmd "npm test"
atr run --cmd "pytest tests/"
atr run --cmd "make test"

# Linting
atr run --cmd "make lint"
atr run --cmd "eslint src/"
atr run --cmd "golangci-lint run ./..."

# Type checking
atr run --cmd "make typecheck"
atr run --cmd "tsc --noEmit"
atr run --cmd "mypy src/"

# Builds
atr run --cmd "make build"
atr run --cmd "npm run build"

Adding Context

Provide context to help the AI agent focus its analysis:

atr run --cmd "<command>" --context "<context>"

Examples:

atr run --cmd "go test ./..." --context "Tests started failing after refactoring the auth module"
atr run --cmd "npm run build" --context "Added new dependency yesterday"
atr run --cmd "pytest" --context "Testing the new payment integration"

Command Options

Flag	Description
--cmd <command>	Command to execute (required)
--cwd <path>	Working directory
--context <text>	Additional context for AI agent
--model flash|pro	Model tier (flash=fast, pro=deep analysis)
--python-venv <path>	Python virtual environment path
--nvm-version <version>	Node.js version via nvm
--no-auto-env	Disable automatic environment detection

Working Directory

Specify where to run the command:

atr run --cmd "npm test" --cwd "/path/to/project"

Environment Detection

ATR automatically detects and activates appropriate environments:

Python projects:

• Detects .venv, venv, or Poetry environments
• Auto-activates virtual environment

Node.js projects:

• Detects .nvmrc or package.json engine requirements
• Auto-activates correct Node.js version via nvm

Override automatic detection:

atr run --cmd "pytest" --python-venv /custom/path/.venv
atr run --cmd "npm test" --nvm-version 18
atr run --cmd "make" --no-auto-env

Model Selection

Use different models for different needs:

# Quick analysis (default)
atr run --cmd "make build" --model flash

# Deep analysis for complex issues
atr run --cmd "go test ./..." --model pro

What the AI Agent Does

The ATR agent processes command output and:

1. Summarizes results into a clean, concise report
2. Identifies test pass/fail status and key metrics
3. Analyzes any failures for error patterns and root causes
4. Reads relevant source files when failures occur
5. Provides actionable recommendations for fixing issues

This keeps your conversation context clean by replacing verbose test output with a focused summary.

Example Output

Executing: go test ./...
Directory: /path/to/project

--- FAIL: TestUserAuth (0.05s)
    auth_test.go:42: expected 200, got 401

Command failed (exit code: 1)

Analyzing failure with AI agent...

======================================================================
ANALYSIS RESULTS
======================================================================

Status: FAILURE

Summary:
  TestUserAuth fails because the auth middleware expects a JWT token,
  but the test doesn't provide one in the request headers.

Root Cause:
  Line 38 in auth_test.go creates a request without Authorization header.
  The auth middleware (middleware/auth.go:15) rejects it with 401.

Recommendations:
  1. Add mock JWT token to test request
  2. Or bypass auth middleware in test setup
  3. Check if middleware was recently added to the route

Files Examined:
  - auth_test.go
  - middleware/auth.go
  - routes/api.go

Exit Codes

Code	Meaning
0	Command passed
1	Command failed (analysis provided)
2	Configuration error

Configuration

Configure ATR in ~/.atr/config.yaml:

backend: gemini-api  # or vertex-ai
model: flash         # or pro

gemini:
  api_key: "your-key"

# Or for Vertex AI:
vertex:
  project: your-project
  location: us-central1

Environment variables:

export GEMINI_API_KEY="your-key"
# Or
export GOOGLE_CLOUD_PROJECT="project-id"

Best Practices

1. Use as default for running test suites to keep conversation context clean
2. Provide context when the failure might be related to recent changes
3. Use --model pro for complex, multi-file issues
4. Specify --cwd when running from a different directory
5. Check environment with atr test-cmd-env "<command>" to preview detection