opencode-metis 0.1.0

package/opencode/skill/code-quality-review/reference.md

@@ -0,0 +1,322 @@
+# Code Quality Review Reference
+
+Expanded criteria, specific signals, and severity guidance for each review dimension. Load this when a review requires deeper analysis than the dimension tables in SKILL.md provide.
+
+---
+
+## Dimension Deep Dives
+
+### Readability
+
+Readable code is understood correctly on first read. The goal is not brevity — it is clarity.
+
+#### Naming
+
+Good names eliminate the need to trace code to understand it.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Cryptic abbreviations | `usr`, `d`, `tmp`, `val`, `res` as standalone names | MEDIUM |
+| Misleading names | `isEnabled` that returns a count; `getUser` that saves | HIGH |
+| Generic names | `data`, `info`, `obj`, `result`, `item` in non-trivial code | LOW |
+| Boolean non-predicates | `user.active` instead of `user.isActive` | LOW |
+| Inconsistent vocabulary | `fetch` in one function, `get`, `retrieve`, `load` for same concept elsewhere | MEDIUM |
+| Noun-verb confusion | Functions named as nouns (`userSave()`); variables named as verbs | MEDIUM |
+
+Specific names to scrutinize:
+
+- Loop variables: `i`, `j` are acceptable for simple index loops; not acceptable as meaningful identifiers
+- Boolean parameters: `createUser(true)` — what does `true` mean? Should be `createUser({ sendWelcomeEmail: true })`
+- Return value names: a function returning a filtered list should not store the result in `list2`
+
+#### Comments
+
+The right comment explains why code does something, not what it does. The code itself should explain the what.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Redundant comments | `// increment counter` above `count++` | LOW |
+| Stale comments | Comment describes behavior that code no longer implements | HIGH |
+| Missing intent comments | Complex algorithm, regex, or workaround with no explanation | MEDIUM |
+| Commented-out code | Dead code left in place — creates confusion about intent | MEDIUM |
+| TODO without ticket | `// TODO: fix this later` with no owner or reference | LOW |
+
+Comments that add value:
+
+```
+// Stripe requires amounts in cents, not dollars
+// See: https://stripe.com/docs/currencies#zero-decimal
+const amount = Math.round(price * 100);
+
+// We skip soft-deleted records here because the report
+// only counts billable events — deleted users are not billed.
+const events = await Event.where({ deletedAt: null });
+```
+
+#### Complexity
+
+Cyclomatic complexity above 10 is a warning. Above 15 is a blocker.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Nesting depth > 3 | Three or more levels of if/for/while nesting | MEDIUM |
+| Boolean explosion | Conditions with 4+ AND/OR clauses | MEDIUM |
+| Negated negatives | `if (!isNotActive)` — double negation obscures intent | MEDIUM |
+| Long methods | Functions exceeding 20 lines doing multiple things | MEDIUM |
+| Flag parameters | `processOrder(order, true, false, true)` — positional booleans | HIGH |
+
+Measuring complexity in practice:
+
+- Count the number of independent code paths through a function
+- Each `if`, `else if`, `for`, `while`, `case`, `&&`, `||` adds one path
+- A function with complexity of 8 needs 8 distinct test cases to cover all paths
+
+---
+
+### Maintainability
+
+Maintainable code is easy to change safely. The test is: can a developer who did not write this code modify it confidently six months later?
+
+#### Duplication
+
+DRY violations increase the cost of every future change and create drift between copies.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Copy-paste blocks | Identical or near-identical logic in 2+ places | MEDIUM |
+| Repeated conditionals | Same `if (user.role === 'admin')` check in 5 places | HIGH |
+| Structural duplication | Different data, same shape — suggests a missing abstraction | MEDIUM |
+| Literal duplication | Same string constant typed in multiple files | LOW |
+
+The threshold: duplicated logic that appears twice is a candidate for extraction. Appearing three or more times is a requirement to extract.
+
+Exception: premature deduplication that requires complex parameterization to handle slight variations is worse than duplication. Evaluate whether extraction actually simplifies.
+
+#### Coupling
+
+Tightly coupled code breaks in unexpected places when changed.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Feature Envy | A method references another class's fields more than its own | MEDIUM |
+| Inappropriate Intimacy | Class A accesses private internals of Class B | HIGH |
+| Deep import chains | `import { x } from '../../../../core/utils/helpers/string'` | LOW |
+| Circular dependency | Module A imports from B, B imports from A | HIGH |
+| Law of Demeter violations | `order.customer.address.city` — chained navigation | MEDIUM |
+
+#### Cohesion
+
+A class or module should have one reason to change. When it has multiple, changes in one area risk breaking another.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| God Object | Class with 10+ public methods spanning unrelated concerns | HIGH |
+| Utility dumping ground | `utils.ts` or `helpers.py` growing without domain organization | MEDIUM |
+| Mixed abstraction levels | High-level orchestration mixed with low-level string parsing | MEDIUM |
+| Unrelated exports | Module exporting types for two different bounded contexts | MEDIUM |
+
+---
+
+### Testability
+
+If code is hard to test, it is usually hard to understand, change, or reason about. Poor testability is a design signal, not just a testing concern.
+
+#### Dependency Injection
+
+Code that instantiates its own dependencies is hard to test in isolation.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Hard-coded instantiation | `const db = new Database()` inside a service constructor | HIGH |
+| Static method calls | `UserService.getCurrentUser()` called deep inside business logic | HIGH |
+| Global state access | Direct access to `process.env`, singleton registries inside functions | MEDIUM |
+| Date/time coupling | `new Date()` or `Date.now()` called inside functions that need deterministic tests | MEDIUM |
+
+The test: can you run a unit test for this function without starting a database, making a network call, or reading the filesystem? If no, the dependencies are not properly injected.
+
+#### Observability
+
+Code needs to expose enough surface area to write meaningful assertions.
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Hidden side effects | Function sends email, writes file, or mutates global state without returning a testable signal | HIGH |
+| Void returns on complex logic | Functions doing significant work but returning nothing | MEDIUM |
+| Non-determinism | Functions that depend on random values, current time, or external state without injection | MEDIUM |
+| Private everything | Classes with no public interface except the final output | MEDIUM |
+
+#### Test Coverage Gaps
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| No tests for new code | PR adds logic with zero corresponding test file changes | HIGH |
+| Tests for implementation only | Tests that break on every refactor without logic changes | MEDIUM |
+| Happy path only | Tests that never simulate errors, empty inputs, or boundary values | HIGH |
+| Missing boundary tests | Off-by-one errors, empty collections, zero values, maximum values | MEDIUM |
+| Integration tests masking unit gaps | Every test hits the database; no unit-level isolation | MEDIUM |
+
+---
+
+### Error Handling
+
+Error handling is part of correctness. Code that fails silently or loses context on failure is as broken as code with wrong logic.
+
+#### Failure Coverage
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Swallowed exceptions | `catch (e) { /* ignore */ }` or `catch (e) { return null; }` | HIGH |
+| Generic catch-all | Catching `Exception` or `Error` instead of specific types | MEDIUM |
+| Missing error propagation | Callers cannot distinguish success from failure | HIGH |
+| Optimistic code | Database calls, API calls, file reads with no error handling | HIGH |
+
+#### Error Quality
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Context-free messages | `throw new Error('invalid input')` — which field? what value? | MEDIUM |
+| Exposing internals | Stack traces or SQL errors returned to API callers | CRITICAL |
+| Type information lost | Re-throwing as a different error type without preserving original | MEDIUM |
+| Logging without acting | `console.error(e)` followed by normal code execution | HIGH |
+
+What good error handling looks like:
+
+```
+// Specific error type
+// Context in the message (what failed, what was expected)
+// Original error preserved for debugging
+throw new ValidationError(
+  `User age must be between 18 and 120, got ${age}`,
+  { field: 'age', received: age, min: 18, max: 120 }
+);
+```
+
+#### Null and Undefined Safety
+
+| Signal | What to Look For | Severity |
+|--------|------------------|----------|
+| Unchecked optional chaining | Accessing `.property` on a value that could be null/undefined | HIGH |
+| Missing null guards at boundaries | Data from external APIs, user input, or database queries used without null check | HIGH |
+| Implicit truthiness checks | `if (user)` when the check should be `if (user !== null)` | LOW |
+| Nullable return not handled | Function documented to return null used without null check at call site | HIGH |
+
+---
+
+### Naming Specifics
+
+Naming deserves its own expanded section because it is the most frequent source of LOW and MEDIUM findings.
+
+#### Functions and Methods
+
+| Pattern | Problem | Better |
+|---------|---------|--------|
+| `getData()` | What data? Where from? | `fetchUserProfileFromCache()` |
+| `process()` | Process what? How? | `normalizeIncomingWebhookPayload()` |
+| `handle()` | Vague event handler | `handlePaymentFailedEvent()` |
+| `check()` | Returns bool? Throws? Logs? | `validateEmailFormat()` or `assertEmailIsValid()` |
+| `update()` | Updates one field? All fields? | `updateUserEmailAddress()` |
+| `calculate()` | Calculate and return? Side effects? | `computeOrderSubtotal()` |
+
+#### Variables
+
+| Pattern | Problem | Better |
+|---------|---------|--------|
+| `flag` | Flag for what? | `isEmailVerified` |
+| `list` | List of what? | `pendingOrderIds` |
+| `count` | Count of what? | `failedLoginAttemptCount` |
+| `temp` | Temporary what? | `intermediateCalculationResult` (or extract a function) |
+| `data` | Data from where? | `rawApiResponse` or `parsedUserRecord` |
+| `config` | Config for what? | `databaseConnectionConfig` |
+
+#### Boolean Naming
+
+Booleans should always be readable as a yes/no question:
+
+- `isActive` not `active`
+- `hasPermission` not `permission`
+- `canEdit` not `editable`
+- `shouldRetry` not `retry`
+- `wasDeleted` not `deleted`
+
+---
+
+## Severity Reference
+
+The SKILL.md severity matrix covers broad categories. This section provides finer guidance for borderline cases.
+
+### CRITICAL
+
+Reserve CRITICAL for findings that represent immediate risk if the code ships:
+
+- Any code path that could expose secrets, credentials, or PII
+- SQL/command/script injection without sanitization
+- Missing authentication on endpoints that modify data
+- Logic that can corrupt or permanently destroy data
+- Breaking changes to a public API or shared contract without versioning
+
+Do not use CRITICAL for style issues, even severe ones.
+
+### HIGH
+
+Use HIGH for issues that will cause problems in production — not might, but will, given normal usage:
+
+- Logic error affecting the stated purpose of the code
+- Missing error handling for a failure mode that occurs in the real world (network timeout, disk full, invalid user input)
+- N+1 queries in endpoints that handle realistic data volumes
+- Race condition in code that runs concurrently
+- Architectural violation that will require significant rework later
+
+### MEDIUM
+
+Use MEDIUM for issues that reduce quality, increase risk over time, or add friction without causing immediate breakage:
+
+- Code duplication that will drift
+- Missing tests for new, non-trivial logic
+- Naming that requires reading surrounding code to understand
+- Cyclomatic complexity between 10-15
+- Missing documentation for public APIs
+- Hard-coded values that belong in configuration
+
+### LOW
+
+Use LOW for findings where the current code works correctly but could be improved:
+
+- Style inconsistencies not caught by linters
+- Mild optimization opportunities not in hot paths
+- Naming that could be slightly clearer
+- Comments that could be more precise
+- Minor structural improvements with no behavioral impact
+
+### Nitpick (not a severity level)
+
+Anything caught by a configured linter should not appear as a review finding. Flag it once if the linter is misconfigured, then stop.
+
+---
+
+## Severity Escalation Rules
+
+Some findings warrant escalating from their initial severity based on context:
+
+| Situation | Escalation |
+|-----------|-----------|
+| MEDIUM issue in security-critical path | Escalate to HIGH |
+| LOW naming issue on public API boundary | Escalate to MEDIUM (it will outlive this PR) |
+| HIGH issue but only reached by authenticated admins | May stay HIGH, document the mitigating control |
+| MEDIUM duplication in code with frequent change history | Escalate to HIGH (drift will occur) |
+| Any finding in code with zero test coverage | Escalate one level (harder to catch regressions) |
+
+---
+
+## Dimension Interaction
+
+Dimensions are not fully independent. Findings often span multiple:
+
+| Finding | Primary Dimension | Secondary Dimensions |
+|---------|-------------------|----------------------|
+| God Object | Design | Testability, Maintainability |
+| Hardcoded API key | Security | Correctness (will break in different environments) |
+| N+1 query | Performance | Correctness (may timeout in production) |
+| Swallowed exception | Correctness | Readability (hides failure signals) |
+| Missing null check | Correctness | Readability (reader cannot tell if null is valid) |
+
+When a finding spans dimensions, report it under the highest-severity dimension and note the secondary impact in the recommendation.

package/opencode/skill/code-review/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: code-review
+description: "Multi-perspective code review methodology with severity/confidence scoring, deduplication, and actionable findings"
+license: MIT
+compatibility: opencode
+metadata:
+  category: development
+  version: "1.0"
+---
+
+# Code Review
+
+Roleplay as a code review methodology specialist that coordinates comprehensive review feedback across specialized perspectives.
+
+CodeReview {
+  Activation {
+    Reviewing pull requests or code changes
+    Providing multi-perspective code analysis
+    Coordinating specialized review agents
+    Synthesizing findings into actionable feedback
+  }
+
+  Constraints {
+    1. Every finding must include a specific location -- no generic "the codebase has issues"
+    2. Every recommendation must be actionable -- no "consider improving"
+    3. Include positive observations alongside issues
+    4. Deduplicate overlapping findings across perspectives
+    5. Sort findings by severity (Critical > High > Medium > Low) then confidence
+  }
+
+  ReviewPerspectives {
+    AlwaysReview {
+      | Perspective | Intent | What to Look For |
+      |-------------|--------|------------------|
+      | Security | Find vulnerabilities before they reach production | Auth/authz gaps, injection risks, hardcoded secrets, input validation, CSRF, cryptographic weaknesses |
+      | Simplification | Aggressively challenge unnecessary complexity | YAGNI violations, over-engineering, premature abstraction, dead code, "clever" code that should be obvious |
+      | Performance | Identify efficiency issues | N+1 queries, algorithm complexity, resource leaks, blocking operations, caching opportunities |
+      | Quality | Ensure code meets standards | SOLID violations, naming issues, error handling gaps, pattern inconsistencies, code smells |
+      | Testing | Verify adequate coverage | Missing tests for new code paths, edge cases not covered, test quality issues |
+    }
+
+    ReviewWhenApplicable {
+      | Perspective | Intent | Include When |
+      |-------------|--------|-------------|
+      | Concurrency | Find race conditions and async issues | Code uses async/await, threading, shared state, parallel operations |
+      | Dependencies | Assess supply chain security | Changes to package.json, requirements.txt, go.mod, Cargo.toml, etc. |
+      | Compatibility | Detect breaking changes | Modifications to public APIs, database schemas, config formats |
+      | Accessibility | Ensure inclusive design | Frontend/UI component changes |
+      | Constitution | Check project rules compliance | Project has CONSTITUTION.md |
+    }
+  }
+
+  SeverityClassification {
+    Evaluate top-to-bottom, first match wins:
+
+    | Trigger | Severity |
+    |---------|----------|
+    | Security vulnerability, data loss, production crash | CRITICAL |
+    | Incorrect behavior, perf regression, a11y blocker | HIGH |
+    | Code smell, maintainability, minor perf | MEDIUM |
+    | Style preference, minor improvement | LOW |
+  }
+
+  ConfidenceClassification {
+    | Level | Definition | Presentation |
+    |-------|------------|-------------|
+    | HIGH | Clear violation of established pattern or security rule | Present as definite issue |
+    | MEDIUM | Likely issue but context-dependent | Present as probable concern |
+    | LOW | Potential improvement, may not be applicable | Present as suggestion |
+  }
+
+  ClassificationMatrix {
+    | Finding Type | Severity | Confidence | Priority |
+    |--------------|----------|------------|----------|
+    | SQL Injection | CRITICAL | HIGH | Immediate |
+    | XSS Vulnerability | CRITICAL | HIGH | Immediate |
+    | Hardcoded Secret | CRITICAL | HIGH | Immediate |
+    | N+1 Query | HIGH | HIGH | Before merge |
+    | Missing Auth Check | CRITICAL | MEDIUM | Before merge |
+    | No Input Validation | MEDIUM | HIGH | Should fix |
+    | Long Function | LOW | HIGH | Nice to have |
+    | Missing Test | MEDIUM | MEDIUM | Should fix |
+  }
+
+  FindingFormat {
+    Every finding must include:
+    - id: Auto-assigned `[PREFIX]-NNN` (e.g., C1, H2, M3)
+    - title: One-line description (max 40 chars)
+    - severity: From severity classification
+    - confidence: HIGH / MEDIUM / LOW
+    - location: file:line or file:line-line
+    - finding: What was found (evidence-based)
+    - recommendation: What to do (actionable)
+    - diff: Suggested code change (required for CRITICAL, recommended for HIGH)
+    - principle: YAGNI, SRP, OWASP, etc. (if applicable)
+    - perspectives: Which review perspectives flagged this
+  }
+
+  VerdictDecision {
+    Evaluate top-to-bottom, first match wins:
+
+    | IF Critical > | AND High > | THEN Verdict |
+    |:---:|:---:|:---|
+    | 0 | Any | REVISIONS_NEEDED |
+    | -- | 3 | REVISIONS_NEEDED |
+    | -- | 1-3 | APPROVED_WITH_NOTES |
+    | -- | 0 (Medium > 0) | APPROVED_WITH_NOTES |
+    | -- | 0 (Low only or none) | APPROVED |
+
+    BLOCKED is reserved for findings that indicate the review cannot be completed (e.g., insufficient context, missing files).
+  }
+
+  AgentPromptTemplates {
+    SecurityReviewer {
+      ```
+      FOCUS: Security review of the provided code changes
+        - Identify authentication/authorization issues
+        - Check for injection vulnerabilities (SQL, XSS, command, LDAP)
+        - Look for hardcoded secrets or credentials
+        - Verify input validation and sanitization
+        - Check for insecure data handling (encryption, PII)
+        - Review session management
+        - Check for CSRF vulnerabilities in forms
+
+      EXCLUDE: Performance optimization, code style, or architectural patterns
+
+      CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+
+      OUTPUT: Security findings in Finding format
+      SUCCESS: All security concerns identified with remediation steps
+      TERMINATION: Analysis complete OR code context insufficient
+      ```
+    }
+
+    PerformanceReviewer {
+      ```
+      FOCUS: Performance review of the provided code changes
+        - Identify N+1 query patterns
+        - Check for unnecessary re-renders or recomputations
+        - Look for blocking operations in async code
+        - Identify memory leaks or resource cleanup issues
+        - Check algorithm complexity (avoid O(n^2) when O(n) possible)
+        - Review caching opportunities
+        - Check for proper pagination
+
+      EXCLUDE: Security vulnerabilities, code style, or naming conventions
+
+      CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+
+      OUTPUT: Performance findings in Finding format
+      SUCCESS: All performance concerns identified with optimization strategies
+      TERMINATION: Analysis complete OR code context insufficient
+      ```
+    }
+
+    QualityReviewer {
+      ```
+      FOCUS: Code quality review of the provided code changes
+        - Check adherence to project coding standards
+        - Identify code smells (long methods, duplication, complexity)
+        - Verify proper error handling
+        - Check naming conventions and code clarity
+        - Identify missing or inadequate documentation
+        - Verify consistent patterns with existing codebase
+        - Check for proper abstractions
+
+      EXCLUDE: Security vulnerabilities or performance optimization
+
+      CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+        - Project standards: [from CLAUDE.md, .editorconfig]
+
+      OUTPUT: Quality findings in Finding format
+      SUCCESS: All quality concerns identified with clear improvements
+      TERMINATION: Analysis complete OR code context insufficient
+      ```
+    }
+
+    TestCoverageReviewer {
+      ```
+      FOCUS: Test coverage review of the provided code changes
+        - Identify new code paths that need tests
+        - Check if existing tests cover the changes
+        - Look for test quality issues (flaky, incomplete assertions)
+        - Verify edge cases are covered
+        - Check for proper mocking at boundaries
+        - Identify integration test needs
+        - Verify test naming and organization
+
+      EXCLUDE: Implementation details not related to testing
+
+      CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+        - Related test files: [existing tests]
+
+      OUTPUT: Test coverage findings in Finding format
+      SUCCESS: All testing gaps identified with specific test recommendations
+      TERMINATION: Analysis complete OR code context insufficient
+      ```
+    }
+
+    SimplificationReviewer {
+      ```
+      FOCUS: Complexity review - aggressively challenge unnecessary complexity
+        - Identify YAGNI violations (You Aren't Gonna Need It)
+        - Find over-engineered solutions
+        - Spot premature abstractions
+        - Look for dead code paths
+        - Challenge "clever" code that should be obvious
+        - Find unnecessary indirection
+        - Identify code that could be deleted
+
+      EXCLUDE: Security vulnerabilities or performance optimization
+
+      CONTEXT:
+        - Files changed: [list]
+        - Changes: [the diff or code]
+        - Full file context: [surrounding code]
+
+      OUTPUT: Simplification findings in Finding format
+      SUCCESS: All complexity issues identified with simpler alternatives
+      TERMINATION: Analysis complete OR code context insufficient
+      ```
+    }
+  }
+
+  SynthesisProtocol {
+    DeduplicationAlgorithm {
+      1. Collect all findings from all reviewers
+      2. Group by location (file:line range overlap -- within 5 lines = potential overlap)
+      3. For overlapping findings: keep highest severity, merge complementary details, credit all perspectives
+      4. Sort by severity (Critical > High > Medium > Low) then confidence
+      5. Assign finding IDs (C1, C2, H1, H2, M1, M2, L1, etc.)
+    }
+
+    MergeRules {
+      | Field | Merge Rule |
+      |-------|-----------|
+      | severity | `max()` -- keep the highest severity from any finding in the group |
+      | confidence | `max()` -- keep the highest confidence |
+      | title | Use the title from the highest-severity finding |
+      | location | Use the most specific location (narrowest line range) |
+      | finding | Combine descriptions from all perspectives, labeled by perspective |
+      | recommendation | Use the most actionable recommendation; append complementary ones |
+      | diff | Keep the most complete diff; prefer diffs from highest-severity finding |
+      | principle | Union of all principles cited |
+      | perspectives | List all perspectives that flagged this location |
+
+      ConflictResolution: When two findings have equal severity but different recommendations:
+      - If recommendations are complementary (address different aspects), combine them
+      - If recommendations conflict, keep the one from the more specialized perspective (e.g., Security > Quality for auth-related code)
+    }
+  }
+
+  PresentationFormat {
+    ```markdown
+    ## Code Review: [target]
+
+    **Verdict**: [VERDICT from decision table]
+
+    ### Summary
+
+    | Category | Critical | High | Medium | Low |
+    |----------|----------|------|--------|-----|
+    | Security | X | X | X | X |
+    | Simplification | X | X | X | X |
+    | Performance | X | X | X | X |
+    | Quality | X | X | X | X |
+    | Testing | X | X | X | X |
+    | **Total** | X | X | X | X |
+
+    *Critical & High Findings (Must Address)*
+
+    | ID | Finding | Remediation |
+    |----|---------|-------------|
+    | C1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+    | H1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+
+    #### Code Examples for Critical Fixes
+
+    **[C1] Title**
+    // Before -> After code diff
+
+    *Medium Findings (Should Address)*
+
+    | ID | Finding | Remediation |
+    |----|---------|-------------|
+    | M1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+
+    *Low Findings (Consider)*
+
+    | ID | Finding | Remediation |
+    |----|---------|-------------|
+    | L1 | Brief title *(file:line)* | Specific fix *(concise issue description)* |
+
+    ### Strengths
+
+    - [Positive observation with specific code reference]
+
+    ### Verdict Reasoning
+
+    [Why this verdict was chosen based on findings]
+    ```
+
+    TableColumnGuidelines {
+      - ID: Severity letter + number (C1 = Critical #1, H2 = High #2, M1 = Medium #1, L1 = Low #1)
+      - Finding: Brief title + location in italics
+      - Remediation: Fix recommendation + issue context in italics
+    }
+
+    CodeExamples {
+      - REQUIRED for all Critical findings (before/after style)
+      - Include for High findings when the fix is non-obvious
+      - Medium/Low findings use table-only format
+    }
+  }
+
+  PositiveFeedback {
+    Always include positive observations alongside issues:
+    - Good test coverage
+    - Proper error handling
+    - Clear naming and structure
+    - Security best practices followed
+    - Performance considerations
+    - Clean abstractions
+  }
+
+  Scoping {
+    1. Parse target:
+       - PR number: fetch PR diff via `gh pr diff`
+       - Branch name: diff against main/master
+       - `staged`: use `git diff --cached`
+       - File path: read file and recent changes
+
+    2. Retrieve full file contents for context (not just diff)
+
+    3. Analyze changes to determine applicable conditional perspectives:
+       - Contains async/await, Promise, threading: include Concurrency
+       - Modifies dependency files: include Dependencies
+       - Changes public API/schema: include Compatibility
+       - Modifies frontend components: include Accessibility
+       - Project has CONSTITUTION.md: include Constitution
+  }
+}
+
+## References
+
+See [reference.md](reference.md) for:
+- Detailed per-perspective review checklists (Security, Performance, Quality, Testing, Simplification)
+- Severity and confidence classification matrices
+- Agent prompt templates with FOCUS/EXCLUDE structure
+- Synthesis protocol for deduplicating findings
+- Example findings with proper formatting