| 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