ai-instructions: Skill for Cursor

Handoff

Long threads die two deaths: the context window fills up, or the human walks away for a week. Either way, restarting from nothing costs hours of re-explaining, and worse, silently loses decisions, so the next session relitigates settled questions and repeats rejected approaches. A good handoff document is the difference between "continue" and "start over".

The core insight: a handoff is a state snapshot, not a story. The next reader does not need to know what happened in what order; they need to know where things stand, what's been ruled out, and what's next. The number one failure mode of conversation summaries is chronological narration ("First we discussed X, then we explored Y..."), which buries the actionable state under a play-by-play nobody needs.

Step 1: Identify the recipient

The document differs by who receives it. Infer from context or ask one question:

• New AI session (most common): optimized for pasting into a fresh chat. Includes working preferences, exact constraints, and ends with a paste-ready opening prompt.
• Human colleague: more background on why the work exists, less instruction-style framing, no opening prompt.
• Future self: leans on reminders of intent ("you chose X because the client hated Y") since they'll half-remember everything.

Step 2: Mine the conversation for what actually transfers

Re-read the whole thread and extract, in priority order:

1. Decisions and their reasons. Not just "we chose PostgreSQL" but "chose PostgreSQL over SQLite because of concurrent writes". Without the reason, the next session reopens the decision.
2. Dead ends. Approaches tried and rejected, and why. This is the most valuable and most-omitted section of any handoff: it is the only thing standing between the next session and re-exploring every failed path. If something was rejected for a fixable reason, say so.
3. Corrections the user made. Every time the user pushed back ("shorter", "not that tone", "the deadline is Friday not Monday"), that correction is a preference paid for once and must never be paid for again. Sweep the thread specifically for these; they hide in throwaway lines.
4. Constraints stated once. A requirement mentioned in message 3 and never repeated still governs everything. Recency is not importance. This is exactly what naive summaries lose.
5. Artifact state. Every file, draft, or deliverable produced: its name, where it lives, and its status (final / draft / superseded). When there were multiple versions, only the current one and what distinguishes it. Never make the reader guess which version is live.
6. Open items. What is in progress, what is blocked and on what, and the single concrete next step.