Handoff

• Handoff documents become stale immediately after they are used. A stale handoff in the repo will confuse future agents.
• A handoff document may contain sensitive debugging notes, intermediate state, or work-in-progress summaries that should not be committed.
• Temp directory artifacts are automatically cleaned up by the OS. No manual cleanup needed.
• Multiple agents may produce handoffs at the same time; temp directories avoid conflicts.

# Handoff document location
/tmp/handoff-[project]-[date]-[session-id].md

# Example:
/tmp/handoff-order-notifications-2025-06-01-a1b2c3.md

# Contents are NOT committed. Contents ARE shared between agent
# sessions if the system supports session context inheritance.

The next agent starts without context. Suggesting skills eliminates the “what do I do first?” problem and ensures the agent applies the right methodology for the type of work remaining.

• If remaining work is a PRD decomposition: suggest To Issues.
• If remaining work is debugging a failing test: suggest Diagnose.
• If remaining work is redesigning a module: suggest Improve Architecture.
• If remaining work is building a quick option test: suggest Prototype.

## Suggested Skills

For the remaining work on this handoff, load these skills:

1. **To Issues** — The PRD is approved. The next step is decomposing
   it into issues. Use the vertical slice methodology and AFK/HITL
   classification from the To Issues skill.

2. **Diagnose** — NOTIFY-003 has a flaky test (see Current Blockers
   section). Apply the Phase 1 feedback loop methodology before
   continuing with implementation.

Skills are at: ~/.claude/skills/ (or load via /[skill-name] command)

• Duplicated content becomes stale. If the original changes, the handoff has the wrong version.
• Large handoffs with pasted artifacts exceed context windows and prevent the agent from reading the full handoff.
• Referencing by path forces the next agent to read the live artifact, ensuring they have current information.

## Artifacts

**PRD:** /docs/prds/order-notifications-v2.md
(Approved 2025-06-01. Sections 1-5 are final. Section 6 has
a pending question about retry behavior — see Further Notes.)

**Current ADRs:**
- /docs/decisions/ADR-007-event-sourcing-notifications.md
- /docs/decisions/ADR-008-email-idempotency-key.md

**Active issues:**
- https://github.com/[org]/[repo]/issues/341 (NOTIFY-003 — in progress)
- https://github.com/[org]/[repo]/issues/342 (NOTIFY-004 — not started)

**Latest test run output:**
- /tmp/test-output-2025-06-01-14-30.txt
  (NOTIFY-003 has one flaky test: "triggers on duplicate within window"
   fails intermittently. See line 47.)

**Prototype reference:**
- /tmp/notification-idempotency-prototype.ts
  (The idempotency key structure. Verified working. Do not modify
   for production — rebuild cleanly using the PRD snippet.)

# Before redaction (do not include in handoff):
The SendGrid API key is SGKEY-xk9m2... used in production.
User john.doe@client.com reported the bug on order #9923.
The internal service URL is http://internal-api.aws-us-east-1.corp.

# After redaction (safe to include):
The SendGrid API key is [REDACTED: SENDGRID_API_KEY] — stored in
the production secrets manager under the key SENDGRID_API_KEY.

A customer reported the bug — see the support ticket in Linear.
(PII not included in handoff.)

The internal service URL is [REDACTED: INTERNAL_API_BASE_URL] —
configuration is in the deployment environment vars.

An argument-hint is a short header block that tells different types of readers exactly which sections of the handoff are relevant to them. It reduces time-to-context for the next agent.

## Argument Hints

This handoff can be consumed at different depths depending on the
next agent's role:

**Implementation agent (continuing NOTIFY-003):**
Read: Current State, Current Blockers, Next Steps.
Skip: Background, Architecture Overview (already built by this agent).

**QA agent (validating NOTIFY-002 and NOTIFY-003):**
Read: Background, Current State, Test Coverage, Artifacts (test paths).
Skip: Next Steps (not your work), Implementation Notes.

**Planning agent (decomposing NOTIFY-004 through NOTIFY-008):**
Read: Background, PRD reference, Architecture Overview, Out of Scope.
Skip: Current Blockers (implementation-specific), Test Coverage.

**New engineer onboarding to the notifications system:**
Read all sections in order.

# Handoff: [Project / Feature Name]
Generated: [ISO 8601 datetime]
Session: [session-id or agent-id]

---

## Argument Hints
[See above — tailor for each consumer type]

---

## Background
[2-3 sentences. What was the goal of this session?
What problem is this feature/work solving?]

---

## Current State
[What was built or completed in this session?
Be specific: which issues, which acceptance criteria, what tests pass.]

### Completed
- [NOTIFY-001] Tracer bullet: end-to-end event flow verified ✓
- [NOTIFY-002] EmailService interface + MockEmailService ✓

### In Progress
- [NOTIFY-003] Trigger notification on status change
  - Status: implementation complete, one flaky test
  - See: Current Blockers

### Not Started
- [NOTIFY-004] Email template rendering
- [NOTIFY-005] through [NOTIFY-008]: not decomposed yet

---

## Current Blockers
[What is preventing progress? Be specific.]

**Blocker 1: NOTIFY-003 flaky test**
Test: "triggers on duplicate within window"
Failure: intermittent — passes 8/10 times
Hypothesis: race condition in the 5-minute bucket calculation
when the test runs across a minute boundary.
Suggested skill: Diagnose → Phase 1 (build a deterministic loop).
See test output: /tmp/test-output-2025-06-01-14-30.txt line 47.

---

## Architecture Overview
[Key architectural decisions made during this session.
Reference ADRs by path, do not duplicate content.]

- Event-driven: OrderService emits → NotificationService consumes
  Details: /docs/decisions/ADR-007-event-sourcing-notifications.md
- Idempotency: 5-minute bucket key
  Details: /docs/decisions/ADR-008-email-idempotency-key.md
- EmailService is an interface; MockEmailService in tests

---

## Test Coverage
[What is tested, what is not.]

Covered:
- All four status transitions (unit tests)
- Idempotency key generation logic (unit tests)

Not covered:
- Template rendering (NOTIFY-004 not built yet)
- Real email delivery (requires integration test with Mailpit)
- Concurrent status changes (the flaky test)

---

## Artifacts
[Paths and URLs. No pasted content.]

PRD: /docs/prds/order-notifications-v2.md
ADRs: /docs/decisions/ADR-007-*.md, ADR-008-*.md
Issues: https://github.com/[org]/[repo]/issues?milestone=notifications
Test output: /tmp/test-output-2025-06-01-14-30.txt
Prototype: /tmp/notification-idempotency-prototype.ts (throwaway)

---

## Next Steps
[Ordered. First step is unambiguous.]

1. Fix the flaky test in NOTIFY-003 before merging.
   Apply Diagnose skill, Phase 1: make the test deterministic
   by injecting a mock clock or flooring to a fixed time bucket.

2. Merge NOTIFY-002 and NOTIFY-003 after the flaky test is fixed.

3. Begin NOTIFY-004: email template rendering.
   PRD Section 3 (User Stories US-1 through US-4) defines the
   required content per template. Start with US-1 (pending/confirmation).

---

## Suggested Skills
[Skills relevant to next steps]

1. Diagnose — for the flaky test (step 1 above)
2. To Issues — for decomposing NOTIFY-005 through NOTIFY-008

---

## Sensitive Information Notes
[What was redacted and where the real values live]

- No API keys or credentials encountered in this session.
- Test data used: fake orders with synthetic IDs (no real user data).