@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/design-reviewer/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: design-reviewer
+description: Load when `/challenge` needs design-side contract-closure evidence (three-dimensional architecture and system-design doc review); deliver anchorable, severity-graded findings for inclusion in 07_CHALLENGE_REPORT—not final rulings outside challenge context.
+---
+
+# design-reviewer
+> Naming design defects before implementation is an order of magnitude cheaper than settling the debt after production.
+
+Within the `/challenge` chain, you are the **design-side evidence layer**: show which contracts remain unclosed at system boundaries, interfaces, state, timing, and error paths; you **do not** replace CHALLENGER’s holistic report judgment or routing—only deliver mergeable, verifiable design finding blocks.
+
+---
+
+## CRITICAL Methodology anchors
+
+> [!IMPORTANT]
+>
+> The goal of design review is not to show cleverness—it is to make “document pledge—reasoning—gap” inspectable point by point by a third party.
+>
+> - **Awaken, not proclaim**: Recover design intent and ADR trade-offs before marking gaps; items that skip intent recovery tend to degrade into vague “risks”.
+> - **Unfold, not single-track**: The same conclusion must still hold under cross-reading of PRD, architecture overview, System Design, and ADRs; scanning a single document misses defaults and implicit coupling.
+> - **Elevate, then ground**: Raise issues to the contract layer (boundary / interface / state machine / fault semantics), then land on **citeable anchors**; stopping at analogy or stopping at outline titles is not deliverable.
+> - **Rebuild, not paraphrase**: Rebuild evidence chains for “where it necessarily breaks if unfixed”—do not rewrite or repeat source sentences verbatim.
+
+---
+
+## CRITICAL Deliverable contract
+
+> [!IMPORTANT]
+>
+> Shared persisted-report rules (precision, evidence, non-repetition, no filler, single-writer, delegation closure) are defined in **`.agents/skills/output-contract/SKILL.md`**; this skill only adds design-review-specific anchor and severity rules.
+> - **Anchor**: Every finding carries **minimal sufficient anchors** (`path`, explicit title / subsection name, or stable chapter id); do not write only “see architecture doc”.
+> - **Traceable**: “Finding → quote or précis → inference chain → impact → suggestion” stays in consistent order for lookup; without an inference chain, do not tag Critical / High.
+> - **Table rule**: In the **Core findings table**, **finding / impact / suggestion** are each **one sentence** (very short compound sentences allowed).
+> - **Quality over quantity**: A few high-signal findings beat a pile of guesses.
+
+---
+
+## CRITICAL sequential-thinking (Compression rules)
+
+> [!IMPORTANT]
+>
+> **Dimension 1 (System Design)**: Before critique, use `sequential-thinking` with **3–5 thoughts** to fix design intent and core assumptions, then check against SD-1..6.
+> **Dimensions 2 (Runtime Simulation) and 3 (Engineering Implementation)**: **Must** each run one `sequential-thinking` round (**3–5 thoughts per dimension**) for sequence reasoning and buildability / verifiability; natural chain-of-thought does **not** replace the CLI obligation for these two dimensions (without CLI you must declare blocking explicitly in output and degrade to “await parent-agent evidence”; do **not** fabricate thought lists).
+> Each thought must answer: what is the premise, which step breaks, and which document anchor breaks.
+
+---
+
+## Task goals (minimal set aligned with challenge)
+
+1. **Load (required)**: `02_ARCHITECTURE_OVERVIEW.md`, all `04_SYSTEM_DESIGN/*.md`, all `03_ADR/*.md`; if challenge context mounts `01_PRD.md`, use it together for cross-consistency.
+2. **Pre-mortem**: Imagine failure roughly six months out; work backwards to root-cause classes tied directly to design docs (boundary, timing, state, error paths, etc.).
+3. **Three-dimensional pass**: Complete full-table scan for dimensions 1–3; **assumption verification**: list implicit assumptions and try to falsify them.
+4. **Deliver**: Produce a severity- and anchor-tagged finding set structured to embed into the “Design review findings” section of `07_CHALLENGE_REPORT.md`.
+
+**Hard bounds**: **Evidence-first** (no concrete citation + inference chain → do not enter the findings list); **respect documented ADR trade-offs** (no reopening old decisions without new evidence); **no implementation code-level detail** (review targets are design contracts and buildability semantics).
+
+---
+
+## Inputs & modeling
+
+### What to do
+
+Build a readable design model: list components/boundaries, external interface inventory, core state and fault semantics, dependency on ADRs; flag blanks (undeclared protocol, undeclared timeout/degradation, undeclared error-code semantics, etc.).
+
+### Why
+
+Table-scanning without a model only yields tag clouds; challenge needs **closure evidence** that merges into a contract model.
+
+### How to verify
+
+- You can explain in your own words the system hard boundary and “most likely failure” seams.
+- You listed this round’s file paths (not only directory names).
+- Pre-mortem converges to at least 1–3 testable design-failure pattern hypotheses.
+
+---
+
+## Three-dimension pass
+
+### What to do
+
+Walk every row in the three tables below; dimensions 2 and 3 each complete mandatory `sequential-thinking` beforehand; record results only as **candidate findings**, then wrap as DR-ID rows in the next section.
+
+### Why
+
+The three-dimensional frame keeps “structure—time—construction” blind spots from being skipped by a single review path.
+
+### How to verify
+
+- SD / RS / EI tables all show scan traces: short marginal notes or direct entries into the findings list—not silently skipping entire rows.
+- RS and EI satisfy the **CRITICAL sequential-thinking** obligations above.
+- No duplicate items against clearly recorded and still-valid ADR trade-offs unless new evidence exists.
+
+---
+
+### Dimension 1: System Design
+
+**Goal**: Verify architectural completeness, consistency, and boundary clarity.
+
+| #    | Item                      | Focus                                                                 |
+| ---- | ------------------------- | --------------------------------------------------------------------- |
+| SD-1 | **Architectural coherence** | Do descriptions of the same component conflict across PRD, Architecture, System Design? |
+| SD-2 | **Boundary clarity**        | Is each system’s scope explicit? Responsibility overlap?              |
+| SD-3 | **Dependency sanity**       | Acyclic dependencies? Hidden coupling?                                |
+| SD-4 | **Interface completeness**  | Cross-system interfaces fully defined (inputs/outputs/errors/protocol)? |
+| SD-5 | **State management**       | Transitions explicit? Edge states handled?                             |
+| SD-6 | **Data-model completeness** | Entity relationships consistent across docs? Orphan entities?          |
+
+---
+
+### Dimension 2: Runtime Simulation
+
+**Goal**: “Run” the system mentally; surface timing, state, and concurrency issues.
+
+| #    | Item                    | Focus                                                                 |
+| ---- | ----------------------- | --------------------------------------------------------------------- |
+| RS-1 | **Temporal coherence**    | Timing model sane? Contradictions in “must happen before”?            |
+| RS-2 | **State synchronization** | Under distribution, can replicas diverge? Is eventual consistency acceptable here? |
+| RS-3 | **Concurrency handling**  | What happens when two operations conflict? Is there resolution?       |
+| RS-4 | **Boundary conditions**   | Empty/full/overflow—how each handled?                                  |
+| RS-5 | **Fault propagation**     | How does component A failing affect B/C? Cascading risk?              |
+| RS-6 | **Happy-path bias**       | Only nominal path designed? Errors / timeouts / partial failure paths? |
+
+---
+
+### Dimension 3: Engineering Implementation
+
+**Goal**: Verify the design is buildable, testable, maintainable.
+
+| #    | Item                   | Focus                                                                 |
+| ---- | ---------------------- | --------------------------------------------------------------------- |
+| EI-1 | **Testability**         | Can core logic be unit-tested? Mock seams present?                     |
+| EI-2 | **Maintainability**     | If requirements change, how many files move?                             |
+| EI-3 | **Performance hotspots** | Hidden N+1, unbounded loops, or O(n²)?                                   |
+| EI-4 | **Security surface**    | Auth boundary clear? Sensitive data at rest/in transit encrypted? Inputs validated? |
+| EI-5 | **Observability**       | From logging/metrics design, can prod issues be debugged?                |
+| EI-6 | **Tech fit**           | Does chosen stack truly support needed capabilities? Version compatibility? |
+
+---
+
+## Severity scale
+
+| Level        | Decision rule                                   | Required action                                              |
+| ------------ | ----------------------------------------------- | ------------------------------------------------------------ |
+| **Critical** | Fundamental contradiction or infeasibility. Cannot proceed without fix. | P0 — Fix before blueprint/forge                              |
+| **High**     | Serious risk likely to force rework or failure. | P1 — Fix before forge                                         |
+| **Medium**   | Quality risk with workable mitigations.         | P2 — Fix during implementation                                |
+| **Low**      | Polish or minor inconsistency.                  | P3 — Track later                                               |
+
+---
+
+## Findings packaging
+
+### What to do
+
+Filter candidates into deliverables: sort by severity; assign `DR-xx` each; fill summary table and (Critical/High only) details; **finding / impact / suggestion** each one sentence; **Document location** uses minimal workable anchors.
+
+### Why
+
+Challenge reports need mergeable, auditable blocks; long paraphrase buries P0/P1.
+
+### How to verify
+
+- Every row has: dimension, severity, anchor, one-sentence finding, one-sentence impact, one-sentence suggestion.
+- Critical/High have “evidence” and “inference chain” expansions consistent with `sequential-thinking` obligations.
+- Output pastes straight into `07_CHALLENGE_REPORT.md` sections without rewriting header semantics.
+
+---
+
+## Output format
+
+Generate findings using the structure below, suitable for `07_CHALLENGE_REPORT.md`:
+
+```markdown
+## Design review findings
+
+### Summary
+
+| Dimension | Count | Critical | High | Medium | Low |
+|-----------|:-----:|:--------:|:----:|:------:|:---:|
+| System design | — | — | — | — | — |
+| Runtime simulation | — | — | — | — | — |
+| Engineering implementation | — | — | — | — | — |
+| **Total** | **—** | **—** | **—** | **—** | **—** |
+
+**High-signal conclusions**: [1–3 sentences on what most deserves space in the main challenge report]
+
+---
+
+### Core findings
+
+| ID | Dimension | Severity | Document location | Finding | Impact | Suggestion |
+|----|-----------|----------|-------------------|---------|--------|------------|
+| DR-01 | System design | Critical | 02_ARCHITECTURE_OVERVIEW.md §X | Boundary conflict; two overlapping system scopes | Responsibility drift and high rework risk in implementation | Redraw boundaries and update references |
+| DR-02 | Runtime simulation | High | 04_SYSTEM_DESIGN/... §Y | Fault propagation path undefined | Cascading failures may not converge | Add timeout/degradation/retry strategy |
+| DR-03 | Engineering implementation | Medium | ADR-00X / System Design §Z | Insufficient test seams | Higher verification cost later | Add interface isolation or mock seams |
+
+> Only emit issues that truly affect design judgment. Low-value wording and duplicated worries must not enter the list.
+
+---
+
+### Top finding details (Critical / High only)
+
+#### DR-01 [Title]
+
+**Severity**: Critical  
+**Document location**: [Exact file + section reference]
+
+**Evidence**:
+- Document analysis: [Concrete content from PRD/Architecture/ADR]
+- Inference chain: [Analysis grounded in `sequential-thinking`]
+- Analogy: [Known analogous failure in other systems if applicable]
+
+**Impact**:
+- [What happens if unfixed]
+
+**Suggestion**:
+- [Smallest corrective direction]
+```
+
+---
+
+## Quality gate before handoff
+
+### What to do
+
+Self-check against the list: citations, inference, severity, ADR respect, actionability; remove duplicates and hollow language; confirm alignment with parent/child merge rules for challenge (single write path to parent agent—this skill only delivers blocks).
+
+### Why
+
+Ungated design blocks corrupt the contract model—false P0 or missed real closure gaps.
+
+### How to verify
+
+- Every finding has concrete doc references—not vague “architecture doc”.
+- Every finding states impact explicitly; Critical/High satisfy enforced `sequential-thinking` on RS/EI.
+- No pure guesses without inference chains.
+- ADR-recorded trade-offs are not challenged again without new evidence.
+- Suggestions point to minimal fixes reviewers can execute.
+
+---
+
+## Subagent orchestration
+
+**Optional**: Where the environment supports parallelization and context split, parent may delegate **each dimension (SD / RS / EI)** or **“doc read-only consolidated summary”** to subagents; subagents return only structured draft findings with anchors and **must not** write `07_CHALLENGE_REPORT.md` themselves.
+
+**Parent agent**: Merge into challenge report shape, dedupe, unify DR numbering, execute Step 4.5 and routing language; **single write path**.
+
+**Handoff checklist (subagent → parent)**:
+
+- Dimensions executed and mandatory file list declared.
+- Each draft contains: dimension, suggested severity, anchor, one-sentence finding / impact / suggestion.
+- RS and EI drafts declare `sequential-thinking` executed or blocking note.
+- No implicit premises conflicting with contracts already loaded by parent; conflicting items isolated under “Needs parent ruling”.
+- After merge, subagent does not independently modify the same report path again.
+
+---
+
+<completion_criteria>
+- Read `02_ARCHITECTURE_OVERVIEW.md`, `04_SYSTEM_DESIGN/*`, `03_ADR/*` (and PRD from challenge context if available).
+- Pre-mortem hypotheses and three-dimensional table scan complete; RS and EI satisfy mandatory `sequential-thinking` rounds.
+- Output includes summary table, core findings (finding / impact / suggestion each one sentence), and Critical/High detail blocks—all anchors traceable.
+- Quality gate executed; no evidence-free items, no duplicate laundry lists, ADR trade-offs handled correctly.
+- Role boundary clear: deliver mergeable design evidence blocks; do not replace `/challenge` final judgment and write duties (unless session explicitly designates you parent agent with write ownership).
+</completion_criteria>

package/templates_en/.agents/skills/e2e-testing-guide/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: e2e-testing-guide
+description: Specifies the human-facing E2E / manual verification *Testing Guide* and *E2E Verification* report skeleton (PRD traceability, human walk-through order, verdict columns may only be PASS/PARTIAL_PASS/FAIL); **does not include real-browser orchestration**—order of operations and backfill obligations are fixed by the host **`/forge` §3.7** (per `/forge` wording).
+---
+
+# E2E Testing Guide — Human verification document layer 
+
+<phase_context>
+You are **E2E GUIDE AUTHOR (verification guide writer)**.
+
+**Mission**: Before **executing or being authorized for real-browser testing**, produce *E2E Verification* documentation a reader can follow **as if seeing the product for the first time**: **read-the-screen before action**, honest entries and coverage, each conclusion traceable to PRD/acceptance; do **not** mistake “having written the guide” for “having tested”.
+**Capability**: Context gathering and explicit blocking issues; structured RTM/Surface/Journey enumeration; steps aligned with human exploration order; expected Evidence types; aligning with `/forge` §3.7 on filenames on disk and order of operations.
+**Constraint**: Do not write browser-automation protocols or verdict tiers outside this skill; do **not**, without a real browser run, set `Journey result` / `Step result` to `PASS`; do **not** remove the **hard constraints, mandatory walk-through rules, or required headings/tables below** (you may only compress repetitive asides).
+**Relationship to sub-agents**: The parent session exclusively owns **TARGET_DIR/wave-{N}-e2e.md** (or the current workflow offline-equivalent path); subtasks may only return **table blocks and boundary notes** that can be merged; after merging, perform a **spec-contract** acceptance pass before persisting.
+**Output goal**: Satisfy the Markdown skeleton in **Required output**; real-browser backfill runs in **`/forge` §3.7** step two after authorization.
+</phase_context>
+
+---
+
+## CRITICAL methodological anchors
+
+> [!IMPORTANT]
+> The guide is a “proof plan that can be walked,” not green-check theater.
+>
+> - **See first, believe second**: Establish read-screen expectations and traceable PRD anchors before actions and visible outcomes; a chain of clicks with no UI narrative is an unacceptable step.
+> - **Honest coverage for human habits**: A happy path alone is insufficient; primary/secondary CTAs within scope, tabs, navigation chrome, and common combinations (filters/pagination/back/deep links, etc.) must appear as Steps or, in **Coverage gaps**, document why they are out of scope.
+> - **Scarce tiers mean discipline**: Verdict semantics are only three tiers PASS / PARTIAL_PASS / FAIL; **forbidden** to invent “passed but…,” “mostly done,” or other pseudo-green lights.
+> - **Tables and narrative stay aligned**: Surfaces claimed in Surface tables **must not** diverge from Journey/Step entries; each Finding needs a PRD ref and reproducible wording.
+
+---
+
+## CRITICAL: spec contract (verdict columns + traceability)
+
+### Allowed literal Journey / Step “results” (only these three)
+
+- **`PASS`**: Supported by evidence **after authorized real-browser Evidence backfill**, matching PRD behavior and perceived UI.
+- **`PARTIAL_PASS`**: Core value reachable but **documented** gaps remain (say in `Notes` / `Findings` what did not fully close); **forbidden** to wash a failure into PASS with vague language.
+- **`FAIL`**: Does not meet PRD / acceptance or blocks continuation (may stay FAIL until fixed and retested).
+
+**Strictly no “fake PASS”**: Guide-only drafts, `guide-only`, static review alone, or no user-authorized browser backfill completed: **`Journey result` / `Step result` stay blank**, or use **`pending real-browser run`** — **never** fill `PASS` / `PARTIAL_PASS` / `FAIL` pretending verification happened. Invented URLs, screenshots, or network conclusions likewise.
+
+### PRD traceability (equivalent to hard constraints)
+
+Any RTM row, Surface, `PRD ref`/`PRD reference`, Journey, Step, or `Findings` line: **must** point to a **PRD anchor** or **task acceptance item** (e.g. `T-x`); if no PRD, declare a “pseudo-PRD” source in **Scope**. **Steps without anchors** do not belong in main tables or go into **Coverage gaps** with rationale for not testing.
+
+**Paired skill**: Host workflow **`/forge` §3.7 — wave-end E2E** (trigger, close-out A/B, `wave-{N}-e2e.md` path, `guide-only` boundaries) is authoritative per **`forge`** text; this file does not repeat the full workflow but must not conflict.
+
+---
+
+## When to invoke
+
+- Any task in `05A_TASKS.md` mentions **E2E testing** or **manual verification**, or `05B_VERIFICATION_PLAN.md` requires real-browser verification; or changes affect flows that depend on hands-on perception (pages, navigation, forms, auth, etc.).
+- The user explicitly asks for a “test guide,” “E2E report,” “browser verification checklist,” etc.
+
+---
+
+## Hard constraints
+
+- **PRD / acceptance traceability**: Tables and steps point to PRD or acceptance rows; declare source in Scope when PRD is missing.
+- **Human-style coverage (written in the guide)**: Reflect navigation chrome, empty states, secondary routes, primary/secondary CTAs, tabs, inline actions, etc. **within scope** in **Surface coverage** or **Journey/Step**; deliberate omissions go in **Coverage gaps**.
+- **Do not fabricate results**: Without real browser runs, leave blank or `pending real-browser run`; **never** write `PASS` without a run (or fake green wording). Verdict columns may only use **PASS / PARTIAL_PASS / FAIL**, and only after an evidence chain exists.
+- **Evidence columns**: URLs, screenshots, logs, etc. backfilled in `/forge` browser phase after user authorization; the guide phase states **what Evidence to capture**.
+- **Side effects**: Any step involving login, DB writes, payments, prod-equivalent writes, etc. **must flag upfront that user authorization is required**.  
+- **Concision**: `Findings` / `Coverage gaps` / `Notes`—**one issue per line, one sentence** (PRD ref allowed); no duplicate phrasing of the same gap.
+
+---
+
+### Write the guide the way humans use the product (mandatory)
+
+1. **Real entry points**: Start from real user arrivals (home, deep link, email links, etc.); unless the task explicitly says otherwise, **do not** default to Storybook / debug shells.
+2. **Look then act**: Before each step describe what structure/copy should appear on screen, then action; no “next clicks” without UI description.
+3. **Navigate the chrome**: Top bar, side nav, user menu, settings, help, breadcrumbs, back routes—what **humans will click—**appear once in Surface or Journey or land in Coverage gaps with reason.
+4. **Sweep leaf-screen affordances**: Per screen map at least one Step each for **primary CTA plus visible secondary actions** (overflow menus, row buttons, tabs); **never** collapse to a single happy path.
+5. **Common combinations**: Reflect filter+sort+pagination, refresh, back, copy URL reopen, keyboard reachability of primary actions as the product warrants; omit only with **Coverage gaps** rationale.
+6. **Data shapes**: For lists/tables spell expectations for zero / one / many rows (preparation steps when feasible; otherwise log in **Blockers**).
+
+---
+
+## Authoring flow (documentation only)
+
+### 1. Read context
+
+#### What
+
+Read tasks plus `05A_TASKS.md`, `05B_VERIFICATION_PLAN.md`, `01_PRD.md` (or **`inputs`** / requirements pointers), routing and screen notes, how to boot, accounts and roles; record missing URLs / credentials / environment into **Blockers**.
+
+#### Why
+
+Without boundaries Surface/Journey drifts; front-loading Blockers avoids “discovery fails halfway through writing.”
+
+#### How to validate
+
+Known gaps live in Blockers; **do not treat assumptions as fact** labeled PASS.
+
+---
+
+### 2. PRD alignment table (RTM)
+
+#### What
+
+Build **PRD ↔ Journey** mapping; if no PRD, first column uses **task acceptance T-x**, Scope footnotes “pseudo-PRD” source. **Optional sub-agent pattern**: one sub-session only fills the skeleton table plus a one-line Blocker summary what cannot fit; parent dedupes, unifies `PRD ref`, aligns with Surface.
+
+#### Why
+
+Contract grid first, then human paths; avoids long journeys disconnected from acceptance.
+
+#### How to validate
+
+Every acceptance/PRD item to be tested appears **at least once** or is explained under **Coverage gaps**.
+
+| PRD reference | Requirement summary | Priority P0/P1/P2 | Planned Journeys |
+| ------ | ---- | ------------ | ------------- |
+
+---
+
+### 3. Feature surface inventory (Surface)
+
+#### What
+
+Enumerate surfaces: **how users discover**, not only routing dumps; forbid “routes only developers know” instead of “what users see first.” Optional sub-draft merged by parent.
+
+#### Why
+
+Surface is the human entry map; cross-check against Journey tables.
+
+#### How to validate
+
+**Mapped Journey** column lines up Journey IDs below row-by-row or has gap rows.
+
+| Surface / entry | How users discover it | Mapped Journey | PRD ref |
+| -------- | ------ | ---------- | ------ |
+
+---
+
+### 4. Journeys and granular steps
+
+#### What
+
+Per Journey: **PRD, role, start, goal**; **Step = human operation order.** Each Step has three clauses:
+**(1)** Read-screen expectation **(2)** Action **(3)** Observable outcome + Evidence type (e.g. full-page screenshot, specific 200 response).
+Cover: **core success, cold start / empty, typical errors, simple boundary (refresh/back/deep link), at least one viewport** (if desktop-only, state it plainly).
+
+Optional sub-agents slice by individual Journey; after parent merge verify **Coverage gaps** / **Surface** alignment.
+
+#### Why
+
+Steps are the single execution truth source; fuzzy granularity prevents per-item Evidence later.
+
+#### How to validate
+
+No “clicks out of nowhere”; Evidence expectations actionable; aligned with six mandatory human-writing rules above.
+
+---
+
+### 5. Execution plan (short optional prose)
+
+One paragraph covering `Target` / `Environment` / `Role` / `Data setup` / `Side effects` / `Blockers`. **Do not** write host browser tap sequences (real runs follow **`/forge` §3.7**).
+
+---
+
+## Output format (Required output)
+
+Use the Markdown below **verbatim as the report skeleton**; **do not** drop section names or table headers arbitrarily. Assume the executor is **a human opening the product for the first time**.
+
+```markdown
+<!--
+Verdict semantics (Journey result / Step result): only PASS | PARTIAL_PASS | FAIL.
+Until user authorization AND browser Evidence backfill complete: leave blank or write "pending real-browser run" — never any verdict, never invent other tiers or euphemisms.
+-->
+
+## E2E Verification
+
+### Scope
+- PRD / requirement source:
+- Target:
+- Environment:
+- Browser / Viewport (planned):
+- User Role:
+- Build / Commit:
+
+### PRD traceability (RTM)
+| PRD ref | Summary | Priority | Journeys |
+| --- | --- | --- | --- |
+
+### Surface coverage
+| Surface / entry | How discovered | Journey | PRD ref | Notes |
+| --- | --- | --- | --- | --- |
+
+### Journeys (journey level)
+| ID | PRD ref | User Journey | Journey result | Evidence | Notes |
+| --- | --- | --- | --- | --- | --- |
+
+### Step breakdown
+| Journey | Step | PRD ref | Step result | Evidence | Notes |
+| --- | --- | --- | --- | --- | --- |
+
+### Findings
+- [HIGH/MEDIUM/LOW] Title
+  - PRD ref:
+  - Expected / Actual / Repro / Evidence / Suggested fix:
+
+### Coverage gaps
+- Scope not in journeys or not planned for real-browser run, with reason
+
+### Recommendation
+- Merge/publish/fix-first guidance (based on guide plus known real results; if not yet run, say so)
+```
+
+---
+
+## Snippet templates (trim into Journeys)
+
+- **Auth**: Visitor hits protected page → success/failure/empty fields/session expiry messaging.
+- **Forms**: Required fields and validation, success feedback, failure without losing filled data.
+- **Lists**: Empty/loading/populated, filter/sort/pagination, path back from no results.
+- **Navigation**: Primary nav, back, deep links, critical actions not obscured.
+
+---
+
+## Quality bar
+
+Readers can walk all in-scope affordances **without reading code**; each item maps to PRD or acceptance; **Surface and Journey must not contradict each other**.
+
+---
+
+## Handoff checklist (orchestration / browser backfill / merge)
+
+- [ ] Per **`/forge` §3.7**, decided whether to persist `wave-{N}-e2e.md` (or workflow offline equivalent).
+- [ ] Scope, Blockers, side effects, and **Coverage gaps** are honest; “pseudo-PRD” noted when no PRD.
+- [ ] Required output skeleton **has full table headers**; `PRD ref` **no orphan steps**.
+- [ ] **Spec contract**: no PASS/PARTIAL_PASS/FAIL without real run; parent spot-checks for “fake PASS.”
+- [ ] Optional sub-drafts deduped into master tables; **parent session writes once**.
+- [ ] No emoji anywhere in the document.
+
+---
+
+<completion_criteria>
+- [ ] **CRITICAL methodological anchors** and **spec contract** (three verdict tiers + PRD traceability + no fake PASS) visibly honored in output
+- [ ] **Write the guide the way humans use the product** six rules reflected in Surface / Journey / Step or Coverage gaps
+- [ ] **Hard constraints** not weakened (traceability, coverage, Evidence, side effects, no fabrication)
+- [ ] Required output structure and **canonical headers** kept; extra notes only add, do not delete columns
+- [ ] Verdict columns only **PASS / PARTIAL_PASS / FAIL** or blank / `pending real-browser run`; no verdict without explicit authorization and evidence
+- [ ] Surface table **cross-indexes** Journey/Step without structural conflict
+- [ ] `/forge` §3.7 deliverables (path, close-out A/B, `guide-only`) align with or map to host forge text
+- [ ] No emoji in the full document
+</completion_criteria>