coherence-review

name	coherence-review
description	Review recent PRs in a feature area for architectural consistency, missed integration points, duplicated patterns, and wrong directions. File issues for problems found. Use after 3-4 related issues merge or when a session's cost exceeds $15.

Coherence Review

Review a batch of related PRs for architectural consistency. Catches integration issues early — before multiple sessions build on top of a flawed foundation.

Input

A feature area description and/or PR numbers. Parse from: $ARGUMENTS

Examples:

• /coherence-review auth overhaul PRs #301 #305 #310 #312
• /coherence-review daemon session lifecycle
• /coherence-review 350 351 352 353

When to Run

• After every 3-4 issues in the same feature area merge
• When a session's cost exceeds $15 (sign of complexity/struggle)
• When you suspect related PRs may have diverged architecturally

Workflow

1. Gather Context

If PR numbers were provided, fetch each:

gh pr view <number> --json title,body,files,mergedAt
gh pr diff <number>

If only a feature area was provided, find recent merged PRs in that area:

gh pr list --state merged --limit 20 --json number,title,files,mergedAt

Filter to PRs that touch relevant files. Build a picture of what changed across the batch.

2. Review for Architectural Consistency

For each concern below, compare across all PRs in the batch:

Consistent patterns

• Do the PRs use the same approach for the same problem? (e.g., error handling, logging, IPC patterns)
• Are naming conventions consistent across the changes?
• Do similar features follow the same structure?

Integration points

• Do the PRs interact correctly where they touch shared code?
• Are there missing integration points where PRs should connect but don't?
• Did any PR change an interface that another PR depends on?

Duplicated work

• Did multiple PRs implement the same or similar functionality?
• Are there new utilities or helpers that overlap with existing ones?
• Could shared abstractions reduce duplication?

Wrong directions

• Does any PR introduce a pattern that contradicts the project's conventions?
• Are there changes that will be painful to maintain or extend?
• Did any PR optimize for the wrong thing (e.g., premature abstraction, unnecessary flexibility)?

3. Cross-reference with Project Standards

Check that changes align with:

• CLAUDE.md conventions (strict TypeScript, no any, Bun-native, etc.)
• Existing patterns in the codebase (IPC protocol, config loading, test patterns)
• test/CLAUDE.md testing conventions

4. File Issues

For each problem found, file a GitHub issue:

gh issue create --title "<type>: <concise description>" --body "..."

Include in the issue body:

• Which PRs exhibit the problem
• Specific file paths and line numbers
• What the consistent approach should be
• Severity: is this a "fix now" or "fix next time you're in this area"

Batch related problems — don't file one issue per nit. Group related concerns into coherent issues.

5. Report

Summarize findings:

• PRs reviewed: list with titles
• Consistency: overall assessment (strong / minor drift / significant divergence)
• Issues filed: list with numbers and titles
• Recommendations: any broader architectural guidance for future work in this area

Guidelines

• Be constructive, not pedantic. Focus on problems that will compound if left unaddressed.
• Minor style differences between PRs are normal — only flag patterns that will cause confusion or bugs.
• If the PRs are architecturally coherent, say so. A clean review is valuable signal too.
• Prefer filing actionable issues over vague concerns. "These two PRs handle errors differently" is vague; "PR #301 uses try/catch while #305 uses Result types for the same error category — standardize on Result types per CLAUDE.md" is actionable.