CLI Failure Handoff Checklist

# CLI Failure Handoff Checklist

CLI failures are easy to under-report because the person who saw the error has terminal context in their head. The next person usually does not. A handoff checklist turns a failed command into a reproducible debugging packet.

## Required fields
Include the exact command, working directory, environment variables that matter, expected output, actual output, exit code, and whether rerunning changes the result. If the command mutates state, say whether it was dry-run, partial, or safe to retry.

## Capture version context
CLI behavior often changes with runtime versions. Record Node, Python, package manager, OS, and tool version when relevant. Do not assume the next person shares the same shell profile.

## Separate stdout and stderr
Many handoffs paste only the last visible line. That often hides the useful part. If possible, capture stdout and stderr separately or mark where the error began. Long logs should be sliced around the failure rather than pasted whole.

## Retry notes
Write what was already tried: rerun, different account, different flag, network check, permission check. This prevents the next person from repeating low-value checks.

## Example
Command: npm run import -- --dry-run. CWD: app root. Expected: parse 120 files. Actual: exit 1 after file 47, JSON parse error. Tried: rerun same result, file 47 opens locally, network not involved. Unknown: whether parser changed after last dependency update.

A good CLI handoff should let someone reproduce or reject the failure within minutes.

CLI Failure Handoff Checklist

// COMMENTS

ON THIS PAGE