Gen Backend Handoff

Backend Handoff Generator

Overview

Create evidence-based handoff documents for backend implementers. The handoff must make the server-side contract, data model, rollout risk, verification state, and remaining work clear enough for another developer or coding agent to continue.

Core principle: changed server behavior in, continuation-ready backend plan out.

Announce at start: "I'm using the gen-backend-handoff skill to create a backend handoff."

Scope Resolution

Use the scope the user requested. Do not broaden it.

Record the final command under Evidence. If the user supplied main...feature, HEAD~5..HEAD, or another range, the document must state that it used the user-specified scope.

Evidence Collection

Gather only what is needed for the handoff:

git status --short
git log --oneline --decorate -n 10
git diff --stat [scope]
git diff [scope]

Also use current conversation notes, Codex/Claude session summaries, pasted review comments, test output, or deployment notes when the user provides them. Label them as "User-provided session context" unless verified from files or commands.

Never include secrets from .env, credentials, tokens, private keys, or local-only config values.

Required Analysis

Extract the server-side continuation surface:

• API contract: routes, methods, request/response schemas, status codes, headers, auth, permissions, validation, rate limits.
• Data model: schema changes, database migrations, seed data, backfills, indexes, constraints, rollback risk.
• Service behavior: business logic, feature flags, config, environment variables, third-party integrations, caching.
• Async work: jobs, queues, and scheduled tasks, retry policy, idempotency, dead-letter handling, observability.
• Compatibility: backward compatibility, old client behavior, old server version behavior, rollout order.
• Cross-team impact: frontend/client action, SDK action, QA action, ops action, or "No external action found".
• Verification evidence: tests, type checks, migrations, manual checks, or "Not verified".

Do not claim unverified tests, deploys, or runtime behavior. If there is no command output proving it, write "Not verified in this handoff."

Natural Korean Prose

When the handoff is in Korean, write reader-facing text as plain, concrete Korean prose. Use direct sentences; avoid translation-like rhythm, vague AI filler, and internal method vocabulary. Preserve facts, numbers, dates, proper nouns, code identifiers, commands, quotes, links, API fields, and evidence.

This selector is self-contained. If the runtime already exposes human-friendly-writing, it is an optional final pass over only the newly authored Korean draft before writing the handoff. Do not install, fetch, or require it. If it is absent or unreadable, continue silently with the rules above and complete the handoff. After an optional pass, run the normal validation again. The pass may change wording only, never evidence, template headings, API details, or the Continuation Prompt's instructions.

Output

Write the handoff to:

.handoffs/<YYYY-MM-DD>_<scope>_backend.md

Use working for unstaged/staged changes, the short SHA for a single commit, or a sanitized range/branch label for explicit scopes. Create .handoffs/ if needed.

Document Template

# Backend Handoff

**Date:** YYYY-MM-DD
**Scope:** [working tree | staged changes | HEAD~N..HEAD | main...feature | PR #N]
**Audience:** Backend developer or server-side coding agent

## Summary

- What changed:
- Remaining backend work:
- Primary risk:

## Evidence

- Diff command:
- Files inspected:
- User-provided session context:
- Tests/deploys verified:

## API Contract

| Endpoint | Change | Compatibility impact |
|---|---|---|

## Data And Migrations

- Database migrations:
- Schema/index/constraint changes:
- Backfill/seed data:
- Rollback notes:

## Service Behavior

- Business logic:
- Auth/permissions:
- Feature flags/config:
- Caching/integration impact:

## Jobs And Async Work

- Jobs, queues, and scheduled tasks:
- Retry/idempotency:
- Observability:

## Cross-Team Impact

- frontend/client action:
- QA action:
- Ops/deploy action:
- SDK/API docs action:

## Rollout And Backward Compatibility

- Required order:
- backward compatibility:
- Fallback:
- Known risks:

## Verification

- Tests run:
- Migration checks:
- Manual checks:
- Not verified:

## Backend Implementation Checklist

- [ ] Complete remaining code changes
- [ ] Add or update tests
- [ ] Run migration/rollback checks if applicable
- [ ] Verify API contract and compatibility
- [ ] Update docs or downstream handoffs if needed

## Open Questions

- ...

## Continuation Prompt

Use the evidence above to continue the backend implementation. Preserve the stated scope, do not assume unverified tests or deploys, and resolve open questions before modifying ambiguous API, data, or rollout behavior.

Baseline Failures

Common Mistakes

• Treating database migrations as implementation detail only; they are rollout and rollback risk.
• Omitting old-client or old-server compatibility.
• Forgetting job retry, idempotency, and observability changes.
• Mixing current working-tree changes with an explicit commit range.
• Copying session context as fact without labeling whether it was verified.

Example

User: "Use HEAD~5..HEAD and make a backend handoff."

Expected behavior:

1. Run git diff --stat HEAD~5..HEAD and git diff HEAD~5..HEAD.
2. Extract API contract, database migrations, service behavior, jobs, queues, and scheduled tasks.
3. Write .handoffs/YYYY-MM-DD_HEAD-5-HEAD_backend.md.
4. Include backend remaining work, rollout/backward compatibility, verification evidence, and a Continuation Prompt.