Overview

perf-investigation-logger appends structured investigation notes to {state-dir}/perf/investigations/<id>.md, following the canonical contract in docs/perf-requirements.md. It enforces capturing exact user quotes, a phase summary, decisions with rationale, and evidence pointers (files, metrics, commands) to keep investigations reproducible and auditable.

How This Skill Works

When invoked, the skill writes a Markdown block for each investigation phase, including a header with the phase name and date, the exact user quote (verbatim), a summary, evidence pointers, and a decision section. It uses AI_STATE_DIR as the base path for state storage (default .claude) and outputs to {AI_STATE_DIR}/perf/investigations/<id>.md, conforming to the required format shown in the SKILL.md.

When to Use It

• You need to log a new investigation phase with an exact user quote and a structured evidence trail.
• You’re documenting a perf regression or incident for audit and future reference.
• You want to preserve precise evidence pointers (commands, files) alongside a concise phase summary.
• You’re collaborating with teammates and require a consistent, machine-readable investigation note format.
• You must follow the perf-investigation contract in docs/perf-requirements.md when recording notes.

Quick Start

1. Step 1: Confirm or set the state directory (AI_STATE_DIR; default .claude).
2. Step 2: Start a new phase by providing a Phase Name and the exact user quote to log verbatim.
3. Step 3: Provide a Summary, Evidence pointers (commands/files), and a Decision; the tool will format output to the Markdown template.

Best Practices

• Always capture the user quote verbatim; do not paraphrase.
• Use a clear Phase Name and a date in the header for easy identification.
• Include at least one Evidence pointer (command and/or file) per phase.
• Keep the Summary concise and actionable; avoid extraneous details.
• Validate the output against the canonical format in docs/perf-requirements.md and store under AI_STATE_DIR.

Example Use Cases

• Example 1: CPU spike investigation — Phase Name: CPU- spike - 2026-03-08; User Quote: "CPU spike to 95% during peak load"; Evidence includes Command: `perf stat -d` and File: `logs/perf_cpu.log:112`; Decision: CPU bound by scheduler overhead during peak traffic.
• Example 2: Memory growth over time — Phase Name: MemGrowth-Session - 2026-03-08; User Quote: "Memory increases by 200MB over 15 minutes"; Evidence: Command: `smem -t` and File: `memory_profiler.log:45`; Decision: Investigate memory leaks in persistent workers.
• Example 3: Disk I/O latency spike — Phase Name: DiskIO-Latency - 2026-03-08; User Quote: "Disk latency > 100ms during writes"; Evidence: Command: `iostat -x 1` and File: `io_latency.log:22`; Decision: Check backend storage queue depth.
• Example 4: JVM GC pauses — Phase Name: GC-Pause - 2026-03-08; User Quote: "GC pause of 2.3s during request burst"; Evidence: Command: `jstat -gc` and File: `gc.log:18`; Decision: Optimize GC tuning or reduce allocation pressure.
• Example 5: Cross-service latency — Phase Name: Service-Latency - 2026-03-08; User Quote: "Service A to B latency exceeds 80ms"; Evidence: Command: `trace` and File: `network_trace.log:150`; Decision: Inspect service traces and network path.

Frequently Asked Questions