nezam-handoff-report

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).