XzhLoongSkills/skills/essential/handoff-doc/SKILL.md

---

name: handoff-doc

description: Generate comprehensive handoff documentation when transitioning work to another agent or developer. Documents current state, decisions, blockers, and next steps for seamless context transfer.

Handoff Document Generator

Generate a structured handoff document when transitioning work. Run this before pausing, switching context, or transferring to another agent.

When to Use

• Pausing work mid-task and resuming later
• Transferring to another agent or developer
• Switching branches or contexts
• End of session / work shift handover
• Project status checkpoint

Process

1. GATHER: Collect all context about current work
2. STRUCTURE: Follow the handoff template
3. WRITE: Generate handoff document
4. VERIFY: Check for completeness

Information to Gather

CURRENT STATE:
- What was I working on? (task, branch, files)
- What is complete? (commit/task IDs)
- What is in progress? (partial work, WIP)
- What is blocked? (dependencies, decisions pending)

DECISIONS:
- Key design/architecture decisions made
- Why those decisions (rationale, tradeoffs)
- Alternatives considered and rejected

CONTEXT:
- Relevant files and their purposes
- Key functions/classes modified
- External references (docs, issues, PRs)
- Environment/setup details

NEXT STEPS:
- What to do next (ordered priority)
- What to avoid (known pitfalls)
- Recommended approach
- Open questions needing resolution

BLOCKERS:
- External dependencies waiting on
- Decisions pending from stakeholders
- Infrastructure/CI issues
- Knowledge gaps

Reference Other Artifacts

Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. This keeps the handoff document focused and avoids information staleness.

Handoff Template

Write the output to docs/handoff/HANDOFF-{YYYY-MM-DD-HHMM}.md in the current project directory. Create the docs/handoff/ directory if it doesn't exist:

# Handoff: {YYYY-MM-DD HH:MM}

## Summary
{One paragraph: what was the goal, what state is it in}

## Current State
- **Complete:** {list of finished items}
- **In Progress:** {list of WIP items}
- **Blocked:** {list of blockers with reasons}

## Key Decisions
| Decision | Rationale | Alternative |
|----------|-----------|-------------|
| {decision} | {why} | {what was rejected} |

## Files Touched
| File | Purpose | Status |
|------|---------|--------|
| {path} | {what changed} | {modified/created/deleted} |

## Next Steps (Priority Order)
1. {high priority} — {detail}
2. {medium priority} — {detail}
3. {low priority} — {detail}

## Suggested Skills
{List skills the next agent should call, based on the work being handed off}
- skill-name-1: {reason why this skill is needed}
- skill-name-2: {reason why this skill is needed}

## Open Questions
- {question 1} — needs input from {who}
- {question 2} — needs investigation

## Known Pitfalls
- {gotcha 1}
- {gotcha 2}

## Branch Info
- **Branch:** `{current-branch}`
- **Latest Commit:** `{commit-hash}` — "{commit-message}"
- **Base Branch:** `{base-branch}`

Quick Handoff (for lightweight context switches)

When time is limited, generate a compact version and save to docs/handoff/HANDOFF-{YYYY-MM-DD-HHMM}.md:

## Handoff Summary ({YYYY-MM-DD})
Goal: {one line}
Status: {done/in-progress/blocked} — {1 sentence}
Key decision: {1 sentence}
Next: {1-2 sentences}
Branch: {branch}
Files: {key files only}
Suggested Skills: {list 1-2 skills the next agent should use}

Examples

Full handoff (complex feature, multi-session)

Follow the full template above. Focus on decisions and rationale — 
the next agent needs to know WHY, not just WHAT.

Quick handoff (simple bugfix, short interruption)

Use the compact summary. Omit template sections that are empty.

Verification Checklist

Before finalizing the handoff, verify:

• Summary answers: "What is this about?"
• Current state accurately reflects reality
• Key decisions include rationale (not just what)
• Next steps are actionable (not vague)
• Blocker dependencies are identified
• Branch/commit info is correct
• No sensitive credentials, secrets, API keys, or passwords exposed
• No internal/confidential information exposed inappropriately
• Any sensitive information replaced with <REDACTED>
• Handoff document is saved to the correct location (docs/handoff/HANDOFF-{YYYY-MM-DD-HHMM}.md)