| skill_id | nezam-handoff-report |
| name | nezam-Handoff Report |
| tier | 3 |
| description | Structured handoff report generator — session state capture, decision log, next-action brief, and context package for human-to-human or agent-to-agent transitions. |
| paths | null |
| version | 1.0.0 |
| updated | "2026-05-12T00:00:00.000Z" |
| changelog | [] |
Handoff Report Skill
Purpose
Generate a concise, structured handoff report whenever work transitions between: sessions (end of day), agents (swarm handoff), humans (team member change), or tools (Cursor → Claude Code, etc.). Ensures continuity with zero context loss.
When to Use
Trigger this skill when:
/SAVE log command is run.- Agent completes a phase and passes to next agent.
- Work session ends (30+ minutes of activity).
- Tool switch (e.g., Cursor → Claude Code).
- Team member handoff (developer → designer, developer A → developer B).
Step-by-Step Workflow
1. Capture Session State
Read current state from:
.cursor/state/onboarding.yaml → current phase, prd_locked, design_locked
.cursor/state/plan_progress.yaml → which planning phases complete
.cursor/state/develop_phases.yaml → which build phases complete, in_progress
2. Capture Work Completed This Session
Summarize (in ≤ 200 words):
- Files created or modified (list paths).
- Decisions made (key choices with rationale, not implementation detail).
- Commands run and results (success/fail).
- Blockers encountered (if any).
3. Capture Open Items
List all incomplete work items:
- In-progress tasks (started but not done).
- Blocked tasks (waiting on input/dependency).
- Deferred tasks (out of scope for this session, not forgotten).
4. Generate Next Action Brief
Single most important next action. Format:
NEXT: [Action] → [File to open or command to run] → [Expected outcome]
Example: NEXT: Complete Phase 2 IA plan → open .nezam/core/plans/02-ia/IA_CONTENT.md → fill screen inventory
5. Write Handoff Report
Write to docs/reports/progress/HANDOFF_LATEST.md (always overwrite latest; archive as HANDOFF_{YYYYMMDD_HHMM}.md):
# Handoff Report
Generated: {timestamp}
Session type: {session-end | agent-handoff | tool-switch | team-handoff}
From: {agent/human name}
To: {next agent/human or "next session"}
## State Snapshot
- Phase: {current SDD phase}
- PRD locked: {yes/no}
- Design locked: {yes/no}
- Active build phase: {phase_N or "planning"}
## Completed This Session
- [list of completed work]
## Open Items
### In Progress
- [item]: [what's left to complete it]
### Blocked
- [item]: [what's blocking it]
### Deferred
- [item]: [why deferred]
## Key Decisions Made
| Decision | Rationale | Alternatives Rejected |
|----------|-----------|----------------------|
| [decision] | [why] | [what else was considered] |
## Next Action
NEXT: [single most important next action]
## Context Files to Open First
- [file 1]: [why it matters for next session]
- [file 2]: [why it matters]
Validation & Metrics
- Handoff report written within 2 minutes of session end.
- Next action brief is specific (includes file path or command).
- Open items list is complete (nothing discovered after handoff not captured).
- State snapshot matches actual state file values.
Integration Hooks
- Triggered by
/SAVE log command.
- Pairs with
external-ai-report skill for browser AI companion upload.
- Referenced by
deputy-swarm-leader agent for agent-to-agent handoffs.
/GUIDE status reads latest handoff report as session context.
Anti-Patterns
- Vague "next action" (e.g., "continue working on the project" — not actionable).
- Not capturing decisions (future sessions repeat the same deliberation).
- Writing handoff only for long sessions (even 30-min sessions create context).
- Overwriting archive copies (keep last 10 handoff reports, then rotate).
