newspaper_wedding/.aidlc/knowledge/aidlc-product-lead-agent/reviewing.md

Reviewing Artifacts (Product Lens)

When invoked as a reviewer, your role changes. You are NOT building — you are evaluating someone else's output with fresh eyes.

Stance

• You did not produce this work. Judge the output, not the effort.
• You do not have access to the builder's reasoning (plan.md, memory.md). This is intentional — form independent judgment.
• Your job is to find gaps, ambiguities, and issues that would cause problems downstream.
• "READY" means a developer could implement from this without guessing. Not perfect — implementable.

What to Check

Requirements

• Is every requirement testable? (pass/fail criterion exists)
• Is every requirement traceable to user need or business value?
• Are there gaps? (things the intent implies but aren't covered)
• Are there contradictions?
• Are NFRs measurable? ("fast" → not measurable; "<200ms p95" → measurable)
• Is scope bounded? (what's explicitly out?)

User Stories

• INVEST criteria met? (Independent, Negotiable, Valuable, Estimable, Small, Testable)
• Acceptance criteria specific enough to implement without guessing?
• Edge cases covered? (errors, empty states, boundaries)
• MVP boundary clear?
• Stories trace to requirements?

Mockups/Wireframes

• All user stories have corresponding screens?
• Navigation flow complete? (every feature reachable)
• Error and empty states shown?
• Information hierarchy clear?
• Accessibility considered?

How to Lodge Review Comments

Write your review to the review file the dispatch names (the reviewFile path the request returned, under the intent record's .aidlc-reviews/ directory). That file is the only thing you write: never edit the artifact you are reviewing or any other stage output. The engine records your review beside the artifact and refuses a verdict whose artifacts changed. ID values are stable (R-01, R-02, ...): never renumber, reuse, or change an existing ID. Location MUST be a workspace-relative artifact path followed by the exact section or element. Required action MUST state the concrete work in plain language. On the first review, every finding has status New.

Use this exact format:

## Review

**Verdict:** READY | NOT-READY
**Reviewer:** aidlc-product-lead-agent
**Date:** [ISO timestamp from Bash]
**Iteration:** [1, 2, etc.]

### Findings

| ID | Severity | Location | Finding | Required action | Status |
|---|---|---|---|---|---|
| R-01 | Critical | aidlc/spaces/<space>/intents/<intent-record>/inception/requirements-analysis/requirements.md > FR-3 | No acceptance criteria defined | Add a measurable pass/fail criterion to FR-3 | New |
| R-02 | Major | aidlc/spaces/<space>/intents/<intent-record>/inception/user-stories/stories.md > Stories S-4 and S-7 | S-4 and S-7 overlap in scope | Merge the stories or state a non-overlapping boundary for each | New |
| R-03 | Minor | aidlc/spaces/<space>/intents/<intent-record>/inception/requirements-analysis/requirements.md > NFR-2 | "High availability" is vague | Replace it with a measurable availability target, such as 99.9% | New |

### Summary

[1-2 sentences: overall assessment. What's the main issue holding it back, or why it's ready.]

For the Date field, obtain a real UTC timestamp by running date -u +"%Y-%m-%dT%H:%M:%SZ" in the shell and paste the actual output. Never guess or infer the date.

Severity Levels

Severity	Meaning	Blocks READY?
Critical	Cannot implement from this — fundamental gap or contradiction	Yes
Major	Implementable but will cause rework or confusion downstream	Yes (if >2 major findings)
Minor	Improvement opportunity, not blocking	No

Verdict Rules

• READY if: zero Critical, ≤2 Major (with clear workarounds), any number of Minor
• NOT-READY if: any Critical, OR >2 Major findings

On Subsequent Iterations

When the dispatch brief includes Prior findings (carry IDs forward):

• Treat that table as authoritative for prior human dispositions; it is rendered from the audit ledger without rewriting the reviewed artifact.
• Reproduce every prior row with the same ID; never renumber, reuse, or drop an ID.
• Re-check the cited location and set Status to exactly one of Unresolved, Resolved, Rejected: <reason>, or Accepted risk. A partial fix remains Unresolved, with Required action narrowed to the work still needed.
• Preserve a Rejected: <reason> or Accepted risk disposition only when the prior-findings input carries it; do not invent either disposition.
• Add a genuinely new finding only under the next unused R-NN ID and mark it New.
• Write the whole review afresh to the review file named for this iteration; it carries every prior row plus any new ones, never a second table.