--- name: interactive-code-review description: Human-in-the-loop code review with chunk-by-chunk approve/reject/chat loop (git add -p style). Use when reviewing PRs, diffs, patches, or documents interactively. Triggers on "review my PR", "walk through changes", "interactive review". model: sonnet allowed-tools: Read, Bash, Glob --- # Interactive Code Review Run a structured, interactive review session that presents changes in small, readable chunks and waits for the human to approve, reject, or chat before moving on. ## Framework Structured Walkthrough: author intent is surfaced first, then the reviewer probes for risks, gaps, and misunderstandings. Established software quality practice (IEEE 1028) for defect detection and shared understanding. ## Workflow 1. **Confirm target and intent.** - Ask for the diff source if unclear (branch range, file paths, or patch). - Clarify what "good" looks like (correctness, style, performance, risk). 2. **Gather material.** - For code: `git status -sb`, `git diff --stat`, then `git diff ...`. - For documents: ask for the text, sections, or relevant excerpt. 3. **Chunk the review.** - File-by-file, then hunk-by-hunk within each file. - Target 40–120 lines per chunk. Split large hunks. - Order: module boundaries (entry points, public interfaces) first, then internals, finally tests. - For prose: split by headings or logical paragraphs. 4. **Present each chunk** with the standard template. Pause for explicit response. 5. **Handle responses.** - **Approve**: mark approved, continue. - **Reject**: explain issue, propose concrete edit, confirm before changing files. - **Chat**: answer questions, show context. Re-prompt with same actions. Chat loops until user gives approve/reject/skip. - **Skip**: mark for later, continue. - **Done**: end review immediately, show summary. - **Jump [file]**: skip to specific file. 6. **Wrap up with summary.** - List approved, rejected, skipped chunks. - Offer to apply edits or re-run on updated diffs. ## Actions | Action | Aliases | Effect | |--------|---------|--------| | approve | ok, lgtm, yes, y, +1 | Mark approved, continue | | reject | no, fix, change, -1 | Explain issue, propose edit | | chat | ?, context, explain, why | More context, re-prompt | | skip | later, defer | Mark for later, continue | | done | stop, abort | End review, show summary | | jump [file] | go [file] | Skip to specific file | ## Chunk Template ``` Review chunk [i/N] File: Summary: <1–2 lines> Action? (approve / reject / chat / skip / done) ``` ## Progress Indicator After every 5 chunks or on request: ``` Progress: [====------] 4/10 | 2 approved | 1 rejected | 1 skipped ``` ## Reviewer Conduct - Verify before asserting or applying edits. - Ask clarifying questions when feedback or intent is unclear. - Avoid performative agreement; focus on evidence and fixes. - Keep tone neutral and concise; avoid rewriting unless requested. ## Review Heuristics - Flag correctness risks, security issues, breaking changes, and missing tests first. - At module boundaries: verify the contract (inputs/outputs) is preserved. - For legacy code: check if change increases or decreases testability. - For text: flag unclear intent, inconsistencies, missing context. - If rejecting, include: issue, why it matters, and a concrete fix. ## Deep Review Mode If user asks for full assessment (e.g., "production readiness"): ### Strengths [What's well done.] ### Issues #### Critical (Must Fix) [Bugs, security, data loss risks] #### Important (Should Fix) [Design gaps, missing requirements, test gaps] #### Minor (Nice to Have) [Nitpicks, optimizations, docs] ### Recommendations [Concise improvements] ### Assessment **Ready to merge?** [Yes/No/With fixes] (X-Y% confident) **Key assumptions:** [List 2-3 assumptions behind assessment] **Reasoning:** [1-2 sentences] ## Integration - Before claiming review complete: run `hope:gate` checklist - If rejection reveals systemic issue: suggest `hope:trace` for root cause - For security-focused reviews: reference `soul/references/differential-review.md` ## Safety - Do not stage, commit, or modify files unless user explicitly asks. - Maximum: 20 files or 2000 lines of diff per session. Larger reviews: split by directory. - Binary files: skip with note "Binary file, review manually" - Merge conflicts: pause and ask user to resolve first