Session open

Session Open

Absorb a handover the right way: descend from cheap-and-ambient to authoritative, verify what's load-bearing, translate the state for the user, recommend a next step, then wait for their call.

CONFIGURATION (adapt to your project)

Name your project's canonical files here. Defaults that work well:

• ROADMAP.md — the plan: sequence, status, gates, pending decisions
• TASKS.md — current actionable items
• Latest HANDOVER — the previous session's delta (written by session-close)
• (optional) an operating-model or conventions doc, a decision log, a ledger of shipped work, style/process guides your project follows

If your project has a second execution environment (a CLI agent, a build server, a separate machine) whose disk is the ground truth, name it too — it is "the implementation channel" below. If you have none, skip the probe step; the canonical files are your highest tier.

The trust ladder (read in increasing order of authority)

1. Ambient memory / chat context — what this conversation already believes. A summary; possibly stale. Baseline only.
2. Canonical files — the durable record. Overrides memory wherever they differ.
3. Ground truth — the implementation channel's disk (real file state, hashes, test results), if one exists. The final authority; everything else is a claim.

When tiers disagree, the higher tier wins. Never act on a tier-1 belief as if it were tier-3 verified. A report is a claim; the artifact is evidence.

Step 1 — Read the canonical files (+ one targeted past-chat search)

Read the canonical files. If the handover references something it doesn't explain ("the X trap", "why Y was reverted") and past-conversation search is available, run ONE focused search to resolve it — a targeted query, not a sweep. Skip if nothing is unclear.

If a file is missing from where you look first, try the project's other access paths (mounted copies can lag an uploaded knowledge base) before concluding it doesn't exist.

Step 2 — Verify load-bearing claims before acting on them

Identify what this session will act on first: anything the handover tagged UNVERIFIED, any status the next action depends on, any number about to be cited.

• If an implementation channel exists: draft a READ-ONLY probe (no edits, no long jobs) asking for on-disk facts only — "report what is on disk; do not infer." Scope it to what the session will act on, not everything pending — each probe costs the user a round-trip. If several items qualify, ask the user which they'll work on, then probe that. Present the probe as a copy-pasteable block.
• If none exists: treat the canonical files as top tier, and explicitly tag anything that is only asserted in the handover as UNVERIFIED in your orientation.

Step 3 — Orient the user, recommend, then wait

## Caught up — <date>

### Where we are (plain language)
[2-4 sentences anyone can act on: state, what last session did, what's next.]

### Verified
[Facts confirmed against the highest available tier — safe to act on.]

### Unverified or desynced
[Claims the probe did NOT confirm, or places the tiers disagree.
Flag them; don't resolve silently.]

### Decisions waiting on you
[Open decisions from the roadmap/tasks, each framed: the choice, the tradeoff,
a recommendation.]

### Recommended next action
[A concrete recommendation WITH reasoning — what to do first, what it unblocks,
what it costs. If two options are close, give both with the tradeoff.
End with: "Confirm and I'll proceed, or redirect me."]

Then wait for confirmation or redirection. Recommend actively — the user expects a reasoned proposal, not a menu — but the user decides.

Rules

• Descend memory → canonical files → ground truth; the higher tier always wins.
• One targeted past-chat search, not a fishing expedition.
• Verify load-bearing facts BEFORE acting; tag what you could not verify.
• Surface desyncs between tiers; never resolve them silently.
• Translate for the user; frame decisions as decisions.
• End with a reasoned recommendation, then wait for confirmation or redirection.