The runbook your software handover should include

A software handover should include a tested runbook for the tasks the receiving team must perform without the original developer. Repository access and an architecture diagram are necessary context, but they do not explain how to recover a stuck job or determine whether a deployment worked.

The acceptance test is practical: can someone with the intended access follow the procedure and produce the expected outcome?

Organize procedures around work, not components

Start with recurring operational tasks: deploy a release, investigate a failed integration, restore data in a safe environment, and revoke a departing user’s access. Each deserves a procedure with a clear entry condition. A chapter called “Database” does not tell an operator when to use it.

AWS’s runbook guidance calls for required tools and permissions, error handling, escalation, and validation by another team member. Those are useful handover acceptance criteria regardless of hosting provider.

Keep procedures near their ownership and change process. If a deployment change makes a runbook inaccurate, updating it belongs in the same delivery work. A document that only gets reviewed at contract renewal will drift.

Give each procedure a complete operating envelope

Use this checklist for every consequential procedure:

• State the intended outcome and when the procedure does not apply.
• List environment, access role, tools, and prerequisites.
• Show steps with safe placeholders and expected observations.
• Include stop conditions before destructive or ambiguous actions.
• Explain recovery, verification, and escalation if the result differs.
• Record the owner and the last successful rehearsal.

Link to the approved secret-management location rather than copying credentials into the runbook. Distinguish staging from production visibly. If rollback cannot reverse a database migration, say so and provide the actual recovery decision instead of a generic “redeploy the previous version.”

A hypothetical stalled export

Suppose the receiving team must recover an export job stuck after a provider timeout. “Restart the worker” is an incomplete instruction: the remote system may already have accepted the export.

The runbook first asks the operator to find the operation ID and inspect its durable state. It then describes checking the destination reference. A confirmed existing record is reconciled locally; a confirmed safe retry uses the same operation identity. An unknown destination outcome triggers escalation rather than a fresh submission.

Verification includes the destination record, the local terminal state, and absence of duplicate business actions. The procedure also tells support what status can be communicated while reconciliation is pending. These are hypothetical steps to adapt, not commands to execute blindly against an unfamiliar system.

Rehearse before calling the handover complete

Have the receiving operator run a bounded exercise in a safe environment while the author observes without taking over. Missing permissions and unexplained assumptions belong on the handover issue list, even if the original developer could fix them quickly.

For Costa Rica and US teams sharing operations, document coverage hours and the next responsible person explicitly. Time-zone overlap does not establish after-hours ownership. Agree on the language of operational instructions so the on-call reader can use them under pressure.

Before the next delivery sign-off, select one recovery procedure for an independent rehearsal. Include its unresolved gaps in the custom software development handover scope, then repeat the blocked steps with the receiving operator once the corrections are in place.