axiomantic/branch-context

<analysis> Reference for inspecting branch diffs, detecting stacked branches, and writing branch-relative documentation using branch-context.sh. </analysis> <reflection> Did I run branch-context.sh from the correct directory (worktree path, not main repo) and verify the merge target is correct? </reflection>

Branch Context

Type: Reference + Technique

Practical guide for inspecting branch context, handling stacked branches, and producing branch-relative documentation. Core definitions (merge target, merge base, branch diff) live in AGENTS.spellbook.md; this skill covers usage details.

Invariant Principles

1. Directory Determines Truth - Branch-context commands must run from the correct working directory; running from the wrong repo produces silently wrong results.
2. Merge Base Is the Reference Point - All branch diffs, PR descriptions, and changelogs describe changes relative to the merge base, never absolute state.
3. Stacked Branches Show Only Their Layer - In a stack, each branch's diff includes only what it added on top of its parent branch.

---

Script Usage

Use $SPELLBOOK_DIR/scripts/branch-context.sh to detect branch context automatically:

branch-context.sh              # summary: target, base, stats, uncommitted state
branch-context.sh diff         # full diff (merge base to working tree)
branch-context.sh diff-committed   # committed only (merge base to HEAD)
branch-context.sh diff-uncommitted # uncommitted only (staged + unstaged vs HEAD)
branch-context.sh log          # commit log since merge base
branch-context.sh files        # changed file list
branch-context.sh json         # machine-readable JSON

$SPELLBOOK_DIR is substituted at load time from spellbook configuration.

---

Stacked Branches

This matters for stacked branches: if master -> branch-A -> branch-B, the work on branch-B is only what branch-B added on top of branch-A. The script auto-detects stacking via PR base refs.

When reviewing stacked branches:

1. Run branch-context.sh to confirm the detected merge target.
2. Verify the merge target is the parent branch (e.g., branch-A), not main or master.
3. The diff will show only branch-B's additions, not the full stack.

---

Worktree Notes

In worktrees, run this script FROM the worktree directory. It detects worktree context automatically.

Before running any branch-context command in a worktree, verify you are in the correct directory:

cd <worktree-path> && pwd && git branch --show-current

Running branch-context.sh from the main repo while intending to inspect a worktree branch will produce silently wrong results (empty diffs, wrong merge base).

---

Branch-Relative Documentation

Changelogs, PR titles, PR descriptions, commit messages, and code comments describe the merge-base delta only. No historical narratives in code comments. Full policy in finishing-a-development-branch skill.

Rules:

• Describe what the branch introduces relative to its merge base.
• Do not narrate the development history ("first we tried X, then switched to Y").
• Do not reference work from parent branches in stacked PRs.
• PR descriptions should summarize the diff, not the journey.