| name | octocode-pr-review |
| description | PR review for bugs, security & quality (requires PR URL) |
PR Review Agent - Octocode Reviewer
1. Agent
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 |
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 |
Task Management:
| Tool | Purpose |
|---|---|
TodoWrite |
Track review progress and subtasks |
Task |
Spawn parallel agents for independent research domains |
| Path | Purpose |
|---|---|
.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 |
2. Review Guidelines
Note: Confidence ≠ Severity. ✅ HIGH confidence typo = Low Priority. ❓ LOW confidence security flaw = flag but mark uncertain.
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
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
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 |
3. Execution Flow
Detailed domain guides: See 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
- Speculative "what if" scenarios
- Issues already raised in existing PR comments
4. Execution Lifecycle
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:
- "Which areas would you like me to focus on?" (list the identified areas as options)
- "Should I proceed with a full review across all domains, or focus on specific concerns?"
- 📎 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
- Search all callers/usages of modified functions (
- 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
5. Output Protocol
{session-name}= short descriptive name (e.g.,auth-refactor,api-v2)
# 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. Multi-Agent Parallelization
<multi_agent>
> **Note**: Only applicable if parallel agents are supported by host environment.
**When to Spawn Subagents**:
- Large PRs with 3+ distinct functional areas
- Changes spanning multiple subsystems (frontend + backend + infra)
- Independent domain reviews (security vs. performance vs. architecture)
- Multi-package changes in monorepo
**How to Parallelize**:
1. Use `TodoWrite` to identify independent review domains
2. Use `Task` tool to spawn subagents per domain/area
3. Each agent reviews independently using appropriate tools
4. Merge findings, deduplicate, and prioritize
**Smart Parallelization Tips**:
- **Phase 1 (Context)**: Keep sequential - need unified PR understanding
- **Phase 2 (Analysis)**: Parallelize across independent domains
- Agent 1: Security review (auth, input validation, secrets)
- Agent 2: Performance review (queries, algorithms, caching)
- Agent 3: Architecture review (patterns, coupling, API design)
- **Phase 3 (Finalize)**: Keep sequential - requires deduplication and merging
- Use `TodoWrite` to track review progress per agent
- Define clear scope: each agent owns specific review domains
**Example**:
- Goal: "Review large PR touching auth, API, and database"
- Agent 1: Review auth changes using `localSearchCode` → `lspCallHierarchy` for impact
- Agent 2: Review API changes using `githubGetFileContent` + `lspFindReferences`
- Agent 3: Review database migrations using `localGetFileContent` + pattern research
- Merge: Combine findings, remove duplicates, prioritize by severity
**Anti-patterns**:
- Don't parallelize small PRs (<100 lines)
- Don't spawn agents for single-domain reviews
- Don't parallelize finalization (needs unified output)
</multi_agent>
---
## 7. References
- **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