WHAT
Purpose and context
- Purpose: generate ONE
.mdself-standing handover file so that another session (with no context) can open it and continue: unfinished work, order with reasons, measurements as evidence, pitfalls, open debt. - Trigger (when to use):
- A long session is about to end with work unfinished, and the next session has no context.
- Just investigated a chain of findings, need to lock in the order of resolution before forgetting the reasons.
- Handing off work to another person/agent while the work is still vague (no approved SPEC yet).
- Non-goals (do NOT use when):
- The task is approved and every step is clear → use
plan(execution brief for a headless agent). - You only need a retrieval machine for "what did the previous session do" → use
record-episode(mem-rank). - Transferring ownership of the worktree/terminal to another agent → use
orca-cli(full handoff).
- The task is approved and every step is clear → use
Mental model
bằng chứng chạy thật (git log/status, medic) → việc còn lại → quan hệ CHẶN → file 7 mục trong sources/handover/ → index + log.
Principles — why this file is different from a summary
The reader of it has nothing at all: no transcript, doesn't know what was tried yesterday and why it was dropped. A summary recounts what was done; a handover must answer what to do next and why that order.
Three things decide whether this file is usable:
- Every claim must have a MEASUREMENT. "Grep isn't good enough" is an opinion. "Across 8 changed files: grep suspects 36, graph 25, overlap 21 ⇒ 15 excess 4 missed" is evidence — the next session can verify it, and doesn't have to take anyone's word.
- The order must have REASONS, and must point out which thing BLOCKS which. A flat list makes the next session pick the easiest task first and then stumble on the unfinished one.
- Pitfalls are the most valuable part. Every mistake already paid for but not written down means the next session pays for it again.
Input and output contract
| Field | Required? | Meaning | |
|---|---|---|---|
| In | session state (repo, unfinished work, findings) | yes | obtained via real commands run, not from memory |
| In | underlying concept/ADR | no | link it in the "Read first" section instead of copying it again |
| Out | llmwiki/wiki/sources/handover/DDMMYY-<tên>.md |
yes | seven sections in the correct order (table in W03) |
| Out | line in llmwiki/wiki/index.md + append llmwiki/wiki/log.md |
yes | registered; index_sync green if the repo has a validator |
Rules and capabilities
- RULE-01 (MUST): Measurement > adjective. Every statement about degree ("slow", "a lot", "badly broken") must come with a number or be deleted.
- RULE-02 (MUST): Absolute or exact repo-relative paths — the next session copy-pastes and it runs, without having to guess the directory.
- RULE-03 (MUST): Do not repeat the architecture — link to the existing concept. A handoff file bloats because it copies the background again and becomes a file nobody reads to the end.
- RULE-04 (MUST): Also record what is NOT verified — "not measured", "not cross-checked" is valuable information; hiding it makes the next session build on false assumptions.
- RULE-05 (MUST): The "Tried and DISCARDED" section must not be missing — this is the most easily forgotten section and the most costly when missing.
- RULE-06 (MUST): Do NOT copy the transcript. A handoff is distillation, not a log. Longer than 200 lines is a sign you are copying instead of distilling.
- RULE-07 (MUST): Anti-pattern: writing "continue the unfinished work" without saying where it is unfinished, which file, which line.
- Capabilities: read repo state + run a local health gate (read-only); write one file in the wiki + index + log.
Failure boundaries
- A number that cannot be reproduced by a command → do not make it up: state clearly not verified (partial is valid).
- The task is actually already clear + already approved → clarify/switch
plan; if only machine retrieval is needed →record-episode. - The file cannot stand on its own (must ask again, wrong path, "as discussed above") → failed self-check W05, fix, then check again.
- Longer than 200 lines → sign you are copying the transcript, cut it down.
HOW
Main workflow
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|---|---|---|---|---|
| W01 | deterministic | repo | Collect evidence BEFORE writing (git log, git status, medic if available) |
real measurements | cannot reproduce → record "not verified" |
| W02 | judgment | remaining work | Identify what BLOCKS (what breaks if you do B before A?) | step 0 + order with reasons | no relationship → record "order is free" |
| W03 | effect | W01–W02 | Write llmwiki/wiki/sources/handover/DDMMYY-<tên>.md seven items |
file handover | — |
| W04 | judgment | each task | Estimate time using a specific unit | ⏱ each task | — |
| W05 | judgment | file | Check that the file stands on its own (exact path, the number states clearly what it was measured on, no "as above") | file passes | missing → fix, repeat W05 |
| W06 | effect | file | Register index + log; index_sync if there is a validator |
index/log matches | validator red → fix |
Details of each step (source of truth for W01–W06):
1. Gather evidence BEFORE writing (do not write from memory)
git log --oneline -15
git status --short
python3 fdk/tools/medic.py --ci 2>&1 | tail -5 # nếu repo có medic
Every number in the file must come from a command actually run in the session, not re-estimated. Any number that cannot be reproduced should be marked clearly as unverified, do not round it into truth.
2. Identify the BLOCKER
For each remaining task, ask: if task B is done before task A, what breaks? If there is a specific answer → A is step 0, record the consequence if skipped. If not → the order is free, say outright that it is free.
3. Write the file llmwiki/wiki/sources/handover/DDMMYY-<tên>.md
Folder separate sources/handover/ — do not mix into sources/draft/. Reason: draft is a proposal awaiting approval, handover is work currently in progress; the two have different lifecycles and different readers. If merged, the next session has to filter. (R5 only checks first-level subfolders so sources/handover/ is valid.)
Seven items, in exactly this order:
| Item | Required content |
|---|---|
| Read first | 1–2 links to the underlying concept/ADR. This file only says what to do next, it does not repeat the architecture |
| Next tasks | Numbered. Each task: evidence · why it is in this position · ⏱ estimate · risk. Blocking steps are marked clearly BLOCKER |
| Small cleanup tasks | Can be done at any time, combine the estimates together |
| Open debt, not blocking | Table: task · status. Include the things not yet fully measured |
| Pitfalls | Numbered. Each one: symptom → cause → consequence if it happens again |
| Tried and DISCARDED | Directions already ruled out + reason. Without this item, the next session will try exactly the same thing again |
| Origin | Source, commit in the session, related concept |
4. Estimate time in concrete units
~30 phút · ~2 giờ · nửa ngày — do not use "a little", "pretty fast". A wrong estimate is better than a vague one: the next session reads "half a day" and knows not to squeeze it into the last 20 minutes of the day.
5. Check that the file stands on its own
Read it back and ask yourself: can someone who wasn't in this session get started? Anywhere they'd have to ask again is a gap. In particular, check:
- Are the file paths exact (copy-paste works)
- Do the numbers clearly state what they were measured on ("across 8 changed files" not "across a few files")
- Is there anywhere that says "as discussed above" without an "above"
6. Register
Add a line to llmwiki/wiki/index.md, append llmwiki/wiki/log.md. If the repo has a validator: run index_sync until it's green.
Branches
| ID | Kind | Guard | Behavior | Skip / failure | Rejoin |
|---|---|---|---|---|---|
| B01 | capability_optional | repo has medic | run python3 fdk/tools/medic.py --ci in W01 |
none → skip | W02 |
| B02 | capability_optional | repo has validator | run index_sync until green in W06 |
none → skip | finish |
Validation and stopping
Self-check W05 is the gate: someone who wasn't in the session must be able to start. The "Tried and DROPPED" section is mandatory; every intensity adjective comes with a number. Stop when the file is registered in the index + log.
Examples
- Positive: the session ended while cross-checking
travel-policy.yaml↔install-harness.sh→ W01 takes the actual mismatched line (install-harness.sh:128vstravel-policy.yaml:71), W02 marks it as a step 0 BLOCKER, the file has all 7 sections + ⏱ ~1 hour, registered in the index + log (see the opening example below). - Boundary/failure: the user says "handoff" for a task that already has an approved SPEC and clear steps → don't write a handover, switch to
plan; or the draft says "grep is slow" with no number → RULE-01 forces adding a measurement or deleting the sentence.
Opening example that meets the requirements
### 0. `travel-policy.yaml` phải khớp `install-harness.sh` — CHẶN mọi việc dưới
Bằng chứng nó sai ngay lúc này:
install-harness.sh:128 cp fdk/tools/build-capabilities.py → ~/.claude/hooks/
travel-policy.yaml:71 build-capabilities.py → TẦNG 3 FRAMEWORK-ONLY
Installer copy xuống. Hợp đồng khai ở lại.
Hệ quả nếu bỏ qua: mọi câu trả lời "cái gì travel" đều chưa kiểm chéo.
⏱ ~1 giờ cho validator đối chiếu hai bên.
After reading it you immediately know: where it's wrong, how to prove it, what you lose by skipping it, and how long it takes.