Leave a "Handover Card" for Automated Tasks: Get the Next Person Up to Speed in 10 Seconds

Late last night, while troubleshooting a scheduled task that runs in the middle of the night, I asked three AIs and checked two documentation sources for answers to "When was the last successful run?" and "Which logs should I check if it fails?" None of them gave me an answer. The task itself wasn't dead, but no one could clearly state its current status—this state of being "alive but opaque" is more dangerous than the task simply crashing.

From this experience emerged the concept of a "Handover Card": any automated task I write must include a fixed-format description upon deployment. The card isn't complex; it consists of four sections:

Task: sfd-daily-skill-1400
Purpose: Publishes a short skill article daily at 14:00 (SGT)
Dependencies: Local routing / CMS API / sfd-article-publish.py
Last Run: PASS (Report located at reports/daily-pipeline/sfd-daily-skill-20260910.md)

A card without the "Last Run" section is considered incomplete. The real loss occurs when a task has been down for so long that no one remembers how long it's been dead.

When to Use It

- Tasks that run long-term (cron jobs, CI pipelines, watchers), with a lifespan exceeding your "forget-after-a-few-days" memory window

- Scripts involving external dependencies: routing, databases, third-party APIs

- Any incident where a successor had to debug a script in the dark—regardless of whether they fixed it, it’s worth documenting

- Any workflow handed over to another person or agent; even if separate business logic documentation exists, this card is still required

When Not to Use It

- One-off scripts: querying data, generating a report, then deleted—don’t waste a card on these

- Tasks reproducible within five minutes: a verbal explanation suffices

- Tasks that already have a complete runbook in the documentation library—don’t create a duplicate, inconsistent version

Handover Card Checklist

□ Clearly state "what problem it solves" in one sentence, without piling on adjectives

□ List dependencies: services, credential file locations (filenames only, never actual values), script paths

□ Record the date and location of the last successful run

□ Specify where to look when things fail: log locations, report locations

□ For tasks that modify production state (publishing, deleting data), explicitly note this in the "Purpose" line

Pitfalls Encountered

- **Listing purpose but omitting failure entry points**: A card with "Purpose" but no "Where to look when things go wrong" is the root cause of pain during early-morning outages. Both fields are mandatory.

- **Making it too long**: If the card exceeds one paragraph, you’re likely trying to cram in an unresolved concept. Cut it down to four lines.

- **Writing it once and never updating**: If the "Last Run" information is outdated, the card is useless. Performing a routine update after every PASS/HOLD/BLOCKED status is the cheapest form of insurance.

- **Leaking actual secrets into the card**: Passwords and tokens should only reference "stored in [filename]," never include actual values; logs, like the card, are documentation.

The next time I open that task list, I hope to look at my own words and say: Every task knows who it is.