Command Failure Diagnoser

Analyzes failed terminal executions, compilation errors, and nonzero exit codes. Separates root cause from cascading error noise and prescribes exact corrective commands.

1. Purpose

Turn cryptic terminal stack traces into an immediate root cause and fix. An "Exit Code" indicates process termination status (0 = success, 1+ = error, 127 = command not found, 137 = out of memory).

2. When to Use

Use this skill when:

• A build, install, test, or deployment command fails in terminal.
• CI/CD job fails with exit code != 0.
• User asks: "Why did npm run build fail?" or pastes terminal stderr.

3. When Not to Use

• Do not use to isolate logic bugs in application code; use bug-reproducer.
• Do not use to clean up disk space; use reversible-cleanup-planner.

4. Required Inputs

• failed_command: The command string executed.
• exit_code: Numeric exit code (e.g. 1, 127, 137).
• log_output: Terminal stdout and stderr text.

5. Missing-Input Behavior

1. If exit_code is missing: infer from logs if visible (e.g. exited with code 127).
2. If log_output is truncated: ask for the first 20 lines of the error stack trace.
3. Never recommend destructive commands like rm -rf / or disabling security checks as a "fix".

6. Procedure

Follow these numbered actions:

1. Action 1: Classify Failure Mechanism
   • Missing Tool / Command: Exit 127 (command not found).
   • Permissions: Exit 126 or EACCES / Permission denied.
   • Resource Exhaustion: Exit 137 (SIGKILL / Out of memory).
   • Compilation / Syntax: Compiler error with file and line.
   • Dependency Missing: Cannot find module, No such file or directory.
2. Action 2: Isolate Root Cause Line
   • Find the earliest fatal error in log, ignoring downstream cascades.
3. Action 3: Prescribe Targeted Corrective Command
   • Provide the exact shell command to cure the root cause.
4. Action 4: Emit Diagnosis Report
   • Format per Section 8.

7. Decision Rules

• If exit code is 137: root cause is Out of Memory (OOM Killer). Prescribe increasing RAM or reducing build concurrency (--max-workers=2).
• If permission denied: do not recommend sudo chmod -R 777. Recommend appropriate user-level permissions or chown.

8. Output Format

Emit the diagnosis using this template:

### Command Failure Diagnosis

- **Failed Command**: `[command]`
- **Exit Code**: [Code, e.g. 127]
- **Category**: [Missing Dependency | Syntax Error | OOM | Permissions | Configuration]

#### Root Cause Analysis
[1-2 sentences identifying the exact error line and why it happened.]

#### Offending Log Line
```text
[Exact log excerpt containing the fatal error]

Corrective Action

[Exact command to resolve the issue]

## 9. Verification Checklist
- [ ] Root cause identified from earliest fatal log line.
- [ ] Corrective command is safe and non-destructive.
- [ ] Exit code semantics are accurately interpreted.
- [ ] No generic "reboot your computer" advice.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Diagnosing downstream crash | Focusing on last line of log | Scroll up to find the initial fatal error. |
| Insecure recommendation | Suggesting `chmod 777` | Recommend user ownership change `chown -R $USER`. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- Error indicates hardware failure, disk corruption, or cloud outage.

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Command: npx vitest
Exit code: 127
Log: /bin/sh: line 1: npx: command not found

Output:

### Command Failure Diagnosis

- **Failed Command**: `npx vitest`
- **Exit Code**: 127
- **Category**: Missing Tool / Environment

#### Root Cause Analysis
Exit code 127 indicates that the executable `npx` was not found in the current shell `$PATH`. Node.js/npm is either not installed or not loaded into the active environment.

#### Offending Log Line
```text
/bin/sh: line 1: npx: command not found

Corrective Action

Ensure Node.js is installed and loaded:

source ~/.nvm/nvm.sh && which npx

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Command: make
Exit code: 2
Log: (Empty)

Output:

### Command Failure Diagnosis: Insufficient Error Log

- **Failed Command**: `make`
- **Exit Code**: 2
- **Status**: Halted

Exit code 2 indicates a general Make error, but no terminal log was provided. Please paste the terminal output printed before the command exited.

Example 3: Expected Final Output

Output:

### Command Failure Diagnosis

- **Failed Command**: `npm run build`
- **Exit Code**: 137
- **Category**: Resource Exhaustion (OOM)

#### Root Cause Analysis
Exit code 137 indicates process terminated by Linux kernel OOM (Out Of Memory) Killer (SIGKILL, signal 9 + 128). Node process exceeded container RAM.

#### Offending Log Line
```text
Killed
npm ERR! Lifecycle script `build` failed with error: 137

Corrective Action

Increase Node memory limit:

NODE_OPTIONS="--max-old-space-size=4096" npm run build