# Analyzer Output Reference

Each analyzer produces a JSON file with top-level summary stats and a `per_session` array of per-session details.

Run with: `cd analysis-14022026 && python -m analyzers.runner --email <email> --since YYYY-MM-DD --until YYYY-MM-DD`

---

## A-Series: Heuristic Analyzers

### `a01_interruptions.json` — User Interruptions

When users stop/reject/redirect the AI mid-action.

| Field | Type | Description |
|-------|------|-------------|
| `total_interrupts` | int | Total interrupt events across all sessions |
| `sessions_with_interrupts` | int | Sessions that had at least one interrupt |
| **per_session** | | |
| `interrupt_count` | int | Number of interrupts in this session |
| `first_interrupt_position_pct` | float | Where the first interrupt occurred (0-100%) |
| `interrupt_position_bucket` | str | `mostly_early`, `mostly_late`, or `spread` |
| `session_recovered` | bool | Whether AI continued productively after interrupts |
| `interrupts[]` | array | Each interrupt: `tool_name`, `tool_category`, `position_pct`, `guidance_source` (inline/rejected/stop), `guidance_text` |

---

### `a02_autonomy.json` — AI Autonomy Level

How independently the AI works between user messages.

| Field | Type | Description |
|-------|------|-------------|
| `global_max_streak` | int | Longest tool streak across all sessions |
| `sessions_with_tools` | int | Sessions where AI used at least one tool |
| **per_session** | | |
| `tool_calls_per_user_msg` | float | Ratio of tool calls to user messages |
| `max_tool_streak` | int | Longest consecutive tool calls without user input |
| `avg_tool_streak` | float | Average streak length |
| `autonomous_segments` | int | Number of uninterrupted tool streaks |
| `user_intervention_rate` | float | How often users intervene (0-1) |

---

### `a03_prompt_signals.json` — User Prompt Characteristics

What users include in their prompts (errors, URLs, code, etc).

| Field | Type | Description |
|-------|------|-------------|
| `sessions_with_error_paste` | int | Sessions where user pasted error output |
| `sessions_with_url` | int | Sessions with URLs in prompts |
| `sessions_with_terse` | int | Sessions with very short prompts (≤20 chars) |
| **per_session** | | |
| `has_error_paste` | bool | User pasted error/traceback |
| `has_log_paste` | bool | User pasted log output |
| `has_url` | bool | User included a URL |
| `has_structured_data` | bool | User included JSON/YAML/XML |
| `has_code_paste` | bool | User pasted code |
| `has_terminal_output` | bool | User pasted terminal output |
| `prompt_is_terse` | bool | First prompt ≤20 chars |
| `first_prompt_char_len` | int | Character length of first real prompt (warmup/init excluded) |

---

### `a04_session_outcomes.json` — What Got Done

Concrete outputs: edits, commits, tests, pushes.

| Field | Type | Description |
|-------|------|-------------|
| `sessions_with_edits` | int | Sessions with file edits |
| `sessions_with_commits` | int | Sessions with git commits |
| `sessions_with_tests` | int | Sessions where tests were run |
| **per_session** | | |
| `has_edits` | bool | Files were edited |
| `edit_count` | int | Number of edit tool calls |
| `files_edited` | list[str] | File paths that were edited |
| `has_git_commit` | bool | A git commit was made |
| `has_git_push` | bool | Code was pushed |
| `has_test_run` | bool | Tests were executed |
| `has_test_pass_after_fail` | bool | Tests went from failing to passing |
| `session_ended_with_user_msg` | bool | User had the last word |
| `git_operations` | list[str] | Git commands used (commit, push, checkout, etc) |

---

### `a05_undo_revert.json` — Undo & Revert Signals

When users ask to undo, or AI self-corrects.

| Field | Type | Description |
|-------|------|-------------|
| `sessions_with_undo` | int | Sessions with user undo requests |
| `sessions_with_git_revert` | int | Sessions with git revert/reset/checkout |
| `sessions_with_ai_correction` | int | Sessions where AI self-corrected |
| **per_session** | | |
| `user_requested_undo` | bool | User explicitly asked to undo |
| `undo_request_count` | int | Number of undo requests |
| `git_revert_in_session` | bool | Git revert/reset was run |
| `ai_self_corrected` | bool | AI acknowledged and fixed its own mistake |
| `ai_self_correction_count` | int | Number of self-corrections |

---

### `a06_ai_clarification.json` — AI Asking Clarifying Questions

When the AI asks "should I...", "would you like...", etc.

| Field | Type | Description |
|-------|------|-------------|
| `total_clarifications` | int | Total clarification questions across all sessions |
| `sessions_with_clarification` | int | Sessions with at least one |
| **per_session** | | |
| `ai_asked_clarification` | bool | AI asked a clarifying question |
| `clarification_count` | int | How many times |
| `clarification_position` | float\|null | Position of first clarification (0-100%) |

---

### `a07_conversation_dynamics.json` — Conversation Shape

Turn structure, timing, message ratios.

| Field | Type | Description |
|-------|------|-------------|
| **per_session** | | |
| `total_turns` | int | Number of user turns |
| `avg_ai_msgs_per_turn` | float | Average AI messages between user messages |
| `deepest_turn` | int | Most AI messages in a single turn |
| `user_to_ai_char_ratio` | float | User chars / AI chars |
| `session_duration_min` | float\|null | Session length in minutes |
| `avg_gap_between_user_msgs_sec` | float\|null | Average time between user messages |
| `longest_gap_sec` | float\|null | Longest gap (potential context switch) |

---

### `a08_session_linkage.json` — Session Relationships

Continuations, sequential chains, parallel sessions.

| Field | Type | Description |
|-------|------|-------------|
| `continuation_sessions` | int | Sessions that are continuations (have compaction) |
| `sequential_sessions` | int | Sessions within 2 hours of previous (same repo) |
| `parallel_sessions` | int | Sessions that overlap in time with another |
| **per_session** | | |
| `is_continuation` | bool | Has compaction message (resumed session) |
| `compaction_count` | int | Number of compaction events |
| `time_gap_to_prev_session_min` | float\|null | Minutes since last session ended (same repo) |
| `is_sequential` | bool | Within 2-hour chain of same repo |
| `has_parallel_sessions` | bool | Overlaps with another session |
| `parallel_same_repo` | bool | Overlaps with another session on same repo |

---

### `a09_tool_profile.json` — Tool Usage Breakdown

Which tool categories the AI uses and how much.

| Field | Type | Description |
|-------|------|-------------|
| **per_session** | | |
| `explore_count` | int | Read, Grep, Glob, etc |
| `edit_count` | int | Edit, Write, MultiEdit, etc |
| `shell_count` | int | Bash, shell_command, etc |
| `plan_count` | int | TodoWrite, TaskCreate, ExitPlanMode, etc |
| `delegation_count` | int | Task/subagent tool |
| `web_count` | int | WebSearch, WebFetch |
| `mcp_count` | int | MCP tool calls |
| `explore_edit_ratio` | float | explore / max(edit, 1) |
| `unique_tools_used` | int | Distinct tool names |
| `dominant_tool_category` | str | Most-used category |

---

### `a10_error_detection.json` — Shell Errors

Errors in tool output, cascades (3+ in a row), user rescues.

| Field | Type | Description |
|-------|------|-------------|
| `total_shell_errors` | int | Total errors detected across all sessions |
| `sessions_with_errors` | int | Sessions with at least one error |
| `sessions_with_cascades` | int | Sessions with 3+ consecutive errors |
| **per_session** | | |
| `shell_error_count` | int | Errors in this session |
| `consecutive_shell_errors` | int | Longest error streak |
| `error_cascade_count` | int | Number of cascade events (3+ in a row) |
| `error_then_user_rescue` | bool | User intervened after an error cascade |

---

## B-Series: LLM-Based Analyzers

Run with `--include-llm`. Requires `OPENAI_API_KEY` in `.prod.env`. Uses gpt-4o-mini with file-based caching.

### `b01_task_classification.json` — Task Type Classification

LLM classifies the session's task from the first user prompt.

| Field | Type | Description |
|-------|------|-------------|
| **per_session** | | |
| `task_type` | str | `bug_fix`, `build_feature`, `refactor`, `understand_code`, `debug`, `test`, `config_infra`, `code_review`, `exploration` |
| `task_complexity` | str | `simple`, `moderate`, `complex` |
| `task_domain` | str | `backend`, `frontend`, `mobile`, `infra`, `data`, `mixed` |

### `b03_prompt_quality.json` — Prompt Quality Assessment

Only for sessions with interrupts or AI clarifications.

| Field | Type | Description |
|-------|------|-------------|
| **per_session** | | |
| `prompt_quality` | str | `clear`, `vague`, `missing_context` |
| `prompt_improvement_suggestion` | str | One-line suggestion |

### `b04_failure_root_cause.json` — Failure Root Cause

Only for sessions with error cascades or undo requests.

| Field | Type | Description |
|-------|------|-------------|
| **per_session** | | |
| `failure_root_cause` | str | `wrong_approach`, `missing_context`, `tool_limitation`, `user_changed_mind`, `ai_hallucination` |
| `failure_summary` | str | One-line explanation |

---

## C-Series: Cross-Session Aggregations

### `c01_developer_profile.json` — Developer Behavioral Profile

Single aggregated profile across all sessions.

| Field | Type | Description |
|-------|------|-------------|
| `session_count` | int | Total sessions |
| `sessions_per_active_day` | float | Sessions / active days |
| `preferred_source` | str | Most-used CLI tool |
| `avg_prompts_per_session` | float | Average user messages per session |
| `avg_first_prompt_length` | float | Average first prompt character length |
| `interrupt_rate` | float | Fraction of sessions with interrupts |
| `undo_rate` | float | Fraction of sessions with undo requests |
| `edit_session_pct` | float | Fraction of sessions with file edits |
| `commit_session_pct` | float | Fraction of sessions with git commits |
| `avg_autonomy_ratio` | float | Average tool calls per user message |
| `exploration_tendency` | float | Average explore/edit ratio |
| `total_cost_usd` | float | Total estimated API cost |

### `c02_team_trends.json` — Weekly Team Trends

Aggregated by ISO week across all users in the date range.

| Field | Type | Description |
|-------|------|-------------|
| **weeks[]** | | |
| `iso_week` | str | e.g. `2026-W07` |
| `sessions_count` | int | Sessions that week |
| `edit_sessions_pct` | float | Fraction with edits |
| `interrupt_rate` | float | Fraction with interrupts |
| `avg_session_cost` | float | Average cost per session |
| `total_cost` | float | Total cost that week |
| `source_distribution` | dict | `{"claude_code": 50, "codex_cli": 10, ...}` |

---

## Combined Output

### `all.json`

All analyzer results combined into a single file, keyed by analyzer name:
```json
{
  "a01_interruptions": { ... },
  "a02_autonomy": { ... },
  ...
}
```
