Cy Review Round

Review Round

Perform a structured code review of a spec implementation and produce a review round directory that the cy-fix-reviews workflow can process.

Required Inputs

• Feature name identifying the .compozy/tasks/<name>/ directory.
• Optional: specific files or directories to scope the review.

Workflow

1. Determine the review round directory.

   • Derive the spec directory from the feature name: .compozy/tasks/<name>/.
   • Verify the spec directory exists. If it does not, stop and report the missing directory.
   • List existing reviews-NNN/ subdirectories to determine the next round number. If none exist, use round 1.
   • If prior review rounds exist, read their issue files to build a list of already-known issues. The current round must only contain NEW issues not already tracked in prior rounds. Do not re-flag issues that are pending, valid, or resolved in earlier rounds.
   • Determine the review round directory path: .compozy/tasks/<name>/reviews-NNN/ with the round number zero-padded to 3 digits. Do NOT create it yet — wait until step 4 confirms there are issues to write. This avoids leaving empty directories when the review finds no issues.

2. Identify the review scope.

   • Read _spec.md and _tasks.md from the spec directory to understand what was implemented and why, plus the contract catalogs _user_stories.md and _tests.md when present.
   • Read ADRs from .compozy/tasks/<name>/adrs/ for architectural decision context.
   • If _spec.md is missing, warn that the review will lack requirements context but proceed with a code-quality-only review.
   • If the user provided specific files or directories, scope the review to those paths.
   • If no explicit scope was provided, resolve the actual PR or repository base and inspect its merge-base-to-head diff, including owned working-tree changes when requested. Reuse an established scope; ask only if the intended range remains ambiguous.
   • Map the relevant changed paths and consumers locally; use bounded read-only agents only for substantial independent review slices. Reuse current implementation research.

3. Perform the code review.

   • Read references/review-criteria.md for severity definitions and evaluation areas.
   • Prioritize the review scope. For a large scope, review slice by slice instead of silently sampling: partition the diff by the task boundaries that produced it (task checkpoint commits, _tasks.md slices) and review each partition against its task's contract, core implementation files first. When the scope cannot be partitioned and still exceeds what a complete read can honestly cover, say so in the summary and recommend splitting the delivery — a review that silently degrades to sampling at scale certifies nothing.
   • Inspect every changed behavior in the prioritized scope, including enclosing contracts and affected consumers. Read full files when needed to understand their invariants; unchanged boilerplate does not require repeated reading.
   • Requirements validation: If _spec.md was available in step 2, cross-check the implementation against every stated requirement, acceptance criterion, and architectural decision — including every acceptance criterion and edge case in _user_stories.md when it exists. Flag any requirement that is missing, partially implemented, or implemented differently than specified. These are correctness issues — assign severity based on the gap's impact (critical if a core feature is missing, high if behavior deviates from spec, medium if an edge case from the spec is unhandled).
   • Mission fit: when _spec.md states a Motivating Problem, verify the delivered work solves it and name the slice that does — checking the implementation against the spec alone cannot catch a spec that drifted from its own mission. An ADR that narrowed or deferred the Motivating Problem without the user's recorded sign-off is itself a finding, at the severity of the gap it created.
   • Test-contract parity: If _tests.md exists, verify that every test ID assigned in completed tasks' ## Tests sections is implemented in the suite and asserts the behavior the contract specifies. A missing case, or a hollow one that exists without asserting the contracted behavior, is an issue — assign severity based on the impact of the behavior left unverified.
   • Use the relevant evaluation areas for the changed behavior: Security, Correctness, Concurrency, Performance and Scalability, Error Handling, Code Quality and Maintainability, Testing, Architecture, and Operations.
   • Identify issues in severity order: critical first, then high, medium, and low.
   • For each issue record: the file path relative to the repository root, the approximate line number, the severity level, a concise title (max 72 characters), and a detailed review comment describing the problem and a suggested fix.
   • Deduplicate before writing. If the same pattern (e.g., missing nil check, missing error wrap) appears in multiple files, create one issue for the most representative instance and list the other affected files in its Review Comment. Do not create N identical issues for N files exhibiting the same root cause. One issue per distinct problem, not per occurrence.
   • Verify before flagging. Before creating an issue, check whether the pattern is intentional: look for adjacent comments explaining the choice, ADR references, or test coverage that validates the behavior. If code looks suspicious but has a clear justification (e.g., // nolint: intentionally ignoring close error on read-only file), do not create an issue. Only flag patterns that are genuinely problematic, not merely unconventional.
   • Skip issues already owned by linters or formatters. Reuse current scoped gate evidence; run the owning lane only when its result is needed, not an unconditional full lint pass.
   • Focus on signal, not volume. Aim for fewer, higher-quality issues rather than an exhaustive list. Deduplicate by root cause and retain actionable findings supported by evidence. Issue counts are not quality targets or caps.
   • Also note well-implemented aspects of the code. These observations inform the summary but do not produce issue files.
   • If no issues are found after a thorough review, report that the implementation looks clean and skip steps 4 through 6. Do not create the review round directory.

4. Generate issue files.

   • Create the review round directory determined in step 1.

   • Read references/issue-template.md for the canonical format.

   • For each issue identified in step 3, create an issue_NNN.md file in the review round directory.

   • Issue numbering starts at 001 and increments sequentially.

   • Each file must use this exact structure:

     ---
     provider: manual
     pr:
     round: <N>
     round_created_at: <UTC timestamp in RFC3339 format>
     status: pending
     file: path/to/file.go
     line: 42
     severity: high
     author: claude-code
     provider_ref:
     ---
     
     # Issue NNN: <title>
     
     ## Review Comment
     
     <detailed review body>
     
     ## Triage
     
     - Decision: `UNREVIEWED`
     - Notes:

   • The <author> field must be claude-code.

   • The provider_ref field must be empty.

   • The provider field must be manual.

   • The pr field is empty for manual reviews. If the user provides a PR number, include it.

   • The round field must match the directory number as an integer (not zero-padded).

   • The round_created_at field must use the same current UTC RFC3339 timestamp in every issue in this round.

   • The severity field must be exactly one of: critical, high, medium, low.

5. Summarize and present the review.

   • Print a summary listing:
     • Merge recommendation: If any critical or high issues exist, state "Needs fixes before merge" with the blocking issues. If only medium/low issues exist, state "Safe to merge with follow-ups." If no issues, state "Clean — ready to merge."
     • Total issues found, broken down by severity (critical, high, medium, low).
     • The review round directory path.
     • The full list of generated issue file names.
     • Well-implemented aspects observed during the review.
   • Suggest running compozy loop run --workspace <ref> --name review-and-fix --input task_name=<name> to process the review round.

6. Verify before completion.

   • Use installed cy-final-verify before claiming the review round is complete.
   • Read back each generated issue file and verify the frontmatter parses correctly.
   • Verify every issue file in the round has matching provider, pr, round, and round_created_at values.
   • Confirm the review round directory follows the reviews-NNN naming convention.