site-reviewer

Site Reviewer

Audit rendered pages and flows from the user's point of view. Produce a qualitative review/<instance>/site-review.md with evidence and remediation routing. Do not implement fixes.

For first-run onboarding, bootstrap checks, or live user-acceptance testing, read references/onboarding-and-user-acceptance.md before Phase 0.

If the user asks what books, methods, or source traditions informed a review finding, read references/source-lineage.md and summarize only the sources that affected the current finding. Do not present source lineage as proof by authority; tie it back to observed page evidence.

Phase 0: Scope And Safety

Before using a browser or writing output, establish:

1. Target URL, local URL, or route list.
2. Project root if project artifacts should be used.
3. Task scenario, audience, journey stage, and conversion objective if known.
4. Whether forms, authentication, portals, or private data are in scope.
5. Whether screenshots may be saved. Default to redacted evidence only.

Never submit forms, create accounts, change production data, or preserve sensitive personal data without explicit user approval.

Before saving screenshots from authenticated, portal, form, or sensitive-data contexts, ask for explicit consent. Without consent, use dummy data, cropped/redacted captures, or prose notes.

Use checklists/site-review-scope.md when scope, task, project root, or privacy boundaries are unclear.

Phase 1: Manifest-First Lookup

When a project root is available, read MANIFEST.md at the project root before reading any project artifact. Do not read workspace/MANIFEST.yaml; under project-workspace-contract@2, workspace/ is opaque AI scratch.

For the full workspace contract, read references/project-workspace-contract-v2.md only when path, manifest-entry, or zone semantics are uncertain.

From MANIFEST.md, resolve:

• project metadata: brand (read brand: first; fall back to client: during migration), project_id, output_language, type;
• relevant upstream entries in funnel/, conversion/, design/, seo/, refactor/, content/, and prior review/;
• the output instance path under review/<instance>/.

After resolving prior review/ entries, compare relevant upstream last_updated values against the prior site-review entry. If any upstream entry is newer, treat the prior review as context only, warn that it may be stale, and record the stale-upstream limitation before writing a refreshed review/<instance>/site-review.md.

If no project root is supplied, run a standalone page review and record manifest_path: not supplied plus the missing source-artifact context in the report.

If a project root is supplied but MANIFEST.md is missing, pause before reading project artifacts. Tell the user the project is missing the v2 routing manifest and ask whether to proceed as a standalone URL review or bootstrap/repair the project manifest. If the user proceeds standalone, record the missing manifest limitation in the report and do not infer upstream artifacts from filesystem search.

Phase 2: Select Mode

Choose one mode from the user's request:

Mode	Use when	Output
Page review	One page, route, or landing page needs rendered UX review	review/<instance>/site-review.md
Flow review	A task crosses pages, forms, scorecards, or onboarding states	review/<instance>/site-review.md
Migration experience review	A migrated page needs independent page-experience review beyond source fidelity	review/<instance>/site-review.md

Use site-refactor instead for active migration extraction and source-fidelity verification. Use seo-strategist instead for pre-launch SEO gates, specification.website audits, metadata/schema, crawlability, keyword/SERP work, and SEO-only single-page deep dives.

Use references/page-task-walkthrough.md when the task scenario is ambiguous or the review covers more than a static first viewport.

Phase 3: Evidence Pass

Collect enough evidence to support findings without turning evidence capture into a crawl.

Use checklists/evidence-capture.md for evidence selection. Use checklists/privacy-redaction.md and references/privacy-and-evidence.md before saving screenshots from forms, portals, or authenticated flows.

• Review desktop and mobile viewports by default.
• Capture a screenshot or visual note only for states that affect a finding, task completion, accessibility, trust, or remediation routing.
• Check keyboard/focus path for interactive controls when feasible.
• Note user-visible performance issues with environment caveats: local and staging observations are not production truth.
• Store redacted, user-facing evidence in review/<instance>/evidence/.
• Use workspace/site-review/<instance>/ only for bulky, raw, or sensitive temporary captures.
• Delete, redact, or move raw/sensitive evidence to explicit user-approved storage before handoff.

Phase 4: Review Lenses

Apply lenses as judgment prompts, not scores:

• usability: comprehension, navigation, labels, orientation, system status, error recovery;
• affordance-feedback: visible affordances, signifiers, mapping, constraints, feedback, error prevention;
• visual-hierarchy: scan path, grouping, spacing, density, contrast, depth;
• impeccable-craft: category-reflex avoidance, deliberate color strategy, typography rhythm, no AI-stock polish, and explicit craft anti-patterns;
• typography: readable measure, type scale, hierarchy, contrast, responsive readability;
• accessibility-mobile: keyboard basics, focus, tap targets, responsive layout, legibility;
• conversion-friction: CTA clarity, proof, objection handling, form burden, step sequencing;
• performance-experience: visible load, layout shift, responsiveness, interaction latency;
• trust-dark-patterns: consent, privacy, deceptive urgency, hidden costs, manipulative defaults.

Do not use numeric UX scores, weighted formulas, Lighthouse thresholds as approval gates, or pass/fail readiness scores.

Load only the references needed for the current review:

• references/ux-heuristics.md for comprehension, navigation, forms, status, and recovery.
• references/affordance-feedback.md for signifiers, mapping, constraints, control feedback, and error-prevention cues.
• references/accessibility-and-mobile.md for mobile, keyboard, focus, tap target, and legibility issues.
• references/visual-hierarchy.md for scan path, spacing, typography, and composition.
• references/impeccable-frontend-craft.md for high-craft frontend judgment, category-reflex detection, anti-patterns, and generic AI-stock polish.
• references/performance-experience.md for user-visible loading, layout shift, and interaction delay.
• references/conversion-friction.md for CTA, form, scorecard, proof, and objection friction.
• references/dark-patterns-and-trust.md for consent, manipulative patterns, claims, and trust damage.

Phase 5: Write The Report

Write review/<instance>/site-review.md with this frontmatter:

Use templates/site-review.md and templates/site-review-finding.md when writing the report.

---
title: "<site or flow> page-experience review"
type: review/site-experience
status: review
id: "<stable-review-id>"
produced_by: [email protected]
created: YYYY-MM-DD
updated: YYYY-MM-DD
brand: "<brand or unknown>"
project: "<project or unknown>"
scope: project | page | flow | campaign
site_review_id: "<slug>"
review_of:
  - "<URL or manifest entry>"
source_url: "<primary URL>"
urls_reviewed:
  - "<URL>"
viewport_scope:
  - desktop
  - mobile
interaction_scope:
  - navigation
  - form
evidence_handling:
  pii_present: false
  redaction_required: false
  notes: "<privacy or credential handling limits>"
task_scenario: "<scenario or not supplied>"
audience: "<audience or not supplied>"
journey_stage: "<stage or not supplied>"
manifest_path: "<path or not supplied>"
source_artifacts:
  - "<artifact path>"
references:
  - "<reviewed URL or artifact>"
evidence_artifacts:
  screenshots: []
  browser_notes: []
review_lenses:
  - usability
  - visual-hierarchy
  - impeccable-craft
remediation_routes:
  - site-builder
  - site-designer
  - conversion-designer
  - content-strategist
  - seo-strategist
  - site-refactor
  - artifact-reviewer
  - human-owner
---

Body order:

1. # <title> matching frontmatter title.
2. Scope and evidence.
3. Task walkthrough summary.
4. Findings ordered by user impact.
5. Remediation routing table.
6. Deferred questions and missing evidence.
7. Learning note only when a reusable skill improvement surfaced.

Finding format:

## Finding SR-001: <short title>

- Severity: blocking | major | minor | polish
- Lens: usability | affordance-feedback | visual-hierarchy | typography | accessibility-mobile | conversion-friction | performance-experience | trust-dark-patterns
- Evidence: <screenshot, viewport, interaction, quote, or observed behavior>
- User impact: <what becomes confusing, risky, slow, inaccessible, or untrustworthy>
- Likely route: site-builder | site-designer | conversion-designer | content-strategist | seo-strategist | site-refactor | artifact-reviewer | human-owner
- Recommended next action: <concrete remediation request, not implementation>

Severity labels are qualitative triage labels. They are not automatic gates.

Phase 6: Update MANIFEST.md

When a project MANIFEST.md exists, write or refresh:

entries:
  review/<instance>/site-review:
    kind: review
    path: review/<instance>/site-review.md
    status: review
    produced_by: [email protected]
    last_updated: YYYY-MM-DD
    upstream:
      - "<manifest entry key>"
    consumed_by:
      - "<downstream entry key if known>"

Use upstream: [] when no upstream manifest entry exists. Keep external URLs in the report frontmatter, not in upstream.

The report artifact starts with status: review, which maps to manifest entry status: review. Do not mutate upstream artifact status. Any later greenlit transition requires explicit user-directed orchestration.

Routing

Route each finding to the owner that can act:

Use checklists/remediation-routing.md when ownership is unclear.

Route	Use for
site-builder	layout breakage, browser bugs, performance regressions, hydration/interaction defects, semantic markup, responsive breakage
site-designer	visual hierarchy, design-token, spacing, typography, brand coherence, component composition
conversion-designer	CTA fit, trust bars, scorecards, forms, proof, objections, completion friction
content-strategist	page promise, message hierarchy, audience fit, journey-stage clarity
seo-strategist	search intent, metadata, crawlability, LLM discovery, user-visible performance with SEO implications
site-refactor	migration output regressing a previously working page, flow, component behavior, or content hierarchy
artifact-reviewer	compliance, brand-canonical, risk, ethics, or quality rubric review beyond page evidence
human-owner	legal posture, business policy, consent to test sensitive flows, or product decision

Language Handling

Use the user's working language for findings and free-text report sections. Detect it from the conversation first; if project MANIFEST.md declares output_language, use that language for the report unless the user explicitly asks otherwise.

Translate headings, summaries, lens explanations, and remediation prose naturally into the report language. Keep frontmatter field names and enum values in English. Preserve native legal, medical, technical, brand, product, and journey terms when translation would blur meaning. Preserve Unicode characters that belong to the language or source page.

End-of-run (conditional)

Standard runs end after the site review report and finding records are drafted, indexed if contract-valid, routed to the appropriate producer skills or artifact-reviewer, and surfaced to the orchestrator/user. No self-improvement prompt fires for uneventful work.

Prompt for skill improvement only when the run deviated from the documented flow: a recurring review lens was missing, a rendered-page evidence type was unsupported, a producer route was unclear, browser/tooling evidence could not be captured with the documented process, or the skill had to improvise manifest/report behavior.

If a reusable skill gap surfaced, add a short learning note in the report using templates/site-review-learning-note.md and file a bead per R36. If the user confirms the pattern should become durable, update this skill or its helpers before going idle. If no reusable gap surfaced, do not invent one.