Codebase Handoff Checklist

Handoff Is a Rehearsal

A codebase is not handed off when another person can browse its folders. It is handed off when they can take a bounded, customer-relevant change from a clean checkout to a safe release without the founder supplying the missing system from memory.

Use this checklist before work goes to a contractor or first hire, during technical due diligence, or when testing whether a future version of you could recover the product after months away. Do not begin by documenting everything. Choose one representative change and let the work reveal which knowledge is still private.

The task should cross the paths a collaborator will actually need: product intent, local setup, a core workflow, verification, deployment, and recovery. Avoid a cosmetic change that proves only that the repository can be opened.

Choose the Proof Task

Write a task brief before improving the documentation:

• Customer outcome: What useful behavior should change?
• Boundaries: Which behavior, data, or customer promise must remain unchanged?
• Acceptance evidence: What observable result proves the change works?
• Highest-consequence mistake: What plausible implementation could harm a customer, corrupt data, weaken trust, or make recovery harder?
• Safe stopping point: When should the collaborator stop and ask rather than guess?

A useful proof task is small enough to complete, but consequential enough to expose the real codebase. Examples include adding a validation rule to an import, changing a billing-state transition, or repairing a background job without duplicating its external effect.

Prepare the Handoff Brief

Copy this brief into the repository or onboarding workspace. Link to maintained sources instead of copying volatile detail. Replace an irrelevant prompt with Not applicable and the reason.

# Codebase handoff: [product or repository]

Proof task:
Customer outcome:
Behavior that must not change:
Acceptance evidence:
Highest-consequence mistake:
Stop and escalate when:

[PRODUCT CONTEXT]
Current customer and product promise:
Core workflow this task touches:
Important product assumptions or legacy commitments:
Out-of-scope behavior:

[START FROM A CLEAN CHECKOUT]
Supported runtime, package manager, and operating environment:
Install, migration, seed, and start commands:
Representative local data and how to reset it:
Environment-variable reference and source of authorized secrets:
Fake or sandbox adapters that prevent contact with customers and production:
Lint, type, test, format, and build commands that carry real confidence:
Known setup failure or flaky check, including the honest workaround:

[TRACE THE WORKFLOW]
Customer action and application entry point:
Authorization and trust boundary:
Core objects and product meaning of ambiguous names:
Durable state and ownership of that state:
Jobs, retries, integrations, and external effects:
Normal signals, failure signals, logs, metrics, and support view:
Architecture note or decision record that constrains this change:

[MAKE AND VERIFY THE CHANGE]
Existing convention the implementation should follow:
Focused automated proof:
Important failure-path proof:
Manual customer-visible check:
Data, permission, migration, compatibility, or performance risk:
Known gap the current checks do not cover:

[RELEASE AND RECOVER]
Who can deploy and how access is granted:
Supported release path and order of config, migration, app, and worker changes:
Post-release proof and observation window:
How to pause, disable, roll back, or repair forward:
External effect or data change that an application rollback will not undo:
Runbook and escalation owner for a failed release:

[KNOWN DEBT AND OWNERSHIP]
Hazard likely to be mistaken for harmless mess:
Customer, workflow, or system that still depends on it:
Current containment and condition for safe removal:
Deferred decision and why it remains deferred:
Questions that still require founder product judgment:
Documents or tools that this task proved stale:

Keep real credentials out of the brief. A collaborator needs to know which access exists, what it permits, who grants it, and how to use a safe local substitute. They do not need a secret copied into another file.

Run Without Founder Narration

Give the collaborator the repository, the proof task, normal access, and the handoff brief. Let them work through it. The founder may stop an unsafe action, but should not quietly complete setup, point to files, translate product terms, or explain a deployment ritual. Those interruptions are the evidence the rehearsal is meant to collect.

For each interruption, choose one durable response:

1. Fix the system. Repair a broken script, remove a dead path, provide representative seed data, or make failure visible.
2. Put stable knowledge where it is needed. Improve the README, product context, workflow map, decision record, test guidance, release procedure, runbook, or debt note.
3. Define the judgment boundary. State when the founder must still decide and what evidence the collaborator should bring.

Prefer a durable fix when it is cheaper than preserving a workaround. A setup script that works is stronger than a paragraph explaining how to rescue it. A safe admin action is stronger than a twelve-step database ritual remembered by one person.

Example: The Second Import Path

A property-maintenance product uses an import to connect vendor records with customer buildings. The proof task is to reject duplicate vendor identifiers during preview while preserving an older mapping used by retained customers.

The repository starts, but the rehearsal stalls. Seed data has no representative building or vendor records. Two import paths exist, and nothing says which customers use the older one. The tests cover parsing but not the preview-to-commit boundary. Only the founder knows that deployment starts workers after the application migration, or that preview failures appear in a particular metric.

The useful handoff work is now precise. Add representative import data, trace upload through preview and commit, record the legacy customer’s dependency, prove that a conflict does not commit records, and write the release and disable path. There is no need to document every directory. The collaborator needs a truthful route through this change and an explicit warning around the path that looks obsolete but is not yet safe to remove.

Decide Whether Work Can Travel

The handoff is ready when a competent collaborator can, without live founder commentary:

• explain the customer promise and the boundary the proof task must protect;
• create a representative local state from a clean checkout;
• trace the affected workflow through code, data, jobs, and integrations;
• make the bounded change and prove its important failure path;
• release through the supported process or stop safely;
• recognize failure, begin recovery, and find the known hazards before touching them.

If the rehearsal fails, do not compensate with a larger documentation inventory. Repair the first missing piece that blocks safe independent work, then run the same proof task again. The handoff is complete when the work can travel, not when every prompt contains text.