repo-handoff

Repo Handoff Skill

A handoff is the moment a codebase changes hands: one team stops owning it, another starts. Most of what the outgoing team knows is not in the repo — which account owns the DNS, why that migration was never run, which cron job must not overlap, who gets paged. This skill reads the repo from the receiving team's point of view, records everything the code does answer, and turns everything it doesn't into a concrete, prioritized list of questions for the previous team — so the knowledge-transfer meeting is spent on the real gaps, not on things grep could have told you.

The analysis is read-only with exactly one write: the finished report is printed in chat and saved to docs/repo-handoff.md at the analyzed repo's root (docs/ is created if missing; the file is overwritten on re-run, preserving answers already filled in). Nothing else is created, edited, committed, or pushed.

Discovery — Do This First

Classify the project before analyzing anything. Every check in references/dimensions.md depends on knowing the stack and where things live.

1. Detect the stack(s) from manifests at the root and in workspace globs (package.json#workspaces, pnpm-workspace.yaml, turbo.json, Gemfile in subdirs, pyproject.toml, go.mod, *.csproj, pubspec.yaml, app.json/eas.json).

2. Inventory the written knowledge — read in full, don't skim: README*, CONTRIBUTING*, docs/**, AGENTS.md, CLAUDE.md, CHANGELOG*, ADRs, wikis checked into the repo, .env.example, docker-compose*.yml, Dockerfile*, .github/**, .gitlab-ci.yml, config/deploy*, terraform/, infra/, Procfile, fly.toml, render.yaml, vercel.json, app.yaml.

3. Mine the history — git log, git shortlog -sn, git branch -a, tags, open PRs/issues via gh if available. Authorship concentration, last-activity dates, and unmerged branches are the handoff's early-warning signals.

4. Enumerate every external touchpoint — anything the code talks to that lives outside the repo: databases, queues, SaaS APIs, payment providers, email/SMS, auth providers, object storage, CDNs, analytics, error tracking, app stores, domains. Each one is an account someone owns and a credential someone holds — the two things most often lost in a handoff.