Test and Debug Handoff

Stabilize evidence before transferring work

Capture the exact revision, environment, command or user action, deterministic inputs, earliest meaningful failure, expected behavior, observed behavior, and whether the failure reproduces from a clean state. Preserve relevant logs and artifacts without secrets or unnecessary personal data.

Separate observations from hypotheses. Record experiments already attempted, including negative results and reverted changes, so the next investigator does not repeat them. If an external action may have partially succeeded, reconcile the system of record before anyone retries it.

Write a reproducible handoff

Keep the next action bounded and falsifiable. If the failure cannot be reproduced, state that explicitly and preserve the original evidence rather than declaring it fixed.

Goal and acceptance criterion: [OUTCOME -> CRITERION]
Revision and worktree: [COMMIT, BRANCH, LOCAL CHANGES]
Environment: [OS, RUNTIME, DEPENDENCIES, CONFIG CLASS]
Reproduction: [PRECONDITIONS, INPUT, EXACT COMMAND/STEPS]
Expected: [OBSERVABLE RESULT]
Observed: [OBSERVABLE RESULT]
Failure signature: [FIRST RELEVANT ERROR, TEST ID, LOG REF]
Frequency: [ALWAYS | INTERMITTENT WITH RATE | ONCE]
Clean-state result: [RESULT OR NOT RUN WITH REASON]
Known-good comparison: [VERSION/ENVIRONMENT -> RESULT]
Observations: [VERIFIED FACTS]
Hypotheses: [HYPOTHESIS -> DISPROVING TEST]
Experiments completed: [CHANGE/TEST -> RESULT -> REVERTED?]
External side-effect state: [VERIFIED STATE | NONE]
Sensitive data removed: [YES | APPROVED EXCEPTION]
Next bounded action: [ONE TEST OR INSPECTION]
Done when: [PASSING EVIDENCE OR CONFIRMED ROOT CAUSE]
Rollback/recovery: [REVERT CHANGE, RESTORE FIXTURE, OR COMPENSATE SIDE EFFECT]
Owner and escalation condition: [OWNER -> WHEN TO ESCALATE]

Expected evidence and verification

The expected evidence is a handoff that lets a different contributor reproduce or conclusively classify the failure without relying on hidden session context.

Have the recipient run the reproduction from the named revision and confirm the signature before editing. Verify artifact links are accessible, secrets are absent, attempted changes are identified, and the next test can disprove at least one hypothesis. Close the handoff only with passing acceptance evidence or a documented disposition and owner.