# Investigation Report

> Produce a single self-contained HTML report that explains a command-line investigation — the commands actually run, their real output, and just enough reasoning to teach it. Use when the user asks for a walkthrough, tutorial, write-up, teaching artifact, or "show me how you did that" of a shell debugging or exploration session.

- Skill: `motlin/investigation-report` (Agent Skill)
- Install (CLI): `npx skillmds@latest add motlin/investigation-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/motlin/investigation-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: motlin (https://skillmd.com/u/motlin)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/motlin/investigation-report

---


# Command-Line Investigation Report

When asked to explain or document a command-line investigation, produce a chronological command log as a single HTML page: what you ran, what it printed, and enough reasoning that the reader could rerun it and understand every flag. The goal is teaching, not a status update.

## Structure it as a chronological command log

Walk the investigation in the order it actually happened — including dead ends, wrong hypotheses, and the command that disproved them. Do not sanitize it into a clean after-the-fact story; the wrong turns are where the learning is. Each step is: the command, its real output, one line of why you ran it, and — only where the evidence changed your conclusion — a short "changed my mind" note.

## Show real commands and real output

- Reproduce commands verbatim. Never invent flags, clean them up, or show a command you didn't run.
- Paste the actual output, trimmed to what's relevant.
- When you trim output, mark the cut visibly (e.g. `... ~60 more lines ...`). Silent truncation reads as "this was the whole output" — always show that something was removed.
- Skip output entirely for commands that revealed nothing useful; just note what you ran and why.

## Explain unfamiliar commands and flags

- For any command or flag that isn't obvious, add a breakdown: one row per flag, in plain language.
- Split fused flags apart — e.g. `-nrk3` is `-n -r -k3`.
- Explain a pipeline inside-out, like nested parentheses (command substitution first, then the tools it feeds).
- When a whole tool is likely unfamiliar (e.g. `pgrep`), add a short "what is X" explainer: the basics, the flags used here, and its closest sibling (`pgrep`/`pkill`).
- Pitch explanations at the reader. Let their questions drive which breakdowns to add — skip what they already know, expand what they ask about, and add detail on request rather than up front.

## Keep reasoning short; mark the turning points

- One line of "why I ran this" per command is plenty.
- Reserve emphasis for the moments where evidence changed the conclusion. Those turning points are the spine of the story — make them stand out.
- Cut editorializing, "lessons learned" summaries, and meta-commentary about method unless asked. Prefer "here is what I did" over "here is what you should learn."

## End with a command reference

Close with a compact table mapping question → command → what to read from the output. This is the reusable cheat-sheet the reader keeps after the specific incident fades.

## Styling is not the point

Emit one self-contained HTML file with no external assets, so it opens with a double-click. Keep visual styling minimal and out of the way — the content is the command log, not the design. Don't spend effort on elaborate CSS, and don't ask the user to weigh in on it.

## Deliver and open the file

Write it to a durable location (the project directory, or wherever the user names — not a scratch/temp path they'll lose). Then open it (`open <file>` on macOS) so the user can read it right away.