Software projects
Hand off a software project with known issues visible
A good handoff tells the next maintainer what works, how to run it and what is broken. List each known issue with a symptom someone can reproduce, a workaround if one exists and a named owner. Leave out general warnings that give them nothing to act on.
A text to start with
I'm handing [project name] to [next maintainer or team]. Current state: [what runs, what doesn't]. Setup notes I have: [steps or links]. Known problems: [list]. Draft a handoff document with the running state, a pointer to setup, and one entry per open issue with its symptom, steps to see it, any workaround and an owner. Mark anything I haven't confirmed.
Example request. Change the details to fit your situation.Software handoff and known issues
Project: [ ] Handed to: [ ] Date: [ ] What runs today: [ ] What does not run: [ ] Setup reference: [ ] Last date setup was verified: [ ] Open issue: [ ] Symptom a person can see: [ ] Steps to reproduce: [ ] Workaround: [ ] What the workaround does not cover: [ ] Owner: [ ] Where it is tracked: [ ] Confirmed or suspected: [ ] Decisions not written down elsewhere: [ ] Person to ask about them: [ ]
Warnings without a next step
Phrases like "be careful with the import" or "this part is fragile" leave the next person guessing. Each issue needs something observable: what they will see, the steps that trigger it and what to do next. Check that every workaround says how long it has been in use and what it doesn't cover. Confirm that setup steps still match the current project, since stale instructions cost new maintainers time. Mark issues you suspect but have not reproduced as suspected, so they aren't mistaken for confirmed bugs.
Ask another agent to check the result
Find warnings in this handoff that lack a reproducible symptom or a next step. List each vague entry, say what information is missing and suggest the question to ask its author. Also flag setup steps that cannot be followed as written.
Walk through it with the new owner
Ask the next maintainer to follow your setup steps on a clean machine and note where they get stuck. Fix the document from what they report. Confirm that each open issue has a person assigned and a place where it is tracked. Keep a short list of who to ask about decisions you made but never wrote down.