diffdive

---
name: diffdive
description: Branch analysis and context loading. Analyses the diff between the current branch and trunk (master/main) to get up to speed quickly. Use when switching to an unfamiliar branch, resuming work after time away, onboarding onto a colleague's branch, reviewing a PR, or when you need a situation report on what a branch has changed relative to trunk.
license: MIT
metadata:
  author: itzcull
---

## Purpose

Get up to speed on a branch by analysing its divergence from trunk. Produces a structured situation report covering what changed, why it likely changed, areas of risk, and open questions.

## Relationship to structured development

Within [structured development](../structured-development/SKILL.md), this skill supplies context for [establishing intent](../structured-development/SKILL.md#1-establish-intent-and-boundaries), [preparing further work](../structured-development/SKILL.md#3-select-and-prepare-the-next-increment), and [reconciling a branch with its original goal](../structured-development/SKILL.md#6-reconcile-and-adapt). It is an orientation activity, not an implementation or verification protocol.

Use the branch, comparison base, available history, and any stated goal. Return the [situation report](#output-format) with evidence-backed changes, likely intent clearly separated from known requirements, and questions that affect the next decision. The enclosing procedure uses that context to choose investigation, implementation, or review work.

A diff cannot establish that requirements were approved, checks passed, or a feature is complete. Keep analysis read-only and return uncertain intent or apparent scope changes to the user rather than inventing requirements or modifying the branch to match an interpretation.

## When to use

- Switching to an unfamiliar branch
- Resuming work on a branch after time away
- Onboarding onto a colleague's branch or PR
- Before a code review to understand the full scope of changes
- When asking "what has this branch done?" or "catch me up"

## Process

### Step 1: Detect current branch

Run `git branch --show-current` to identify the active branch.

If on a detached HEAD, report this and ask the user which branch to analyse.

### Step 2: Determine trunk branch

If the user provided an argument, use that as the trunk branch name.

Otherwise, auto-detect by checking which of these exist (in order of preference):

1. `main`
2. `master`

Verify the chosen trunk branch exists with `git rev-parse --verify <trunk>`. If neither exists, ask the user to specify the trunk branch.

### Step 3: Find the divergence point

Run `git merge-base <trunk> HEAD` to find where this branch diverged from trunk.

### Step 4: Gather context

Collect the following information using git commands:

1. **Commit count**: `git rev-list --count <merge-base>..HEAD`
2. **Commit log**: `git log --oneline --no-decorate <merge-base>..HEAD`
3. **Diff stats**: `git diff --stat <merge-base>..HEAD`
4. **Full diff**: `git diff <merge-base>..HEAD`
5. **Files changed count**: `git diff --name-only <merge-base>..HEAD | wc -l`
6. **Trunk commits since divergence** (optional context): `git rev-list --count <merge-base>..<trunk>`

If the full diff is very large (many files or thousands of lines), prioritise the diff stats and commit log for the high-level summary, then read the full diff in sections grouped by module/directory.

### Step 5: Analyse and present the report

Study the gathered information and produce the structured report described below. Focus on understanding the **intent** behind the changes, not just describing what lines changed.

Look for:

- The overarching goal or feature being built
- Patterns in the changes (new modules, refactoring, bug fixes, test additions)
- Architectural decisions (new dependencies, structural changes, API changes)
- Potential risks (large files changed, missing tests, complex logic)
- Incomplete work (TODOs, commented-out code, partial implementations)

## Output Format

Present the report using this structure:

```
## Diff Dive: [branch-name]

**Branch:** [current branch]
**Trunk:** [trunk branch]
**Divergence point:** [short merge-base hash]
**Commits on branch:** [count]
**Commits on trunk since divergence:** [count]
**Files changed:** [count]

---

### Summary

[2-4 sentence high-level summary of what this branch is doing and why.
Frame it as a narrative: "This branch introduces...", "This branch refactors...", etc.]

### Changes by Area

**[area/module/directory]**
- [What changed and the likely intent behind it]
- [Notable additions, removals, or modifications]

**[area/module/directory]**
- [What changed and the likely intent behind it]

[...repeat for each significant area...]

### Architectural Observations

- [Patterns, design decisions, or structural changes worth noting]
- [New dependencies or tooling changes]
- [API surface changes (new endpoints, changed interfaces, etc.)]

### Risk Areas

- [Files or changes that warrant careful review]
- [Missing test coverage for new functionality]
- [Complex logic that could harbour bugs]
- [Breaking changes or backwards compatibility concerns]

### Open Questions

- [Things that are unclear from the diff alone]
- [Decisions that might need discussion]
- [Incomplete work that may need follow-up]
```

## Constraints

- **Read-only analysis** — do not modify any files, make commits, or change branch state
- **Intent over mechanics** — explain WHY changes were made, not just WHAT lines changed
- **Honest assessment** — flag genuine risks and gaps; do not gloss over problems
- **Proportional detail** — spend more analysis time on complex or risky changes, less on trivial ones
- **Respect scope** — analyse only the diff between trunk and the current branch; do not conflate with unrelated changes