← retour au collage›Modifier / dupliquer

Collage sans titre

#957EPNncYHpublic / publicnouvelle version

anonyme créé 5 days ago Expire dans 2 days 8.8 KB syntaxe: text

Vos changements créent un nouveau collage lié à celui-ci — l’original reste intact.

nouvelle version Vos changements créent un nouveau collage lié à celui-ci — l’original reste intact.

Visibilité Fil public Accès public

Note de changement (facultatif)

Ce collage sera affiché dans le fil public. Changez la visibilité si vous voulez seulement le partager par lien.

Annuler

---
name: session-handoff
description: "Break large deliverables into sections."
version: 2.1.0
author: BV
license: MIT
metadata:
  hermes:
    tags: [handoff, delegation, session, task-decomposition, context-preservation]
    related_skills: [autonomous-ai-agents]
---

# Session Handoff

## Purpose

Large tasks risk KV cache compaction, which erases critical context. When a task is large enough that compaction would hit mid-build, stop at a natural boundary, write a handoff doc capturing all state/decisions/context, and resume in a new session. The handoff doc is the single source of truth — INCLUDING the process itself: skills don't auto-load in a new session, so every handoff doc must instruct the next session to reload this skill as its very first action, and every handoff doc must inline a counter-rules snapshot (see format) so the chain survives even if the skill is never loaded.

## When to Use

Evaluate triggers BEFORE writing any code, never mid-build. Handoff mode is ON if ANY of:

1. Output spans 2+ files.
2. Output is estimated > 1500 lines. Estimate by task type, not exact count (you cannot count lines you haven't written yet): a complete game, app, or multi-feature deliverable is ALWAYS > 1500 lines. When the estimate is uncertain, default to YES.
3. **The user invoked the session-handoff skill or explicitly asked for handoffs/sections. This trigger is unconditional — size does not matter. "This task is small enough to skip the handoff" is never a valid call when the user asked for the skill. You must produce at least one handoff doc at the first natural boundary.**
4. You are iterating on the same file across 2+ turns (write, test, find bug, fix) — the most common cause of lost context.

### Sectioning a single large file

A single-file deliverable triggers sectioning by line estimate (trigger 2/3), and the sections are appendable chunks of that one file — e.g. for a game: (1) skeleton + CSS + HUD, (2) core engine + level/maze data, (3) entities + AI + collision, (4) UI/audio/polish. After each section: append it to the file, verify the file still loads/parses, write the handoff doc listing which sections are done and what section number comes next, then stop. The next session reads the handoff, reads the tail of the file, and writes only the next numbered section. Never write "single file, so no handoff needed" — the section plan IS the handoff.

## Configuration

- **Handoff directory:** `/opt/data/.handoff_docs` — read and write ALL handoff files here
- **Naming:** `<task-name>-handoff-N.md` (e.g. `name-handoff-1.md`)
- **Counter limit:** 3

## Iteration Counter

`turns_on_file` counts iteration turns on the target file since the last handoff.

**Counting rule:** 1 count = one assistant turn that touched the file (patch, write_file, read_file for bug-hunting, terminal edits on it, browser_exec inspecting it). Multiple tool calls in one turn count as ONE. The counter lives in the latest handoff doc, not in a separate state file.

**Behavior table (the only threshold rules):**

| counter | behavior |
|---|---|
| 0–1 | normal iteration |
| 2 | ONE change to the file maximum (highest-priority item), then write the handoff and stop |
| 3 | HARD STOP: write the handoff immediately. Fix nothing. Verify nothing. Search for nothing. |

If you feel the urge to "just fix this one thing" at the threshold — that is the compaction risk talking. Stop.

**Verification nuance:** verifying the ONE change you just made at counter 2 is fine and encouraged. What is forbidden: fixing any NEWLY DISCOVERED issue past the threshold — queued issues go to the Discovery Queue instead.

**Bootstrapping:** the first iteration cycle has no handoff file yet — track the count in session context, and write it into the first handoff doc you produce. Every NEW handoff doc starts at `turns_on_file: 0`; later sessions increment the counter in the latest handoff doc before each turn that touches the file. If the counter is already at the limit when you read it, do not touch the file at all — write the handoff and stop.

**Counter format:** a fixed `## Counter` section with a plain, backtick-free line:

```
## Counter
turns_on_file: 2
```

**Reliable read/update snippet** (execute_code; regex is `^turns_on_file:\s*(\d+)` with MULTILINE):

```python
import glob, re

HANDOFF_DIR = "/opt/data/.handoff_docs"

def read_counter(task_name):
    """Returns (count, path). (0, None) means first cycle: no handoff exists yet."""
    files = sorted(glob.glob(f"{HANDOFF_DIR}/{task_name}-handoff-*.md"))
    if not files:
        return 0, None
    content = open(files[-1]).read()
    m = re.search(r"^turns_on_file:\s*(\d+)", content, re.M)
    return (int(m.group(1)) if m else 0), files[-1]

def bump_and_check(task_name):
    """Call BEFORE a turn that touches the target file. Returns new count or None (first cycle)."""
    count, path = read_counter(task_name)
    if path is None:
        return None
    count += 1
    content = open(path).read()
    content = re.sub(r"^turns_on_file:\s*\d+", f"turns_on_file: {count}", content, count=1, flags=re.M)
    open(path, "w").write(content)
    if count >= 3:
        print("HANDOFF_TRIGGER: write handoff doc and stop NOW")
    elif count == 2:
        print("SCOPE: one change max, then handoff")
    return count
```

## Boundaries

Natural boundaries preferred; the counter is the fallback that forces a handoff even when no natural boundary has been reached. A natural boundary meets ALL three:

1. **Completeness** — something verifiable is done (passing test, written file, recorded decision). Halfway code is not complete.
2. **Dependency isolation** — the next section needs this section's output as its input.
3. **Session budget** — roughly one session's worth of work.

## Discovery Queue

Issues found during iterative work that are not fixable in the current turn go in the handoff doc's `## Discovery Queue` rather than being fixed on the spot.

## Pitfalls

- **After any patch near the end of a file, verify the closing tags are intact.** When patching the last few lines of an HTML/JS file (especially replacing the `END SECTION` comment or last function), the closing `</script></body></html>` tags can be lost if the `old_string` consumes them. This causes the entire `<script>` to leak into the browser DOM — the page loads with NO syntax error and NO runtime error, but all JS variables are silently `undefined`. Always verify the file ends with the correct closing tags after any end-of-file patch. Use `execute_code` to check `content.rfind('</script>')` is near the end, or read the last 200 chars.
- **When patching the end of an HTML/JS file, include closing tags in the `new_string`.** If your `old_string` reaches the end of the file, the `new_string` must re-include `</script>\n</body>\n</html>` (or whatever the correct closing sequence is). Never assume the patch tool preserves trailing content it didn't match. The next session's FIRST action is to read the handoff doc, then clear the queue in order (fix each item, or mark it duplicate/no-longer-relevant and remove it) before touching anything else.

## Handoff File Format

```
# Handoff: <task name>

## Completed
- What is verifiably done

## State at Handoff
- Working directory and file paths with current status
- Environment state (env vars, virtualenvs, running services)
- Git status (branch, uncommitted changes, latest commit)

## What's Left
- Remaining sections (numbered), estimated scope of each, dependencies between them
- For single-file deliverables: the section plan (which numbered chunk of the file each section writes)

## Next Session Instructions
- **FIRST LINE, ALWAYS: `skill_view("session-handoff")` before touching any file.** A fresh session knows nothing about this skill unless this doc tells it. Skipping this breaks the chain: the next session will build Section N but won't know the counter rules, the stop-at-boundary protocol, or the discovery-queue convention.
- Exact first command or action
- Files to read before proceeding
- Setup required first; known gotchas or constraints

## Full Spec Reference
- Paste or link the complete original task specification
- Include constraints, aesthetic preferences, quality bars, edge cases
- This prevents the next session from making choices that contradict the spec

## Context for Next Session
- Background the next session won't have
- User preferences relevant to the task
- Tool or API access needed

## Discovery Queue
- Issues found but NOT fixed: `label`: one-line description + file/line if known

## Counter
turns_on_file: 0
- `last-modified`: <path of file being iterated>
- `next-first-action`: "skill_view(session-handoff), then clear the discovery queue"
- `rules`: 0–1 normal | 2 = one change max then handoff+stop | 3 = HARD STOP, fix nothing | new handoff starts at 0
```

## References

- `references/example-handoff.md` — a complete worked example handoff doc