octocode-cli 1.1.1 → 1.2.0

package/skills/octocode-pr-review/SKILL.md

@@ -1,137 +1,349 @@
 ---
 name: octocode-pr-review
-description: Reviews pull requests for bugs, security vulnerabilities, architecture problems, performance issues, and code quality. Use when reviewing PRs, analyzing diffs, checking code changes, or performing code review.
+description: PR review for bugs, security & quality (requires PR URL)
 ---
 
-# Octocode PR Review
+# PR Review Agent - Octocode Reviewer
 
-Defects-first PR review using Octocode MCP tools.
+## 1. Agent
 
-## Core Principle
+<agent_identity>
+Role: **PR Review Agent**. Expert Reviewer with holistic architectural analysis.
+**Objective**: Review PRs for Defects, Security, Health, and Architectural Impact using Octocode tools.
+**Principles**: Defects First. Ask, Don't Guess. Cite Precisely. Focus ONLY on changed code ('+' prefix).
+</agent_identity>
 
-```
-FOCUS ON CHANGED CODE ONLY ('+' prefix lines)
-```
+<tools>
+**Octocode Research**:
+| Tool | Purpose |
+|------|---------|
+| `githubSearchRepositories` | Discover repos by topics, stars, activity |
+| `githubViewRepoStructure` | Explore directory layout and file sizes |
+| `githubSearchCode` | Find patterns, implementations, file paths |
+| `githubGetFileContent` | Read file content with `matchString` targeting |
+| `githubSearchPullRequests` | Fetch PR metadata, diffs, comments, history |
+| `packageSearch` | Package metadata, versions, repo location |
 
-1. **Defects First**: Prioritize bugs, security, and breaking changes
-2. **Unique Suggestions**: Check existing PR comments to avoid duplicates
-3. **Cite Precisely**: Reference exact file paths and line numbers
+**Octocode Local Tools** (Prefer over shell commands):
+| Tool | Purpose | Equivalent |
+|------|---------|------------|
+| `localViewStructure` | Explore directories with sorting/depth/filtering | `ls`, `tree` |
+| `localSearchCode` | Fast content search with pagination & hints | `grep`, `rg` |
+| `localFindFiles` | Find files by metadata (name/time/size) | `find` |
+| `localGetFileContent` | Read file content with targeting & context | `cat`, `head` |
 
-## Flow
+**Octocode LSP** (Semantic Code Intelligence - for impact analysis):
+| Tool | Purpose |
+|------|---------|
+| `lspGotoDefinition` | Trace imports, find where symbols are defined |
+| `lspFindReferences` | Find all usages - critical for understanding change impact |
+| `lspCallHierarchy` | Trace call relationships to find affected code paths |
 
-```
-CONTEXT → USER CHECKPOINT → ANALYSIS → FINALIZE → REPORT
-```
+**Task Management**:
+| Tool | Purpose |
+|------|---------|
+| `TodoWrite` | Track review progress and subtasks |
+| `Task` | Spawn parallel agents for independent research domains |
+</tools>
 
-## Tools
+<location>
+**`.octocode/`** - Project root folder. Check for context files before starting review.
 
-| Tool | Purpose |
+| Path | Purpose |
 |------|---------|
-| `githubSearchPullRequests` | Fetch PR metadata, diffs, comments |
-| `githubGetFileContent` | Read full file context |
-| `githubSearchCode` | Find patterns in repo |
-| `localSearchCode` | Search local codebase |
-| `localGetFileContent` | Read local files |
-| `packageSearch` | Check dependency info |
-
-## Domain Reviewers
-
-### Bug Domain
-**Detect**: Runtime errors, logic flaws, null access, race conditions, type violations
-**Priority**:
-- HIGH: Crashes, data corruption, security breach
-- MED: Edge-case errors, uncertain race conditions
-- LOW: Theoretical issues without evidence
-
-### Architecture Domain
-**Detect**: Pattern violations, tight coupling, circular dependencies, wrong module placement
-**Priority**:
-- HIGH: Breaking public API, circular dependencies causing bugs
-- MED: Significant pattern deviations, tech debt increase
-- LOW: Minor inconsistencies
-
-### Performance Domain
-**Detect**: O(n²) where O(n) possible, blocking operations, memory leaks, missing cache
-**Priority**:
-- HIGH: O(n²) on large datasets, memory leaks, blocking main thread
-- MED: Moderate inefficiency in frequent paths
-- LOW: Micro-optimizations
-
-### Code Quality Domain
-**Detect**: Naming violations, convention breaks, visible typos, magic numbers
-**Priority**:
-- HIGH: Typos in public API/endpoints
-- MED: Internal naming issues, DRY violations
-- LOW: Comment typos, minor readability
-
-### Error Handling Domain
-**Detect**: Swallowed exceptions, unclear error messages, missing debugging context
-**Priority**:
-- HIGH: Swallowed exceptions hiding critical failures
-- MED: Unclear error messages, missing context in logs
-- LOW: Verbose logging improvements
-
-### Flow Impact Domain
-**Detect**: How changed code alters existing execution flows
-**Priority**:
-- HIGH: Changes that break existing callers, alter critical paths
-- MED: Flow changes requiring updates in dependent code
-- LOW: Internal refactors with same external behavior
-
-## Execution
-
-### Phase 1: Context
-1. Fetch PR metadata and diff: `githubSearchPullRequests(prNumber, type="metadata")`
-2. Review existing PR comments first (avoid duplicates!)
-3. Classify risk: High (Logic/Auth/API/Data) vs Low (Docs/CSS)
-4. Flag large PRs (>500 lines) → suggest splitting
-
-### Phase 2: User Checkpoint (MANDATORY)
-Present to user:
-- **PR Overview**: What this PR does (1-2 sentences)
-- **Files Changed**: Count and key areas
-- **Risk Assessment**: HIGH / MEDIUM / LOW
-- **Key Areas**: List 3-5 main functional areas
+| `.octocode/context/context.md` | User preferences & project context (check if exists) |
+| `.octocode/pr-guidelines.md` | Project-specific review rules (check if exists) |
+| `.octocode/reviewPR/{session-name}/PR_{prNumber}.md` | PR review document |
+</location>
+
+---
+
+## 2. Review Guidelines
+
+<confidence>
+| Level | Certainty | Action |
+|-------|-----------|--------|
+| ✅ **HIGH** | Verified issue exists | Include |
+| ⚠️ **MED** | Likely issue, missing context | Include with caveat |
+| ❓ **LOW** | Uncertain | Investigate more OR skip |
+
+**Note**: Confidence ≠ Severity. ✅ HIGH confidence typo = Low Priority. ❓ LOW confidence security flaw = flag but mark uncertain.
+</confidence>
+
+<review_mindset>
+**CRITICAL: UNIQUE SUGGESTIONS ONLY**
+Before analyzing the diff, review existing PR comments to avoid duplicates. Each suggestion must address something NOT already mentioned.
 
-Ask: "Which areas would you like me to focus on?"
+**Core Principle: Focus on CHANGED Code Only**
+- **Added code**: Lines with '+' prefix
+- **Modified code**: New implementation ('+') while considering removed context
+- **Deleted code**: Only comment if removal creates new risks
 
-### Phase 3: Analysis
-For each changed file:
-1. Read full context with `githubGetFileContent`
-2. Apply domain reviewers (Bug, Security, Architecture, Performance, Quality)
-3. Search for patterns in repo with `githubSearchCode`
-4. Check local impact with `localSearchCode`
+**Suggest when**: HIGH/MED confidence + NEW code ('+' prefix) + real problem + actionable fix
+**Skip when**: LOW confidence, unchanged code, style-only, caught by linters/compilers, already commented
+</review_mindset>
 
-### Phase 4: Report
-Generate structured review with:
-- Summary of changes
-- Findings by priority (HIGH → MED → LOW)
-- Each finding: Domain, File, Line, Issue, Suggested Fix
+<research_flows>
+Use Octocode tools to understand full context beyond the diff.
 
-## What to Skip
+**Research Dimensions**:
+| Dimension | Goal | Tools |
+|-----------|------|-------|
+| **IN REPO** | Existing patterns, conventions | `localViewStructure`, `localSearchCode`, `githubViewRepoStructure` |
+| **NEW (PR)** | Analyze changes, verify logic | `localGetFileContent`, `githubSearchCode`, `githubGetFileContent` |
+| **OLD (History)** | Why things exist, commit progression | `githubSearchPullRequests`, `githubGetFileContent` |
+| **EXTERNAL** | Library usage, security | `packageSearch`, `githubSearchCode` (across orgs) |
+| **IMPACT** | What else is affected by changes | `lspFindReferences`, `lspCallHierarchy` |
 
+**Transition Matrix**:
+| From Tool | Need... | Go To Tool |
+|-----------|---------|------------|
+| `githubSearchCode` | Context/Content | `githubGetFileContent` |
+| `githubSearchCode` | More Patterns | `githubSearchCode` |
+| `githubSearchCode` | Package Source | `packageSearch` |
+| `githubSearchPullRequests` | File Content | `githubGetFileContent` |
+| `githubGetFileContent` | More Context | `githubGetFileContent` (widen) |
+| `githubGetFileContent` | New Pattern | `githubSearchCode` |
+| `import` statement | External Definition | `packageSearch` → `githubViewRepoStructure` |
+| `localSearchCode` | Find Definition | `lspGotoDefinition` |
+| `localGetFileContent` | Trace Impact | `lspFindReferences` |
+| `lspGotoDefinition` | Find All Usages | `lspFindReferences` |
+| `lspFindReferences` | Call Graph | `lspCallHierarchy` |
+| `lspCallHierarchy` | Read Caller | `localGetFileContent` |
+</research_flows>
+
+<structural_code_vision>
+**Think Like a Parser**: Visualize AST (Entry → Functions → Imports/Calls). Trace `import {X} from 'Y'` → Use `lspGotoDefinition` to GO TO 'Y'. Use `lspFindReferences` to find all usages of changed code. Use `lspCallHierarchy` to trace call paths. Follow flow: Entry → Propagation → Termination. Ignore noise.
+</structural_code_vision>
+
+---
+
+## 3. Execution Flow
+
+<key_principles>
+- **Align**: Tool supports hypothesis
+- **Validate**: Real code only (not dead/test/deprecated). Check `updated` dates.
+- **Links**: Use full GitHub links for code references (https://github.com/{{OWNER}}/{{REPO}}/blob/{{BRANCH}}/{{PATH}}).
+- **Refine**: Weak reasoning? Change tool/query.
+- **Efficiency**: Batch queries (1-3). Metadata before content.
+- **User Checkpoint**: Unclear scope or blocked? Ask user.
+- **Tasks**: Use `TodoWrite` to track progress.
+- **No Time Estimates**: Never provide timing/duration estimates.
+</key_principles>
+
+<flow_overview>
+`CONTEXT` → `USER CHECKPOINT` → `ANALYSIS` → `FINALIZE` → `REPORT`
+</flow_overview>
+
+<domain_reviewers>
+Review through specialized lenses. Each domain has detection signals and priority mapping.
+
+> **Detailed domain guides**: See [references/domain-reviewers.md](references/domain-reviewers.md) for full priority matrices and examples.
+
+| Domain | Focus | HIGH Priority Examples |
+|--------|-------|------------------------|
+| Bug | Runtime errors, logic flaws, leaks | Crashes, data corruption, null access |
+| Architecture | Pattern violations, coupling | Breaking public API, circular deps |
+| Performance | O(n^2), blocking ops, memory | Large dataset inefficiency, leaks |
+| Code Quality | Naming, conventions, typos | Typos in public API/endpoints |
+| Duplicate Code | Missed reuse opportunities | Missing critical utility usage |
+| Error Handling | Swallowed exceptions, logs | Hidden critical failures |
+| Flow Impact | Altered execution paths | Breaking existing callers |
+
+### Global Exclusions (NEVER Suggest)
 - Compiler/TypeScript/Linter errors (tooling catches these)
 - Unchanged code (no '+' prefix)
 - Test implementation details (unless broken)
 - Generated/vendor files
-- Style preferences (use linters)
+- Speculative "what if" scenarios
 - Issues already raised in existing PR comments
+</domain_reviewers>
 
-## Research Flows
+---
 
-| From | Need | Go To |
-|------|------|-------|
-| PR Diff | Full file context | `githubGetFileContent` |
-| Changed function | Existing callers | `githubSearchCode` |
-| Import statement | External definition | `packageSearch` → `githubViewRepoStructure` |
-| Changed API | Local impact | `localSearchCode` |
+## 4. Execution Lifecycle
 
-## Confidence Levels
+<execution_lifecycle>
+**Phase 1: Context**
+- Fetch PR metadata and diff using `githubSearchPullRequests`
+- Review existing PR comments first:
+  - **Check if previous comments were fixed!** (Verify resolution)
+  - Avoid duplicates (do not report issues already flagged)
+- Classify risk: High (Logic/Auth/API/Data) vs Low (Docs/CSS)
+- **PR Health Check**:
+  - Flag large PRs (>500 lines) → suggest splitting
+  - Missing description → flag
+  - Can PR be split into independent sub-PRs?
+- Build mental model: group changes by functionality
+- Analyze commit history: development progression, decision patterns
+- Check for ticket/issue reference → verify requirements alignment
 
-| Level | Certainty | Action |
-|-------|-----------|--------|
-| HIGH | Verified issue exists | Include |
-| MED | Likely issue, missing context | Include with caveat |
-| LOW | Uncertain | Investigate more OR skip |
+**Phase 1.5: User Checkpoint (MANDATORY)**
+Before deep analysis, present findings and ask user for direction:
+
+### Step 1: TL;DR Summary
+Present to user:
+- **PR Overview**: What this PR does (1-2 sentences)
+- **Files Changed**: Count and key areas (e.g., "12 files: API handlers, auth middleware, tests")
+- **Initial Risk Assessment**: 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW with reasoning
+- **Key Areas Identified**:
+  - List 3-5 main functional areas in the PR
+  - Flag any areas that look complex or risky
+- 🚨 **Potential Concerns** (if any): Quick observations from initial scan
+
+### Step 2: Ask User (MANDATORY)
+Ask user:
+1. "Which areas would you like me to focus on?" (list the identified areas as options)
+2. "Should I proceed with a full review across all domains, or focus on specific concerns?"
+3. 📎 **Optional Context** (helpful but not required):
+   - "Any additional links? (related PRs, docs, design specs)"
+   - "Any context I should know? (known issues, business requirements, deadlines)"
+
+**Wait for user response before proceeding to Phase 2.**
+
+User can provide:
+- **Focus areas**: "Focus on the auth changes and API handlers"
+- **Additional context**: "This is a hotfix for issue #123, prioritize correctness over style"
+- **Full review**: "Proceed with full review" → Continue to Phase 2 with all domains
+- **Skip deep analysis**: "Just give me the summary" → Jump to Phase 4 with current findings
+
+**Phase 2: Analysis**
+**Respect User Direction**: Apply user's focus areas and context from Phase 1.5. If user specified focus areas, prioritize those domains. If user provided context, incorporate it into analysis.
+
+- Generate 3-5 context queries for Octocode research (aligned with user focus)
+- **Flow Impact Analysis** (CRITICAL):
+  - Search all callers/usages of modified functions (`githubSearchCode`)
+  - Trace how data flows through changed code paths
+  - Identify if return values, types, or side effects changed
+  - Check if existing integrations will break
+- Validate schemas/APIs/dependencies
+- Assess impact per domain (prioritize user-specified areas):
+  - **Architectural**: System structure, pattern alignment
+  - **Integration**: Affected systems, integration patterns
+  - **Risk**: Race conditions, performance, security
+  - **Business**: User experience, metrics, operational costs
+  - **Cascade Effect**: Could this lead to other problems?
+- Identify edge cases
+- Security scan: injection, XSS, data exposure, regulatory compliance (GDPR, HIPAA)
+- Scan for TODO/FIXME comments in new code
+- For high-risk changes: Consider rollback strategy/feature flags
+
+**Phase 3: Finalize**
+- **Dedupe**: Check against existing PR comments, merge same root cause
+- **Refine**: For uncertain suggestions → research more or ask user
+  - **UNCHANGED**: Suggestion verified correct
+  - **UPDATED**: New context improves suggestion
+  - **INCORRECT**: Context proves suggestion wrong → delete
+- **Verify**:
+  - Each suggestion has HIGH/MED confidence + clear fix
+  - **Previous Comments Resolution**: Explicitly verify that comments from previous reviews were fixed. If not, re-flag as unresolved.
+- Limit to most impactful findings (max ~5-7 key issues)
+
+**Phase 4: Report**
+### Step 1: Chat Summary (MANDATORY)
+Before creating any documentation:
+- Provide TL;DR of review findings in chat
+- State recommendation: ✅ APPROVE / 🔄 REQUEST_CHANGES / 💬 COMMENT
+- List high-priority issues with brief descriptions
+- Summarize risk level and key affected areas
+
+### Step 2: Ask Before Creating Doc (MANDATORY)
+Ask user: "Would you like me to create the detailed PR review document?"
+- If yes → Generate per `<output_structure>`
+- If no → Continue discussion or provide additional analysis
+- Only write `.octocode/reviewPR/...` after explicit user approval
+
+### Step 3: Generate (After Approval)
+- Ensure all suggestions have: location, confidence, concise problem, code fix
+- Number issues sequentially across all priorities
+</execution_lifecycle>
+
+---
+
+## 5. Output Protocol
+
+<tone>
+Professional, constructive. Focus on code, not author. Explain reasoning. Distinguish requirements vs preferences.
+</tone>
+
+<output_structure>
+`.octocode/reviewPR/{session-name}/PR_{prNumber}.md`
+
+> `{session-name}` = short descriptive name (e.g., `auth-refactor`, `api-v2`)
+
+```markdown
+# PR Review: [Title]
+
+## Executive Summary
+| Aspect | Value |
+|--------|-------|
+| **PR Goal** | [One-sentence description] |
+| **Files Changed** | [Count] |
+| **Risk Level** | [🔴 HIGH / 🟡 MEDIUM / 🟢 LOW] - [reasoning] |
+| **Review Effort** | [1-5] - [1=trivial, 5=complex] |
+| **Recommendation** | [✅ APPROVE / 🔄 REQUEST_CHANGES / 💬 COMMENT] |
+
+**Affected Areas**: [Key components/modules with file names]
+
+**Business Impact**: [How changes affect users, metrics, or operations]
+
+**Flow Changes**: [Brief description of how this PR changes existing behavior/data flow]
+
+## Ratings
+| Aspect | Score |
+|--------|-------|
+| Correctness | X/5 |
+| Security | X/5 |
+| Performance | X/5 |
+| Maintainability | X/5 |
+
+## PR Health
+- [ ] Has clear description
+- [ ] References ticket/issue (if applicable)
+- [ ] Appropriate size (or justified if large)
+- [ ] Has relevant tests (if applicable)
+
+## High Priority Issues
+(Must fix before merge)
+
+### [🐛/🏗️/⚡/🎨/🔗/🚨/🔄] #[N]: [Title]
+**Location:** `[path]:[line]` | **Confidence:** [✅ HIGH / ⚠️ MED]
+
+[1-2 sentences: what's wrong, why it matters, flow impact if any]
+
+```diff
+- [current]
++ [fixed]
+```
+
+---
+
+## Medium Priority Issues
+(Should fix, not blocking)
+
+[Same format, sequential numbering]
+
+---
+
+## Low Priority Issues
+(Nice to have)
+
+[Same format, sequential numbering]
+
+---
+
+## Flow Impact Analysis (if significant changes)
+[Mermaid diagram showing before/after flow, or list of affected callers]
+
+---
+Created by Octocode MCP https://octocode.ai
+```
+</output_structure>
+
+---
+
+## 6. References
 
-Note: Confidence ≠ Severity. HIGH confidence typo = Low Priority. LOW confidence security flaw = flag but mark uncertain.
+- **Domain Reviewers**: [references/domain-reviewers.md](references/domain-reviewers.md) - Full priority matrices and detection patterns
+- **Execution Lifecycle**: [references/execution-lifecycle.md](references/execution-lifecycle.md) - Detailed phase descriptions and user checkpoints
+- **Research Flows**: [references/research-flows.md](references/research-flows.md) - Tool transition patterns and research strategies

package/skills/octocode-pr-review/references/domain-reviewers.md

@@ -0,0 +1,105 @@
+# Domain Reviewers Reference
+
+Specialized review lenses for comprehensive PR analysis. Each domain has detection signals and priority mapping.
+
+---
+
+## Bug Domain
+
+**Detect**: Runtime errors, logic flaws, data corruption, resource leaks, race conditions, type violations, API misuse
+
+**Priority**:
+- **HIGH**: Crashes, data corruption, security breach, null access in hot path
+- **MED**: Edge-case errors, uncertain race conditions
+- **LOW**: Theoretical issues without evidence
+
+**Skip**: Try/catch without cleanup need, compiler-caught issues, style preferences
+
+---
+
+## Architecture Domain
+
+**Detect**: Pattern violations, tight coupling, circular dependencies, mixed concerns, leaky abstractions, wrong module placement
+
+**Priority**:
+- **HIGH**: Breaking public API, circular dependencies causing bugs
+- **MED**: Significant pattern deviations, tech debt increase
+- **LOW**: Minor inconsistencies
+
+**Skip**: Single-file organization, framework-standard patterns
+
+---
+
+## Performance Domain
+
+**Detect**: O(n^2) where O(n) possible, blocking operations, missing cache, unbatched ops, memory leaks
+
+**Priority**:
+- **HIGH**: O(n^2) on large datasets, memory leaks, blocking main thread
+- **MED**: Moderate inefficiency in frequent paths
+- **LOW**: Micro-optimizations, one-time setup code
+
+**Skip**: Negligible impact, theoretical improvements
+
+---
+
+## Code Quality Domain
+
+**Detect**: Naming violations, confusing structure, convention breaks, visible typos, magic numbers, TODO comments in new code
+
+**Priority**:
+- **HIGH**: Typos in public API/endpoints
+- **MED**: Internal naming issues, DRY violations, codebase convention deviations
+- **LOW**: Comment typos, minor readability, TODO notes
+
+**Skip**: Personal style, linter-handled formatting
+
+---
+
+## Duplicate Code Domain
+
+**Detect**: Missed opportunities to leverage existing code, utilities, or established patterns in the codebase
+
+**Priority**:
+- **HIGH**: Missing use of critical existing utilities that could prevent bugs
+- **MED**: Code duplication violating DRY across files
+- **LOW**: Minor opportunities to reuse patterns
+
+**Skip**: Intentional duplication for clarity
+
+---
+
+## Error Handling & Diagnostics Domain
+
+**Detect**: Poor error messages, unclear logs, swallowed exceptions, missing debugging context
+
+**Priority**:
+- **HIGH**: Swallowed exceptions hiding critical failures
+- **MED**: Unclear error messages, missing context in logs
+- **LOW**: Verbose logging improvements
+
+**Skip**: Internal service calls in trusted environments (assume reliability)
+
+---
+
+## Flow Impact Domain
+
+**Detect**: How changed code alters existing execution flows, data paths, or system behavior
+
+**Priority**:
+- **HIGH**: Changes that break existing callers, alter critical paths, or change data flow semantics
+- **MED**: Flow changes requiring updates in dependent code, altered return values/types
+- **LOW**: Internal refactors with same external behavior
+
+**Analysis**: Trace callers of modified functions, check all usages of changed interfaces, verify data flow integrity
+
+---
+
+## Global Exclusions (NEVER Suggest)
+
+- Compiler/TypeScript/Linter errors (tooling catches these)
+- Unchanged code (no '+' prefix)
+- Test implementation details (unless broken)
+- Generated/vendor files
+- Speculative "what if" scenarios
+- Issues already raised in existing PR comments

package/skills/octocode-pr-review/references/execution-lifecycle.md

@@ -0,0 +1,116 @@
+# Execution Lifecycle Reference
+
+This document contains detailed execution lifecycle phases for PR review.
+
+---
+
+## Phase 1: Context
+
+- Fetch PR metadata and diff using `githubSearchPullRequests`
+- Review existing PR comments first:
+  - **Check if previous comments were fixed!** (Verify resolution)
+  - Avoid duplicates (do not report issues already flagged)
+- Classify risk: High (Logic/Auth/API/Data) vs Low (Docs/CSS)
+- **PR Health Check**:
+  - Flag large PRs (>500 lines) - suggest splitting
+  - Missing description - flag
+  - Can PR be split into independent sub-PRs?
+- Build mental model: group changes by functionality
+- Analyze commit history: development progression, decision patterns
+- Check for ticket/issue reference - verify requirements alignment
+
+---
+
+## Phase 1.5: User Checkpoint (MANDATORY)
+
+Before deep analysis, present findings and ask user for direction.
+
+### Step 1: TL;DR Summary
+
+Present to user:
+- **PR Overview**: What this PR does (1-2 sentences)
+- **Files Changed**: Count and key areas (e.g., "12 files: API handlers, auth middleware, tests")
+- **Initial Risk Assessment**: HIGH / MEDIUM / LOW with reasoning
+- **Key Areas Identified**:
+  - List 3-5 main functional areas in the PR
+  - Flag any areas that look complex or risky
+- **Potential Concerns** (if any): Quick observations from initial scan
+
+### Step 2: Ask User (MANDATORY)
+
+Ask user:
+1. "Which areas would you like me to focus on?" (list the identified areas as options)
+2. "Should I proceed with a full review across all domains, or focus on specific concerns?"
+3. **Optional Context** (helpful but not required):
+   - "Any additional links? (related PRs, docs, design specs)"
+   - "Any context I should know? (known issues, business requirements, deadlines)"
+
+**Wait for user response before proceeding to Phase 2.**
+
+User can provide:
+- **Focus areas**: "Focus on the auth changes and API handlers"
+- **Additional context**: "This is a hotfix for issue #123, prioritize correctness over style"
+- **Full review**: "Proceed with full review" - Continue to Phase 2 with all domains
+- **Skip deep analysis**: "Just give me the summary" - Jump to Phase 4 with current findings
+
+---
+
+## Phase 2: Analysis
+
+**Respect User Direction**: Apply user's focus areas and context from Phase 1.5. If user specified focus areas, prioritize those domains. If user provided context, incorporate it into analysis.
+
+- Generate 3-5 context queries for Octocode research (aligned with user focus)
+- **Flow Impact Analysis** (CRITICAL):
+  - Search all callers/usages of modified functions (`githubSearchCode`)
+  - Trace how data flows through changed code paths
+  - Identify if return values, types, or side effects changed
+  - Check if existing integrations will break
+- Validate schemas/APIs/dependencies
+- Assess impact per domain (prioritize user-specified areas):
+  - **Architectural**: System structure, pattern alignment
+  - **Integration**: Affected systems, integration patterns
+  - **Risk**: Race conditions, performance, security
+  - **Business**: User experience, metrics, operational costs
+  - **Cascade Effect**: Could this lead to other problems?
+- Identify edge cases
+- Security scan: injection, XSS, data exposure, regulatory compliance (GDPR, HIPAA)
+- Scan for TODO/FIXME comments in new code
+- For high-risk changes: Consider rollback strategy/feature flags
+
+---
+
+## Phase 3: Finalize
+
+- **Dedupe**: Check against existing PR comments, merge same root cause
+- **Refine**: For uncertain suggestions - research more or ask user
+  - **UNCHANGED**: Suggestion verified correct
+  - **UPDATED**: New context improves suggestion
+  - **INCORRECT**: Context proves suggestion wrong - delete
+- **Verify**:
+  - Each suggestion has HIGH/MED confidence + clear fix
+  - **Previous Comments Resolution**: Explicitly verify that comments from previous reviews were fixed. If not, re-flag as unresolved.
+- Limit to most impactful findings (max ~5-7 key issues)
+
+---
+
+## Phase 4: Report
+
+### Step 1: Chat Summary (MANDATORY)
+
+Before creating any documentation:
+- Provide TL;DR of review findings in chat
+- State recommendation: APPROVE / REQUEST_CHANGES / COMMENT
+- List high-priority issues with brief descriptions
+- Summarize risk level and key affected areas
+
+### Step 2: Ask Before Creating Doc (MANDATORY)
+
+Ask user: "Would you like me to create the detailed PR review document?"
+- If yes - Generate per output structure
+- If no - Continue discussion or provide additional analysis
+- Only write `.octocode/reviewPR/...` after explicit user approval
+
+### Step 3: Generate (After Approval)
+
+- Ensure all suggestions have: location, confidence, concise problem, code fix
+- Number issues sequentially across all priorities