How to Prompt AI to Write a Handover Document
Ask a model to write a handover document and you get a tidy summary of what you already told it. The useful version starts with questions.
To prompt AI to write a handover document well, do not ask it to write one first. Ask it to interview you. A handover document's entire value is the context living in one person's head, and a model can only summarise what it has been given. Giving it the repository, the tickets and a two-line brief produces something that reads professional and helps nobody. Two rounds of questions first, then the draft, produces something the next person can actually use.
Why Handover Documents Fail
The person writing a handover is, by definition, the worst-placed person to notice what needs explaining. Everything obvious to them is invisible to them. They document the architecture, which is discoverable from the code, and omit that the staging database is restored from production every Tuesday and any test data is wiped, which is not discoverable from anywhere.
AI amplifies this exactly. Feed it your summary and it will organise your summary beautifully. The gaps stay gaps, now with better headings.
Step One: Make It Interrogate You
Start by refusing to let the model write. This prompt does that:
You are helping me write a handover document for a project I am
leaving. Do not write the document yet.
Context: [one paragraph: what the project is, who takes it over,
what their background is, and when you leave]
First, ask me the 12 questions that a competent successor would
most regret not having asked me, in priority order. Favour
questions about things that are not discoverable from the code,
the tickets, or the documentation: undocumented decisions, known
fragilities, informal agreements with other teams, things that
look wrong but are deliberate, and anything that only breaks
once a quarter.
Ask the questions. Do not answer them yourself.The phrase most regret not having asked is doing the work. It points the model at absence rather than at content, and the questions that come back are usually uncomfortable in a productive way. Answer them roughly. Bullet points and half sentences are fine, you are supplying facts and not prose.
Then run one more round: ask what is still missing given your answers. The second round is where the genuinely buried material surfaces, because your first answers reveal the shape of the project and the model can spot holes in that shape.
Step Two: Feed It the Right Raw Material
Alongside your answers, give it artefacts rather than descriptions of artefacts:
The last two or three months of tickets or issues, which show what actually breaks rather than what you remember breaking.
The deployment and rollback procedure exactly as performed, including the manual steps nobody has automated.
The list of third-party accounts, who owns each one, and where billing lands.
Any runbook, however stale, plus a note saying which parts are stale.
Recent incident notes, which are the highest-value input per word in the whole set.
Withhold credentials entirely. Not redacted, not partially, not in a prompt you intend to delete. Access transfers happen in a password manager and are referenced by name in the document, never by value.
Step Three: Constrain What It Writes
Now let it write, with the shape specified. Handover documents get read in a hurry by someone under pressure, so the structure matters more than the prose.
Section | What goes in it | Why it earns its place |
|---|---|---|
Start here | The three things to do in the first week | The reader is overwhelmed and needs a first action |
How to run it | Local setup, deploy, rollback, exactly as performed | The most immediately needed and most often wrong section |
What breaks | Known fragilities, with symptoms and the actual fix | Saves the successor's first bad week |
Decisions and why | Choices that look wrong but are deliberate | Prevents a well-meaning rewrite of something load-bearing |
People and accounts | Who to ask about what, who owns which account | Rarely written down anywhere and rots fastest |
Calendar | Anything recurring: renewals, audits, quarterly jobs | Invisible until it is late |
Ask for the what-breaks entries in symptom, cause, fix order, because the successor will arrive at them through the symptom. Ask for the decisions section to be written as plain statements rather than justifications: the goal is to stop someone undoing something, not to win an argument.
Step Four: The Pass Everyone Skips
Give the finished draft back to the model with fresh framing:
Here is the handover document. You are the person receiving this
project on their first day. You have never seen this codebase.
List every place where you would have to ask a follow-up question
before you could act. Quote the exact sentence and say what you
would need to know. Be literal, not generous.Be literal, not generous is the operative instruction, since models default to reading charitably and a handover needs a hostile reader. This pass reliably catches the sentences that made sense only to you, which is the failure mode the whole exercise exists to prevent.
What a Weak Entry Looks Like Next to a Strong One
The difference between a handover that works and one that does not is visible at the level of individual sentences. Both of these describe the same fact:
Weak: The nightly sync job is occasionally unreliable and may need attention.
Strong: The nightly sync fails roughly once a month, always with a timeout in the vendor API call, always between 02:00 and 02:30 when their side is under load. It is safe to re-run: the job is idempotent on order id. Re-run with the make command in the deploy repo. If it fails twice in a row it is not the timeout, and you should check whether their schema changed.
The weak version is true and useless. The strong version contains the frequency, the symptom, the safety property, the command, and the point at which the usual explanation stops applying. A model will produce the weak version from a brief and the strong version only if you answered a question that pulled the specifics out of you. That is the entire case for the interrogation step.
When you review the draft, grade every entry in the what-breaks section against that standard. Anything that reads like the weak version is a question you have not answered yet.
When to Start
Start the interrogation round about two weeks before you leave, not in the final days. The questions surface things you need time to check, and some of them will turn out to be wrong: a process you believed was automated, an account you thought someone else owned, a cron job that has been failing silently for months.
Those discoveries are a large part of the value, and they are only useful while you are still there to act on them. A handover written in the last afternoon is a summary. One started a fortnight out becomes an audit, which is a considerably more useful thing to leave behind.
What Not to Hand Over to the Model
Beyond credentials, keep out anything about people. Performance concerns, interpersonal friction, and opinions on colleagues do not belong in a document that will be forwarded further than you expect. If the successor needs to know that a particular team takes three weeks to respond, write the fact and not the characterisation.
Client contract terms deserve the same care. Reference the agreement, do not paraphrase it, because a paraphrase in a handover document has a way of becoming the version people rely on.
Related Prompting Patterns
The interrogate-first shape transfers. It is the same underlying move as getting a design doc out of a model rather than a description of one, and it is close kin to turning a process you perform by habit into a written procedure. If your handover is for a client engagement rather than an internal move, the proposal structure covers the commercial half this document deliberately leaves out. For the general principles behind prompts like these, Anthropic's prompt engineering overview is a solid reference.
Frequently Asked Questions
How long should a handover document be?
Long enough that the what-breaks section is complete, short enough to be read in one sitting, which in practice means two to six pages. Length is a poor proxy for quality here. A one-page document naming the five real hazards beats twenty pages of architecture description.
Can I just record a video instead?
Record the video and then transcribe it as the raw material for this process. Video is excellent for capture and terrible for retrieval, since nobody scrubs through forty minutes of screen recording to find the deploy command. See turning a recording into structured notes for the capture half.
Should the successor review the draft before I leave?
Yes, and ideally they should attempt one real task using only the document while you stay quiet. Every question they have to ask out loud is a defect to fix while you are still there to fix it.
What if I am handing over to nobody in particular?
Write for a competent stranger arriving in six months with no access to you. That framing is stricter than writing for a named colleague and produces a better document, so it is worth using even when you do know who is taking over. More patterns like this live in the prompting guide.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
