handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

You are tasked with producing a **handoff brief** for the current conversation.
The purpose is to capture enough state that a fresh conversation (new context
window) can resume the work without re-asking what's been done.

## Step 0: Route — is this a Linear-tracked multi-slice build?

Before writing anything, check whether the dated state belongs in **Linear** rather
than a file. This is the case when **any** of these hold:

- The work this session is one slice of a larger build tracked in a **Linear
  project** — a ticket with a `project` (and usually an epic `parentId`).
- The repo has a `docs/**/handoff.md` that points resumers at **Linear project
  status updates** (e.g. `services/git-server/docs/handoff.md`).

If so, **stop and invoke `linear-handoff` instead** — for these builds the durable
resume point is an append-only project status update, not a checked-in (often
gitignored) file. Writing a file here is the known footgun: it lands in `plans/`,
nobody reads it, and the Linear update never gets posted.

```
Skill(skill: "linear-handoff")
```

Only when the work is **not** tracked in a Linear project (a one-off investigation,
a personal scratch brief, or no Linear MCP available) continue with the file-based
handoff below.

## Step 1: Extract Current-State Facts from the Conversation

Pull out concrete, verifiable facts — not discussion:

- **Active task(s):** what the user is working on right now
- **PR(s) in flight:** PR numbers, branch names, head SHAs, current CI/review
  state, outstanding review threads (with short rationale for any left
  intentionally unresolved)
- **Files touched:** the set of files modified across the session, with
  one-line descriptions of what changed in each
- **Key decisions made:** short bullets only — no rationale blocks. If a
  decision warrants deeper capture, direct the user to `decisions-capture`.
- **Unresolved items:** open review comments, failing checks, questions that
  didn't get answered, blockers encountered
- **What's left to do:** ordered, concrete next steps
- **Dependencies and ordering:** anything that must happen before/after
  something else (e.g., "merge PR X before applying Terraform Y")
- **Pointers for next session:** relevant file paths, scripts, slash
  commands, memory entries, or external URLs the next session will need

Do NOT invent state that wasn't observed in the conversation. If a fact is
uncertain, say so explicitly.

## Step 2: Determine Output Location and Filename

If the user supplied an explicit path as the argument, use that path.

Otherwise, pick a location using this priority:
1. `plans/` directory in the project root, if it exists
2. `~/plans/<month>-<year>/` if `~/plans/` exists (check for a current
   month-year subdirectory, create it if a sibling exists)
3. Project root

Default filename: `handoff-<topic>.md` where `<topic>` is a short, hyphenated
description of the work (e.g., `handoff-dds-ca-pools.md`,
`handoff-auth-migration.md`). Keep it specific — "handoff-dds" is too broad
when there may be multiple DDS workstreams.

If the user's argument is a directory, append `handoff-<topic>.md` to it.
If the user's argument is a full file path, use it verbatim.

## Step 3: Write the Handoff Document

Follow this structure. Omit sections that don't apply — don't invent content
to fill them.

```markdown
# Handoff: [Subject] — YYYY-MM-DD

Brief (one sentence) of what this work is and why you'd pick it up.

## What We Worked On

- Active task(s) in 1–3 bullets. Link to Linear/Jira ticket if present.

## PR(s) In Flight

### PR #NNNN — <short title>
- Branch: `<branch-name>`
- Head SHA: `<sha>`
- Linear: <URL or ticket ID, omit if none>
- **State:** green/red/pending — describe CI, SonarCloud, Copilot review state
- **Outstanding threads:** list any unresolved review threads, with whether
  they are Fix-pending, Disagree (with rationale), or Cannot-determine
- **Ready for:** merge / human review / more fixes / rebase / etc.

(Repeat per PR. Omit this section entirely if no PRs are in flight.)

## Files Changed

- `path/to/file.ext` — one-line description of the change
- ...

## Key Decisions (brief)

- Decision 1 — one line
- Decision 2 — one line

(No rationale blocks. If rationale matters, note "see decisions-capture
output" and invoke that skill separately.)

## Unresolved Items

- What's still open, who/what is blocking it, and what needs to happen to
  unblock it.

## What's Left to Do

Ordered, concrete steps. Use numbered list.

1. Step 1
2. Step 2

From thrawn01/claude-dotfiles, MIT.

More from thrawn01/claude-dotfiles