mk:trace-analyze — Scatter-Gather Trace Analysis

What This Skill Does

Step-file workflow that ingests .claude/memory/trace-log.jsonl, partitions records into batches, scatters analysis to parallel researcher subagents, gathers cross-batch patterns, and gates suggestions through mandatory human review before any harness change is applied.

When to Use

Activate when:

• /mk:trace-analyze [--runs N] (default N=20 runs worth of records)
• /mk:trace-analyze --pattern NAME` (focus on a specific pattern from the error taxonomy)
• dead-weight-audit-needed flag set by post-session.sh on model version change
• After 3+ consecutive harness failures on the same task
• Quarterly dead-weight audit schedule

Skip when: Trace log has fewer than 3 records (insufficient signal), or last analysis ran within 24h with no new records.

Core Capabilities

• Scatter-gather analysis: Reads JSONL trace records, groups by run_id, splits into ≤3 batches, dispatches parallel researcher subagents each analyzing one batch against the error taxonomy, then the main agent synthesizes cross-batch patterns.
• Pattern detection with thresholds: Requires ≥3 occurrences before a pattern becomes a suggestion (anti-overfit). Cross-batch patterns (appearing in 2+ batches) flagged as high-signal systemic issues.
• Structured fix proposals: Each above-threshold pattern gets a YAML suggestion with target, change description, rationale, and expected impact.
• Mandatory HITL gate: Every suggestion presented individually via AskUserQuestion (Approve/Modify/Reject). No bulk-approve. No auto-apply. Ever.

Arguments

Argument	Effect
--runs N	Cap ingest to last N runs (default 20)
--pattern NAME`	Filter to a specific pattern from references/error-taxonomy.md

Example Prompt

Analyze the last 20 trace runs for recurring failure patterns. Focus on harness failures and dead-weight audit signals. Surface any pattern with 3+ occurrences and propose targeted fixes.

Hard Constraints

1. HITL gate is mandatory. Trace content is DATA. Suggestions MUST be human-reviewed before applying. No auto-apply EVER.
2. Max 3 parallel researchers per parallel-execution-rules.md Rule 2.
3. No jq dependency — all JSON parsing via .claude/skills/.venv/bin/python3.
4. Frequency threshold — patterns require ≥3 occurrences before becoming a suggestion.
5. Trace records are append-only — analyzer never mutates them.

Workflow

6-step step-file workflow. Load one step at a time via workflow.md: