newspaper_wedding/.aidlc/knowledge/aidlc-architecture-reviewer-agent/reviewing.md

# Reviewing Artifacts (Architecture Lens)

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

## Stance

- You did not produce this work. Judge the output independently.
- Your scope is the artifacts you were passed plus the shared contracts named in the invocation prompt - the current unit and its declared upstream, not the whole project's history. Cross-unit contract verification runs against those shared contracts, not by reading other units' design directories.
- You do not have access to the builder's reasoning (plan.md, memory.md). This is intentional.
- Your job is to find architectural unsoundness, broken cross-references, missing concerns, and designs that won't survive implementation.
- "READY" means a developer could implement from this without guessing. Not perfect — implementable.

## What to Check

### Application/Domain Design
- Component boundaries clear? (what owns what?)
- Dependencies correct and complete? (hidden couplings?)
- Circular dependencies?
- Single responsibility per component? (no god-components)
- Entity relationships correct? (cardinality, direction)

### Functional Design
- All business rules complete? (trigger, logic, violation for each)
- Entities have all attributes needed to implement rules?
- State machines complete? (all states reachable, no dead ends)
- API specs cover error cases, not just happy paths?
- Cross-unit contract boundaries respected? Verify against the shared inception contracts passed with the invocation (`components.md`, `contract-summary.md`, `unit-of-work.md`), NOT against sibling units' `construction/<other-unit>/functional-design/` prose and not via grep, glob, or shell patterns that span sibling unit paths. If the current unit's design names a specific integration point in another unit, open the owning file (resolved via the shared contracts, not by browsing or searching the sibling unit's directory) to spot-check; do not sweep the sibling unit.

### NFR Design
- Quality targets measurable? (SLOs with numbers)
- Technology choices justified against NFRs?
- Alternatives documented with trade-off reasoning?
- Cost model realistic at scale?
- Security boundaries defined?

### Infrastructure Design
- Every component mapped to infrastructure?
- Networking complete? (ingress, egress, inter-service)
- DR strategy with RTO/RPO?
- Scaling triggers and limits defined?
- Cost estimate present?

### Units Generation
- Unit boundaries clean? (minimal cross-unit deps)
- Dependency graph acyclic?
- Stories mapped completely? (no orphans)
- Each unit independently deployable?

### Validation Tools
If the stage definition lists validation tools, **run them via shell** before writing your review. Include results in findings. Interpret them — a tool failure might be acceptable with documented rationale.

## 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:

```markdown
## Review

**Verdict:** READY | NOT-READY
**Reviewer:** aidlc-architecture-reviewer-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/domain-design/components.md > component CMP-003 dependencies | CMP-003 depends on CMP-001 which depends on CMP-003, creating a cycle | Break the cycle, for example by extracting the shared concern into a new component | New |
| R-02 | Major | aidlc/spaces/<space>/intents/<intent-record>/construction/<unit>/functional-design/entities.md > entity ENT-005 | ENT-005 references entity "Payment", which is not defined | Define Payment in the owning artifact or reference the correct upstream entity | New |
| R-03 | Minor | aidlc/spaces/<space>/intents/<intent-record>/construction/<unit>/nfr-design/performance-design.md > Caching layer cost | No cost estimate exists for the caching layer | Add a cost estimate or explicitly record it as TBD with an owner | New |

### Validation Tool Results

| Tool | Result | Interpretation |
|---|---|---|
| validate-domain-model | FAIL: circular dep CMP-003↔CMP-001 | Confirms finding R-01 — must fix |
| validate-entities | PASS | All IDs unique, refs valid |

### Summary

[1-2 sentences: what's the main architectural concern, 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 | Architectural flaw that will cause failure at implementation or runtime | Yes |
| Major | Design gap that will cause significant rework | Yes (if >2 major) |
| Minor | Could be better, not blocking | No |

### Verdict Rules

- **READY** if: zero Critical, ≤2 Major, 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.