# Feature Handoff Template

Template for the handoff document generated at the end of each feature build.
Captures **only what is not obvious from reading the code**, so that the next
session or feature can start with clean, minimal context.

> **Location in the project**: `.handoff/feature-{order}-{screen-kebab}.md`
> Example: `.handoff/feature-01-order-list.md`

---

## Format

```markdown
# Handoff: {Feature Name}

**Module**: {ModuleName}
**Screen**: {ScreenName}
**Order**: {N} of {total}
**Commit**: {short hash} — {message}
**Notion**: {link to the feature record}

## Files created

- `src/pages/{Module}/{Screen}/index.tsx`
- `src/pages/{Module}/{Screen}/types.ts`
- ...

## Files modified (already existed)

- `src/App.tsx` — new route `/{module}/{screen}`
- `src/layouts/DashboardLayout.tsx` — new nav item "{Label}"
- ...

## Shared artifacts

Things this feature created that other features may consume or need to know about:

- **Context**: `src/pages/{Module}/contexts/{Name}Context.tsx` — {what it provides}
- **Shared type**: `src/pages/{Module}/types.ts` — `type {Name}` — {what it is for}
- **Service**: `src/pages/{Module}/services.ts` — `{functionName}()` — {which endpoint it calls}
- **Hook**: `src/pages/{Module}/hooks/use{Name}.ts` — {what it does}
- **Reusable component**: `src/pages/{Module}/components/{Name}/` — {what it renders}

> Omit this section if the feature did not create anything shared.

## Non-obvious decisions

Decisions made during the build that are not evident from reading the code:

- {Example: "Used polling every 30s instead of websockets because the endpoint does not support SSE"}
- {Example: "The `status` field arrives as a number from the API but is mapped to a string in the frontend"}

> Omit this section if no out-of-the-ordinary decisions were made.

## Project status

- Features completed: {N}/{total}
- Next feature: **{name}** ({module} / {screen})
- Blockers or pending items: {none | description}
```

---

## What NOT to include

- **File contents** — the agent can read them directly.
- **Explanation of rules or conventions** — loaded automatically via glob.
- **History of errors or failed attempts** — not relevant to the next feature.
- **Refinement details** — they live in Notion.

## When to generate

As the last step of `/build-feature`, after the commit and the Notion update.
The agent writes the handoff and suggests to the user:

> Done. If you want to start the next feature with clean context,
> run `/compact` or open a new session.
> The context of what we did is saved in `.handoff/feature-{N}-{screen}.md`.

## When to read

At the start of a `/build-feature`, if files exist in `.handoff/`:
1. Read **only the latest** handoff (the one with the highest order).
2. Pay attention to **Shared artifacts** and **Non-obvious decisions**.
3. Reading handoffs older than the latest is unnecessary — they are cumulative in the parts that matter.
