# Mattkotsenas Agent Plugins Delve > Delve — Interactive Diff Review - Skill: `tomevault-io/mattkotsenas-agent-plugins-delve` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/mattkotsenas-agent-plugins-delve` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mattkotsenas-agent-plugins-delve/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/mattkotsenas-agent-plugins-delve --- # 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 ` | `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 1. Run `git diff --stat ` to get the file-level summary. 2. For each changed file, run `git diff -- ` to get the full unified diff. 3. Parse each file diff into **atomic hunks**. A hunk is one contiguous block of changes (one `@@` section in unified diff format). 4. 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. 1. **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. 2. **High cohesion** — group hunks that belong to the same logical change: same function, same module, same feature. 3. **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. 4. **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 1. 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). 2. 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) 3. 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. 1. **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 -- [...] | wc -l` - **Windows:** `git diff -- [...] | Measure-Object -Line` 2. **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. 3. **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 -- [...] > /delve-chunk-01.diff git diff -- > /delve-chunk-02.diff ``` Where `` is the session workspace directory. 4. **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: 1. **Display the chunk** using `show_file`: - If the chunk file is **≤ 40 lines**: ``` show_file(path: "/delve-chunk-NN.diff") ``` - If the chunk file is **> 40 lines** (a single oversized hunk from Phase 3.4 step 3): ``` show_file(path: "/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`. 2. **Prompt the user** with a structured form using `ask_user`: ```json { "message": "Chunk N/M: — ", "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"] } } ``` 3. **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. 4. **"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) 1. **TodoWrite / built-in todo tool** — if the session has a todo or task creation tool, write each TODO there. 2. **External task tracker** — if a tool like Trekker is available, create issues/tasks there. 3. **Session file fallback** — write TODOs as a JSON array to a file in the session workspace (e.g., `delve-todos.json`). 4. **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) 1. **SQL tool** — if available, create a `delve_state` table: ```sql 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. 2. **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: 1. **Summarize the review:** - Total chunks reviewed - Number of TODOs captured - Files covered 2. **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 3. **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](https://tomevault.io/claim/mattkotsenas) — claim your Tome and manage your conversions.