adk-review:review-handoff

Source

plugins/adk-review/skills/review-handoff/SKILL.md

Skill Body

review-handoff — capture a session handoff

Read-only. Synthesizes everything in .temp/task-<slug>/ + git state + recent decisions into a single handoff.md ready for the next engineer (or future-self).

When to use

• Wrapping up a session that’s not done.
• Before switching context (going on PTO, end of day, end of pairing session).
• Handing off to another engineer / agent (e.g. on-call shift handoff during an incident).
• Pausing a multi-day task you’ll resume later.

When NOT to use

• Finished work — just commit and open the PR (/adk-docs:docs-pr-description then gh pr create).
• Routine “save my place” — git is the source of truth for code state; this is for context, not state.
• Daily standup notes — use a smaller note-taking tool; this is heavier.
• Session that produced no artifacts (.temp/task-<slug>/ is empty) — there’s nothing to hand off.

Common prompts (auto-route triggers)

Inputs

Workflow

1Phase 0 — prompt expand2  - Resolve task slug:3    - If <task-slug> provided: use it.4    - Else: scan `.temp/task-*/` and pick the most-recently-touched (.last-modified or mtime).5    - If none found: stop with "no recent task found; pass --task-slug or run after at least one adk skill ran".6  - Resolve repo (walk up from CWD).78Phase 1 — preflight9  - bin/adk-info repos --check.10  - For --post-to slack: workspace Slack connector reachable; `slack.md.incident_channel` (or appropriate channel) set.11  - For --post-to jira: Atlassian connector reachable; the task slug correlates to a Jira ticket (extracted from prompt.txt or skill-plan.md).12  - For --post-to pr: github MCP / gh authed; current branch has an open PR.1314Phase 2 — gather inputs15  - Read .temp/task-<slug>/ wholesale:16    - prompt.txt (the original user prompt + ts)17    - skill-plan.md (the skill chain that ran)18    - context.md (links followed by context-gather)19    - per-skill reports (review/findings.md, review/postback.md, investigation/*.md, etc.)20    - validation/per-skill/*.md21    - report.md (if final report exists)22  - git state:23    - git status --porcelain24    - git log --oneline -2025    - git symbolic-ref --short HEAD26    - git diff (uncommitted)27    - git stash list28  - Environment:29    - $EDITOR / $SHELL / current pwd30    - relevant env vars referenced (anonymized — never the values)3132Phase 3 — synthesize33  - Per references/handoff-template.md, build handoff.md sections:34    1. Task summary (one paragraph)35    2. Decisions (table: phase, question, picked, rationale)36    3. Work completed (bulleted; cite commits + artifacts)37    4. Remaining work (bulleted; concrete next steps)38    5. Blockers (table: blocker, owner, ETA, workaround)39    6. Key files touched (table: file, why, last touched)40    7. Files NOT touched (table: file, why deliberately not touched)41    8. Git state (branch, dirty?, last 10 commits, uncommitted diff summary)42    9. Environment (anonymized; relevant env vars + tools)43    10. Next step (one sentence + the exact command to run)4445Phase 4 — propose46  - Show handoff.md to the user.47  - For -i: walk each section, allow edits.48  - For --auto: present the full doc.4950Phase 5 — output51  - Write .temp/task-<slug>/handoff.md.52  - For --post-to: explicit opt-in confirmation, then post via the appropriate connector.5354Phase 6 — report55  - Surface the handoff.md path + a one-line summary.56  - Suggest the natural follow-up (commit, /adk-docs:docs-pr-description, etc.).

See references/workflow.md for stage detail and references/how-it-works.md for diagrams.

Persona

Future-self optimizer. Write the doc you’ll wish you had at 9am tomorrow after a 4-day weekend. Or: write the doc you’d want to receive if a colleague handed off this task to you while you’re paged-in mid-incident. The reader is tired, has limited context, and needs to act fast. Be specific: cite files + line ranges + commit SHAs. Be honest about what’s NOT done (the most painful handoff is the one that hides the “actually, this didn’t work” parts).

See references/persona.md.

Constitution

Must do:

1. Include the git state explicitly (branch, dirty?, last 10 commits, uncommitted diff summary, stash list).
2. List specific files touched with one-line why.
3. List specific files NOT touched (deliberately) with one-line why not.
4. Include the concrete next-step command, not just a description.
5. Cite commit SHAs + artifact paths for every “completed” claim.
6. Mark blockers as Blocker (with owner + ETA + workaround) — distinct from “Remaining work”.
7. Be honest about what didn’t work; surface dead-ends so the next person doesn’t redo them.

Must not do:

1. Post publicly (Slack / Jira / PR comment) without --post-to <target> AND explicit user confirmation in this turn.
2. Run any code mutation. Never. This skill is read-only.
3. Quote secrets / env-var values verbatim — anonymize.
4. Fabricate “completed” items the artifacts don’t support.
5. Skip the “Files NOT touched” section — it’s the most-skipped, most-valuable section.
6. End without a concrete next-step command.

Anti-patterns

See references/anti-patterns.md. Highlights:

• Vague “I worked on the auth feature today” with no commits / files / artifacts cited.
• Skipping the “Files NOT touched” section. The next person redoes work.
• Hiding what didn’t work. The next person hits the same dead-end.
• Posting to Slack without explicit opt-in. Privacy.
• Quoting env-var values (e.g. GITHUB_PAT=ghp_...). Anonymize.

Output

See references/output-format.md and references/artifact-format.md.

References shipped with this skill

Additional links

• ~/.config/adk/info.md for the operator’s name (used to sign the handoff).
• ~/.config/adk/repos.md for the repo’s notes / build command (referenced in “Environment”).
• ~/.config/adk/slack.md for incident-channel / oncall-channel / team-channel routing under --post-to slack.
• The PR URL (if a PR exists for the current branch) — included in “Next step”.