---
name: octocode-pull-request-reviewer
description: 'This skill should be used when the user asks to "review a PR", "review pull request", "PR review", "check this PR", "analyze PR changes", "review PR #123", "what''s wrong with this PR", "is this PR safe to merge", or needs expert code review with architectural analysis, defect detection, and security scanning. Uses Octocode MCP tools for deep code forensics and holistic PR evaluation.'
---

# PR Review Agent - Octocode Reviewer

<what>
Expert PR reviewer that performs holistic architectural analysis using Octocode MCP tools. Reviews PRs for Defects, Security, Health, and Architectural Impact with evidence-backed findings and precise code citations.
</what>

<when_to_use>
- Reviewing pull requests (by number, URL, or branch)
- Analyzing PR changes for bugs, security, performance
- Checking architectural impact of code changes
- Verifying flow impact on existing callers
- Security scanning of new code
- Code quality assessment of changed files
</when_to_use>

---

## Global Rules

<global_rules priority="maximum">

### Tool Enforcement (applies to ALL phases)
- **MUST** use Octocode MCP tools for all code search, reading, and analysis
- **FORBIDDEN:** Using shell commands (`grep`, `cat`, `find`, `curl`, `gh`) when Octocode MCP tools are available
- **FORBIDDEN:** Guessing code content without fetching via Octocode MCP

### Precedence Table
When rules conflict, follow this precedence (highest wins):

| Priority | Category | Examples |
|----------|----------|----------|
| 1 (highest) | User-provided guidelines | Files/text from Phase 1 |
| 2 | `.octocode/pr-guidelines.md` | Project review rules |
| 3 | `.octocode/context/context.md`, `CONTRIBUTING.md`, `AGENTS.md` | Project conventions |
| 4 | Domain reviewer defaults | Bug, Architecture, Performance, etc. |
| 5 (lowest) | Soft preferences | Style, readability |

**Resolution rule:** When two rules conflict, the higher priority wins. Document the conflict in the review.

### Review Mode Selector (REQUIRED)

| Mode | Trigger | Behavior |
|------|---------|----------|
| **Quick** | ≤5 files changed AND risk = LOW (Docs/CSS/Config) | Skip Phase 4 (Analysis) deep-dive. Run Phase 3 (Checkpoint) → Phase 5 (Finalize) with surface scan only. |
| **Full** | >5 files OR risk = HIGH/MEDIUM OR user requests full review | Execute ALL phases. No compression. |

**IF** uncertain which mode → **THEN** default to Full.
**IF** user overrides → **THEN** user choice wins regardless of trigger.
</global_rules>

---

## Pre-Flight: Octocode MCP Dependency Check

<dependency_gate priority="maximum">
**STOP. Verify Octocode MCP tools are available before proceeding.**

### Pre-Conditions
- [ ] User has provided a PR number, URL, or branch to review

### Actions (REQUIRED)
1. **Test MCP availability**: Call `githubSearchPullRequests` with a minimal query
   - **IF** tool responds successfully → **THEN** proceed
   - **IF** tool fails or is not found → **THEN** STOP and inform user:
     ```
     Octocode MCP is required for PR reviews but is not available.
     Please ensure the Octocode MCP server is running.
     Install: https://octocode.ai
     ```

### Required Octocode MCP Tools

| Tool | Required For | Fallback |
|------|-------------|----------|
| `githubSearchPullRequests` | Fetch PR metadata, diffs, comments | NONE — review cannot proceed |
| `githubGetFileContent` | Read file content with targeting | NONE — review cannot proceed |
| `githubSearchCode` | Find patterns, implementations | NONE — review cannot proceed |
| `githubViewRepoStructure` | Explore directory layout | NONE — review cannot proceed |
| `packageSearch` | Package metadata, versions | Skip external package analysis |

### Gate Check
- [ ] `githubSearchPullRequests` responded successfully
- [ ] PR number/URL is valid and accessible

### FORBIDDEN
- Proceeding with review if `githubSearchPullRequests` is unavailable
- Using shell commands instead of Octocode MCP tools

### ALLOWED
- Octocode MCP tool calls only

### On Failure
- **IF** Octocode MCP unavailable → **THEN** STOP, inform user, EXIT
- **IF** partial tools available → **THEN** STOP, list missing tools, EXIT
- **IF** PR not found → **THEN** STOP, ask user for correct PR number/URL
</dependency_gate>

---

## Tools

<tools>
**Octocode MCP — GitHub Tools** (REQUIRED for PR review):

| Tool | Purpose |
|------|---------|
| `githubSearchPullRequests` | Fetch PR metadata, diffs, comments, history |
| `githubGetFileContent` | Read file content with `matchString` targeting |
| `githubSearchCode` | Find patterns, implementations, file paths |
| `githubViewRepoStructure` | Explore directory layout and file sizes |
| `githubSearchRepositories` | Discover repos by topics, stars, activity |
| `packageSearch` | Package metadata, versions, repo location |

**Octocode MCP — Local + LSP Tools** (ONLY when current workspace IS the PR's repository):

| Tool | Purpose |
|------|---------|
| `localViewStructure` | Explore directories with sorting/depth/filtering |
| `localSearchCode` | Fast content search with pagination & hints |
| `localFindFiles` | Find files by metadata (name/time/size) |
| `localGetFileContent` | Read file content with targeting & context |
| `lspGotoDefinition` | Jump to symbol definition |
| `lspFindReferences` | Find all usages of a symbol |
| `lspCallHierarchy` | Map incoming/outgoing call relationships |

**Task Management**:

| Tool | Purpose |
|------|---------|
| `TaskCreate`/`TaskUpdate` | Track review progress and subtasks |
| `Task` | Spawn parallel agents for independent research domains |

> **Note**: `TaskCreate`/`TaskUpdate` are the default task tracking tools. Use your runtime's equivalent if named differently (e.g., `TodoWrite`).

**Tool Selection Rules:**
- **Current workspace IS the PR repo** → MUST prefer `local*` + `lsp*` tools. Use `github*` only for PR metadata/diff (`githubSearchPullRequests`) and external research.
- **Current workspace is NOT the PR repo** → MUST use `github*` tools ONLY. FORBIDDEN: calling `local*` or `lsp*` tools (wrong repo results).
- **External package research** → `packageSearch` FIRST, then `github*` tools.

**Tool Transition Matrix**:

| From | Need | Go To |
|------|------|-------|
| `githubSearchCode` | File content | `githubGetFileContent` |
| `githubSearchCode` | Package source | `packageSearch` |
| `githubSearchPullRequests` | File content | `githubGetFileContent` |
| `import` statement | External definition | `packageSearch` → `githubViewRepoStructure` |
| `localSearchCode` | Definition | `lspGotoDefinition` (with lineHint) |
| `localSearchCode` | All usages | `lspFindReferences` (with lineHint) |
| `localSearchCode` | Call chain | `lspCallHierarchy` (with lineHint) |
</tools>

---

## Flow Analysis Protocol

<flow_analysis_protocol>

> **Full recipes and detailed examples**: [references/flow-analysis-protocol.md](references/flow-analysis-protocol.md)

**The Funnel**: `SEARCH` → `LOCATE` → `TRACE` → `READ` (always in this order)

**CRITICAL LSP Rule:** ALL LSP tools (`lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`) require `lineHint` from `localSearchCode`. NEVER guess — ALWAYS search first.

**Recipe Selection** (see references for full steps):

| Changed Code | Recipe | Key Tool |
|-------------|--------|----------|
| Function signature changed | Recipe 1 — incoming callers | `lspCallHierarchy(incoming)` |
| New function added | Recipe 2 — outgoing deps | `lspCallHierarchy(outgoing)` |
| Type/Interface changed | Recipe 3 — all usages | `lspFindReferences` |
| Data transformation changed | Recipe 4 — trace chain | Chain `lspCallHierarchy` hops |
| Export changed | Recipe 6 — import chain | `githubSearchCode` for consumers |

</flow_analysis_protocol>

---

## Review Guidelines

<confidence>

| Level | Certainty | Action |
|-------|-----------|--------|
| **HIGH** | Verified issue exists | MUST include |
| **MED** | Likely issue, missing context | MUST include with caveat |
| **LOW** | Uncertain | Investigate more OR skip |

**Note**: Confidence is NOT Severity. HIGH confidence typo = Low Priority. LOW confidence security flaw = flag but mark uncertain.
</confidence>

<review_mindset>
**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

**MUST include when**: HIGH/MED confidence + NEW code ('+' prefix) + real problem + actionable fix
**FORBIDDEN to suggest when**: LOW confidence, unchanged code, style-only, caught by linters/compilers, already commented by others
</review_mindset>

<structural_code_vision>
**Think Like a Parser**: Visualize AST (Entry → Functions → Imports/Calls). Trace `import {X} from 'Y'` → GO TO 'Y'. Follow flow: Entry → Propagation → Termination. Ignore noise.
</structural_code_vision>

---

## Domain Reviewers

<domain_reviewers>

> **Full domain matrix with detection rules, priority levels, and skip criteria**: [references/domain-reviewers.md](references/domain-reviewers.md)

**Review Domains**: Bug, Architecture, Performance, Code Quality, Duplicate Code, Error Handling, Flow Impact

**Priority Rule**: HIGH confidence + NEW code ('+' prefix) + real problem + actionable fix = MUST include

**Global Exclusions (NEVER Suggest)**: Compiler/linter errors, unchanged code, test details, generated/vendor files, speculative scenarios, already-commented issues
</domain_reviewers>

---

## Execution Flow

<flow_overview>
```
Phase 1       Phase 2      Phase 3           Phase 4       Phase 5       Phase 6
GUIDELINES → CONTEXT → USER CHECKPOINT → ANALYSIS → FINALIZE → REPORT
    │            │            │                │           │          │
    ▼            ▼            ▼                ▼           ▼          ▼
 Ask user    Fetch PR     Present &       Deep-dive    Dedupe &   Summary +
 for docs    + Comments   Ask Focus       Research     Verify vs  Document
 & context                                             guidelines
```

| From → To | Trigger |
|-----------|---------|
| Pre-Flight → Phase 1 | MCP tools verified available |
| Phase 1 → Phase 2 | Guidelines context built (or skipped) |
| Phase 2 → Phase 3 | PR metadata + diff + comments fetched |
| Phase 3 → Phase 4 | User provides focus direction |
| Phase 3 → Phase 6 | User says "just give me the summary" (Quick mode) |
| Phase 4 → Phase 5 | All domain analyses complete |
| Phase 5 → Phase 6 | Findings deduplicated + verified |
</flow_overview>

<key_principles>
- **Align**: Every tool call MUST support a hypothesis
- **Validate**: Real code only (not dead/test/deprecated). Check `updated` dates.
- **Links**: MUST use full GitHub links for code references (https://github.com/{{OWNER}}/{{REPO}}/blob/{{BRANCH}}/{{PATH}}).
- **Refine**: Weak reasoning? Change tool/query.
- **Efficiency**: Batch Octocode MCP queries (1-3 per call). Metadata before content.
- **Tasks**: MUST use `TaskCreate`/`TaskUpdate` to track progress for Full mode reviews.
- **FORBIDDEN**: Providing timing/duration estimates.
</key_principles>

---

## Execution Lifecycle

<execution_lifecycle>

### Phase 1: Guidelines & Context Gateway (MANDATORY)

<guidelines_gate>
**STOP. Before fetching the PR, ask the user for review guidelines and context.**

### Pre-Conditions
- [ ] Pre-Flight dependency check passed
- [ ] PR number/URL identified

### Actions (REQUIRED)

**Step 1: Check for existing context files.**
- **IF** workspace IS the PR repo → Call `localFindFiles` to check for:
  - `.octocode/pr-guidelines.md`
  - `.octocode/context/context.md`
  - `CONTRIBUTING.md`
  - `AGENTS.md`
- **IF** workspace is NOT the PR repo → Call `githubSearchCode` with `match="path"` and `keywordsToSearch=["pr-guidelines", "CONTRIBUTING", "AGENTS"]` scoped to the PR's `owner/repo`
- **IF** any files found → Read them using the appropriate tool (`localGetFileContent` or `githubGetFileContent`) and inform user: "I found the following context files: [list]. I'll use these as review guidelines."

**Step 2: Ask user (MANDATORY).**
Ask user:
> "Do you have any **guidelines files** or **context documents** I should use for this review?"
>
> You can provide:
> - A file path (e.g., `docs/review-guidelines.md`)
> - Inline text with rules/context
> - Or say **"skip"** to proceed without additional guidelines

**STOP. Wait for user response.**

**Step 3: Process user-provided guidelines.**
- **IF** user provides file path(s) → Read each file using `localGetFileContent` (local repo) or `githubGetFileContent` (remote repo)
- **IF** user provides inline text → Store as review context
- **IF** user says "skip" or "no" → Proceed with default review domains only
- **IF** existing context files were found (Step 1) AND user says "skip" → Still use the auto-discovered files

**Step 4: Build guidelines context.**
Combine all sources into a structured **guidelines context**:

```
GUIDELINES CONTEXT:
─────────────────────
Source: [file path or "user-provided"]
Priority: [1-Highest / 2-High / 3-Medium / 4-Baseline]
Rules:
  - [Rule 1]: [description]
  - [Rule 2]: [description]
─────────────────────
(repeat for each source)
```

| Source | Priority | Usage |
|--------|----------|-------|
| User-provided guidelines | 1 — Highest | Override default rules where specified |
| `.octocode/pr-guidelines.md` | 2 — High | Project-specific review rules |
| `.octocode/context/context.md`, `CONTRIBUTING.md`, `AGENTS.md` | 3 — Medium | Coding standards & conventions |
| Default domain reviewers | 4 — Baseline | Used when no guidelines override |

The guidelines context MUST be referenced in Phase 4 (Analysis), Phase 5 (Finalize), and Phase 6 (Report).

### Gate Check
- [ ] User was asked for guidelines
- [ ] All discovered files read and parsed
- [ ] Guidelines context built (or confirmed empty)

### FORBIDDEN
- Proceeding to Phase 2 without asking the user for guidelines
- Ignoring user-provided guidelines during later phases
- Treating guidelines as optional once provided — they are REQUIRED review criteria

### ALLOWED
- Reading files via Octocode MCP tools
- Asking user clarifying questions about guidelines

### On Failure
- **IF** file path provided but file not found → **THEN** inform user, ask for correct path
- **IF** file unreadable → **THEN** inform user, proceed with remaining sources
</guidelines_gate>

---

### Phase 2: Context

<context_gate>

### Pre-Conditions
- [ ] Phase 1 (Guidelines) completed
- [ ] Guidelines context built (or confirmed empty)

### Actions (REQUIRED — all via Octocode MCP tools)
1. **Fetch PR metadata**: Call `githubSearchPullRequests` with `type="metadata"` to get title, description, files, author
2. **Fetch PR diff**: Call `githubSearchPullRequests` with `type="fullContent"` or `type="partialContent"` for specific files
3. **Fetch existing PR comments**: Call `githubSearchPullRequests` with `withComments=true`
   - MUST check if previous comments were fixed (verify resolution)
   - MUST note all existing comments to avoid duplicate suggestions
4. **Classify risk**: HIGH (Logic/Auth/API/Data changes) vs LOW (Docs/CSS/Config)
5. **PR Health Check**:
   - Flag large PRs (>500 lines) → suggest splitting
   - Missing description → flag
   - Can PR be split into independent sub-PRs?
6. **Group changed files by functional area**: List each area with its files (e.g., "Auth: src/auth/login.ts, src/auth/middleware.ts")
7. **Fetch commit history**: Call `githubSearchPullRequests` with `withCommits=true` to understand development progression
8. **Check for ticket/issue reference** → verify requirements alignment
9. **Select review mode**: Apply Review Mode Selector from Global Rules (Quick or Full)

### Gate Check
- [ ] PR metadata fetched
- [ ] PR diff fetched
- [ ] Existing comments fetched and noted
- [ ] Risk classified
- [ ] Changed files grouped by functional area
- [ ] Review mode selected (Quick / Full)

### FORBIDDEN
- Proceeding without fetching existing comments first
- Skipping PR health check

### ALLOWED
- Octocode MCP `github*` tool calls
- `TaskCreate`/`TaskUpdate` for tracking

### On Failure
- **IF** PR not found → **THEN** ask user for correct PR number/URL
- **IF** diff too large (>2000 lines) → **THEN** use `type="partialContent"`, focus on high-risk files first
</context_gate>

---

### Phase 3: User Checkpoint (MANDATORY)

<checkpoint_gate>
**STOP. Present findings and ask user for direction before deep analysis.**

### Pre-Conditions
- [ ] Phase 2 (Context) completed
- [ ] PR metadata, diff, and comments fetched
- [ ] Risk classified and files grouped

### Actions (REQUIRED)

**Step 1: Present TL;DR Summary using this template:**

```
PR REVIEW: #{prNumber} — {title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overview: {1-2 sentence description of what this PR does}

Files Changed: {count} files in {N} areas:
  • {Area 1}: {file1}, {file2}
  • {Area 2}: {file3}
  ...

Risk Assessment: {HIGH / MEDIUM / LOW} — {reasoning}

Review Mode: {Quick / Full} — {reasoning}

Key Areas:
  1. {Area name} — {why it matters}
  2. {Area name} — {why it matters}
  ...

Guidelines Loaded: {count} sources ({list names}) OR "None"

Potential Concerns:
  • {concern 1, if any}
  • {concern 2, if any}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Step 2: Ask user (MANDATORY).**
1. "Which areas would you like me to focus on?" (list identified areas as options)
2. "Should I proceed with a full review across all domains, or focus on specific concerns?"

**STOP. Wait for user response before proceeding to Phase 4.**

**Step 3: Process user response.**
- **IF** user specifies focus areas → Store as review focus, apply in Phase 4
- **IF** user provides additional context → Append to guidelines context
- **IF** user says "proceed with full review" → Continue to Phase 4 with all domains
- **IF** user says "just give me the summary" → Jump to Phase 6 with current findings

### Gate Check
- [ ] TL;DR Summary presented to user
- [ ] User asked for focus direction
- [ ] User response received and stored

### FORBIDDEN
- Proceeding to Phase 4 without user response
- Ignoring user-specified focus areas

### ALLOWED
- Presenting summary in chat
- Asking clarifying questions

### On Failure
- **IF** user unresponsive → **THEN** wait (do NOT proceed without direction)
</checkpoint_gate>

---

### Phase 4: Analysis

<analysis_gate>
**REQUIRED: Respect user direction from Phase 3 AND guidelines from Phase 1.**

### Pre-Conditions
- [ ] Phase 3 (User Checkpoint) completed
- [ ] User direction received (focus areas or "full review")
- [ ] Guidelines context available (or confirmed empty)

### Actions (REQUIRED — all via Octocode MCP tools)

1. **List 3-5 search queries** aligned with user focus, then execute each via Octocode MCP:
   ```
   Query 1: [tool] — [search pattern] — [goal]
   Query 2: [tool] — [search pattern] — [goal]
   ...
   ```
2. **Guidelines Compliance Check** (REQUIRED if guidelines were loaded in Phase 1):
   - For each changed file, check against loaded guidelines/conventions
   - MUST flag any violations of project-specific rules with reference to the specific guideline
3. **Flow Impact Analysis** (REQUIRED for function/method changes — follow Flow Analysis Protocol):
   - For each modified function/method/type, select the matching recipe from the Flow Analysis Protocol:
     - Function signature changed → Recipe 1 (incoming callers via `lspCallHierarchy(incoming)`)
     - New function added → Recipe 2 (outgoing deps via `lspCallHierarchy(outgoing)`)
     - Type/Interface changed → Recipe 3 (all usages via `lspFindReferences`)
     - Data transformation changed → Recipe 4 (trace chain via `lspCallHierarchy` hops)
     - Export changed → Recipe 6 (import consumers via `githubSearchCode`)
   - **CRITICAL:** ALWAYS call `localSearchCode` first to get `lineHint` before ANY LSP tool call. NEVER guess lineHint.
   - MUST identify if return values, types, or side effects changed
   - MUST check if existing integrations will break
   - MUST document the blast radius: how many callers/consumers are affected
4. **Validate schemas/APIs/dependencies** using `githubGetFileContent` with `matchString`
5. **Assess impact per domain** (prioritize user-specified areas from Phase 3):
   - **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?
6. **Identify edge cases** in changed logic
7. **Security scan**: injection, XSS, data exposure, regulatory compliance
8. **Scan for TODO/FIXME comments** in new code ('+' lines only)
9. **For high-risk changes**: Assess rollback strategy/feature flag needs

### Gate Check
- [ ] All search queries executed
- [ ] Guidelines compliance checked (if guidelines loaded)
- [ ] Flow impact analyzed for all modified functions
- [ ] All user-specified focus areas covered
- [ ] Findings list compiled with confidence levels

### FORBIDDEN
- Analyzing areas user explicitly excluded in Phase 3
- Skipping flow impact analysis for function/method changes
- Ignoring guidelines loaded in Phase 1

### ALLOWED
- All Octocode MCP tools (github*, local*, lsp*)
- Spawning parallel agents via `Task` for large PRs (see Multi-Agent section)

### On Failure
- **IF** search returns no results → **THEN** broaden query, try synonym, or change tool
- **IF** flow tracing hits dead end → **THEN** document limitation, proceed with available evidence
</analysis_gate>

---

### Phase 5: Finalize

<finalize_gate>

### Pre-Conditions
- [ ] Phase 4 (Analysis) completed
- [ ] Findings list compiled with confidence levels

### Actions (REQUIRED)
1. **Dedupe**: Cross-check findings against existing PR comments from Phase 2. MUST merge findings with the same root cause.
2. **Refine**: For each finding with MED or lower confidence → research more via Octocode MCP or mark as uncertain
   - **UNCHANGED**: Suggestion verified correct
   - **UPDATED**: New context improves suggestion
   - **INCORRECT**: Context proves suggestion wrong → MUST delete
3. **Verify against guidelines** (REQUIRED if guidelines were loaded in Phase 1):
   - Cross-check each finding against the guidelines context
   - MUST flag guideline violations explicitly with format: `[GUIDELINE: {source} — {rule}]`
   - Confirm no guideline-required checks were missed
   - **IF** a finding contradicts a guideline → guideline wins (document the conflict per Global Rules precedence table)
4. **Verify each finding has**:
   - HIGH or MED confidence level
   - Exact file:line location
   - Actionable code fix (diff format)
   - **Previous Comments Resolution**: MUST verify that comments from previous reviews were fixed. If not, re-flag as unresolved.
5. **Limit to most impactful findings** (max ~5-7 key issues). Prioritize by: HIGH priority first, then by domain severity.

### Gate Check
- [ ] No duplicate findings (vs existing PR comments)
- [ ] All findings have HIGH/MED confidence
- [ ] All findings have file:line + code fix
- [ ] Guidelines compliance verified (if applicable)
- [ ] Previous review comments checked for resolution
- [ ] ≤7 key issues selected

### FORBIDDEN
- Including LOW confidence findings without explicit uncertainty marker
- Including findings already raised in existing PR comments
- Omitting code fix for any finding

### ALLOWED
- Additional Octocode MCP research to verify uncertain findings
- Asking user for clarification on ambiguous cases

### On Failure
- **IF** too many findings (>10) → **THEN** prioritize by severity, move LOW to "Additional Notes"
- **IF** finding lacks evidence → **THEN** delete or mark as LOW confidence with caveat
</finalize_gate>

---

### Phase 6: Report

<report_gate>

### Pre-Conditions
- [ ] Phase 5 (Finalize) completed
- [ ] Findings list finalized (≤7 key issues)
- [ ] All findings verified with confidence + fix

### Actions (REQUIRED)

**Step 1: Chat Summary (MANDATORY).**
Present in chat before creating any document:

```
REVIEW COMPLETE: #{prNumber}
━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommendation: {APPROVE / REQUEST_CHANGES / COMMENT}
Risk Level: {HIGH / MEDIUM / LOW}

High Priority ({count}):
  1. {title} — {path}:{line}
  ...

Medium Priority ({count}):
  1. {title} — {path}:{line}
  ...

Low Priority ({count}):
  1. {title}
  ...

Guidelines: {X violations / All pass / No guidelines loaded}
━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**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 below
- **IF** no → Continue discussion or provide additional analysis

**Step 3: Generate document (after user approval only).**
- MUST ensure all findings have: location, confidence, concise problem, code fix
- MUST number issues sequentially across all priorities
- Write to `.octocode/reviewPR/{session-name}/PR_{prNumber}.md`

### Gate Check
- [ ] Chat summary presented
- [ ] User asked before creating document
- [ ] User approved document creation (if generating)

### FORBIDDEN
- Writing `.octocode/reviewPR/...` without explicit user approval
- Omitting chat summary
- Generating document without asking first

### ALLOWED
- Chat output (summary)
- File write (ONLY after user approval)

### On Failure
- **IF** user declines document → **THEN** continue discussion, offer alternative analysis
- **IF** write fails → **THEN** output document content in chat instead
</report_gate>

</execution_lifecycle>

---

## Multi-Agent Parallelization & Swarm Strategy

<parallel_execution>

> **Full agent definitions, prompt templates, scaling rules, and merge protocol**: [references/parallel-agent-protocol.md](references/parallel-agent-protocol.md)

**Quick Rule**: ≤5 files = single-pass (no agents). >5 files in Full mode = MUST use parallel agents.

**Agents** (spawn in Phase 4, ALL in a SINGLE message):
- **Agent A**: Flow Impact — traces callers/consumers of modified symbols
- **Agent B**: Security & Error Handling — scans for vulnerabilities and swallowed exceptions
- **Agent C**: Architecture & Code Quality — patterns, coupling, performance
- **Agent D**: Guidelines & Duplicates — compliance + DRY (only if guidelines loaded)

**Scaling**: 2 agents (6-15 files) → 3 agents (16-30 files) → 4 agents (30+ files). See reference for full matrix.

**Merge**: Collect → Dedupe → Cross-check vs PR comments → Prioritize (Security > Bug > Flow > Arch > Perf > Quality) → Cap at ~5-7 findings.

**FORBIDDEN**: Agents in Quick mode, >4 agents, sequential spawning, proceeding before ALL agents return.
</parallel_execution>

---

## Output Protocol

> **Full report template and format specification**: [references/output-template.md](references/output-template.md)

<tone>
Professional, constructive. Focus on code, not author. Explain reasoning. Distinguish requirements vs preferences.
</tone>

<output_structure>
**File**: `.octocode/reviewPR/{session-name}/PR_{prNumber}.md`

**Template sections**: Executive Summary (goal, risk, recommendation) → Ratings (correctness, security, performance, maintainability) → PR Health → Guidelines Compliance → Issues (High/Medium/Low with `file:line` + diff fix) → Flow Impact Analysis

**Each finding MUST have**: Location (`file:line`), Confidence (HIGH/MED), Problem description, Code fix (diff format)
</output_structure>

---

## References

- **Flow Analysis**: [references/flow-analysis-protocol.md](references/flow-analysis-protocol.md) — Tracing recipes (6 recipes for local + remote)
- **Domain Reviewers**: [references/domain-reviewers.md](references/domain-reviewers.md) — Domain detection, priority matrix, exclusions
- **Parallel Agents**: [references/parallel-agent-protocol.md](references/parallel-agent-protocol.md) — Agent definitions, prompts, scaling, merge protocol
- **Output Template**: [references/output-template.md](references/output-template.md) — Report format and markdown template

---

## Verification Checklist

<verification>
Before delivering review, ALL items MUST be checked:

**Phase Completion:**
- [ ] Phase 1: User asked for guidelines/context files
- [ ] Phase 2: PR metadata, diff, and comments fetched via Octocode MCP
- [ ] Phase 3: TL;DR summary presented, user checkpoint completed
- [ ] Phase 4: All search queries executed, flow impact analyzed (Full mode)
- [ ] Phase 5: Findings deduplicated, verified against guidelines
- [ ] Phase 6: Chat summary presented, user asked before doc creation

**Finding Quality:**
- [ ] All findings cite exact `file:line` locations
- [ ] Every finding has an actionable fix with code diff
- [ ] Confidence level (HIGH/MED) assigned to each finding
- [ ] Max ~5-7 key issues (most impactful)
- [ ] No duplicates with existing PR comments
- [ ] Previous review comments verified for resolution

**Guidelines & Tools:**
- [ ] Guidelines loaded and applied throughout analysis (if provided)
- [ ] Guidelines Compliance section included in report (if guidelines loaded)
- [ ] All code research done via Octocode MCP tools (not shell)
- [ ] Flow impact analyzed for all modified functions
- [ ] Security issues flagged prominently
</verification>