feat(skills): Add session-replay skill for trace analysis

[rysweet]

Summary

• Adds new session-replay skill for analyzing claude-trace JSONL files
• Provides session health reports (token usage, latency, errors)
• Detects error patterns across multiple sessions
• Analyzes tool usage distribution

Part of Issue #1611 (Enhancement 1)

Files Added

• .claude/skills/session-replay/SKILL.md - Main skill definition
• .claude/skills/session-replay/README.md - Documentation

How to Use

Triggers: 'analyze session', 'session health', 'trace analysis', 'debug session'

🤖 Generated with Claude Code

[rysweet]

Code Review for session-replay Skill

Reviewer: Claude Code Reviewer Agent
Files Reviewed: .claude/skills/session-replay/SKILL.md, .claude/skills/session-replay/README.md

---

User Requirement Compliance

Status: COMPLIANT - The skill addresses the stated goal of analyzing claude-trace JSONL files for session insights.

---

Philosophy Compliance

Principle	Score	Notes
Ruthless Simplicity	8/10	Good - direct file parsing approach, no unnecessary abstractions
Zero-BS Implementation	9/10	All documented functions are working code snippets, no stubs
Brick Philosophy	9/10	Self-contained module with clear inputs/outputs
Modular Design	8/10	Well-defined boundaries, clear relationship to other tools

Overall Philosophy Score: 34/40 (85%)

---

Strengths

1. Clear Differentiation: Excellent documentation distinguishing this skill from /transcripts and CodexTranscriptsBuilder - each has a distinct purpose
2. Actionable Output Formats: Well-designed report formats with health scores, specific metrics, and recommendations
3. Practical Code Examples: Working Python snippets for parsing JSONL and extracting metrics
4. Philosophy Alignment Section: Explicitly documents how the skill embodies amplihack principles

---

Issues Found

MINOR: Frontmatter Missing Required Fields

Location: SKILL.md:1-14
Impact: Low
Violates User Requirement: No

The frontmatter uses triggers instead of auto_activates and is missing priority_score per FRONTMATTER_STANDARDS.md:

Current:

triggers:
  - "analyze session"

Should be:

auto_activates:
  - "analyze session"
priority_score: 38.0  # estimated based on frequency/impact

MINOR: Trace File Format Documentation Partially Inaccurate

Location: SKILL.md:86-107
Impact: Low
Violates User Requirement: No

The documented trace format shows a simplified structure. Actual traces have:

• request.timestamp inside request object (not top-level)
• Additional fields like headers, metadata
• Token counting API calls (/v1/messages/count_tokens) alongside message calls

The code examples correctly handle this, but the documentation example could be more accurate.

MINOR: README Relative Path May Break

Location: README.md:93-96
Impact: Low

- [.claude-trace/](../../..) - Trace file location

This relative path goes 3 levels up, which may not resolve correctly in all contexts. Consider documenting the absolute path: .claude-trace/ at project root.

---

Recommendations

1. Update frontmatter to use auto_activates and add priority_score for consistency with other skills
2. Add maturity field: maturity: production to indicate skill readiness
3. Consider adding dependencies section:

dependencies:
  tools:
    - Read
    - Glob
  external: []

4. Add evaluation_criteria for transparency on priority scoring

---

Comparison to Existing Skills

Compared against test-gap-analyzer/SKILL.md:

• Missing: priority_score, auto_activates (uses triggers)
• Present in both: name, version, description
• Documentation quality: Comparable - both have thorough action descriptions

---

Verdict

[x] Approved with Minor Suggestions - Ready to merge

The skill is well-designed, follows philosophy principles, and provides genuine value for session debugging and optimization. The issues identified are minor frontmatter standardization items that don't affect functionality.

The skill correctly:

• Parses actual trace file formats (verified against real .claude-trace/*.jsonl files)
• Provides actionable metrics and recommendations
• Maintains clear boundaries with related tools

---

Review by Claude Code Reviewer Agent

[rysweet]

Follow-up: Review Feedback Implemented

The minor frontmatter issues identified in the review have been addressed in commit f9e5c74:

Changes Made:

• Changed triggers to auto_activates for consistency with FRONTMATTER_STANDARDS.md
• Added priority_score: 38.0 with full evaluation_criteria breakdown
• Added dependencies section (Read, Glob tools)
• Added maturity: production indicator
• Fixed broken relative paths in README.md

CI Status: All checks passing

This PR is now ready for final review and merge.

---

Claude Code Reviewer Agent

[rysweet]

Quality Improvement Update

Previous Score: 8.5/10
New Score: 9/10

Improvements Made

1. Enhanced Philosophy Alignment - Expanded each principle (Ruthless Simplicity, Zero-BS, Brick Philosophy) with concrete examples showing how the skill adheres to them

2. Added Limitations Section - Documents what the skill CANNOT do:

   • Read-only (no trace modification)
   • Local only (no remote traces)
   • JSONL format only
   • Post-session analysis (not real-time)

3. Added Error Handling Section - Working code for:

   • Malformed JSONL handling
   • Missing files
   • Permission errors
   • Encoding issues
   • Error table with scenarios, causes, and handling approaches

4. Added Tool Selection Matrix - Clear table showing when to use session-replay vs /transcripts vs CodexTranscriptsBuilder vs context_management

5. Added Trigger Phrases - Explicit activation triggers for each tool to help Claude auto-discover the right skill

6. Added Combined Workflows - Three practical workflows:

   • Diagnose and Fix Token Issues
   • Post-Incident Analysis
   • Performance Baseline

7. Added Troubleshooting Section - Common issues and fixes:

   • No trace files found
   • Incomplete metrics
   • Health score explanation (with weights)
   • Large trace file handling

8. Updated README.md - Consistent with SKILL.md improvements including Related Tools matrix and Limitations

Why These Improvements Matter

The original skill was functional but lacked:

• Clear boundaries (what it won't do)
• Error handling guidance
• Integration clarity with existing tools
• Troubleshooting for common problems

These additions make the skill more production-ready and user-friendly without adding unnecessary complexity.

🤖 Generated with Claude Code