Perform code review

Perform Code Review

Outcome

Produce a structured, severity-classified code review report based on:

• Git diff analysis
• Conformance with project rules and instructions
• Test validation evidence
• Adherence to tech spec and task artifacts

When to Use

• User asks for a code review
• User asks to validate code quality before merge
• User asks for pre-merge verification against requirements

Do Not Use

• Running QA-only exploratory testing
• Implementing fixes directly
• Executing task implementation work

Required Inputs

• Review scope: PR, branch diff, commit range, or changed files
• Optional references: tech spec path, task plan path, task IDs, PRD path
• Optional constraints: release deadline, risk tolerance, compliance needs

Workflow

1) Resolve Review Scope

Identify exactly what code is under review.

Collect:

• Diff source (PR, branch, commit range)
• Changed files list
• Related feature/task context

Decision points:

• If no diff scope is provided, request PR link or commit range.
• If no relevant changed files are detected, stop and report no reviewable changes.

2) Load Governing Context

Load quality and requirement references that define correctness.

Load and extract:

• Project instructions in .github/instructions/
• Relevant tech spec sections
• Relevant task artifacts (tasks.md, task files)
• Relevant PRD constraints when provided

Decision points:

• If tech spec or task references are missing, continue with diff review and flag traceability limits.
• If project rules are unavailable, state assumptions explicitly.

3) Analyze Diff for Code Quality and Risk

Review changes for correctness and maintainability.

Check:

• Functional correctness and regression risk
• Error handling and edge cases
• Security, privacy, reliability, and performance impacts
• Architecture and boundary conformance
• Data/API compatibility changes

Decision points:

• If a change violates architecture/spec constraints, raise high-severity finding.
• If potential production breakage is detected, raise critical severity.

4) Validate Test Coverage and Results

Assess whether the change is adequately verified.

Validate:

• Existing tests affected by changed behavior
• New tests for new behavior
• Relevant automated checks (unit, integration, workflow, static checks)

Decision points:

• If required tests are missing, raise severity by risk level.
• If tests cannot be run, report evidence gap and residual risk.

5) Verify Adherence to Tech Spec and Tasks

Confirm implementation matches approved design and scope.

Check:

• Mapping from changed behavior to tech spec decisions
• Mapping from changed behavior to task objectives and acceptance criteria
• Scope creep or unplanned behavior

Decision points:

• If implementation diverges from spec/task without rationale, raise high severity.
• If beneficial but out-of-scope changes exist, flag for explicit approval.

6) Build Severity-Classified Findings

Findings must be listed in strict severity order:

• Critical
• High
• Medium
• Low

Each finding includes:

• Finding ID and title
• Evidence with file path and line reference
• Why it matters
• Recommended remediation

7) Return Structured Review Report

Generate the final report using Code review report template.

Report rules:

• Findings must appear first, ordered by severity.
• Include open questions and assumptions after findings.
• Include explicit residual risks and testing gaps.
• If no findings exist, state that explicitly and still report residual risk/testing coverage.

Quality Check Before Finalizing

A review is complete only if:

• Scope and assumptions are explicit.
• Findings are evidence-based and actionable.
• Severity ordering is consistent.
• Test validation status is clearly documented.
• Tech spec/task adherence is explicitly addressed.
• Final verdict is provided (Approve, Approve with Conditions, Request Changes, or Blocked).

Output Contract

Return a structured report in chat and optionally save it as a markdown artifact using Code review report template.