Codebase Handoff Checklist

Test a Route Through the Work

A codebase is not handed off when its folders have been described. It is handed off when another engineer can take a bounded change from a clean checkout to a safe release without the founder supplying missing context at every step.

Use this checklist before a contractor or first engineer begins consequential work. Choose one real assignment that crosses the parts of the product they will need to understand. A useful rehearsal is small enough to review and rich enough to expose private knowledge: add a validation rule, change a permission, repair an import, or trace a failed notification. “Explore the repository” is not an assignment.

Run the rehearsal with normal collaborator access. The founder may answer a question, but every answer becomes evidence of a gap. Repair the code or tooling when that is the durable fix; document stable knowledge; define an escalation boundary when the decision should remain with the founder.

Define the Handoff Change

Write the test before improving the documentation:

HANDOFF REHEARSAL

Collaborator:
Bounded change:
Customer or operating outcome it protects:
Acceptance evidence:
Representative local data or fixture:
Systems and integrations touched:
Production actions allowed:
Founder-retained decisions:
Conditions that require a stop and escalation:

The assignment should reveal product judgment as well as code mechanics. If a developer is changing duplicate handling in a customer import, for example, they need to know whether a duplicate is an error, a legitimate branch, or an old customer mapping that must remain intact. A tidy implementation can still break the product promise.

Follow the Change from Checkout to Recovery

Work through the route in order. Mark an item complete only when the collaborator can demonstrate it or find the answer without live narration.

1. Find the Product Boundary

• The repository states who uses the product, which core workflow creates value, and what that workflow must preserve.
• The assignment names its customer consequence and acceptance evidence.
• Current product assumptions, deliberate exclusions, and legacy behavior that protects real users are findable.
• Decision rights are explicit: the collaborator knows what they may decide and what must return to the founder.

This context should be short enough to remain current. It is not a pitch deck. Its purpose is to prevent a technically plausible change from violating a customer promise.

2. Reach a Representative Local State

• The README leads from a clean checkout to a running product using the supported runtime, package manager, services, migrations, and commands.
• A safe environment example names every required variable, its purpose, and the approved source for any secret. No real secret is stored in the repository.
• Seed data or fixtures exercise the assigned workflow and its important edge case; a blank dashboard is not treated as proof of setup.
• Test, lint, format, and build commands are accurate, and known flaky or unsupported paths are named honestly.

Observe the setup without taking over the keyboard. A spoken workaround leaves the defect in place for the next person.

3. Trace the Working System

• The architecture overview follows the relevant request, job, event, or data flow rather than merely listing directories.
• Entry points, service boundaries, background work, storage, external integrations, and environment differences are visible where relevant.
• The data model defines important product terms, ownership, tenancy, and trust boundaries; legacy names that look interchangeable are explained.
• APIs or events touched by the change have discoverable contracts, callers, failure behavior, and compatibility obligations.
• Coding conventions cover the decisions that protect safe change, such as authorization, error handling, migrations, retries, and backfills.

Prefer links to stable entry points over a copied inventory of volatile internals. The map may admit rough edges. It must not conceal them.

4. Prove the Change

• Automated checks and manual checks are distinguished; neither claims coverage it does not provide.
• The collaborator can connect each acceptance check to a customer, security, data, reliability, or operating consequence.
• Representative normal, failure, permission, and legacy paths are covered to the degree their risk requires.
• Review expectations say what evidence to present, not merely “follow best practices.”

When automation is thin, write a concise manual path. Honest limited evidence is safer than a green command that never exercises the product behavior.

5. Release, Observe, and Recover

• The supported deployment path names access, commands or automation, configuration, migration order, and approval boundaries.
• A post-release check proves the changed customer workflow, not only that processes are running.
• Logs, metrics, traces, alerts, and support signals needed for this change are findable, with normal and failure signals identified.
• The first safe response to failure is written: pause work, disable a feature, stop a worker, roll back, restore, or repair forward.
• Runbooks name who may take consequential or destructive recovery action.

“Rollback” is not sufficient guidance when a migration has changed data or a job has already produced an external effect. Record the actual recovery boundary.

6. Expose the Hazards and Keep the Route Alive

• Known debt records who or what depends on it, how failure appears, the current mitigation, and the condition for safe removal.
• Short decision records preserve non-obvious choices that a newcomer might otherwise simplify away.
• The README points to product context, architecture and data notes, verification, deployment, runbooks, decisions, and known debt without making the reader search several systems.
• Each maintained document has an owner and an event that should update it.

Do not catalog every inelegant line. Prioritize hidden knowledge with high blast radius or high interruption cost: setup, customer trust, data ownership, permissions, deployment, recovery, and the core workflow.

Record What the Rehearsal Revealed

HANDOFF RESULT

Change completed or stopping point:
Evidence reviewed:
Questions that required founder narration:
Durable fixes made in code or tooling:
Stable knowledge documented, and where:
Decisions assigned an escalation boundary:
Known hazards the collaborator found before touching them:
Remaining blocker and owner:
Rehearsal date:
Next review trigger:

The codebase is ready for this assignment when the collaborator can explain the product constraint, run representative data, trace the workflow, make and verify the change, ship through the supported path, recognize failure, and stop or recover safely. This is readiness for real work, not a claim that the repository is complete.

Delay the handoff when setup still requires live narration, the customer promise is absent, a dangerous path is hidden, or release and recovery remain founder rituals. If one gap blocks the route, fix that gap first. Do not begin a documentation campaign whose scope is “everything.”