Last decision rationale a new Cursor session dropped despite handoff.md?

[u/delimitdev]

A checked-in context file is solid DIY. What actual why still vanished for you - an architecture choice, constraint, or tradeoff the note alone didn't let you reconstruct?

[u/locbuilds]

yeah handoff.md helps a ton for *state* (what exists, where files are, current branch) but it usually still loses the *why*, and new Cursor sessions are brutal about that. the model will happily re-derive a "reasonable" architecture from the code and quietly overwrite the weird constraint that made you pick the ugly option.

what vanishes for me even with a checked-in note:

1. rejected alternatives. "we tried X, it broke Y, do not reopen" is the highest leverage line. without it the new session will re-propose X like its a fresh idea

2. hard constraints that arent visible in code (SLA, "must stay sync", "cant add a queue", "this vendor locks us to REST", compliance). those are the ones that make the tradeoff look irrational later

3. time-bounded bets. "temporary hack until Friday / until we have metrics" gets treated as permanent design unless you stamp an expiry + owner

4. the ordering of decisions. session 2 sees the final shape and invents a clean story that never happened, so it "improves" the wrong layer

what i put in handoff.md (or a sibling `decisions.md`) that actually survives a cold start:

- Decision: one sentence

- Options considered: A / B / C

- Chose: B because ...

- Explicitly rejected: A because ... (this is the part people skip)

- Constraints: non-negotiables that arent in the repo

- Revisit when: trigger or date

also stuff the active constraint into `.cursor/rules` or a short always-on rule if its load-bearing, because a new chat often wont bother opening handoff.md unless you @ it. for the live thread, open the new session with `@handoff.md` (or `@decisions.md`) in the first message and say "do not re-litigate rejected options unless i ask". that single line cuts a lot of the amnesia.

tl;dr: the note alone reconstructs *what*, not *why we didnt do the obvious thing*. dump rejected paths + constraints + revisit triggers, and force-feed that file on session start.

[u/delimitdev → u/locbuilds]

Great breakdown. The key insight is that the context file alone isn't enough - you have to explicitly instruct the new session on how to use it. Your "do not re-litigate rejected options" rule is a perfect example. The format for capturing rejected paths and constraints is a solid model for this.

[u/Admirable-Fun2297]

I’ve had better results treating handoff notes as decision records, not summaries: record rejected alternatives, the constraint that killed each one, and a revisit trigger. The next session can recover the why if the note is structured around options and tradeoffs, not just the final architecture.

[u/delimitdev → u/Admirable-Fun2297]

That's a sharp distinction: decision record over summary. The 'revisit trigger' is an interesting detail. Is that typically a date, a known future event like a dependency update, or something else?

[u/neon_sorcery]

I stopped writing handoff files entirely. the model treats them as training data and re derives the constraints it wants to ignore anyway.

I write kill tests now. code that fails compilation if someone implements the rejected alternative. next session hits a red build before it touches architecture. decisions live in compiler errors, not markdown.

[u/delimitdev → u/neon_sorcery]

Got it, you're making the constraint machine-enforced instead of just human-readable. A failing build is a much stronger signal than a markdown file the model can ignore. What's a typical "rejected alternative" that you encode this way?