corvus-review-extras

name: corvus-review-extras description: Shared schemas, Conventional Comments spec, config schema, and common templates for Corvus PR Review

Corvus Review — Shared References

SUBAGENT REFERENCE

Invoking Subagents

Use the Task tool with subagent_type parameter:

task(
  subagent_type: "pr-context-gatherer",
  description: "Gather PR context: changed files and dependencies",
  prompt: "**TASK**: Analyze all changed files in PR #NNN..."
)

Parallel Invocation

When subagents are independent (R1, R2 Passes 1-3), invoke them in the same message:

// R1: These run in parallel
task(subagent_type: "pr-context-gatherer", description: "PR file analysis", prompt: "...")
task(subagent_type: "researcher", description: "PR external context", prompt: "...")

REVIEW CONFIG SCHEMA

File: .opencode/review-config.yaml

# .opencode/review-config.yaml — Full Schema with Defaults
# All fields are optional. Defaults are applied for missing fields.

# Severity threshold: findings below this level are excluded from the review.
# Values: "blocker" | "critical" | "major" | "minor" | "nitpick"
# Default: "nitpick" (include everything)
severity_threshold: "nitpick"

# Maximum number of nitpick ("nit") comments allowed in the review.
# Excess nits are silently dropped (lowest-confidence first).
# Default: 3
max_nits: 3

# Toggle individual review passes on/off.
# Default: all true
passes:
  architecture: true    # Pass 1: Architecture & Design
  correctness: true     # Pass 2: Logic & Correctness
  security: true        # Pass 3: Security
  conventions: true     # Pass 4: Conventions & Polish

# Path-specific rules: override severity or suppress findings per glob pattern.
path_rules:
  # Example: suppress nitpicks in generated files
  - pattern: "**/*.generated.*"
    suppress_below: "major"
  # Example: elevate security findings in auth paths
  - pattern: "src/auth/**"
    elevate_security: true
  # Example: skip conventions pass for vendored code
  - pattern: "vendor/**"
    skip_passes: ["conventions"]

# Custom regex rules: additional pattern-based checks.
custom_rules:
  - id: "todo-no-issue"
    pattern: "TODO(?!.*#\\d+)"
    severity: "minor"
    message: "TODO comment without linked issue"
    include: ["*.ts", "*.js"]
    exclude: ["*.test.*"]

# Suppression rules: silence specific findings by ID or pattern.
suppressions:
  - id: "no-console-log"
    paths: ["src/debug/**"]
  - message_pattern: "unused import"
    reason: "Auto-imports will be cleaned by CI"

# Autonomous mode: when true, skip R4 user gate and auto-proceed.
# Default: false
autonomous: false

# Review action override: force a specific action.
# Values: null | "APPROVE" | "REQUEST_CHANGES" | "COMMENT_ONLY"
# Default: null (auto-determined by R3)
action_override: null

# Large PR threshold: number of changed files that triggers large-PR handling.
# Default: 20
large_pr_threshold: 20

# Large PR strategy: what to do when PR exceeds threshold.
# Values: "warn" | "split-suggestion" | "proceed"
# Default: "warn"
large_pr_strategy: "warn"

Config Validation Rules

1. severity_threshold must be one of: blocker, critical, major, minor, nitpick
2. max_nits must be a non-negative integer
3. passes keys must be from: architecture, correctness, security, conventions
4. path_rules[].pattern must be valid glob syntax
5. custom_rules[].pattern must be valid regex
6. custom_rules[].severity must be a valid severity level
7. suppressions[].message_pattern must be valid regex (if present)
8. large_pr_threshold must be a positive integer
9. Unknown keys produce a warning but do not fail loading

Config Loading Priority

1. .opencode/review-config.yaml (project-level)
2. Built-in defaults (for any missing fields)

CONVENTIONAL COMMENTS SPECIFICATION

All review findings use the Conventional Comments format.

Labels

Severity Mapping

Finding Structure

Each review finding MUST conform to this structure:

- id: "<pass>-<sequence>"          # e.g., "arch-001", "logic-003", "sec-002", "conv-001"
  pass: "<pass_name>"              # "architecture" | "correctness" | "security" | "conventions"
  label: "<conventional_label>"    # From labels table above
  severity: <1-5>                  # Numeric severity (0 for praise/thought/note)
  file: "<file_path>"             # Relative path from repo root
  line_start: <number>            # Starting line (1-indexed)
  line_end: <number|null>         # Ending line (null for single-line)
  title: "<short_title>"          # Max 80 chars, imperative mood
  body: "<markdown_body>"         # Full explanation with context
  suggestion: "<code|null>"       # Suggested fix (optional, GitHub suggestion format)
  confidence: <0.0-1.0>           # How confident the reviewer is
  related_to: ["<finding_id>"]    # Cross-references to related findings (optional)
  suppressed: false               # Set to true if matched by a suppression rule

Comment Rendering Format

When posting to GitHub, each finding renders as:

For inline comments (file + line):

**<label>** (<pass>): <title>

<body>

[suggestion block if present]

For the review summary body:

**<label>**: <title>
<body>

Nit Budget Enforcement

• Maximum nits per review: config.max_nits (default: 3)
• When findings exceed the nit budget, drop lowest-confidence nits first
• Dropped nits are noted in the review summary: "N additional nitpicks suppressed"
• praise, thought, and note labels do NOT count toward nit budget

DATA OBJECT SCHEMAS

PR_CONTEXT (produced by R0)

PR_CONTEXT:
  pr_number: <number>
  pr_url: "<url>"
  repo: "<owner/repo>"
  base_branch: "<branch>"
  head_branch: "<branch>"
  author: "<username>"
  title: "<string>"
  description: "<string|null>"
  labels: ["<label>"]
  reviewers_requested: ["<username>"]
  linked_issues: ["<issue_ref>"]
  is_draft: <boolean>
  mergeable: <boolean|null>
  ci_status: "pass" | "fail" | "pending" | "none"
  ci_checks:
    - name: "<check_name>"
      status: "pass" | "fail" | "pending"
      url: "<url|null>"
  files_changed: <number>
  additions: <number>
  deletions: <number>
  changed_files: ["<file_path>"]
  flags:
    is_large_pr: <boolean>
    missing_description: <boolean>
    has_ci_failures: <boolean>
    is_draft: <boolean>
    has_breaking_labels: <boolean>
  config: <ReviewConfig>

REVIEW_CONTEXT (produced by R1)

REVIEW_CONTEXT:
  file_map:
    "<file_path>":
      full_content: "<string>"
      diff_hunks: ["<hunk>"]
      language: "<lang>"
      imports: ["<import>"]
      exports: ["<export>"]
      callers: ["<file:function>"]
      test_files: ["<file_path>"]
      git_history:
        last_modified: "<date>"
        recent_authors: ["<username>"]
        change_frequency: "high" | "medium" | "low"
  dependency_graph:
    "<file_path>":
      depends_on: ["<file_path>"]
      depended_by: ["<file_path>"]
  conventions:
    naming: "<pattern_description>"
    file_structure: "<description>"
    error_handling: "<pattern>"
    test_patterns: "<description>"
    import_order: "<convention>"
  test_coverage:
    has_tests: <boolean>
    test_files_for_changes: ["<file_path>"]
    untested_files: ["<file_path>"]
  linked_issues_detail: [<IssueDetail>]
  dependency_advisories: [<Advisory>]
  ci_failure_analysis: [<CIFailure>]
  related_prs: [<RelatedPR>]

REVIEW_FINDINGS (produced by R2)

REVIEW_FINDINGS:
  pass_results:
    architecture:
      status: "completed" | "skipped" | "error"
      findings: [<Finding>]
      summary: "<string>"
    correctness:
      status: "completed" | "skipped" | "error"
      findings: [<Finding>]
      summary: "<string>"
    security:
      status: "completed" | "skipped" | "error"
      findings: [<Finding>]
      summary: "<string>"
    conventions:
      status: "completed" | "skipped" | "error"
      findings: [<Finding>]
      summary: "<string>"
  totals:
    blocker: <count>
    critical: <count>
    major: <count>
    minor: <count>
    nitpick: <count>
    praise: <count>
    thought: <count>
    note: <count>

REVIEW_DOCUMENT (produced by R3)

REVIEW_DOCUMENT:
  summary:
    title: "<one-line summary>"
    body: "<markdown>"
    stats:
      total_findings: <count>
      blockers: <count>
      criticals: <count>
      majors: <count>
      minors: <count>
      nits_shown: <count>
      nits_suppressed: <count>
      praises: <count>
  action: "APPROVE" | "REQUEST_CHANGES" | "COMMENT_ONLY"
  action_reasoning: "<string>"
  findings: [<Finding>]
  inline_comments:
    - path: "<file_path>"
      line: <number>
      start_line: <number|null>
      side: "RIGHT"
      body: "<rendered_comment>"
  review_body: "<rendered_markdown>"
  dedup_log: [<DedupEntry>]
  filtered_log: [<FilterEntry>]

REVIEW_ACTION (produced by R4)

REVIEW_ACTION:
  decision: "post" | "edit" | "local_only" | "rerun" | "auto_post"
  edits: [<Finding>]
  rerun_scope: ["<pass_name>"]

TODO TRACKING PATTERNS

// Initial setup (R0 start)
todowrite([
  { id: "r0-intake", content: "R0: Parse PR and load config", status: "in_progress", priority: "high" },
  { id: "r1-context", content: "R1: Gather context", status: "pending", priority: "high" },
  { id: "r2-review", content: "R2: Multi-pass review", status: "pending", priority: "high" },
  { id: "r3-synthesis", content: "R3: Synthesize comments", status: "pending", priority: "high" },
  { id: "r4-gate", content: "R4: User gate", status: "pending", priority: "medium" },
  { id: "r5-post", content: "R5: Post review", status: "pending", priority: "medium" },
])

// Phase transitions: mark completed, set next to in_progress

ERROR HANDLING

PR Not Found

## Review Aborted
**Reason**: PR #[number] not found in [repo].
**Action**: Verify the PR number and repository.

CI Still Running

Do NOT abort. Note ci_status: "pending" in PR_CONTEXT. R3 adds a note: "CI checks were still running at review time."

Empty Diff

## Review Skipped
**Reason**: PR #[number] has no file changes. No code review needed.

Config Parse Error

Log warning, fall back to all defaults, add note to review summary.

Subagent Failure

• R1 workstream fails: proceed with partial context, note gap
• R2 pass fails: mark as "error", proceed with remaining passes
• R3 fails: escalate to user (cannot produce review without synthesis)
• R5 fails (posting): show rendered review locally, offer retry