Skip to content

tmusser/ai-engineering-skills / skills/handoff

handoff

Verified

Compress project context into HANDOFF.md with workflow state, analysis checkpoint, next gate, verification, current hypothesis, freshness anchors, optional gotcha references, and a resume packet for the next agent session.

Handoff

Purpose

Compress context into a launchpad for the next session. A handoff is not a transcript — it is durable state that lets a fresh agent continue safely without the full chat history.

A handoff is also not authoritative merely because the file exists. A fresh session must establish both snapshot freshness and internal resume trust before treating an existing HANDOFF.md as current state.

When to use

Use at the end of a session, before switching agents, or before pausing work.

When resuming from an existing handoff, run the fresh-session trust gate before using its status, next task, verification claims, referenced files, unresolved items, or analysis checkpoint as current state.

Inputs

  • SPEC.md, PLAN.md, TODO.md, VERIFY.md
  • Optional GOTCHAS.md when recurring project sharp edges have been recorded
  • Active modes, current phase, next gate
  • Analysis checkpoint when one exists: FRESH | NOT_NEEDED | STALE | REQUIRED
  • Compatibility seams, invalid-if constraints, verify gate status, review-required items, next gate command when relevant
  • Context risk level
  • Active debugging hypothesis (if any)
  • When relevant, carry loop state forward: iterations attempted, best known artifact, rejected attempts, current feedback signal, remaining budget, stop condition, and human review trigger.
  • Branch, commit, dirty state
  • Changed files, working/failing commands, unverified files
  • Important decisions, open decisions, traps; when a durable DECISIONS.md ledger exists, refer to active D-IDs instead of reproducing the full history
  • Freshness anchors when Git state is available: snapshot commit + workspace fingerprint
  • Required resume files that must still exist before the next task can start
  • Exact recorded verify-gate status and review-required state expected at resume

Freshness rule

The bundled scripts/handoff_freshness.py helper lives inside this skill directory. Resolve the active handoff skill directory, then use the helper to stamp and check HANDOFF.md.

Status semantics:

  • PASS — non-handoff repository state still matches the stamped snapshot.
  • STALE — repository state changed after the handoff snapshot. Treat the handoff as advisory only, re-read live project state, and regenerate it before resuming.
  • REVIEW_REQUIRED — freshness could not be established. Do not silently trust the handoff as current state.

The helper intentionally excludes HANDOFF.md itself from the workspace fingerprint so editing or committing only the handoff does not invalidate its own snapshot.

If the helper cannot be executed, compare the recorded commit, dirty state, changed files, and live Git status manually. Any mismatch or unresolved uncertainty is REVIEW_REQUIRED, not an implicit pass.

A stale or unresolved handoff also invalidates trust in its recorded analysis checkpoint. Reconcile live state first, then re-evaluate whether analysis is FRESH, NOT_NEEDED, STALE, or REQUIRED for the one next task.

Fresh-session trust rule

The bundled scripts/resume_trust.py helper composes the freshness check with content reconciliation. Run it before a fresh session acts on a handoff:

python <handoff-skill-dir>/scripts/resume_trust.py check \
  --handoff HANDOFF.md \
  --verify VERIFY.md

A resume-trust PASS requires all of the following:

  • the underlying handoff freshness check is PASS;
  • every path named in Required resume files still exists;
  • the handoff's Verify gate status matches the live recorded status in VERIFY.md (or explicitly says NOT_PRESENT);
  • Review-required items is coherent with the live verification state;
  • exactly one next recommended task is present;
  • a next verification command is present.

A freshness PASS by itself is not enough. The workspace can be unchanged while the handoff still contains an incomplete or self-contradictory resume packet. REVIEW_REQUIRED means reconcile the packet with live artifacts before acting. STALE means live repository state changed after the snapshot and the handoff must be regenerated before resume.

Optional file-purpose lookup before expansion

If a project maintains an approved .ai-context/file-ledger.json, a fresh session may query it after resume trust, before reading additional project sources:

python scripts/aes.py files query "next task keywords" --limit 5

The query returns path, purpose, use-when hints, related paths, and a per-file freshness status; it never loads file contents. Read only the necessary live files, following task authority and the handoff's explicit required-file set. Treat REVIEW_REQUIRED (stale, unapproved, missing, or no match) as a prompt for ordinary source discovery, not permission to rely on cached descriptions. Do not create a ledger just to complete a handoff, do not paste its full contents into the resume packet, and do not turn this into another trust gate.

Analysis checkpoint rule

A handoff should tell the next session whether analyze-mini is actually needed; it should not run analysis as a completion ritual.

Reuse the artifacts already being read for the handoff and classify the one next task:

  • FRESH — a full analysis exists and its task-defining inputs still match current state.
  • NOT_NEEDED — no current analysis trigger exists.
  • STALE — a prior analysis exists but task-defining inputs changed.
  • REQUIRED — a current trigger exists and full analysis should run before build-one.

Do not run analyze-mini merely because a handoff is being written.

Missing prior analysis is not itself a reason to mark REQUIRED. Use the triggers defined by analyze-mini: changed task-defining inputs, unresolved implementation-shaping choices, broken criterion-to-task-to-proof mapping, changed strategy after failure, or live-state changes discovered during resume reconciliation.

Gotcha promotion rule

Keep one-off continuation traps in HANDOFF.md. Promote a trap to optional GOTCHAS.md only when it is non-obvious, has a meaningful consequence, is likely to recur across sessions or nearby tasks, and can be grounded in evidence.

A promoted gotcha should record a stable ID, trigger, consequence, safe path, evidence, last verification, and active/resolved status. When it affects the next task, reference the gotcha ID from the handoff instead of copying the whole entry.

Do not turn GOTCHAS.md into a generic bug log, TODO list, or folklore file. BUGS.md owns active defects; GOTCHAS.md owns recurring sharp edges.

Workflow

  1. Read current artifacts first.
  2. If an existing HANDOFF.md will be used for resume, run resume_trust.py check before trusting it. Do not use freshness alone as the final trust decision.
  3. For the exactly one next task, perform the cheap analysis eligibility check using already-loaded artifacts. Record FRESH, NOT_NEEDED, STALE, or REQUIRED; do not invoke full analysis solely to improve the handoff.
  4. Create or update HANDOFF.md starting with a Resume Packet block.
  5. Record Workflow State (active modes, phase, loop, next gate, analysis checkpoint, context risk, hypothesis).
  6. Record continuation guardrails when relevant: compatibility seams preserved, invalid-if constraints, exact verify gate status, review-required items, next gate command, and Required resume files that must exist for the next task.
  7. State the current goal in 1-2 sentences.
  8. List completed slices + verification results.
  9. List changed files with one-line purpose (flag unverified).
  10. Record working commands, known failing commands, important decisions, open decisions, and traps. When an existing DECISIONS.md contains governing active decisions, cite their stable D-IDs and include that file in the read-first set. Check supersession before carrying a decision forward. Do not create a ledger for ephemeral steps, and never treat its text as overriding current instructions, SPEC.md, or verified project state.
  11. Promote recurring evidence-backed traps to GOTCHAS.md; keep one-off session traps in the handoff.
  12. If an active gotcha affects the next task, reference its ID and make GOTCHAS.md part of the read-first set. When generating a context packet for that continuation, prefer --require-file GOTCHAS.md so the dependency is explicit.
  13. Name exactly one next recommended task + its verification command.
  14. After the final non-handoff project edit, stamp the freshness anchors with the bundled helper.
  15. Run resume_trust.py check after stamping. Only HANDOFF RESUME TRUST: PASS should be treated as safe to resume when the helper is available.
  16. Keep under 120 lines unless complexity requires more.

Resume Packet example (place near top):

RESUME PACKET

* Goal: ...
* Workflow State: lean-mode active, next gate=build-one, risk=low
* Analysis: NOT_NEEDED — direct criterion -> task -> proof; no unresolved implementation choice
* Branch: main, Commit: abc123, Dirty: no
* Freshness: PASS, Snapshot: abc123, Workspace: sha256:...
* Required resume files: SPEC.md, VERIFY.md, src/export.py
* Gotchas: G1, G3 | none
* Next task: ...
* Verification: `python test_mini.py --slice=foo`
* Read first: HANDOFF.md, GOTCHAS.md (if present/referenced), SPEC.md, PLAN.md, VERIFY.md (if present), ANALYZE.md only when referenced, then changed files below

Outputs

  • HANDOFF.md with Resume Packet + Workflow State
  • Analysis checkpoint for the exactly one next task
  • Freshness anchors when Git state is available
  • Required resume files and reconciled live verification state
  • Optional references to active GOTCHAS.md entries that affect continuation
  • Clear next task and verification path
  • Continuation guardrails when relevant

Success looks like

  • A new agent can pick up the project from HANDOFF.md + core artifacts without rereading chat.
  • All critical context (modes, risks, decisions, next gate) is in durable files.
  • Exactly one next task is named.
  • The next session knows whether analysis is FRESH, NOT_NEEDED, STALE, or REQUIRED without paying for a full analysis by default.
  • A stale handoff cannot silently outrank live repository state.
  • A fresh-but-incoherent handoff cannot nominate work until resume trust passes.
  • A recurring sharp edge that matters to future work is not buried only in a one-session handoff.

Stop conditions

  • Next session can continue without full chat history.
  • No important context lives only in memory.
  • Next task and verification command are explicit.
  • Analysis need for the next task is classified without ritual invocation.
  • Fresh-session resume trust is PASS when the bundled helper is available; otherwise unresolved trust is surfaced as REVIEW_REQUIRED.
  • Relevant promoted gotchas are referenced without duplicating their full contents.

Anti-patterns

  • Writing a chat transcript summary instead of state.
  • Running analyze-mini solely to make the handoff look complete.
  • Marking analysis FRESH after task-defining inputs changed.
  • Marking analysis REQUIRED only because no previous analysis exists.
  • Vague status ("mostly done").
  • Omitting active modes, failing commands, or dirty state.
  • Carrying multiple debug hypotheses forward.
  • No explicit next gate or verification.
  • Treating HANDOFF.md as current merely because it exists.
  • Continuing from a STALE or REVIEW_REQUIRED handoff without reconciling live state.
  • Treating freshness PASS as sufficient when required files, verification status, or unresolved items contradict live artifacts.
  • Burying a recurring evidence-backed sharp edge only in HANDOFF.md.
  • Creating GOTCHAS.md for ordinary bugs, temporary failures, or generic reminders.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall