branch-context
Triggers: 'branch diff', 'what changed on this branch', 'merge base', 'stacked branches', 'branch-context.sh', 'what does this branch do', 'PR description', 'changelog', 'branch comparison', 'diff since', 'what work is on this branch'. Also relevant during PR creation and finishing-a-development-branch workflows.
Best use case
branch-context is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Triggers: 'branch diff', 'what changed on this branch', 'merge base', 'stacked branches', 'branch-context.sh', 'what does this branch do', 'PR description', 'changelog', 'branch comparison', 'diff since', 'what work is on this branch'. Also relevant during PR creation and finishing-a-development-branch workflows.
Teams using branch-context should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/branch-context/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How branch-context Compares
| Feature / Agent | branch-context | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Triggers: 'branch diff', 'what changed on this branch', 'merge base', 'stacked branches', 'branch-context.sh', 'what does this branch do', 'PR description', 'changelog', 'branch comparison', 'diff since', 'what work is on this branch'. Also relevant during PR creation and finishing-a-development-branch workflows.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
<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:
```bash
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.Related Skills
finishing-a-development-branch
Use when implementation is complete, tests pass, and you need to decide the integration path. Also use when asked to prepare a branch for release: 'update changelog', 'bump version', 'bump patch version', 'make sure changelog is correct', 'make sure version is correct'. Triggers: 'done with this branch', 'ready to merge', 'ship it', 'wrap this up', 'how should I integrate this', 'what next after implementation'. NOT for: PR creation mechanics (use creating-issues-and-pull-requests) or deciding whether to merge (use finishing-a-development-branch first).
assembling-context
Use when preparing context for subagent dispatch or managing token budgets. Triggers: 'prepare context for', 'assemble context', 'token budget', 'context package', 'what context does the subagent need'. Also invoked by develop during planning and execution phases.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment. Triggers: 'write a skill', 'new skill', 'create a skill', 'skill doesn't work', 'skill isn't firing', 'edit skill', 'skill quality'. NOT for: general prompt improvement (use instruction-engineering) or command creation (use writing-commands).
writing-plans
Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by develop during planning. NOT for: reviewing existing plans (use reviewing-impl-plans).
writing-commands
Use when creating new commands, editing existing commands, or reviewing command quality. Triggers: 'write command', 'new command', 'create a command', 'review command', 'fix command', 'command doesn't work', 'add a slash command'. NOT for: skill creation (use writing-skills).
verifying-hunches
Use when about to claim discovery during debugging. Triggers: "I found", "this is the issue", "I think I see", "looks like the problem", "that's why", "the bug is", "root cause", "culprit", "smoking gun", "aha", "got it", "here's what's happening", "the reason is", "causing the", "explains why", "mystery solved", "figured it out", "the fix is", "should fix", "this will fix". Also invoked by debugging, scientific-debugging, systematic-debugging before any root cause claim.
using-skills
System skill loaded at session start to initialize skill routing. Not invoked directly by users. Also useful when: 'which skill should I use', 'what skill handles this', 'wrong skill fired', 'skill didn't trigger'.
using-lsp-tools
Use when mcp-language-server tools are available and you need semantic code intelligence. Triggers: 'find definition', 'find references', 'who calls this', 'rename symbol', 'type hierarchy', 'go to definition', 'where is this used', 'where is this defined', 'what type is this'. Provides navigation, refactoring, and type analysis via LSP.
using-git-worktrees
Use when starting feature work that needs isolation from current workspace, or setting up parallel development tracks. Triggers: 'worktree', 'separate branch', 'isolate this work', 'don't mess up current work', 'work on two things at once', 'parallel workstreams', 'new branch for this', 'keep my current work safe'.
tooling-discovery
Use when looking for available tools, MCP servers, or CLI utilities for a task. Triggers: 'what tools do I have', 'is there an MCP for this', 'what's available', 'find a tool for', 'discover tooling', 'what CLI tools exist'. NOT for: documenting existing tools (use documenting-tools).
testing-strategy
Test selection strategy and scope guidance. Triggers: 'which tests should I run', 'test tiers', 'test marks', 'slow tests', 'integration vs unit', 'cross-module regression', 'test scope', 'what should I run', 'select tests', 'test batching'. NOT for: writing tests (use test-driven-development) or fixing broken tests (use fixing-tests).
test-driven-development
Use when user explicitly requests test-driven development. Triggers: 'TDD', 'write tests first', 'red green refactor', 'test-first', 'start with the test'. Also invoked by develop and executing-plans for implementation tasks. NOT for: full feature work (use develop, which includes TDD internally).