📋 NEXUS Handoff Templates

# 📋 NEXUS Handoff Templates

> Standardized templates for every type of agent-to-agent handoff in the NEXUS pipeline. Consistent handoffs prevent context loss — the #1 cause of multi-agent coordination failure.

---

## 1. Standard Handoff Template

Use for any agent-to-agent work transfer.

```markdown
# NEXUS Handoff Document

## Metadata
| Field | Value |
|-------|-------|
| **From** | [Agent Name] ([Division]) |
| **To** | [Agent Name] ([Division]) |
| **Phase** | Phase [N] — [Phase Name] |
| **Task Reference** | [Task ID from Sprint Prioritizer backlog] |
| **Priority** | [Critical / High / Medium / Low] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Context
**Project**: [Project name]
**Current State**: [What has been completed so far — be specific]
**Relevant Files**:
- [file/path/1] — [what it contains]
- [file/path/2] — [what it contains]
**Dependencies**: [What this work depends on being complete]
**Constraints**: [Technical, timeline, or resource constraints]

## Deliverable Request
**What is needed**: [Specific, measurable deliverable description]
**Acceptance criteria**:
- [ ] [Criterion 1 — measurable]
- [ ] [Criterion 2 — measurable]
- [ ] [Criterion 3 — measurable]
**Reference materials**: [Links to specs, designs, previous work]

## Quality Expectations
**Must pass**: [Specific quality criteria for this deliverable]
**Evidence required**: [What proof of completion looks like]
**Handoff to next**: [Who receives the output and what format they need]
```

---

## 2. QA Feedback Loop — PASS

Use when Evidence Collector or other QA agent approves a task.

```markdown
# NEXUS QA Verdict: PASS ✅

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempt** | [N] of 3 |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Verdict: PASS

## Evidence
**Screenshots**:
- Desktop (1920x1080): [filename/path]
- Tablet (768x1024): [filename/path]
- Mobile (375x667): [filename/path]

**Functional Verification**:
- [x] [Acceptance criterion 1] — verified
- [x] [Acceptance criterion 2] — verified
- [x] [Acceptance criterion 3] — verified

**Brand Consistency**: Verified — colors, typography, spacing match design system
**Accessibility**: Verified — keyboard navigation, contrast ratios, semantic HTML
**Performance**: [Load time measured] — within acceptable range

## Notes
[Any observations, minor suggestions for future improvement, or positive callouts]

## Next Action
→ Agents Orchestrator: Mark task complete, advance to next task in backlog
```

---

## 3. QA Feedback Loop — FAIL

Use when Evidence Collector or other QA agent rejects a task.

```markdown
# NEXUS QA Verdict: FAIL ❌

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempt** | [N] of 3 |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Verdict: FAIL

## Issues Found

### Issue 1: [Category] — [Severity: Critical/High/Medium/Low]
**Description**: [Exact description of the problem]
**Expected**: [What should happen according to acceptance criteria]
**Actual**: [What actually happens]
**Evidence**: [Screenshot filename or test output]
**Fix instruction**: [Specific, actionable instruction to resolve]
**File(s) to modify**: [Exact file paths]

### Issue 2: [Category] — [Severity]
**Description**: [...]
**Expected**: [...]
**Actual**: [...]
**Evidence**: [...]
**Fix instruction**: [...]
**File(s) to modify**: [...]

[Continue for all issues found]

## Acceptance Criteria Status
- [x] [Criterion 1] — passed
- [ ] [Criterion 2] — FAILED (see Issue 1)
- [ ] [Criterion 3] — FAILED (see Issue 2)

## Retry Instructions
**For Developer Agent**:
1. Fix ONLY the issues listed above
2. Do NOT introduce new features or changes
3. Re-submit for QA when all issues are addressed
4. This is attempt [N] of 3 maximum

**If attempt 3 fails**: Task will be escalated to Agents Orchestrator
```

---

## 4. Escalation Report

Use when a task exceeds 3 retry attempts.

```markdown
# NEXUS Escalation Report 🚨

## Task
| Field | Value |
|-------|-------|
| **Task ID** | [ID] |
| **Task Description** | [Description] |
| **Developer Agent** | [Agent Name] |
| **QA Agent** | [Agent Name] |
| **Attempts Exhausted** | 3/3 |
| **Escalation To** | [Agents Orchestrator / Studio Producer] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Failure History

### Attempt 1
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

### Attempt 2
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

### Attempt 3
- **Issues found**: [Summary]
- **Fixes applied**: [What the developer changed]
- **Result**: FAIL — [Why it still failed]

## Root Cause Analysis
**Why the task keeps failing**: [Analysis of the underlying problem]
**Systemic issue**: [Is this a one-off or pattern?]
**Complexity assessment**: [Was the task properly scoped?]

## Recommended Resolution
- [ ] **Reassign** to different developer agent ([recommended agent])
- [ ] **Decompose** into smaller sub-tasks ([proposed breakdown])
- [ ] **Revise approach** — architecture/design change needed
- [ ] **Accept** current state with documented limitations
- [ ] **Defer** to future sprint

## Impact Assessment
**Blocking**: [What other tasks are blocked by this]
**Timeline Impact**: [How this affects the overall schedule]
**Quality Impact**: [What quality compromises exist if we accept current state]

## Decision Required
**Decision maker**: [Agents Orchestrator / Studio Producer]
**Deadline**: [When decision is needed to avoid further delays]
```

---

## 5. Phase Gate Handoff

Use when transitioning between NEXUS phases.

```markdown
# NEXUS Phase Gate Handoff

## Transition
| Field | Value |
|-------|-------|
| **From Phase** | Phase [N] — [Name] |
| **To Phase** | Phase [N+1] — [Name] |
| **Gate Keeper(s)** | [Agent Name(s)] |
| **Gate Result** | [PASSED / FAILED] |
| **Timestamp** | [YYYY-MM-DDTHH:MM:SSZ] |

## Gate Criteria Results
| # | Criterion | Threshold | Result | Evidence |
|---|-----------|-----------|--------|----------|
| 1 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |
| 2 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |
| 3 | [Criterion] | [Threshold] | ✅ PASS / ❌ FAIL | [Evidence reference] |

## Documents Carried Forward
1. [Document name] — [Purpose for next phase]
2. [Document name] — [Purpose for next phase]
3. [Document name] — [Purpose for next phase]

## Key Constraints for Next Phase
- [Constraint 1 from this phase's findings]
- [Constraint 2 from this phase's findings]

## Agent Activation for Next Phase
| Agent | Role | Priority |
|-------|------|----------|
| [Agent 1] | [Role in next phase] | [Immediate / Day 2 / As needed] |
| [Agent 2] | [Role in next phase] | [Immediate / Day 2 / As needed] |

## Risks Carried Forward
| Risk | Severity | Mitigation | Owner |
|------|----------|------------|-------|
| [Risk] | [P0-P3] | [Mitigation plan] | [Agent] |
```

---

## 6. Sprint Handoff

Use at sprint boundaries.

```markdown
# NEXUS Sprint Handoff

## Sprint Summary
| Field | Value |
|-------|-------|
| **Sprint** | [Number] |
| **Duration** | [Start date] → [End date] |
| **Sprint Goal** | [Goal statement] |
| **Velocity** | [Planned] / [Actual] story points |

## Completion Status
| Task ID | Description | Status | QA Attempts | Notes |
|---------|-------------|--------|-------------|-------|
| [ID] | [Description] | ✅ Complete | [N] | [Notes] |
| [ID] | [Description] | ✅ Complete | [N] | [Notes] |
| [ID] | [Description] | ⚠️ Carried Over | [N] | [Reason] |

## Quality Metrics
- **First-pass QA rate**: [X]%
- **Average retries**: [N]
- **Tasks completed**: [X/Y]
- **Story points delivered**: [N]

## Carried Over to Next Sprint
| Task ID | Description | Reason | Priority |
|---------|-------------|--------|----------|
| [ID] | [Description] | [Why not completed] | [RICE score] |

## Retrospective Insights
**What went well**: [Key successes]
**What to improve**: [Key improvements]
**Action items**: [Specific changes for next sprint]

## Next Sprint Preview
**Sprint goal**: [Proposed goal]
**Key tasks**: [Top priority items]
**Dependencies**: [Cross-team dependencies]
```

---

## 7. Incident Handoff

Use during incident response.

```markdown
# NEXUS Incident Handoff

## Incident
| Field | Value |
|-------|-------|
| **Severity** | [P0 / P1 / P2 / P3] |
| **Detected by** | [Agent or system] |
| **Detection time** | [Timestamp] |
| **Assigned to** | [Agent Name] |
| **Status** | [Investigating / Mitigating / Resolved / Post-mortem] |

## Description
**What happened**: [Clear description of the incident]
**Impact**: [Who/what is affected and how severely]
**Timeline**:
- [HH:MM] — [Event]
- [HH:MM] — [Event]
- [HH:MM] — [Event]

## Current State
**Systems affected**: [List]
**Workaround available**: [Yes/No — describe if yes]
**Estimated resolution**: [Time estimate]

## Actions Taken
1. [Action taken and result]
2. [Action taken and result]

## Handoff Context
**For next responder**:
- [What's been tried]
- [What hasn't been tried yet]
- [Suspected root cause]
- [Relevant logs/metrics to check]

## Stakeholder Communication
**Last update sent**: [Timestamp]
**Next update due**: [Timestamp]
**Communication channel**: [Where updates are posted]
```

---

## Usage Guide

| Situation | Template to Use |
|-----------|----------------|
| Assigning work to another agent | Standard Handoff (#1) |
| QA approves a task | QA PASS (#2) |
| QA rejects a task | QA FAIL (#3) |
| Task exceeds 3 retries | Escalation Report (#4) |
| Moving between phases | Phase Gate Handoff (#5) |
| End of sprint | Sprint Handoff (#6) |
| System incident | Incident Handoff (#7) |