backtrack-analysis

Backtrack Analysis

Deep-dive into backtracking patterns from a distilled clens session. This command focuses entirely on wasted effort: failure retries, iteration struggles, and debugging loops.

Variables

TARGET: $ARGUMENTS

Instructions

1. Resolve the Session

• If TARGET is empty or --last, find the most recent distilled session:
  • List files in .clens/distilled/ sorted by modification time
  • Use the most recently modified .json file
• If TARGET is a session ID (full UUID or prefix), find .clens/distilled/{TARGET}*.json
• If no distilled file is found, tell the user:

  No distilled session found. Run clens distill --last to distill your most recent session, then re-run this command.

2. Read the Data

• Read the distilled JSON file at .clens/distilled/{sessionId}.json
• Parse the full DistilledSession object
• Focus on: backtracks, file_map, decisions, reasoning, timeline, stats
• Load the session-analysis skill for schema and interpretation context

3. Generate the Analysis

Use the following template. If there are zero backtracks, generate a short clean-execution report instead.

---

If Zero Backtracks

Backtrack Analysis: {session_id first 8 chars}

No backtracks detected. This session had a clean execution with no detected failure retries, iteration struggles, or debugging loops.

Session stats for context:

• Duration: {summary.key_metrics.duration_human}
• Tool calls: {stats.tool_call_count}
• Failure rate: {stats.failure_rate as %}%
• Files modified: {summary.key_metrics.files_modified}

{If stats.failure_count > 0 but no backtracks: "Note: {failure_count} tool failures occurred but none triggered backtracking patterns. The agent recovered without retrying."}

---

If Backtracks Exist

Backtrack Analysis: {session_id first 8 chars}

Summary

Metric	Value
Total backtracks	{backtracks.length}
failure_retry	{count of type failure_retry}
iteration_struggle	{count of type iteration_struggle}
debugging_loop	{count of type debugging_loop}
Total wasted attempts	{sum of all backtracks' attempts}
Time spent backtracking	{sum of (end_t - start_t) for all backtracks, formatted as human duration}
% of session in backtracks	{backtrack_time / stats.duration_ms * 100}%
Unique files affected	{count of unique file_path values across backtracks}