analyst

The analyst is your institutional memory keeper. It tracks what every session costs, extracts patterns from recurring issues, and maintains a growing body of lessons learned. Over time, it identifies cost optimizations and proposes improvements to project configuration — always as recommendations, never applied automatically.

Cognitive Framing

"Track everything, learn from everything, auto-apply nothing."

The analyst operates at Phase 0 (session start — loads context) and Phase 6 (Reflect — records data). It is the terminal agent in the pipeline — after it completes, no further routing occurs. Its most important rule is that it proposes changes but never applies them automatically.

Key Facts

Type	Core
Phase	0 (Orient), 6 (Reflect)
Auto-activates	Session start and session end
Owns	.claude/memory/ (cost-log.json, patterns.json, lessons.md)
Never does	Write code, auto-apply configuration changes

When to Use

• At session start — the analyst loads prior context from memory files automatically.
• At session end — the analyst records session cost data, extracts patterns, and updates lessons learned.
• When you want a cost report via /mk:budget — shows spending by task, agent, model tier, and time period.
• When you want to understand recurring patterns across sessions.

Key Capabilities

• Token usage tracking — records task name, model used, tokens consumed, estimated cost, and timestamp in .claude/memory/cost-log.json for every session.
• Cost reporting — generates cost reports via /mk:budget showing spend breakdowns by task, agent, model tier, and time period.
• Pattern extraction — identifies recurring issues, common solutions, and frequently needed refactors from session data and records them in .claude/memory/patterns.json.
• Lessons learned — maintains actionable lessons in .claude/memory/lessons.md documenting what worked, what did not, and what to do differently.
• Configuration recommendations — proposes CLAUDE.md updates every 10 sessions based on accumulated patterns. These are always proposals for human review, never auto-applied.
• Cost optimization — identifies tasks consistently over-classified to expensive model tiers and recommends routing adjustments.

Behavioral Checklist

• [x] Records token usage and cost data for every session
• [x] Generates cost reports on /mk:budget request
• [x] Extracts patterns from recurring issues across sessions
• [x] Maintains lessons learned with actionable takeaways
• [x] Proposes CLAUDE.md updates every 10 sessions — never auto-applies
• [x] Identifies cost optimization opportunities
• [x] Confirms pipeline complete as the terminal agent
• [x] Never writes production code or test code

Common Use Cases

Scenario	What the analyst does
End of session	Records cost data, extracts patterns, updates lessons learned
/mk:budget request	Generates cost report showing spend by task, agent, model tier, and time period
Recurring test failures	Identifies the pattern across sessions and documents it for future reference
Over-classified tasks	Detects that "simple config changes" are consistently routed as Complex and recommends adjustment
Every 10th session	Proposes CLAUDE.md updates based on accumulated patterns for human review

Pro Tips

Use Budget Reports to Catch Classification Drift

If your cost reports show that a large percentage of tasks are classified as Complex (and using the most expensive models), it may indicate that the orchestrator's classification rules need adjustment. The analyst's cost optimization recommendations help identify where routing changes can reduce costs without sacrificing quality.

Review Lessons Learned Periodically

The lessons in .claude/memory/lessons.md accumulate over time and become increasingly valuable. Periodically reviewing them helps identify systemic issues — patterns that a single session might miss but that become obvious when viewed across many sessions.

Key Takeaway

The analyst builds institutional memory that makes every future session smarter. By tracking costs, extracting patterns, and maintaining lessons learned, it ensures that mistakes are not repeated and optimizations compound over time — all without ever making changes automatically.

Related Agents

• documenter — hands off to the analyst as the final step in the Phase 6 reflect sequence
• orchestrator — receives cost anomaly reports and routing adjustment recommendations
• journal-writer — journal entries feed into the analyst's pattern extraction