Technical Handoff Docs

---
name: technical-handoff-docs
description: >
  Write clear technical documentation that lets someone else pick up a project: READMEs, handoff
  docs, runbooks, API documentation, architecture overviews, and onboarding guides. Use when a
  developer needs to document a codebase, hand a project to a coworker, write setup instructions,
  document an API, create a runbook for operations, or explain how a system works. Triggers on
  "write a README for my project", "handoff doc for my coworker", "document this API", "runbook for
  deployment", "onboarding guide for the repo", "explain this architecture", or when someone pastes
  code/config and needs it documented. Optimizes for the reader who has zero context and needs to be
  productive fast.
---

# Technical Handoff Documentation

Write docs that actually get someone unstuck. The test of technical documentation is simple: can a
competent person with zero prior context read it and become productive without asking you questions?
Most docs fail this because they're written by someone who forgot what it's like not to already know.

---

## The reader-first principle

Write for the specific person who will read this: a new hire, a coworker taking over, or future-you
who forgot everything. Assume they're smart but have zero context on THIS project. Every assumption
you leave implicit becomes a question they have to interrupt someone to answer - which defeats the
purpose of documentation.

---

## Document types and what each needs

### README (project front door)

The most-read doc. Someone lands on the repo - what do they need immediately?

```
1. What is this?        - One paragraph. What the project does and why it exists.
2. Status               - Is it prod, WIP, deprecated? Don't make them guess.
3. Quick start          - Copy-pasteable steps to run it locally. The #1 thing people want.
4. Prerequisites        - Exact versions (Node 20+, Python 3.11, etc.). Vague versions waste hours.
5. Setup / installation - Step by step, actually tested. Include env vars needed.
6. Usage                - How to use it once running. Key commands/endpoints.
7. Project structure     - What lives where (brief map of key directories).
8. Configuration        - Env vars, config files, what each does.
9. Deployment           - How it gets to production (or link to the runbook).
10. Troubleshooting     - Common errors and fixes. Grows over time.
```

Not every README needs all ten. A library needs usage + API; a service needs setup + deployment.
Match the sections to what a reader of THIS project actually needs.

### Handoff document (project transfer)

When one person hands a project to another. Beyond the README, cover:

```
- Current state         - What's done, what's in progress, what's broken right now
- What's left           - Remaining tasks, ideally prioritized, with context on each
- Known issues / gotchas - The things that will bite them that aren't obvious from code
- Key decisions          - Why things are the way they are (saves them re-litigating)
- Access & credentials   - What accounts/services/keys they need (NEVER paste secrets - say where to get them)
- Contacts              - Who to ask about what (you, vendors, other teams)
- The "if I had more time" list - What you'd do next
```

The gotchas and key-decisions sections are the highest-value part of a handoff - they transfer the
context that isn't in the code.

### Runbook (operational procedures)

For recurring operational tasks (deploy, rollback, incident response):

```
- When to use this      - The trigger/situation
- Prerequisites          - Access, tools needed
- Steps                 - Exact, numbered, copy-pasteable. No ambiguity under pressure.
- Verification          - How to confirm it worked
- Rollback              - How to undo if it goes wrong
- Escalation            - Who to call if stuck
```

Runbooks are read during stress (things are down). Optimize for zero ambiguity, not elegance.

### API documentation

For each endpoint:
```
- Method + path         - GET /api/v1/users/:id
- What it does          - One line
- Auth required         - What kind
- Parameters            - Each param: name, type, required?, description
- Request example       - Actual example with realistic values
- Response example      - Actual JSON, success case
- Error cases           - Status codes and what they mean
- Rate limits / notes   - Anything else that bites people
```

---

## Writing rules

- **Show, don't describe.** A copy-pasteable command beats a paragraph explaining what to type.
- **Exact versions and values.** "Node 20.x", not "recent Node." Vagueness costs hours.
- **Test your own instructions.** If you can, run the setup steps fresh. Docs that don't work are
  worse than no docs - they destroy trust.
- **Front-load the common case.** What 90% of readers need goes first. Edge cases go later.
- **Explain the why for non-obvious choices.** "We use X because Y" prevents someone undoing a
  deliberate decision.
- **Keep it scannable.** Headers, code blocks, short sections. People scan docs, they don't read prose.
- **Never paste secrets.** Say where to obtain credentials (password manager, vault, a person), never
  the actual keys/passwords in the doc.

---

## The gotchas section is gold

The single highest-value thing in any handoff is the list of non-obvious traps:
- "The build fails silently if you don't set X"
- "This service must start before that one"
- "The staging DB has different schema - don't test migrations against prod data"
- "That function looks unused but the cron job calls it"

These are the things that would take the next person days to discover and cost you a 2am call.
Capture them explicitly.

---

## Hard rules

- Never include actual secrets, passwords, API keys, or tokens in documentation. Reference where to
  get them securely instead.
- Don't document aspirational behaviour - document what the code actually does now. Note WIP clearly.
- If you're unsure how something works, flag it as "unverified - confirm before relying on this"
  rather than guessing confidently.