Parallel Review Plan

Receive plan artifacts as read-only input and produce structured findings conforming to review-findings.schema.json. Designed for vendor-diverse dispatch — any LLM agent can execute this skill.

Arguments

$ARGUMENTS - OpenSpec change-id to review (e.g., "add-user-authentication")

Prerequisites

OpenSpec proposal exists at openspec/changes/<change-id>/
Proposal has been generated by /parallel-plan-feature or /linear-plan-feature

Input (Read-Only)

The reviewer receives these artifacts as context but MUST NOT modify them:

openspec/changes/<change-id>/proposal.md
openspec/changes/<change-id>/design.md
openspec/changes/<change-id>/tasks.md
openspec/changes/<change-id>/specs/**/spec.md
openspec/changes/<change-id>/contracts/ (if present)
openspec/changes/<change-id>/work-packages.yaml (if present)

Steps

1. Load Review Context

Read all plan artifacts listed above. Build a mental model of:

What the feature does (proposal.md)
How it will be built (design.md)
What requirements it satisfies (specs/)
How work is decomposed (tasks.md, work-packages.yaml)

2. Review Checklist

Evaluate the plan against these dimensions:

Specification Completeness

All requirements use SHALL/MUST language
Requirements are testable and verifiable
No ambiguous or vague terms

Contract Consistency

OpenAPI schemas match spec requirements
Database schemas support all declared operations
Event schemas cover all async flows
Generated types match OpenAPI definitions

Architecture Alignment

Design follows existing codebase patterns
No unnecessary dependencies introduced
Error handling strategy is complete
Migration path is reversible

Security Review

Input validation at system boundaries
Authentication/authorization for new endpoints
No secrets in configuration or code
OWASP top-10 considerations addressed

Work Package Validity (if work-packages.yaml exists)

DAG has no cycles
Parallel packages have non-overlapping write scopes
Lock keys follow canonicalization rules
Verification steps are appropriate for each package tier
Integration package depends on all implementation packages

3. Produce Findings

Generate findings as a JSON array conforming to review-findings.schema.json:

{
  "review_type": "plan",
  "target": "<change-id>",
  "reviewer_vendor": "<model-name>",
  "findings": [
    {
      "id": 1,
      "type": "spec_gap",
      "criticality": "high",
      "description": "Requirement R3 lacks error handling specification for 429 rate limit responses",
      "resolution": "Add a requirement specifying retry-after header handling",
      "disposition": "fix"
    }
  ]
}

Finding Types

spec_gap — Missing or incomplete requirements
contract_mismatch — Inconsistency between contracts and specs
architecture — Design pattern or structural concern
security — Security vulnerability or missing protection
performance — Potential performance issue
style — Code style or convention violation
correctness — Logical error in the plan

Dispositions

fix — Author should fix before implementation
regenerate — Artifact needs regeneration (e.g., contract schema mismatch)
accept — Minor issue, acceptable as-is
escalate — Requires human decision or cross-team coordination

4. Validate Output

Validate the findings JSON against openspec/schemas/review-findings.schema.json:

# Quick validation
python3 -c "
import json, jsonschema
schema = json.load(open('openspec/schemas/review-findings.schema.json'))
findings = json.load(open('<findings-output-path>'))
jsonschema.validate(findings, schema)
print('Valid')
"

5. Submit Findings

Write findings to openspec/changes/<change-id>/review-findings-plan.json.

If CAN_HANDOFF=true, write a review handoff with:

Summary of critical/high findings
Overall disposition recommendation (proceed/revise/block)

Output

openspec/changes/<change-id>/review-findings-plan.json conforming to review-findings.schema.json

Design for Vendor Diversity

This skill is intentionally simple and self-contained so it can be dispatched to any LLM agent:

No coordinator dependencies required
All input is file-based (read-only)
Output is a single JSON file with a well-defined schema
No side effects (no git commits, no lock acquisition)

The orchestrator may dispatch this skill to a different vendor (e.g., GPT-4, Gemini) for independent review diversity.

parallel-review-plan