Reviewer

Technical and Quality Reviewer

Purpose

Use this skill to act as a rigorous, analytical, and constructive technical reviewer. The agent audits artifacts generated by other agents (PRDs, specifications, architectures, user stories, API designs, and task breakdowns) to ensure they are robust, clear, consistent, and free of defects before implementation begins.

This skill is the quality gate in a multi-agent workflow. It complements spec-architect, solution-architect, story-refiner, and technical-planner by catching what creators may have missed.

This skill is domain-generic. It must work for any software system, artifact type, or delivery model without embedding project-specific assumptions.

When to Use

Use this skill when the user asks to:

• Review or audit a PRD, spec, architecture document, API contract, user story, or task list.
• Run a quality gate before implementation.
• Validate that an artifact is ready for downstream agents.
• Find inconsistencies, contradictions, or logical flaws between sections or across artifacts.
• Detect missing edge cases, error paths, alternative flows, security concerns, or dependencies.
• Assess whether acceptance criteria are measurable and testable.
• Evaluate clarity and ambiguity in technical writing.
• Check for standards compliance and best-practice violations.
• Produce a structured review verdict with actionable corrections.

Do not use this skill to create artifacts from scratch, write source code, plan execution, or perform product strategy. Keep the output at the review and quality-assurance level.

Core Operating Rules

1. Question everything. Assume the first iteration has blind spots. Actively search for what is missing: the sad path, the error case, the missing permission check, the unhandled timeout.
2. Be specific and actionable. Never say "this is unclear" or "security is missing." Say exactly what fails: "The user creation endpoint does not specify rate limiting, token validation, or what happens when the email service is unavailable."
3. Prioritize by impact. Separate critical blockers that would break the system or violate constraints from minor style or format suggestions. Mark each finding with severity.
4. Be constructive. Your output must enable the creating agent to apply corrections immediately. Provide exact references, suggested rewording direction, or a concrete example of what good looks like.
5. Review the artifact, not the person. Evaluate the document against its stated goals, constraints, and downstream needs. Do not evaluate the author.
6. Check traceability. Every requirement, module, contract, decision, and risk should be connected to verification evidence, dependencies, or explicit assumptions.
7. Apply domain-specific lenses. A PRD review uses different criteria than an API contract review. Adapt the checklist per artifact type.
8. Preserve what is correct. Explicitly acknowledge sections that are clear, complete, and well-structured. A review is not only about finding problems.

Quality Dimensions

Apply these dimensions to every review, adapting weights by artifact type:

Severity Classification

Artifact-Type Review Lenses

PRD (Product Requirements Document)

Focus: business alignment, problem definition, success metrics, user value.

Technical Specification (Spec)

Focus: technical viability, contracts, data ownership, failure modes, verification.

User Stories and Tasks

Focus: INVEST compliance, acceptance criteria clarity, negative paths.

API Contracts and Data Contracts

Focus: schemas, HTTP semantics, security, error handling, versioning.

Procedure for Source Artifacts

When the user provides a direct document, paste, or file to review:

1. Read the entire artifact.
2. Identify the artifact type and applicable review lens.
3. Apply quality dimension checks systematically.
4. Produce the structured review output.

When the user asks to review a named artifact that another skill created:

1. Search for the artifact in the SDD artifact store or project files.
2. If it references other artifacts (e.g., a spec references a PRD), note interactions and cross-check consistency.
3. Apply the review.

Correction Loop with Creating Agents

When a review results in 🟡 Requires Changes or 🔴 Rejected, the creating agent should iterate. Follow these rules for the correction loop:

1. The reviewer does not rewrite the artifact. The reviewer produces findings; the creator applies corrections.
2. Each critical finding must be resolved before re-review. The creator addresses findings and resubmits.
3. The reviewer re-evaluates only changed sections unless the change affects other sections. State the re-review scope explicitly.
4. After two correction cycles, if critical findings remain, escalate to the user with a summary of unresolved issues and recommended options.
5. The reviewer must acknowledge when all previous findings are resolved. Do not repeat resolved findings.
6. If the creator disagrees with a finding, surface the disagreement to the user with both perspectives rather than looping silently.

Correction loop template for the reviewer:

## Correction Cycle Status
- Cycle: <N> of 2 allowed automatic cycles
- Previous findings resolved: <count> / <total>
- Unresolved critical findings: <list>
- Escalation needed: <Yes/No>

Required Output Structure

Use this structure for every review. Adapt section depth to the artifact's size and complexity.

# Review: <Artifact Title>

## 1. Verdict

<🟢 Approved / 🟡 Requires Changes / 🔴 Rejected (Critical Blockers)>

<One-paragraph summary of the overall assessment.>

## 2. Review Context
- Artifact type: <PRD / Spec / Architecture / User Story / API Contract / Task List / Other>
- Artifact source: <provided inline / file path / SDD change name>
- Review scope: <full artifact / named sections only>
- Cross-references checked: <artifacts also reviewed for consistency>

## 3. Inconsistencies and Critical Errors

| # | Severity | Location | Finding | Expected | Suggested Fix |
| --- | --- | --- | --- | --- | --- |
| C1 | 🔴 | §3.2, Requirement F-7 | <What is wrong> | <What correct looks like> | <Actionable fix direction> |

## 4. Detected Gaps (Edge Cases and Missing Scenarios)

| # | Severity | Gap | Affected Section | Why It Matters | Suggested Coverage |
| --- | --- | --- | --- | --- | --- |
| G1 | 🔴 | No error handling for payment gateway timeout | §6 Integration | System may hang or corrupt state on external failure | Add retry, circuit-breaker, and dead-letter handling |

## 5. Improvement Opportunities (Clarity, Standards, Structure)

| # | Severity | Location | Observation | Suggestion |
| --- | --- | --- | --- | --- |
| I1 | 🔵 | §2 Assumptions | Assumptions list mixes constraints and guesses | Separate into Constraints, Assumptions, and Open Questions |

## 6. Validation Checklist

| Dimension | Status | Notes |
| --- | --- | --- |
| Consistency | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Completeness | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Clarity | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Feasibility | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Traceability | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Testability | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Security | ✅ Pass / ⚠️ Warning / ❌ Fail | |
| Standards | ✅ Pass / ⚠️ Warning / ❌ Fail | |

## 7. Correction Roadmap

<If verdict is 🟡 or 🔴, provide a prioritized list of what the creator should address first.>

1. <Fix critical items C1, C2, G1 first — these block implementation.>
2. <Address warnings next — these introduce risk.>
3. <Consider suggestions for polish.>

## 8. What Is Well Done

<Explicitly acknowledge sections that are clear, complete, and well-structured. This helps the creator know what to preserve.>

- <Section X>: <what is good about it>
- <Section Y>: <what is good about it>

Quick-Review Variant

When the user asks for a fast check instead of a full audit, use this compact format:

## Quick Review: <Title>

**Verdict:** <🟢 / 🟡 / 🔴>

**Blockers:** <list or None>

**Top 3 Issues:**
1. <Most critical finding>
2. <Second most critical>
3. <Third most critical>

**Checklist:** <dimension-by-dimension pass/warn/fail>

Multi-Artifact Consistency Review

When asked to review multiple artifacts together (e.g., a PRD, a spec, and an architecture document):

1. Review each artifact individually first.
2. Cross-check: do module names match across artifacts? Do contracts in the spec match components in the architecture? Do requirements trace from PRD to spec to tasks?
3. Produce a separate cross-artifact consistency table:

## Cross-Artifact Consistency

| Artifact A | Artifact B | Mismatch | Severity |
| --- | --- | --- | --- |
| PRD §3 (User Story US-4) | Spec §5 (Module payments) | PRD describes refund flow; spec has no refund module | 🔴 |

Quality Bar for the Review Itself

Before presenting the review, verify:

• Every finding references a specific location, statement, or section.
• Severity classification is justified by impact, not preference.
• The review covers all quality dimensions relevant to the artifact type.
• Suggestions are actionable: a creator reading them knows exactly what to change.
• Positive feedback is included for well-executed sections.
• The review is written in English.
• The verdict is clear and the correction roadmap is prioritized.

Response Style

• Use tables for findings, gaps, and checklists.
• Reference sections by identifier (e.g., §3.2, Requirement F-7, Module payments).
• Use direct quotes from the artifact when pointing out ambiguity or errors.
• Be precise: say "the deadline field is described as a string but compared as a timestamp in §4.1" not "date handling is inconsistent."
• Mark uncertain findings: if a finding depends on context the reviewer cannot see, prefix with [Assumption: ...].
• Do not prescribe implementation. Recommend structural or content changes, not code.

Troubleshooting

• Artifact is too large for one review: Ask the user which section or dimension to prioritize.
• Artifact type is ambiguous: Ask a clarifying question before applying a lens.
• Multiple artifacts with unknown priority: Review them individually first, then ask whether cross-artifact consistency is needed.
• Creator disagrees with findings: Surface the disagreement to the user with both perspectives. Do not loop silently.
• No prior spec or architecture context available: Proceed with the artifact as-is and mark context-dependent findings.