Harness Notes

Why long-running tasks lose continuity

A new session should inherit the work—not rediscover it.

Notes from Learn Harness Engineering · Lecture 05

SESSION 01SESSION 02
reasoning disappears ↓verification disappears ↓
PROGRESS.mdstate · tests · next actions
DECISIONS.mdchoices · reasons · constraints
git checkpointatomic working state
Durable artifacts bridge the session boundary.

The failure sequence

1

Finite window

Code, tool output, decisions, and conversation grow faster than context capacity.

2

Compaction / reset

Either summarize the session or start clean. Both lose something.

3

Lost “why”

The code survives, but rejected alternatives and reasoning vanish.

4

Rebuild cost

Time is spent rereading, reconstructing decisions, and rerunning checks.

5

Drift

Each session inherits a slightly different understanding; deviations compound.

Core concepts

The durable vocabulary for thinking across session boundaries.

Finite context
Every window eventually fills; a bigger model window does not remove the need for handoff.
State persistence
Repository artifacts let a fresh session resume unambiguously from the real project state.
Rebuild cost
The time needed to become executable again. A strong harness targets about three minutes.
Drift
The gap between the agent's understanding and the repository. Every unstructured boundary widens it.
Context anxiety
Pressure near the limit can trigger premature completion and weak verification.
Compaction vs. reset
Compaction keeps some “what” but can lose “why”; reset is clean but only as good as the handoff.

The handoff stack

01 · LIVING STATE

PROGRESS.md

  • Current commit and checks
  • Completed / in progress
  • Known issues and blockers
  • Ordered next actions
02 · REASONING

DECISIONS.md

  • Decision and date
  • Why it was chosen
  • Rejected alternative
  • Constraints that remain
03 · CHECKPOINTS

Git commits

  • Atomic unit of work
  • Clear “what and why” message
  • Versioned working state
  • Easy rollback and diff
04 · CLOCK IN

Initialization

Read state + decisions
↓
Inspect recent commits
↓
Run checks
↓
Continue next action

Operating routine

Clock in start of session

  1. Pull the latest repository state.
  2. Read PROGRESS.md and DECISIONS.md.
  3. Skim recent commits and diffs.
  4. Run build, tests, and lint.
  5. Confirm the next action and continue.

Clock out end of session

  1. Finish the current atomic unit.
  2. Update state, checks, blockers, and next actions.
  3. Record only new durable decisions.
  4. Commit completed work with a clear message.
  5. Leave the repository clean and resumable.

Evidence

Rebuild time
15 → 3 min
about 78% lower
Feature completion
58% → 100%
7/12 → 12/12
Hidden defects
43% → 8%
35-point reduction

Handoff checklist

  • PROGRESS.md reflects state, checks, blockers, and next actions.
  • DECISIONS.md includes every new durable choice and reason.
  • Verification results are recorded—not left in chat history.
  • Completed work is committed as an atomic checkpoint.
  • The next session can identify one clear first action.
TAKEAWAY

Persist the why, the state, and the next move.