Delve — Interactive Diff Review
Walk a reviewer through a diff one cohesive chunk at a time. Collect comments as structured TODOs that a downstream
agent can act on.
Phase 1: Choose Diff Baseline
Always prompt the user to choose. Suggest a default based on session history, but never auto-select.
Present these options:
- Merge base — changes since the branch diverged from the merge target
(default if this is the first diff action in the session)
- Last session — changes since the previous delve session
(default if a prior delve session exists)
- Last change — uncommitted changes if any exist, otherwise the last commit
- Custom ref — user provides a base and/or head ref
After the user chooses, store the baseline in session state (see Phase 6).
Resolving the baseline to git refs
| Choice |
base ref |
head ref |
| Merge base |
git merge-base HEAD <target-branch> |
HEAD |
| Last session |
stored ref from previous session |
HEAD |
| Last change |
HEAD (if uncommitted) or HEAD~1 |
working tree or HEAD |
| Custom ref |
user-provided |
user-provided or HEAD |
If the target branch is unknown, ask the user. Common defaults: main, master, or the repo's default branch.
Phase 2: Acquire the Diff
- Run
git diff --stat <base> <head> to get the file-level summary.
- For each changed file, run
git diff <base> <head> -- <file> to get the full unified diff.
- Parse each file diff into atomic hunks. A hunk is one contiguous block of changes (one
@@ section in unified
diff format).
- For every hunk, record metadata:
- file path
- change type: added / modified / deleted / renamed
- enclosing symbol: the function, method, or class the hunk sits inside (read the
@@ context line and
surrounding code to determine this)
- symbols referenced: any functions, types, or variables that appear in the changed lines
Process files one at a time to keep context usage bounded. Store hunk metadata as you go rather than holding every diff
in context simultaneously.
Phase 3: Plan the Chunk Order
Group and order hunks into chunks — each chunk is a set of related hunks that the reviewer will see together on one
screen.
3.1 Constraints (co-optimize all four)
[!NOTE]
The screen-fit target is ~40 lines of diff per chunk. This value is
referenced throughout this skill.
- Screen fit — a chunk should fit comfortably on one screen (within the screen-fit target). If a single hunk
exceeds this, it becomes its own chunk.
- High cohesion — group hunks that belong to the same logical change: same function, same module, same feature.
- Utility function placement:
- Show utility functions first if understanding them is required to comprehend later chunks.
- Show utility functions last if they are self-evident or rarely called.
- Call flow — prefer showing function implementations before their call sites. The reader should understand what
a function does before seeing where it's used.
3.2 Heuristic: Build a Symbol Graph
- From the hunk metadata, build a graph:
- Nodes = symbols (functions, classes, methods) that were changed or referenced in changed lines.
- Edges = call/reference relationships (implementation → call site).
- Score each potential chunk grouping by:
- Cohesion: how many hunks in the chunk share the same symbol or module.
- Dependency direction: does the chunk show implementations before uses?
- Screen fit: is the total diff size within the screen-fit target?
- Utility likelihood: is this a standalone helper? (heuristic: small function, many callers, few dependencies)
- Greedily assemble chunks that maximize the combined score.
3.3 Output: the Diff Plan
Store the ordered list of chunks with their hunk assignments. This is the Diff Plan - the sequence the reviewer will
walk through.
3.4 Generate and Validate Chunk Files
Before showing the Diff Plan to the user, verify that each planned chunk fits within the screen-fit target and then
generate the final chunk files. This step is mandatory - do not skip it.
Measure line counts before writing files. For each planned chunk, check how many lines its diff would produce
WITHOUT writing to a file:
- Unix:
git diff <base> <head> -- <file1> [<file2>...] | wc -l
- Windows:
git diff <base> <head> -- <file1> [<file2>...] | Measure-Object -Line
Re-plan any chunk that exceeds 40 lines:
- If it contains hunks from multiple files: split into one chunk per file and re-measure.
- If it contains multiple hunks from one file: split into one chunk per hunk and re-measure.
- If a single hunk still exceeds 40 lines: keep it as one chunk. It will be displayed with
view_range
pagination in Phase 4.
Write all chunk files in one pass once every chunk is validated. Use sequential numbering and output redirection
(no diff content in stdout):
git diff <base> <head> -- <file1> [<file2>...] > <session-dir>/delve-chunk-01.diff
git diff <base> <head> -- <file3> > <session-dir>/delve-chunk-02.diff
Where <session-dir> is the session workspace directory.
Show the user the validated Diff Plan:
- Number of chunks
- Files covered
- Estimated review time (rough: ~1 min per 30 lines of diff)
Phase 4: Review Loop
Walk through the Diff Plan one chunk at a time. All chunk diff files were pre-generated in Phase 3.4 - no shell commands
are needed during the review loop.
For each chunk:
Display the chunk using show_file:
- If the chunk file is ≤ 40 lines:
show_file(path: "<session-dir>/delve-chunk-NN.diff")
- If the chunk file is > 40 lines (a single oversized hunk from
Phase 3.4 step 3):
show_file(path: "<session-dir>/delve-chunk-NN.diff", view_range: [1, 40])
Tell the user the chunk continues beyond what is shown. If they ask to see more, show the next 40-line window with
an updated view_range.
Prompt the user with a structured form using ask_user:
{
"message": "Chunk N/M: <file path(s)> — <symbol(s)>",
"requestedSchema": {
"properties": {
"comment": {
"type": "string",
"title": "Comment (optional)",
"description": "Leave feedback on this chunk. Each submission = 1 TODO."
},
"action": {
"type": "string",
"title": "Action",
"enum": ["Next", "Comment & stay", "Previous", "Done"],
"enumNames": ["Next →", "💬 Comment & stay", "← Previous", "Done ✓"],
"default": "Next"
}
},
"required": ["action"]
}
}
Process the response:
- If
comment is provided: create a TODO (Phase 5).
- If
action = "Next": advance to the next chunk (with or without a comment). After leaving one or more
comments, flip the default to "Next".
- If
action = "Comment & stay": capture the TODO and re-display the same chunk's form for another comment.
- If
action = "Previous": go back one chunk. On the first chunk, tell the user they are at the start.
- If
action = "Done": skip to Phase 7.
- If the user declines the form (cancels without submitting): treat as "Next" with no comment.
"Next" on the last chunk triggers completion (Phase 7).
Phase 5: Capture TODOs
Every comment the reviewer leaves becomes a TODO for a downstream agent.
TODO structure
Each TODO must include:
| Field |
Description |
| comment |
The reviewer's comment, verbatim. |
| file_path |
File(s) the chunk covers. |
| symbol |
Enclosing function/class/method name(s). |
| excerpt |
A short (3–5 line) excerpt of the relevant changed code. |
| content_anchor |
A content-based anchor: the first non-blank changed line |
|
in the hunk. NOT a line number (those drift on rebase). |
Where to store TODOs (tiered — use the first available option)
- TodoWrite / built-in todo tool — if the session has a todo or task creation tool, write each TODO there.
- External task tracker — if a tool like Trekker is available, create issues/tasks there.
- Session file fallback — write TODOs as a JSON array to a file in the session workspace (e.g.,
delve-todos.json).
- Context fallback — if none of the above are available, output the TODO list directly in the conversation for the
user to copy.
Phase 6: Session State
Persist the following across the session so the review can be resumed or referenced later.
| Key |
Value |
delve_baseline |
The chosen baseline (type + resolved refs) |
delve_head_ref |
The HEAD ref at review start (for "last session") |
delve_plan |
The ordered list of chunks with hunk assignments |
delve_position |
Current chunk index |
delve_completed |
Set of chunk indices the user has visited |
delve_todos |
List of TODOs with context anchors |
Storage strategy (tiered — use the first available option)
SQL tool — if available, create a delve_state table:
CREATE TABLE IF NOT EXISTS delve_state (
key TEXT PRIMARY KEY,
value TEXT
);
Store each key/value pair as a row. Values are JSON-encoded.
Session file fallback — write state as a single JSON file in the session workspace (e.g., delve-state.json).
At the start of a new delve session, check for existing state:
- If
delve_head_ref exists from a prior session, offer it as the "Last session" baseline option.
- If
delve_plan exists and the baseline hasn't changed, offer to resume the previous review from delve_position.
Phase 7: Completion
When the user advances past the last chunk:
Summarize the review:
- Total chunks reviewed
- Number of TODOs captured
- Files covered
If TODOs exist, offer to:
- List all TODOs with their context anchors
- Revisit a specific TODO's chunk
- Hand off the TODO list to an implementation agent
Update session state:
- Store the current HEAD as
delve_head_ref so the next session can offer "changes since last session" as a baseline.
Quick Reference
/delve
1. Choose baseline → merge base / last session / last change / custom
2. Acquire diff → git diff per file, parse into hunks
3. Plan chunks → group by cohesion, order by call flow
Validate chunks → generate .diff files, enforce ≤ 40 lines, split if needed
4. Review loop → show_file chunk → ask_user (action + comment) → repeat
5. Capture TODOs → structured TODOs with content anchors
6. Complete → summary + TODO handoff
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: mattkotsenas-agent-plugins-delve3description: Delve — Interactive Diff Review4---56# Delve — Interactive Diff Review78Walk a reviewer through a diff one cohesive chunk at a time. Collect comments as structured TODOs that a downstream9agent can act on.1011---1213## Phase 1: Choose Diff Baseline1415**Always prompt the user to choose.** Suggest a default based on session history, but never auto-select.1617Present these options:1819- **Merge base** — changes since the branch diverged from the merge target20 *(default if this is the first diff action in the session)*21- **Last session** — changes since the previous delve session22 *(default if a prior delve session exists)*23- **Last change** — uncommitted changes if any exist, otherwise the last commit24- **Custom ref** — user provides a base and/or head ref2526After the user chooses, store the baseline in session state (see Phase 6).2728### Resolving the baseline to git refs2930| Choice | base ref | head ref |31|--------------|----------------------------------------------|--------------|32| Merge base | `git merge-base HEAD <target-branch>` | `HEAD` |33| Last session | stored ref from previous session | `HEAD` |34| Last change | `HEAD` (if uncommitted) or `HEAD~1` | working tree or `HEAD` |35| Custom ref | user-provided | user-provided or `HEAD` |3637If the target branch is unknown, ask the user. Common defaults: `main`, `master`, or the repo's default branch.3839---4041## Phase 2: Acquire the Diff42431. Run `git diff --stat <base> <head>` to get the file-level summary.442. For each changed file, run `git diff <base> <head> -- <file>` to get the full unified diff.453. Parse each file diff into **atomic hunks**. A hunk is one contiguous block of changes (one `@@` section in unified46 diff format).474. For every hunk, record metadata:48 - **file path**49 - **change type**: added / modified / deleted / renamed50 - **enclosing symbol**: the function, method, or class the hunk sits inside (read the `@@` context line and51 surrounding code to determine this)52 - **symbols referenced**: any functions, types, or variables that appear in the changed lines5354Process files one at a time to keep context usage bounded. Store hunk metadata as you go rather than holding every diff55in context simultaneously.5657---5859## Phase 3: Plan the Chunk Order6061Group and order hunks into **chunks** — each chunk is a set of related hunks that the reviewer will see together on one62screen.6364### 3.1 Constraints (co-optimize all four)6566> [!NOTE]67> The **screen-fit target** is ~40 lines of diff per chunk. This value is68> referenced throughout this skill.69701. **Screen fit** — a chunk should fit comfortably on one screen (within the screen-fit target). If a single hunk71 exceeds this, it becomes its own chunk.722. **High cohesion** — group hunks that belong to the same logical change: same function, same module, same feature.733. **Utility function placement**:74 - Show utility functions **first** if understanding them is required to comprehend later chunks.75 - Show utility functions **last** if they are self-evident or rarely called.764. **Call flow** — prefer showing function implementations before their call sites. The reader should understand *what*77 a function does before seeing *where* it's used.7879### 3.2 Heuristic: Build a Symbol Graph80811. From the hunk metadata, build a graph:82 - Nodes = symbols (functions, classes, methods) that were changed or referenced in changed lines.83 - Edges = call/reference relationships (implementation → call site).842. Score each potential chunk grouping by:85 - **Cohesion**: how many hunks in the chunk share the same symbol or module.86 - **Dependency direction**: does the chunk show implementations before uses?87 - **Screen fit**: is the total diff size within the screen-fit target?88 - **Utility likelihood**: is this a standalone helper? (heuristic: small function, many callers, few dependencies)893. Greedily assemble chunks that maximize the combined score.9091### 3.3 Output: the Diff Plan9293Store the ordered list of chunks with their hunk assignments. This is the **Diff Plan** - the sequence the reviewer will94walk through.9596### 3.4 Generate and Validate Chunk Files9798Before showing the Diff Plan to the user, verify that each planned chunk fits within the screen-fit target and then99generate the final chunk files. This step is mandatory - do not skip it.1001011. **Measure line counts before writing files.** For each planned chunk, check how many lines its diff would produce102 WITHOUT writing to a file:103 - **Unix:** `git diff <base> <head> -- <file1> [<file2>...] | wc -l`104 - **Windows:** `git diff <base> <head> -- <file1> [<file2>...] | Measure-Object -Line`1051062. **Re-plan any chunk that exceeds 40 lines:**107 - If it contains hunks from **multiple files**: split into one chunk per file and re-measure.108 - If it contains **multiple hunks from one file**: split into one chunk per hunk and re-measure.109 - If a **single hunk** still exceeds 40 lines: keep it as one chunk. It will be displayed with `view_range`110 pagination in Phase 4.1111123. **Write all chunk files in one pass** once every chunk is validated. Use sequential numbering and output redirection113 (no diff content in stdout):114 ```115 git diff <base> <head> -- <file1> [<file2>...] > <session-dir>/delve-chunk-01.diff116 git diff <base> <head> -- <file3> > <session-dir>/delve-chunk-02.diff117 ```118 Where `<session-dir>` is the session workspace directory.1191204. **Show the user** the validated Diff Plan:121 - Number of chunks122 - Files covered123 - Estimated review time (rough: ~1 min per 30 lines of diff)124125---126127## Phase 4: Review Loop128129Walk through the Diff Plan one chunk at a time. All chunk diff files were pre-generated in Phase 3.4 - no shell commands130are needed during the review loop.131132### For each chunk:1331341. **Display the chunk** using `show_file`:135 - If the chunk file is **≤ 40 lines**:136 ```137 show_file(path: "<session-dir>/delve-chunk-NN.diff")138 ```139 - If the chunk file is **> 40 lines** (a single oversized hunk from140 Phase 3.4 step 3):141 ```142 show_file(path: "<session-dir>/delve-chunk-NN.diff", view_range: [1, 40])143 ```144 Tell the user the chunk continues beyond what is shown. If they ask to see more, show the next 40-line window with145 an updated `view_range`.1461472. **Prompt the user** with a structured form using `ask_user`:148 ```json149 {150 "message": "Chunk N/M: <file path(s)> — <symbol(s)>",151 "requestedSchema": {152 "properties": {153 "comment": {154 "type": "string",155 "title": "Comment (optional)",156 "description": "Leave feedback on this chunk. Each submission = 1 TODO."157 },158 "action": {159 "type": "string",160 "title": "Action",161 "enum": ["Next", "Comment & stay", "Previous", "Done"],162 "enumNames": ["Next →", "💬 Comment & stay", "← Previous", "Done ✓"],163 "default": "Next"164 }165 },166 "required": ["action"]167 }168 }169 ```1701713. **Process the response:**172 - If `comment` is provided: create a TODO (Phase 5).173 - If `action` = **"Next"**: advance to the next chunk (with or without a comment). After leaving one or more174 comments, flip the default to "Next".175 - If `action` = **"Comment & stay"**: capture the TODO and re-display the same chunk's form for another comment.176 - If `action` = **"Previous"**: go back one chunk. On the first chunk, tell the user they are at the start.177 - If `action` = **"Done"**: skip to Phase 7.178 - If the user **declines** the form (cancels without submitting): treat as "Next" with no comment.1791804. **"Next" on the last chunk** triggers completion (Phase 7).181182---183184## Phase 5: Capture TODOs185186Every comment the reviewer leaves becomes a TODO for a downstream agent.187188### TODO structure189190Each TODO must include:191192| Field | Description |193|--------------------|------------------------------------------------------------|194| **comment** | The reviewer's comment, verbatim. |195| **file_path** | File(s) the chunk covers. |196| **symbol** | Enclosing function/class/method name(s). |197| **excerpt** | A short (3–5 line) excerpt of the relevant changed code. |198| **content_anchor** | A content-based anchor: the first non-blank changed line |199| | in the hunk. NOT a line number (those drift on rebase). |200201### Where to store TODOs (tiered — use the first available option)2022031. **TodoWrite / built-in todo tool** — if the session has a todo or task creation tool, write each TODO there.2042. **External task tracker** — if a tool like Trekker is available, create issues/tasks there.2053. **Session file fallback** — write TODOs as a JSON array to a file in the session workspace (e.g., `delve-todos.json`).2064. **Context fallback** — if none of the above are available, output the TODO list directly in the conversation for the207 user to copy.208209---210211## Phase 6: Session State212213Persist the following across the session so the review can be resumed or referenced later.214215| Key | Value |216|--------------------|--------------------------------------------------|217| `delve_baseline` | The chosen baseline (type + resolved refs) |218| `delve_head_ref` | The HEAD ref at review start (for "last session")|219| `delve_plan` | The ordered list of chunks with hunk assignments |220| `delve_position` | Current chunk index |221| `delve_completed` | Set of chunk indices the user has visited |222| `delve_todos` | List of TODOs with context anchors |223224### Storage strategy (tiered — use the first available option)2252261. **SQL tool** — if available, create a `delve_state` table:227 ```sql228 CREATE TABLE IF NOT EXISTS delve_state (229 key TEXT PRIMARY KEY,230 value TEXT231 );232 ```233 Store each key/value pair as a row. Values are JSON-encoded.2342352. **Session file fallback** — write state as a single JSON file in the session workspace (e.g., `delve-state.json`).236237At the **start of a new delve session**, check for existing state:238- If `delve_head_ref` exists from a prior session, offer it as the "Last session" baseline option.239- If `delve_plan` exists and the baseline hasn't changed, offer to resume the previous review from `delve_position`.240241---242243## Phase 7: Completion244245When the user advances past the last chunk:2462471. **Summarize the review:**248 - Total chunks reviewed249 - Number of TODOs captured250 - Files covered2512522. **If TODOs exist**, offer to:253 - List all TODOs with their context anchors254 - Revisit a specific TODO's chunk255 - Hand off the TODO list to an implementation agent2562573. **Update session state:**258 - Store the current HEAD as `delve_head_ref` so the next session can offer "changes since last session" as a baseline.259260---261262## Quick Reference263264```265/delve266 1. Choose baseline → merge base / last session / last change / custom267 2. Acquire diff → git diff per file, parse into hunks268 3. Plan chunks → group by cohesion, order by call flow269 Validate chunks → generate .diff files, enforce ≤ 40 lines, split if needed270 4. Review loop → show_file chunk → ask_user (action + comment) → repeat271 5. Capture TODOs → structured TODOs with content anchors272 6. Complete → summary + TODO handoff273```274275---276> Converted and distributed by [TomeVault](https://tomevault.io/claim/mattkotsenas) — claim your Tome and manage your conversions.277<!-- tomevault:4.0:skill_md:2026-04-14 -->
tomevault-io