Agent-Skills.md

Agent Skills: Branch Context

>

UncategorizedID: axiomantic/spellbook/branch-context

Repository

axiomantic/spellbook
axiomanticLicense: MIT
105

Install this agent skill to your local

pnpm dlx add-skill https://github.com/axiomantic/spellbook/tree/HEAD/skills/branch-context

Skill Files

Browse the full folder contents for branch-context.

Download Skill

Loading file tree…

skills/branch-context/SKILL.md

Skill Metadata

Name
branch-context
Description
>
<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 rules/55-diff-semantics.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 stat         # diffstat (merge base to working tree)
branch-context.sh stat-committed   # diffstat, committed only (merge base to HEAD)
branch-context.sh files        # changed file list (merge base to working tree)
branch-context.sh files-committed  # changed file list, committed only
branch-context.sh base         # the merge base SHA
branch-context.sh target       # the detected merge target
branch-context.sh resolution   # base provenance on stdout
branch-context.sh json         # machine-readable JSON
<CRITICAL> **ENDPOINT is a separate decision from BASE.** The `-committed` variants stop at HEAD; the plain ones include the working tree. Pick by TASK:

| Task | Endpoint pair | |------|---------------| | Reviewing what will merge | files-committed + diff-committed | | Describing the branch (PR body, changelog) | files + diff | | Pre-commit self-review | files + diff |

The file list and the diff MUST share one endpoint. Pairing files with diff-committed builds a coverage manifest of files the diff does not contain, which lets a review certify N-of-N against zero hunks.

json reports BOTH counts: files_changed (working tree) and files_changed_committed. Automation deciding "is there anything to review" must read files_changed_committed. </CRITICAL>

Run branch-context.sh --help for the authoritative list; this table and the script's own usage output are ONE contract.

$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.