← Courses
AI Project Scaffolding
← Module 5
Module 6 of 8
Module 7 →
Intro
Scenario
Lesson
Context
Lab Skill ~20 min
Intro

Workflow Structure and Handoffs

2 min read

Every AI session ends. The context window closes. Everything the AI knew — the decisions made, the problems surfaced, the decisions deferred — disappears unless you write it down before the session ends. Most developers don't. The next session starts cold, rediscovers the same terrain, and makes the same decisions again.

Structured handoffs are the solution. A handoff is a document written at the end of a session that contains exactly what the next session needs to start with full context: what was accomplished, what decisions were made and why, what's in progress, what has been explicitly deferred, and what the next session should do first.

NIST MANAGE asks how AI-assisted work is maintained across time — how risks that emerge are tracked and addressed. A handoff protocol is how you implement MANAGE in daily development: it makes the AI's work auditable, recoverable, and continuous rather than fragmented and amnesia-prone.

Portfolio artifact
Skill
A workflow structure for an AI-assisted project — session start protocol, HANDOFF.md template with five required fields, and a session end checklist that ensures complete context transfer.
  • Write a HANDOFF.md that gives a fresh session full working context in under two minutes
  • Distinguish between what must be in a handoff and what is optional noise
  • Design a session start protocol that validates context before any work begins
  • Identify the five categories of information that expire at session end
  • Apply NIST MANAGE's continuity requirements to an AI-assisted development workflow
Scenario

The Decision That Disappeared

3 min read

A developer spent three hours in an AI session working through a complex refactor of the notification system. By the end of the session, they'd made four significant decisions: switched the queue implementation from Redis to a PostgreSQL-backed queue for operational simplicity, added retry logic with exponential backoff, discovered that the existing email templates were inconsistently using two different templating engines, and deferred the template unification to a separate task.

The session ended. No handoff was written. The developer closed the laptop.

Three days later, a new session starts. The developer opens the codebase and asks the AI to continue the notification refactor. The AI sees the Redis code has been removed and the PostgreSQL queue is half-implemented. Without the context from the previous session, the AI has two choices: guess at the rationale, or ask. It guesses. It re-introduces a Redis dependency, because the PostgreSQL queue approach is unusual and the AI's training data favors Redis for queues.

The developer doesn't catch this until code review, two days later. The rationale for the PostgreSQL decision was in the previous session's conversation history, which is now gone. The developer can vaguely remember the reasoning but can't reconstruct it precisely. The code reviewer approves the Redis approach because the rationale for the alternative is unavailable.

A handoff written at the end of the first session would have cost five minutes and preserved all four decisions. Without it, the work regressed and the reasoning was lost.

Lesson

The Five Handoff Fields

4 min read

A handoff document is not a project summary. It is not a changelog. It is not a meeting note. It is a specific document designed for one reader — the AI in the next session — to reconstruct working context. It has five required fields, and each one answers a specific question.

What was accomplished in this session? Completed work, not work in progress. This field is for the AI to understand what has changed since the last handoff. It answers: "What is different now compared to when I started?" Format: a bulleted list of completed work items, each one specific enough that the AI can verify it by reading the code.

What architectural or significant decisions were made, and why? This is the most critical field. The rationale is what expires at session end — the code persists, but the reasoning doesn't. Every decision in this field must include a "why" that is specific enough to reconstruct the reasoning. "Switched to PostgreSQL queue for operational simplicity — avoids adding Redis to the infrastructure dependency stack, which requires a separate ops runbook."

What is not yet complete at the time of handoff? Be specific about the state. Not "working on retry logic" — "retry logic is half-implemented: the exponential backoff is working, the dead-letter queue is not yet written." This field tells the next session exactly where to pick up without needing to read every file.

What was explicitly decided not to do in this session, and why? Deferred items are different from unplanned work — they are things you saw, evaluated, and decided to postpone. The developer in the scenario deferred the template unification. Without that in a deferred field, the next AI session may treat the inconsistency as an unnoticed bug and "fix" it immediately, disrupting the planned sequence.

What should the next session do first? A single sentence. Not a full task list — just the first action. "Start by completing the dead-letter queue implementation in notifications/queue.ts, then run the full test suite." This field is the anti-cold-start mechanism. The AI can begin work immediately without needing to reconstruct a plan.

NIST AI RMF — MANAGE: Continuity and Recovery

The MANAGE function asks how AI risks are tracked and addressed over time. For AI-assisted development, a critical risk is context loss — the AI making decisions based on incomplete information because prior context wasn't preserved. A handoff protocol is the MANAGE practice that closes this gap: it makes AI-assisted work continuous rather than episodic, and makes decisions recoverable rather than lost.

NIST AI RMF — MANAGE: Auditability

MANAGE also requires that AI-related decisions can be reviewed. A HANDOFF.md with a Decisions Made field creates an audit trail for every significant choice made during AI-assisted development. If a decision turns out to be wrong, the rationale is preserved and the team can evaluate whether the reasoning was sound or the premises changed.

Context

Session Protocols

2 min read

A handoff document is only useful if it's actually read. A session start protocol enforces this — it's a short checklist in the CLAUDE.md that defines what must happen before any work begins.

Session Start Protocol

Before generating any code: (1) Read HANDOFF.md if it exists. (2) Confirm understanding of In Progress items — ask one clarifying question if any item is ambiguous. (3) Confirm the Next Session action before beginning. This prevents the cold-start problem: the AI can begin work immediately with validated context.

Session End Checklist

At the end of every session: (1) Update HANDOFF.md with all five fields. (2) Verify the Decisions Made field includes rationale — not just what was decided, but why. (3) Check that In Progress items are specific enough to resume without reading every file. (4) Stage HANDOFF.md for commit. Do not close the session without updating the handoff.

What Doesn't Belong in HANDOFF.md

Code excerpts — they belong in the codebase. Task lists — they belong in the issue tracker. Historical decisions — only the current state. Rationale that is already in the CLAUDE.md — don't duplicate it. HANDOFF.md covers only the current working state: what just happened, what's next, what was decided in this session, what was deferred in this session.

⚙ Skill Lab
Write the Handoff Protocol
~20 minutes · 3 artifacts
What you're doing
Write a HANDOFF.md for the notification refactor scenario, then design the session start protocol and end checklist for the CLAUDE.md. The AI evaluates completeness and specificity of each field.
Roles
You — DeveloperWrite the HANDOFF.md for the notification refactor session, then the session start and end protocols.
🔍
AI — Fresh SessionI'll read your handoff as if I'm a fresh AI session with no memory of the previous work. I'll tell you what I still don't know.
Five required fields
Session summary — what was completed
Decisions made — with rationale
In progress — specific state, not status
Deferred items — what and why deferred
Next session — first action only
Shift + Enter for a new line
✓ Module Complete
You've completed Module 6 of 8. Your handoff protocol is your sixth portfolio artifact.
Next Module →