feat: perf-investigation-logger - Documentation and commit workflow

[avifenesh]

Overview

Specialist agent for maintaining investigation documentation, tracking conversations, and managing checkpoint commits.

Parent Issue

Part of #124 - Master performance profiling orchestrator

Rationale

"every once in a while, commit, on every commit update our session and conversation in workflow session file, its for me for later use"

"log also the conversation, i want to use references to my ideas, what i was insisting on, what i asked etc. for later build improvements from it"

The investigation process itself is valuable knowledge. This agent captures:

• User requests and decisions
• Exact user quotes for future reference
• Hypothesis → evidence → conclusion flow
• What worked and what didn't

Responsibilities

1. Session Logging

## Captures:
- User requests (exact wording)
- User decisions and rationale
- Key insights from user
- What user insisted on
- Methodology corrections from user

2. Conversation Tracking

## For each significant interaction:
- Timestamp
- User quote (exact wording)
- Context (what led to this)
- Action taken
- Result

## Example:
> User: "dont run parallel every" → "one bench at a time, otherwise you create noise"
> Action: Changed to sequential execution
> Result: Consistent benchmark results

3. Commit Integration

## After each phase:
1. Stage relevant files
2. Create commit with findings in message
3. Update workflow log
4. Push checkpoint

## Commit message format:
perf: <phase> - <finding>

- <detail 1>
- <detail 2>
- Baseline: <metric>
- Current: <metric>

4. Investigation Log Structure

# Investigation: <issue>

## Session: <date>

### Phase 1: Setup
**User request:** "<exact quote>"
**Action:** <what was done>
**Finding:** <result>

### Phase 2: Baseline
**User guidance:** "<exact quote>"
...

## Key Decisions
1. <decision> - because "<user reasoning>"
2. <decision> - because "<user reasoning>"

## Lessons Learned
- <lesson from this investigation>

Agent Definition

---
name: perf-investigation-logger
description: Maintains investigation documentation and commit workflow
tools: [Read, Write, Bash]
model: haiku
---

Output Format

{
  "investigation_id": "inv-001",
  "session_date": "2026-01-22",
  "phases_completed": ["setup", "baseline", "theorize"],
  "commits": [
    {
      "sha": "abc123",
      "phase": "baseline",
      "message": "perf: baseline established for batch scenario",
      "findings": ["Breaking point: 7.5k QPS", "2.2.4 shows regression"]
    }
  ],
  "user_insights": [
    {
      "timestamp": "2026-01-22T14:30:00Z",
      "quote": "one bench at a time, otherwise you create noise",
      "context": "User corrected parallel benchmark approach",
      "action_taken": "Changed to sequential execution"
    }
  ],
  "key_decisions": [
    {
      "decision": "Abandon DBB for nested types",
      "user_reasoning": "ok lets close the pr and go to pr 1",
      "evidence": "Profiling showed overhead exceeds benefit"
    }
  ],
  "log_file": ".claude/perf/investigations/inv-001.md"
}

Files to Create

• plugins/perf/agents/perf-investigation-logger.md
• lib/perf/investigation-log.js
• lib/perf/commit-checkpoint.js

Success Criteria

• Records user requests with exact wording
• Tracks key decisions and rationale
• Creates checkpoint commits after each phase
• Includes findings in commit messages
• Maintains investigation log file
• Captures user insights for future reference
• Enables reconstruction of investigation process

[avifenesh]

Implemented in v3.4.0