observatory

name	observatory
description	Analyze a workflow session and produce an insight report. Run after /phase, /epic, or any significant workflow. Usage - /observatory [session-id|latest]
user_invocable	true

Workflow Observatory — Session Analyzer

You are a workflow analyst. Your job is to read raw session stats and event logs, then produce a clear, actionable insight document for the developer.

Step 1 — Locate the Stats File

If the user provided a session ID, look for:

tasks/insights/*-{session-id-prefix}.stats.json

Otherwise, read the latest:

tasks/insights/latest.stats.json

Use the Read tool to load the stats JSON.

Step 2 — Load Raw Event Log (if deeper analysis needed)

The stats JSON contains session_id. Use it to find the raw log:

.claude/logs/{session_id}.jsonl

Read this file to understand the sequence of events — what tools were called, in what order, where errors occurred.

Step 3 — Analyze and Produce Report

Write a markdown report to tasks/insights/{date}-report.md with this structure:

# Workflow Insight Report — {date}

**Session**: `{session_id}`
**Duration**: {start} → {end} ({elapsed})
**Total Tool Calls**: {N} | **Errors**: {N} ({rate}%)

## Summary
<!-- 2-3 sentence overview of what this session accomplished -->

## What Went Well
<!-- Bullet points with evidence from the data -->
- Example: "Zero build failures across N Maven builds"
- Example: "Agent token efficiency: average {N}k tokens per subagent"

## What Could Be Better
<!-- Bullet points with specific, actionable suggestions -->
- Example: "3 Bash failures were retry-related — consider adding retry logic to hook X"
- Example: "Agent Y consumed 85k tokens — brief was likely too large"

## What Didn't Work
<!-- Only include if there were actual failures -->
- Example: "Build failed 2x due to missing dependency — required manual intervention"

## Stats

### Tool Usage
| Tool | Calls | Errors |
|------|-------|--------|
<!-- From tool_counts and error_details -->

### Subagent Performance
| Agent Type | Spawns | Avg Tokens |
|------------|--------|------------|
<!-- From agent_spawns and agent_token_usage -->

### Build Results
<!-- From build_stats — Maven/pnpm pass/fail -->

### Files Modified
<!-- Count + list from files_modified -->

## Raw Data
- Stats: `tasks/insights/{file}.stats.json`
- Event log: `.claude/logs/{session_id}.jsonl`

Guidelines

• Be specific — cite actual numbers, tool names, error messages
• Be actionable — every "could be better" item should suggest a fix
• Be honest — if the session was clean, say so briefly; don't manufacture problems
• Compare to baselines — if previous reports exist in tasks/insights/, note trends
• Keep it concise — aim for 40-80 lines, not a novel