haiku-breadcrumbs

Haiku Breadcrumbs

Prepare structured memory breadcrumbs so a lighter model (typically Haiku) can continue a review, discussion, or walkthrough in a new session. Captures session context, findings, and open questions into a memory file that the next session loads automatically.

When to Use

• User says they want to continue in another session, especially with a lighter model
• End of a review or analysis session where findings should persist
• User explicitly asks to "leave breadcrumbs" or "prepare handoff"
• After a long session where re-exploration would waste the next session's context

Why This Matters

Lighter models (Haiku, Sonnet) have less capacity to explore a codebase from scratch. Without breadcrumbs, the next session starts cold — re-reading files, re-discovering architecture, re-deriving conclusions already reached. Pre-computed breadcrumbs with file paths, line counts, and status classifications give the next session enough context to be productive immediately.

Workflow

Phase 1 — Check for Existing Audit

Scan the current conversation for a spec-vs-reality audit or similar codebase analysis. Look for:

• GREEN/YELLOW/RED classifications
• File paths with line counts
• Layer-by-layer status tables
• Component-level assessments

If found, incorporate the full findings. This is the most valuable content for breadcrumbs — it represents deep analysis that would be expensive to reproduce.

If no audit exists, assemble context from what was discussed: decisions made, files examined, conclusions reached, questions raised.

Phase 2 — Session Summary

Capture what was discussed and decided:

1. Topics covered — What areas of the codebase or project were examined?
2. Decisions made — Any architectural choices, tool selections, or direction changes?
3. Findings — Key discoveries, surprises, or important observations
4. What remains — Topics the user wanted to cover but didn't get to

Phase 3 — Write Memory File

Write a structured memory file to the project's memory directory. Use type project with a descriptive name.

Memory file structure:

---
name: [Descriptive session name]
description: [One-line description — specific enough to judge relevance in future sessions]
type: project
---

[Session context: date, what triggered this session, high-level goal]

**Why:** [Why this breadcrumb exists — what the user wants to continue]

**How to apply:** [How the next session should use this — e.g., "Load at session start, walk user through remaining layers"]

## What Was Covered
[Bullet list of topics discussed with key conclusions]

## Implementation Status (if audit available)
[GREEN/YELLOW/RED table with file paths, line counts, and notes]

## Open Questions
[Numbered list of unresolved questions or decisions]

## Suggested Next Steps
[What the next session should do — ordered by priority]

## Key File Paths
[Quick reference of important files the next session may need to read]

Phase 4 — Update MEMORY.md

Add a one-liner to MEMORY.md pointing to the new memory file:

- [Session Title](filename.md) — One-line description of what's in the breadcrumbs

Keep the entry under 150 characters. MEMORY.md is always loaded, so the next session will see this pointer automatically.

Phase 5 — Resume Advice

Tell the user how to start the next session:

1. What model to use (Haiku for review/discussion, Sonnet/Opus for implementation)
2. What to say to trigger context loading (e.g., "let's continue the architecture review")
3. Any caveats (e.g., "Haiku can discuss findings but shouldn't do deep code exploration")

Content Guidelines

What to Include

• File paths with line counts — src/memory/redis-client.ts (~240 lines) — lets the next session reference without reading
• Status classifications — GREEN/YELLOW/RED with evidence
• Specific findings — "The AgentLoop doesn't call the Claude client" not "some components aren't wired"
• Concrete next steps — "Wire cold tier writes in memory-manager.ts addMessage()" not "finish integration"

What to Exclude

• Full code snippets — the next session can read files if needed
• Generic advice — "write tests" or "follow best practices"
• Conversation-specific ephemera — jokes, tangents, false starts
• Information derivable from git log or the code itself

Sizing

Target 200-400 lines for the memory file. Enough to be comprehensive, short enough that it doesn't overwhelm a lighter model's context. If an audit produced extensive findings, summarize to the table format rather than prose.

Additional Resources

Reference Files

• references/model-capabilities.md — Quick reference for what each model tier handles well in review/handoff scenarios, to calibrate breadcrumb depth appropriately