# Log Triage

> CI/build/runtime error log analysis with root-cause detection, prioritized fix plans, and verification checklists

- Skill: `xspoonai/log-triage` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add xspoonai/log-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xspoonai/log-triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: XSpoonAi (https://skillmd.com/u/xspoonai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xspoonai/log-triage

---


# Skill: Log Triage & Fix Plan (Enterprise Debugging)

**Source:** ETHPanda  
**Track:** Enterprise & Team Skills → Debugging  
**Goal:** Turn raw error logs into (1) root-cause hypotheses, (2) reproducible steps, (3) prioritized fix plan, (4) verification checklist.

## When to use

Use this skill when you have:
- CI failure logs (GitHub Actions, GitLab CI, Jenkins, etc.)
- Runtime crashes, stack traces, uncaught exceptions
- Build failures (TypeScript, Python, Rust, Go, Java, Solidity/Hardhat)
- Dependency / environment / permission / network issues

## Required inputs (ask user to provide)

1. The error log (full text preferred)
2. What command was running (e.g. `pnpm test`, `hardhat test`, `pytest`, `cargo test`)
3. Environment (OS, Node/Python/Rust versions, CI provider if any)
4. Recent changes (commit, dependency bumps, config edits) if known

## Output format (must follow)

1. **1-paragraph summary** of what failed and where
2. **Error signature(s)** (key lines you matched)
3. **Root-cause candidates** (ranked, with confidence and reasoning)
4. **Fix plan** (ranked, each step includes exact commands or code areas to check)
5. **Verification checklist** (how to confirm the fix)
6. **If blocked:** minimal questions to unblock (max 3)

## Triage procedure

1. Extract the *first* fatal error (often earlier than the last line)
2. Classify into categories:
   - Syntax/type errors
   - Missing dependency / wrong version
   - Build toolchain mismatch
   - Env var / secret missing
   - Permission / path / file system
   - Network / rate limit / RPC issues
   - Test flakiness / timing
3. Match known patterns (e.g. "Cannot find module", "TypeError", "revert", "out of gas", "403/429", etc.)
4. Propose minimal reproduction locally
5. Provide safest fix first (pin version / clean install / config correction) before invasive refactors

## Constraints

- Don't hallucinate files that don't exist; when unsure, say "check whether X exists".
- Prefer reversible changes (lockfile pin, config tweak) over broad refactors.
- Always include a verification step (rerun exact command / CI workflow).

## Available Scripts

### log_triage.py

Analyzes error logs using pattern matching and generates a structured Markdown report.

**Usage:**
```bash
python scripts/log_triage.py --file <log_file> --format md
```

**Input:**
- `--file`: Path to log file
- `--format`: Output format (md or txt)

**Output:**
- Matched error signatures
- Prioritized fix plan
- Verification checklist

## Supported Error Patterns

| Category | Pattern | Fix Strategy |
|----------|---------|--------------|
| Node Missing Module | `Cannot find module 'X'` | Clean install, check lockfile |
| TypeScript Errors | `TS\d+:` | Fix types, check TS version |
| Python Module Not Found | `ModuleNotFoundError: No module named 'X'` | Check requirements, reinstall venv |
| Hardhat Errors | `HardhatError\|HH\d+:` | Check compiler version, clear cache |
| Revert Reasons | `reverted with reason string 'X'` | Trace contract logic, check inputs |
| Rate Limits | `429\|rate limit` | Add retries, reduce concurrency |

## Example Usage

### Scenario 1: CI Build Failed

**User Query:**
```
"My GitHub Actions workflow failed with this log: [paste log]"
```

**Agent Response:**
```markdown
## Log Triage Report

### Summary
Node.js build failed due to missing module 'viem'. The dependency exists in 
package.json but wasn't installed in CI environment.

### Matched Error Signatures
1. **node_missing_module**: `Cannot find module 'viem'`

### Fix Plan (Prioritized)
1. Run clean install: `rm -rf node_modules && pnpm install`
2. Check lockfile changes and Node version consistency (CI vs local)
3. If monorepo, ensure package is listed in the right package.json

### Verification Checklist
- [ ] Re-run the exact failing command locally
- [ ] Re-run CI workflow and confirm green
- [ ] Add a regression test if applicable
```

### Scenario 2: Hardhat Test Failure

**User Query:**
```
"My hardhat test is failing with HH600 error"
```

**Agent Response:**
```markdown
## Log Triage Report

### Summary
Hardhat compilation failed due to compiler version mismatch between 
hardhat.config and contract pragma.

### Matched Error Signatures
1. **hardhat_compile**: `HH600: Compilation failed`

### Fix Plan (Prioritized)
1. Run `pnpm hardhat compile --show-stack-traces` locally
2. Check Solidity compiler version in hardhat config matches pragma
3. If error about artifacts/cache: remove `artifacts/ cache/` and recompile

### Verification Checklist
- [ ] Contracts compile successfully
- [ ] Tests pass locally
- [ ] CI passes
```

## Best Practices

1. **Extract First Error**: Often the first error causes cascading failures
2. **Minimal Reproduction**: Simplify to smallest failing case
3. **Reversible Fixes**: Try safe fixes (clean install, version pin) before refactoring
4. **Verify Thoroughly**: Re-run exact command + CI workflow
5. **Document Root Cause**: Add regression test or config comment

## Integration with SpoonReactSkill

```python
from spoon_ai.agents import SpoonReactSkill

agent = SpoonReactSkill(
    name="debug_assistant",
    skill_paths=["./enterprise-skills/debugging/log-triage"],
    scripts_enabled=True
)

await agent.activate_skill("log-triage")

result = await agent.run(
    "My CI failed with this error: [paste log]. What's wrong and how do I fix it?"
)
print(result)
```

## Context Variables

- `{{log_file}}`: Path to log file
- `{{command}}`: Command that failed
- `{{environment}}`: Environment details
- `{{recent_changes}}`: Recent commits or dependency changes