branch-context

Branch Context

This directory is the home for durable PR/branch state that outlives a single session. Three surfaces:

File / dir	Role	Lifetime
issue-brief.md	Synthesis of the issue(s) this branch addresses	Rewritten only when adopting or re-syncing a branch
pr-decisions.md	Append-only log of non-obvious PR-shaping decisions	Append forever; supersede, never edit
handoffs/ + handoffs-index.md	Append-only session handoffs for the next agent	Never overwrite a handoff file; index points at the latest

The instances (issue-brief.md, pr-decisions.md, handoffs-index.md, handoffs/) are per-branch and git-ignored. The scaffolding (this file, the scripts, the *.template.md files) is committed. Instantiate the instances from the templates, or via /adopt-pr when a PR already exists.

Session defaults

On start, before coding:

1. Confirm the branch matches the brief's branch: field (git rev-parse --abbrev-ref HEAD).
2. Read issue-brief.md, pr-decisions.md, and handoffs-index.md.
3. Read the latest handoff -- the last entry in handoffs-index.md points at its file under handoffs/. That is what the previous session left for you. If the index has no entries, there is no handoff yet; start from the brief.
4. If the brief is still the unfilled template, populate it first: run /adopt-pr when a PR already exists, or write it from the linked issue when starting fresh.

While working -- persist without being asked:

• A non-obvious decision (picking path A over B, a plan deviation, an ambiguous thread resolution) goes into pr-decisions.md via append-pr-decision.sh in the same turn you make it, not "later".
• Disk in this directory is the continuity channel, not chat history. Do not rely on the conversation surviving a context clear or a new session.
• Do not write a handoff because the context "feels full" -- that misjudges and primes an early stop. Write a handoff only when the user asks, or when session turnover is already decided (the user is clearing, switching tools, or ending the sitting).

When to write each surface

issue-brief.md

Rewritten only when adopting a branch (/adopt-pr) or re-syncing after new issue activity. Do not freestyle-edit it mid-session.

pr-decisions.md

Append whenever you make a decision the issue did not already spell out:

.claude/skills/branch-context/append-pr-decision.sh \
  --title "<short title>" \
  --decision "<one-line decision>" \
  --why "<one-line why>" \
  --source "<source url -- mandatory>" \
  [--iter N] [--supersedes "<earlier title>"]

Named flags are preferred (they resist arg-order mistakes). Positional order is title decision why source [iter] [supersedes] -- do not pass iter as the second argument.

Entry shape (the script writes this):

## YYYY-MM-DD · <short title> · iter <N or "-">
- Decision: <one line>
- Why: <one line>
- Source: <link -- mandatory>
- Supersedes: <earlier title, if applicable>

When the decision restates a modal claim (always / never / only if / must / unless), quote that clause verbatim instead of paraphrasing -- "always X unless Y" compressed to "always X" is a different instruction.

Handoffs

One handoff per session, newest last. Never overwrite another session's handoff.

.claude/skills/branch-context/append-handoff.sh [--writer <name>] "<one-line summary>" [path-to-body.md]

--writer tags the index line with the skill that produced the handoff. If you omit the body path, the script writes a stub you must fill in via Write/Edit before stopping; prefer writing the full body first and passing its path. To revise a handoff you already wrote this session, edit the file in place rather than appending a second index entry.

Handoff body sections (required):

# Handoff · YYYY-MM-DD · <summary>

## Done
- ...

## Next
- ... (ordered; first item is what the next agent starts on)

## Commitments & constraints carried forward
- ... (verbatim; or "none")

## Key paths
- `path` -- why

## Open questions
- ... (or "none")

## Branch-context pointers
- Brief: issue-brief.md (still valid? yes/no)
- Decisions appended this session: <titles or "none">
- Related plan file (if any): <path>

Commitments & constraints is a required check, not an optional extra. Before writing the handoff, sweep the session for two things and quote them verbatim -- do not paraphrase, the modality is the payload:

• Constraints the user stated that are not already in the brief's Constraints section. "Always X unless Y" and "always X" are different instructions, and a one-line paraphrase is where the qualifier gets dropped.
• Promises you made and have not kept -- to the user ("I'll add the regression test next"), or on the record in a PR/review comment ("I'll file a follow-up issue", "I'll re-run this once CI clears"). A promise made to a reviewer and then dropped across a session boundary is the expensive kind: the next agent cannot know it exists, and the reviewer is still waiting.

A longer, accurate handoff beats a short lossy one. Do not compress this section to save space.

Session turnover

Write the handoff (and any unlogged decisions) when the user turns the session over. If the harness has a plan mode, capture the remaining work as a concrete plan (next steps, files, verification), persist the handoff, then exit plan mode so the fresh session inherits it. If the harness has no plan mode, persist the handoff and tell the user to start a new session in this worktree whose first action is to read handoffs-index.md and the latest handoff.

Scope boundary

• Not for research notes or repro scripts -- those belong outside this directory.
• Not for durable codebase facts that outlive the PR -- those belong in longer-lived project docs or memory. Rule of thumb: if removing the linked thread would make this PR's diff confusing, it is a decision; if the fact still helps after merge, it belongs elsewhere.

Helpers

.claude/skills/branch-context/status.sh              # JSON: brief/decisions/handoffs state
.claude/skills/branch-context/append-pr-decision.sh ...
.claude/skills/branch-context/append-handoff.sh ...