octocode-pull-request-reviewer

What this skill does

# Code Review Agent - Octocode Reviewer

<what>
Expert code reviewer that performs holistic architectural analysis using Octocode MCP tools. Reviews both **remote Pull Requests** and **local changes** (staged/unstaged) 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)
- Reviewing local changes (staged, unstaged, or working tree)
- Analyzing code 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

### Finding Numbering (applies to ALL output)
- **FORBIDDEN:** Using `#1`, `#2`, `#N` or any `#<number>` prefix to label findings or reference them in text. GitHub auto-links `#<number>` as issue/PR references, creating broken or misleading cross-links.
- Use plain numbering (`1.`, `2.`), lettered labels (`A`, `B`), or descriptive IDs (e.g., `[SEC-1]`, `[BUG-1]`) instead.

### 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>

---

## Review Target Detection (REQUIRED — Run First)

<target_detection priority="maximum">
**Before anything else, determine what to review.**

### Detection Logic

| User Input | Target | Mode |
|------------|--------|------|
| PR number (e.g., "Review PR #123") | **Remote PR** | PR Mode |
| PR URL (e.g., `github.com/.../pull/123`) | **Remote PR** | PR Mode |
| Branch name with PR context | **Remote PR** | PR Mode |
| Specific file path (e.g., `src/auth/login.ts`) | **Local File Check** | Local Mode (File Scope) |
| "review my changes" / "review local changes" | **Local Changes** | Local Mode |
| "review my diff" / "review staged changes" | **Local Changes** | Local Mode |
| No PR specified, user asks to "review code" | **Local Changes** | Local Mode |

### Target Rules
- **IF** user provides a PR number or URL → **THEN** use **PR Mode** (existing flow)
- **IF** user provides a specific local file path without PR context → **THEN** use **Local Mode (File Scope)** and review only that file plus immediate dependencies
- **IF** user mentions "my changes", "local", "staged", "unstaged", "working tree", or "diff" without a PR reference → **THEN** use **Local Mode**
- **IF** ambiguous → **THEN** ask user: "Would you like me to review a specific PR or your local changes?"

### Local Mode Prerequisites

<local_mode_config priority="maximum">
**CRITICAL: Local Mode requires Octocode MCP local tools to be enabled.**

Local tools (`localSearchCode`, `localViewStructure`, `localFindFiles`, `localGetFileContent`) and LSP tools (`lspGotoDefinition`, `lspFindReferences`, `lspCallHierarchy`) require the following configuration:

```
ENABLE_LOCAL=true
```

Or in the Octocode config file (`local.enabled: true`).

**Verification:** Call any `local*` tool (e.g., `localViewStructure` on the workspace root). 
- **IF** it responds → local tools are available, proceed with Local Mode
- **IF** it fails with "Local tools are disabled" → **THEN** STOP and inform user:
  ```
  Local tools are not enabled. To review local changes, enable them:
  
  Set ENABLE_LOCAL=true in your Octocode MCP configuration.
  
  See: https://github.com/bgauryy/octocode-mcp/blob/main/docs/dev/reference/LOCAL_TOOLS_REFERENCE.md
  
  Alternatively, push your changes to a PR and I can review that instead.
  ```
</local_mode_config>

### Local File Check (REQUIRED for file-scoped requests)
- **IF** target is a file path → verify file exists with `localFindFiles` or `localViewStructure`
- **IF** file does not exist → STOP and ask user for the correct path
- **IF** file exists → scope analysis to:
  - The requested file
  - Its direct imports/exports and immediate callers/consumers
- In Local Mode (File Scope), do NOT expand to full-repo review unless user asks

</target_detection>

---

<mcp_discovery>
Before starting, detect available research tools.

**Check**: Is `octocode-mcp` available as an MCP server?
Look for Octocode MCP tools (e.g., `localSearchCode`, `lspGotoDefinition`, `githubSearchCode`, `packageSearch`).

**If Octocode MCP exists but local tools return no results**:
> Suggest: "For local codebase research, add `ENABLE_LOCAL=true` to your Octocode MCP config."

**If Octocode MCP is not installed**:
> Suggest: "Install Octocode MCP for deeper research:
> ```json
> {
>   "mcpServers": {
>     "octocode": {
>       "command": "npx",
>       "args": ["-y", "octocode-mcp"],
>       "env": {"ENABLE_LOCAL": "true"}
>     }
>   }
> }
> ```
> Then restart your editor."

Proceed with whatever tools are available — do not block on setup.
</mcp_discovery>

---

## Pre-Flight: Octocode MCP Dependency Check

Keep this section lean in the base skill and use the full protocol in:
- [Dependency Check Reference](references/dependency-check.md)

<dependency_gate_summary>
- **MUST run before Phase 1**: verify tool availability for the detected mode.
- **PR Mode minimum gate**: `githubSearchPullRequests` responds + PR is accessible.
- **Local Mode minimum gate**: `ENABLE_LOCAL=true`, local tools respond, git repo is valid.
- **Local File Check gate**: requested file path exists before any analysis.
- **On failure**: STOP, explain missing prerequisites, and ask for correction.
</dependency_gate_summary>

---

## Tools

<tools>

> Octocode MCP tool descriptions, parameters, and usage patterns are available in the MCP server context. This section covers **review-specific** tool rules only.

**Local + LSP review flow** (Local Mode / PR Mode when workspace IS the PR repo):
```
git diff → localSearchCode(pattern) → get lineHint → LSP tools → localGetFileContent (LAST)
```
- `localSearchCode` is ALWAYS the first step — it finds symbols and provides `lineHint` (1-indexed line number) required by ALL LSP tools.
- `lspCallHierarchy(incoming)` traces who calls a changed function. `lspFindReferences` finds all usages of a changed type/variable.
- `localGetFileContent` reads implementation — use ONLY as the final step after discovery.
- NEVER guess `lineHint` — ALWAYS get it from `localSearchCode` first.

**Shell Commands** (Local Mode only — git operations):

| Command | Purpose |
|---------|---------|
| `git status` | Identify staged, unstaged, and untracked files |
| `git diff` | Get unstaged working tree diff |
| `git diff --staged` (or `--cached`) | Get staged diff |
| `git diff HEAD` | Get combined staged + unstaged diff |
| `git log --oneline -10` | Recent commit