codereview-orchestrator

What this skill does

# Code Review Orchestrator Skill

The coordinator for code reviews. This skill **only** triages and routes - it does NOT perform detailed code review. All actual review work is delegated to specialist skills.

## Quick Start: Full Pipeline

Trigger a complete review by saying:

```
Review PR 123
Review PR owner/repo#123
Review PR https://github.com/owner/repo/pull/123
```

This will:
1. **Retrieve** the PR diff via GitHub API
2. **Triage** and assess risk
3. **Route** to appropriate specialist skills
4. **Review** the code
5. **Submit** the review to GitHub

## Role

- **Triage**: Classify the PR and assess risk level
- **Route**: Select appropriate specialist skills
- **Summarize**: Generate high-level PR summary
- **Delegate**: Hand off to specialists for actual review
- **Orchestrate**: Manage the full review pipeline (input → review → output)

## What This Skill Does NOT Do

❌ Find bugs  
❌ Check security  
❌ Review performance  
❌ Validate tests  
❌ Check style  

All of the above are delegated to specialist skills.

## Full Pipeline Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         INPUT SKILLS                             │
├─────────────────────────────────────────────────────────────────┤
│  retrieve-diff-from-github-pr  │  retrieve-diff-from-commit     │
│  (GitHub PRs via API)          │  (Local git commits)           │
└────────────────────────────────┴────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    codereview-orchestrator                       │
│                   (Triage & Route - this skill)                  │
└─────────────────────────────────────────────────────────────────┘
                                 │
     ┌───────┬───────┬───────────┴───────────┬───────┬───────┐
     ▼       ▼       ▼                       ▼       ▼       ▼
┌─────────┐ ┌─────┐ ┌─────┐             ┌─────────┐ ┌─────┐ ┌─────┐
│security │ │ api │ │data │    ...      │  perf   │ │test │ │style│
└─────────┘ └─────┘ └─────┘             └─────────┘ └─────┘ └─────┘
     │       │       │                       │       │       │
     └───────┴───────┴───────────┬───────────┴───────┴───────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                        OUTPUT SKILLS                             │
├─────────────────────────────────────────────────────────────────┤
│                    submit-github-review                          │
│                 (Post review to GitHub API)                      │
└─────────────────────────────────────────────────────────────────┘
```

## Inputs

| Input | Description |
|-------|-------------|
| `pr_reference` | PR number, short ref (owner/repo#123), or full URL |
| `diff/PR` | The code changes to review (or retrieved automatically) |
| `repo_context` | Language, framework, architecture patterns |
| `focus_areas` | Optional: security, performance, correctness, etc. |
| `auto_submit` | Whether to automatically submit review to GitHub (default: false) |

## Outputs

| Output | Description |
|--------|-------------|
| `summary` | Plain-English description of changes |
| `touched_surfaces` | What parts of the system are affected |
| `risk_assessment` | Overall risk level with justification |
| `review_plan` | Which specialists to invoke and why |
| `questions` | Clarifying questions for the author (if any) |

## Step 1: Understand Intent

Ask these questions (do NOT review the code):

- What behavior change is intended?
- Does the PR description explain the purpose?
- Is this a feature, bugfix, refactor, or infrastructure change?

## Step 2: Identify Touched Surfaces

Categorize modified files into surfaces:

| Surface | File Patterns | Risk Indicator |
|---------|---------------|----------------|
| **Auth** | `**/auth/**`, `**/login/**`, `**/session/**` | 🔴 High |
| **API** | `**/api/**`, `**/routes/**`, `**/handlers/**` | 🟡 Medium |
| **Database** | `**/migrations/**`, `**/models/**`, `**/schema/**` | 🔴 High |
| **Business Logic** | `**/services/**`, `**/domain/**` | 🟡 Medium |
| **Infrastructure** | `Dockerfile`, `*.yaml`, `terraform/**` | 🟡 Medium |
| **Configuration** | `**/config/**`, `.env*`, `*.json` | 🟡 Medium |
| **Tests** | `**/test/**`, `**/spec/**`, `**/*.test.*` | 🟢 Low |
| **Documentation** | `*.md`, `**/docs/**` | 🟢 Low |
| **Dependencies** | `package.json`, `requirements.txt`, `go.mod` | 🟡 Medium |

## Step 3: Assess Risk

Rate overall risk based on:

| Factor | High Risk | Low Risk |
|--------|-----------|----------|
| **Surfaces** | Auth, DB, payments | Docs, tests |
| **Scope** | Many files, cross-cutting | Single file, isolated |
| **Complexity** | New algorithms, state machines | Simple CRUD |
| **Reversibility** | DB migrations, API changes | Internal refactors |

## Step 4: Generate Review Plan

Select specialists based on touched surfaces:

```yaml
review_plan:
  # Always run
  always:
    - codereview-correctness   # Logic bugs
    - codereview-style         # Readability
  
  # Conditional based on surfaces
  conditional:
    - skill: codereview-security
      trigger: auth, input handling, secrets, external APIs
      
    - skill: codereview-api
      trigger: routes, endpoints, schemas, contracts
      
    - skill: codereview-data
      trigger: migrations, models, queries
      
    - skill: codereview-concurrency
      trigger: async, workers, queues, locks
      
    - skill: codereview-performance
      trigger: loops, queries, caching, I/O
      
    - skill: codereview-observability
      trigger: logging, metrics, tracing
      
    - skill: codereview-testing
      trigger: test files modified or missing
      
    - skill: codereview-config
      trigger: config files, env vars, feature flags
      
    - skill: codereview-architect
      trigger: core utilities, shared libraries, breaking changes
```

## Output Format

```markdown
## PR Summary

[2-3 sentence description of what this PR does]

## Touched Surfaces

| Surface | Files | Risk |
|---------|-------|------|
| Auth | `auth/login.ts`, `auth/session.ts` | 🔴 High |
| API | `routes/users.ts` | 🟡 Medium |
| Tests | `tests/user.test.ts` | 🟢 Low |

## Risk Assessment

**Overall Risk: 🟡 MEDIUM**

- 🔴 Touches authentication flow
- 🟡 Modifies public API
- 🟢 Has test coverage

## Review Plan

| Priority | Skill | Files | Reason |
|----------|-------|-------|--------|
| 1 | `codereview-security` | `auth/*` | Auth changes require security review |
| 2 | `codereview-api` | `routes/*` | API contract changes |
| 3 | `codereview-correctness` | All | Standard logic check |
| 4 | `codereview-testing` | `tests/*` | Verify coverage |
| 5 | `codereview-style` | All | Final readability pass |

## Questions for Author

1. [Only if something is genuinely unclear about intent]
```

## Specialist Skills Reference

| Skill | Invoke When |
|-------|-------------|
| `codereview-security` | Auth, input parsing, secrets, external APIs |
| `codereview-correctness` | All PRs - logic bugs, error handling |
| `codereview-api` | API routes, schemas, contracts |
| `codereview-data` | Database migrations, models, queries |
| `codereview-concurrency` | Async code, workers, distributed systems |
| `codereview-performance` | Loops, queries, caching, memory |
| `codereview-observability` | Logging, metrics, tracing |
| `codereview-testing` | Test files or code needing tests |
| `codereview-config` | Config, env vars, feature flags |
| `codereview-architect` | Core libs, shared code, breaking changes |
| `codereview-style` | All PRs - final readability pass |

## Quick Reference

```
□ Understand Intent
  □ What does this PR do?
  □ Feature / bugfix / refactor / infra?

□ Identify Surfaces
  □ Which areas are touched?
  □ What's the risk level of each?

□ Assess