@haaaiawd/anws 2.2.6 → 2.4.0

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

@@ -0,0 +1,428 @@
+---
+name: task-reviewer
+description: "[ALPHA] Systematically reviews 05A_TASKS.md and 05B_VERIFICATION_PLAN.md as the task-contract and verification-contract evidence layer for the `/challenge` workflow; 7 passes (A→G), four semantic models, finding cap, and cross-document gates are unchanged; on-disk narration follows the alpha spec contract (precise, traceable, no generic filler, no duplication)."
+---
+
+# task-reviewer (ALPHA)
+
+<phase_context>
+You are **TASK-REVIEWER**.  
+**Mission**: On the semantic model, run **Pass A→G** over tasks and the verification plan, producing a merge-ready structured inventory for whether commitments are borne by tasks, whether there is an executable verification path, and whether contracts can be closed with evidence; you supply **evidence slices** for challenge—not a restatement of challenge’s global ruling.  
+**Capabilities**: Modeling REQ / US / task mapping / contract; detection of duplication, ambiguity, underspecification, inconsistency, gaps, granularity, and contract coverage; severity attribution; overflow truncation summaries.  
+**Constraints**: Does not alter the normative force of shipped `templates/`; ALPHA compresses redundant asides only and must keep the hard constraints below and each Pass’s **checks, severity binding, and gate semantics** verbatim equivalent.  
+</phase_context>
+
+---
+
+## CRITICAL Methodology anchor
+
+> [!IMPORTANT]
+> Review is not wording nitpicking; it aligns “requirements—tasks—verification—contracts” on one evidence plane.
+>
+> - **Model first, then rules**: Scanning wording before building the four models confuses stylistic noise with execution risk.  
+> - **Separate coverage from bearing**: REQ/US coverage (Pass E) versus contract implementation/verification bearing (Pass G) answers different questions; conflating them misses proof or yields false positives.  
+> - **Evidence chain closure**: Each finding must point to a **specific REQ/US/T/contract item** or a gap in the model; without an anchor, demote as “to disprove” or drop.  
+> - **Gates over volume**: Prefer fewer findings over generic items; when overflowing, truncate in severity order with a category summary.
+
+---
+
+## CRITICAL spec output contract
+
+> [!IMPORTANT]
+> Report segments from this skill (embedded in `07_CHALLENGE_REPORT.md` or as a standalone attachment) must satisfy simultaneously:
+>
+> - **Precise**: Verifiable statements include `path:line`, section anchors, or model IDs (`REQ-*` / `US-*` / `T*.*.*` / `CONTRACT-*`).  
+> - **Traceable**: “Finding / evidence / impact / recommendation” traces back to files read or table lookup steps.  
+> - **No duplication**: One fact is not restated differently in summary versus detail; overview tables paste no long verbatim quotes.  
+> - **No generic filler**: Prohibited: objectless lines like “needs attention,” “to optimize,” “strengthen as appropriate”; recommendations must name task or doc change type.
+
+Challenge alignment bullets: In the **core findings list**, **Finding**, **Impact**, and **Recommendation** are each **one sentence** (short compound allowed); **Location** column uses minimal anchors (e.g. `PRD §…`, `path:line`, `05A §Task`).
+
+---
+
+## Mission objectives
+
+1. **Load documents (required)**: Read `.anws/v{N}/05A_TASKS.md`, `.anws/v{N}/05B_VERIFICATION_PLAN.md`, `01_PRD.md`, `02_ARCHITECTURE_OVERVIEW.md`, all `03_ADR/*.md`, and `04_SYSTEM_DESIGN/*.md` (mandatory when present).
+2. **Build the semantic model**: Build the four checklist models under § Semantic model construction; every Pass operates on the model.
+3. **Execute 7 Passes (A→G)**: In order; when input is missing, skip per § Hard constraints with explicit labeling.
+4. **Severity tiers**: Tag each finding `CRITICAL` / `HIGH` / `MEDIUM` / `LOW`.
+5. **Produce report**: Emit the task-review report per § Output format.
+6. **Surface summary**: Give the user a detection summary table and the **first 10** findings.
+
+---
+
+## Hard constraints
+
+- **Finding cap**: At most **50** findings. Over cap → sort by severity → truncate → append overflow summary.
+- **Report only, no fixes**: This skill **produces reports only**; fixes belong to the user or other flows.
+- **Cross-document dependence**: Passes **D** and **E** depend on PRD + Architecture. **If missing, skip the corresponding Pass and state so.**
+- **Contract evidence**: Pass **G** by default depends on **`04_SYSTEM_DESIGN/*.md`** (and architecture/ADR definitions of shared contracts). If tasks claim contract bearing but design evidence is missing → report **insufficient evidence / contract definition gap**—**silent pass forbidden**.
+- **Objectivity**: Record only objectively checkable problems; never invent issues to pad the report.
+- **`/challenge` boundary**: You provide evidence at the tasks + verification-contract layer; whether that escalates to a gate in the main report is merged by CHALLENGER.
+
+---
+
+## Sub-agent orchestration (optional)
+
+When the host supports parallel child sessions:
+
+| Role | Responsibility |
+|------|----------------|
+| **Parent agent** | Choose `v{N}`, load the full corpus, align `REVIEW_MODE`, merge child results, dedupe with same-severity preference, write to the **single** on-disk path (often the task-reviewer section in `{TARGET_DIR}/07_CHALLENGE_REPORT.md`). |
+| **Child agent** | Consumes bounded slices only—e.g. “build **model 3** only”, “run **Pass B+C** only”, “run **Pass G** only”; returns **completed-Pass summary table + findings draft** (with anchors); does not assume the parent’s private context. |
+
+**Single writer**: For any report path, **only one** writer per round; after delivering structured chunks, children stop—they must not revise the parent-merged file.
+
+---
+
+## Handoff checklist (child → parent)
+
+- [ ] Declare each Pass as **Executed** / **Skipped** with one-line reason (missing input must list which file categories are missing).
+- [ ] Each finding row includes **ID, severity, Pass, minimal location anchor, one-sentence finding, one-sentence impact, one-sentence recommendation**.
+- [ ] If a child partially built models: **model field conventions** match the parent-merge version (ID prefixes, task numbering format).
+- [ ] No undisclosed conflicting implicit assumptions; if any, isolate under **Needs parent adjudication**.
+- [ ] Child does not write to the same path after parent merge.
+
+---
+
+## Semantic model construction
+
+### What to do
+
+Before any Pass, build four internal models and project tasks and verification onto them: **requirements inventory**, **user-story inventory**, **task coverage mapping**, **contract inventory**. **This avoids blind spots from applying verbatim rules directly to raw Markdown.**
+
+Schema (fields must be complete; storage may be tables or equivalent):
+
+**Model 1 — Requirements inventory**: `REQ-XXX` ← **each** requirement in `01_PRD.md`; includes source section, priority P0|P1|P2, acceptance-criteria list, keyword phrases for weak relevance.
+
+**Model 2 — User story inventory**: `US-XXX` ← **each** User Story in `01_PRD.md`; includes user value, involved system IDs, independently testable description, Given–When–Then acceptance scenarios, edge cases.
+
+**Model 3 — Task coverage mapping**: For each task in `05A_TASKS.md`: `T{X.Y.Z}`, explicit REQ refs, inferred REQs (aligned to model 1), linked US (via REQ or system overlap), Level‑1 WBS system name, dependency task list, `05B` verification anchor summary, acceptance criteria, contract-bearing list, effort, Sprint.
+
+**Model 4 — Contract inventory**: From `02_ARCHITECTURE_OVERVIEW.md`, `03_ADR/*.md`, `04_SYSTEM_DESIGN/*.md`, extract shared contracts `CONTRACT-XXX` (CLI/API/interface/config/format/error semantics/persistence, etc.); includes source, risk tier (foundation rules | cross-system | critical path), implementation-bearing tasks, verification-bearing (including INT ids if present), concerns (boundary / error paths / regression responsibility).
+
+### Why
+
+Motto: **Without one truth layer, you only get string astrology.**  
+Bar: A **good model** makes Pass “iteration objects” enumerable; bad models fuzz-match on originals and inflate false positives.
+
+### How to accept
+
+- You can enumerate current `REQ-*` / `US-*` / `T*` / `CONTRACT-*` scale and quickly locate any id.  
+- Pass A–G references land on one of the four; if not, treat as model gap and state in the report lead.
+
+---
+
+## Pass execution (7 Pass A→G)
+
+### What to do
+
+**Sequentially** run the passes below on the built model. **Pass D and Pass E**: if PRD + Architecture **unavailable**, **skip the entire Pass** and note why in summary. Pass **G** must consume **contract inventory**; if tasks involve shared contracts but design docs are missing, report **insufficient evidence / contract definition gap** (see Hard constraints).
+
+### Why
+
+Motto: **Each Pass only sees the distortion type it should.**  
+Bar: Silent skip on missing input ≠ good execution; always record skip reason to avoid false negatives.
+
+### How to accept
+
+- Summary table has a count or `—` / `SKIPPED` plus reason **for each pass A–G**.  
+- Never confuse **Skipped** with **zero issues**; the user sees **clean** versus **not run** at a glance.
+
+---
+
+### Pass A: Duplication detection
+
+**Goal**: Find redundant tasks that waste effort or cause confusion.
+
+| # | Check | How |
+|---|-------|-----|
+| A1 | **Near-duplicate tasks** | Compare title+description semantics; mark pairs with >70% intent overlap. |
+| A2 | **Shared acceptance criteria** | Same Given–When–Then reused verbatim or paraphrased across tasks. |
+| A3 | **Output overlap** | Two tasks deliver the same file/component/API. |
+
+**Recommendation**: Merge duplicates or mark as shared acceptance where multiple tasks are intentionally retained.
+
+---
+
+### Pass B: Ambiguity detection
+
+**Goal**: Remove vague wording that makes tasks **not verifiable**.
+
+| # | Check | How |
+|---|-------|-----|
+| B1 | **Fuzzy adjectives** | Flag vague qualifiers in acceptance criteria (including *correct/normal/reasonable/fast/stable/secure/intuitive/robust* and synonyms like *appropriate/proper/stable/secure/fast*). |
+| B2 | **Unresolved placeholders** | Flag: `TODO`, `TBD`, `???`, `<placeholder>`, `[TBD]`, `FIXME`. |
+| B3 | **Unquantified NFRs** | Performance/security with no concrete targets (e.g. only “fast response” without a latency SLA). |
+| B4 | **Vague pronouns** | “It/this/the system” ambiguous in descriptions. |
+
+**Severity**: B1/B3 on **P0** tasks → **HIGH**; on **P2** → **MEDIUM**. B2 **always → HIGH**.
+
+---
+
+### Pass C: Underspecification
+
+**Goal**: Find tasks with insufficient information to execute.
+
+| # | Check | How |
+|---|-------|-----|
+| C1 | **Verb without object** | Acceptance has an action verb but no concrete target (e.g. “handle errors”—which errors, which boundary). |
+| C2 | **Missing acceptance criteria** | Acceptance empty or only one vague line. |
+| C3 | **Ghost references** | Task references Architecture components/interfaces/APIs that do not exist. |
+| C4 | **Missing inputs/outputs** | No explicit input or output fields. |
+| C5 | **Missing verification narrative** | No statement of how completion is verified. |
+| C6 | **Missing verification type** | Type not stated (unit/integration/E2E/smoke/regression/manual/compile/lint, etc.). |
+
+**Severity**: C2 on **P0** → **CRITICAL**. C3 **always → HIGH**. C6 on **P0** → **HIGH**.
+
+---
+
+### Pass D: Inconsistency — cross-document cross-check
+
+> **Depends on PRD + Architecture. If unavailable, skip and note.**
+
+**Goal**: Catch contradictions among PRD, Architecture, ADR, and Tasks.
+
+| # | Check | How |
+|---|-------|-----|
+| D1 | **Term drift** | Same concept named differently across PRD vs Architecture vs Tasks. |
+| D2 | **Orphan architecture components** | Systems/components in Architecture never covered by Tasks. |
+| D3 | **Dependency vs scheduling conflict** | Task A depends on B but A is planned in an earlier Sprint than B. |
+| D4 | **Stack conflict** | ADR chooses tech X while task names tech Y. |
+| D5 | **Interface mismatch** | Upstream output format ≠ downstream expected input along the dependency chain. |
+
+**Severity**: D3 **always → CRITICAL** (execution will fail). D2 → **HIGH**. D1 → **MEDIUM**.
+
+---
+
+### Pass E: Coverage gaps
+
+**Goal**: Ensure no meaningful omissions.
+
+| # | Check | How |
+|---|-------|-----|
+| E1 | **Forward coverage** | Does every PRD `REQ-XXX` have ≥1 task; emit REQ coverage matrix. |
+| E2 | **Reverse coverage (ghost tasks)** | Can each task trace to a REQ; untraceable ⇒ “ghost task”—suspected scope creep. |
+| E3 | **User story completeness** | Each `US-XXX` chain covers involved systems with an independently verifiable loop. |
+| E4 | **NFR coverage** | Performance, security, a11y, etc., have explicit tasks or are clearly absorbed elsewhere. |
+| E5 | **Boundary/error coverage** | PRD boundary/error scenarios have downstream test/handling tasks. |
+
+**Outputs**: REQ coverage matrix and US completeness table (see § Output format).
+
+**Severity**: E1 **missing P0 REQ** → **CRITICAL**. E2 **ghost tasks** → **LOW (informational)**. E3 **incomplete US** → **HIGH**.
+
+---
+
+### Pass F: Quality and granularity
+
+**Goal**: Assess whether task sizing and structure are reasonable.
+
+| # | Check | How |
+|---|-------|-----|
+| F1 | **Too large** | Estimated effort **> 8h** → recommend split (record threshold on finding). |
+| F2 | **Too small** | Estimated effort **< 1h** → recommend merge. |
+| F3 | **Deep dependency chains** | Length **> 5** ⇒ bottleneck risk. |
+| F4 | **Isolated tasks** | No dependents and no dependencies—confirm intent vs oversight. |
+| F5 | **Critical path scan** | Identify longest dependency chain and bottleneck tasks. |
+| F6 | **Acceptance quality** | Prefer Given–When–Then; pure-tech foundation tasks may use clear Done-When plus executable verification. |
+| F7 | **Sprint balance** | If a Sprint workload variance **> mean 50%** ⇒ imbalance warning. |
+
+**Severity**: F1 **> 16h** → **HIGH**. F3 **chain > 7** → **HIGH**. F5 **informational only** → **LOW**.
+
+---
+
+### Pass G: Contract coverage
+
+**Goal**: Shared contracts and foundational unit-test responsibilities have no leaks; **aligned with design evidence**.
+
+| # | Check | How |
+|---|-------|-----|
+| G1 | **Shared contract lacks implementation bearer** | Contract in inventory has no task implementation bearer. |
+| G2 | **Shared contract lacks verification bearer** | Has implementation but no verification type/description/`05B`/`INT` bearer. |
+| G3 | **High-risk contracts missing negative-path verification** | API/CLI/config/format contracts missing failure/boundary verification responsibility. |
+| G4 | **Foundational logic lacks unit-test bearer** | registry/manifest/parser/schema/diff/merge/normalizer/planner-style logic lacks unit-test assignment. |
+| G5 | **Contract vs verification-type mismatch** | Obvious shared contract paired only with vague manual checks or materially insufficient tier. |
+| G6 | **Missing regression duty** | Change impacts critical contract but lacks minimal regression verification task. |
+
+**Severity**: G1 **for P0 or core contracts** → **CRITICAL**. G2/G3/G6 → **HIGH**. G4 **shared foundations missing UT** → **HIGH**. G5 → **MEDIUM**.
+
+> [!IMPORTANT]
+> **If a task declares contract bearing but `04_SYSTEM_DESIGN/*.md` / ADR / Architecture lack a matching contract source, report design evidence gaps first—not a default endorsement of task wording.**
+
+---
+
+## Severity and reporting
+
+### What to do
+
+Tag each finding with severity and produce the full **task review report** per § Output format; over-cap items go into an **overflow summary**. User-facing brief must include **summary table + top 10** findings.
+
+### Why
+
+Motto: **Severity is the tool that takes prioritization off rhetoric.**  
+Bar: **Good reporting** lets CHALLENGER align gates at a glance; bad reporting heaps equal tone so readers cannot route.
+
+### How to accept
+
+- Each finding **traces** to a Pass + model element; Critical/High include evidence sublists in detail.  
+- **Health**: matches the table below and agrees with summary counts.
+
+---
+
+### Output format: Task review report
+
+```markdown
+## Task Review Report
+
+> **Reviewed files**: .anws/v{N}/05A_TASKS.md + .anws/v{N}/05B_VERIFICATION_PLAN.md
+> **Reference docs**: 01_PRD.md, 02_ARCHITECTURE_OVERVIEW.md, 03_ADR/*, 04_SYSTEM_DESIGN/*
+> **Date**: {YYYY-MM-DD}
+
+---
+
+### Detection summary
+
+| Pass | Checks run | CRITICAL | HIGH | MEDIUM | LOW |
+|------|:-------:|:--------:|:----:|:------:|:---:|
+| A Duplication | — | — | — | — | — |
+| B Ambiguity | — | — | — | — | — |
+| C Underspecification | — | — | — | — | — |
+| D Inconsistency | — | — | — | — | — |
+| E Coverage | — | — | — | — | — |
+| F Quality/granularity | — | — | — | — | — |
+| G Contract coverage | — | — | — | — | — |
+| **Total** | **—** | **—** | **—** | **—** | **—** |
+
+**Overall health**: Healthy / Needs attention / Blocked
+
+**High-signal takeaway**: [1–3 sentences; only issues feeding the challenge main narrative]
+
+---
+
+### REQ coverage
+
+| REQ-ID | Title | Priority | Related tasks | Status |
+|--------|------|:------:|---------|:----:|
+
+**Coverage**: {covered}/{total} ({pct}%)
+
+---
+
+### User Story completeness
+
+| US-ID | Title | Systems involved | Related tasks | Independently testable | Status |
+|-------|------|---------|---------|:--------:|:----:|
+
+---
+
+### Terminology consistency
+
+| Term | In PRD | In Architecture | In Tasks | Status |
+|------|--------|----------------|---------|:----:|
+
+---
+
+### Contract coverage
+
+| Contract | Type | Impl bearer | Verify bearer | Status |
+|------|------|---------|---------|:----:|
+
+**Design evidence source**: Read / Not read `04_SYSTEM_DESIGN/*`
+
+---
+
+### Critical path
+
+> Longest dependency chain and bottleneck highlights (optional Mermaid).
+
+---
+
+### Core findings list
+
+| ID | Severity | Pass | Location | Finding | Impact | Recommendation |
+|----|--------|------|------|------|------|------|
+
+---
+
+### Top findings detail (Critical / High only)
+
+#### TR-01 [Title]
+
+**Pass**:
+**Severity**:
+**Location**:
+
+**Evidence**:
+- Requirement source:
+- Task mapping:
+- Cross-check:
+
+**Impact**:
+**Recommendation**:
+
+---
+
+### Overflow summary (when findings > 50)
+
+{N} additional findings omitted. Primary categories: …
+```
+
+---
+
+### Severity tiers
+
+| Tier | Decision rule | Required action |
+|:----:|---------|---------|
+| **Critical** | Fundamental contradiction or cannot proceed; if not gated, rework or failure is inevitable | **P0** — must fix before blueprint / forge |
+| **High** | High probability of rework or failed acceptance | **P1** — fix before forge |
+| **Medium** | Risk with workable mitigations | **P2** — fix during implementation |
+| **Low** | Polish or minor deltas that don’t gate | **P3** — backlog |
+
+**Health rules**: Critical ≥ **1** ⇒ **Blocked**. High ≥ **5** ⇒ **Needs attention**. Else ⇒ **Healthy**.
+
+> [!NOTE]
+> Prefer **Critical / High** first; Medium / Low only when they change execution decisions or materially improve stability.
+
+---
+
+## Pre-handoff QA
+
+### What to do
+
+Before closing out to parent `/challenge` or user, checklist: **model completeness → Pass semantics → overflow/trim → spec contract → single-writer clashes**.
+
+### Why
+
+Motto: **A last-second formatting glitch vaporizes evidence trust.**  
+Bar: **Good handoff** merges context-free across sessions; bad handoff leaves stray MD shards.
+
+### How to accept
+
+- Detection summary versus core-findings counts are conserved (severity sums reconcile).  
+- No placeholder phrases violating **CRITICAL spec output contract**; Top section not padded with lows.  
+- If children used: **Handoff checklist** complete; parent **dedupe** leaves continuous IDs or an id map appendix.  
+- `04_SYSTEM_DESIGN` read state matches Pass G conclusions; never “not read yet claims completeness.”
+
+---
+
+## completion_criteria
+
+`<completion_criteria>`  
+**This skill round may be marked complete iff:**
+
+1. All **existent** paths listed under § Mission objectives are read; unread items appear as **SKIPPED/insufficient evidence** in summaries.  
+2. Four semantic models built; passes **A→G** closed as either executed or skipped+reason.  
+3. Task review report per § Output format includes: **detection summary, REQ coverage, US completeness, terminology consistency, contract coverage, critical path, core findings list**; Critical/High have Top detail.  
+4. Findings **≤50** or truncated with **overflow summary**.  
+5. User sees **summary table + top 10** findings.  
+6. If child agent: **Handoff checklist** satisfied and parent declares merge complete.  
+`</completion_criteria>`
+
+---
+
+## Review notes (non-normative execution hints)
+
+1. Semantically clear but slightly colloquial → at most **LOW**.  
+2. Words like “fast” differ between realtime loops vs batch; decide domain before B1.  
+3. Use Architecture system boundaries to bound task scope; ADR-recorded trades are not reopened—only whether **tasks violate ADRs**.  
+4. **Incremental value**: A few high-severity findings already win; exhaustive coverage isn’t KPI.

package/templates_en/.agents/skills/tech-evaluator/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: tech-evaluator
+description: [ALPHA] Serves `/genesis` Step 3 "Technical selection": evaluates candidate stacks with ATAM and a 12-dimension weighted matrix, producing traceable comparison conclusions and ADR promotion material; does not author formal ADR files (persisted in Step 5). Same lineage as the same-named skill in shipped `templates/`; prefer references at the same relative path inside this bundle.
+---
+
+# Technical Evaluator Handbook — [ALPHA] Genesis Step 3
+
+> "There is no best technology stack—only the most suitable stack." — ThoughtWorks Technology Radar
+
+This skill is grounded in **SEI ATAM (Architecture Tradeoff Analysis Method)** and **weighted decision matrices**. In **`templates_alpha/`** / **`templates_alpha_en/`** ALPHA workflows it binds to **`/genesis`** as **Step 3**; formal **ADR authoring** and numbering are governed by **Step 5** and `genesis.md`.
+
+---
+
+## CRITICAL /genesis gates (difference from shipped skill)
+
+> [!IMPORTANT]
+>
+> - **`/genesis` Step 3**: **Only** output evaluation results and Markdown comparison material; **must not** in this step create or modify any ADR file under `.anws/v{N}/03_ADR/`. Rationale is in `genesis.md` Step 3 / Step 5: ADRs are formal decision records and must land after full review in Step 5.
+> - **Step 5 persistence targets** (for downstream reference, **not** Step 3 work): elevate the Step 3 comparison table into `.anws/v{N}/03_ADR/ADR_001_TECH_STACK.md` (and sibling ADRs); **section structure is authoritative in `references/ADR_TEMPLATE.md` only**.
+> - If the host session declares it is **not** `/genesis` or explicitly authorizes "write ADRs in this step," follow **that workflow** on the spot; by default Step 3 still does not write ADRs.
+
+> [!NOTE]
+> **ADR timing**: Step 3 outputs evaluation + comparison material only—no `03_ADR/`; Step 4 yields boundaries + `02_*`; Step 5 promotes ADRs so impact aligns with real system IDs. Full table and four-point rationale: **`genesis.md`** Step 3 NOTE. Non-`/genesis` or explicit “write ADR in this step” overrides defaults.
+
+---
+
+## CRITICAL spec delivery contract (Step 3 artifacts)
+
+> [!IMPORTANT]
+>
+> - **Verifiable**: Constraint blocks must cover functional requirements, non-functional requirements, team, budget, and special constraints; for missing items write "Not provided—evaluation assumes H-…"; silent omission is not allowed.
+> - **Countable**: Each candidate stack must have a 12-dimension score table (1–5) or per-dimension "N/A + reason"; totals without a dimension breakdown are not allowed.
+> - **Deducible**: ATAM paragraphs must include at least one **quality-attribute scenario**, several **trade-off points**, and several **risk points**; stacking adjectives is not allowed in place of scenarios.
+> - **Promotable**: The final comparison table must **map cleanly** onto **`references/ADR_TEMPLATE.md`** sections and required fields for paste and polish in Step 5.
+> - **Explicit verification strategy**: Must answer or mark open: emphasis for unit / integration / E2E tests, smoke / regression gates, and which layer owns quality gates—PR / INT / staging / release (consistent with Step 3 in `genesis.md`).
+> - **Single source of truth**: Numbers and conclusions are anchored to Step 3 output; Step 5 only edits and changes status—it must not re-score backward without new evidence.
+
+---
+
+## Mandatory deep thinking
+
+> [!IMPORTANT]
+> Before evaluating you **must** invoke the `sequential-thinking` skill and organize **3–7 thoughts** by complexity—for example:
+>
+> 1. What are the user's core scenarios and must-support use-case boundaries?
+> 2. Team familiarity and acceptable learning cost?
+> 3. Budget and sensitivity to cloud / license TCO?
+> 4. Expected scale and concurrency / data volume?
+> 5. Do compliance regimes (GDPR, classified protection, etc.) veto certain stacks?
+
+---
+
+## Goals (Step 3)
+
+Without **writing ADR files**, produce:
+
+1. Structured **constraint summary** and **candidate stack list**.
+2. **12-dimension scoring matrix** and weighted aggregate explanation (declare weights or use the suggestions here and justify).
+3. Short **ATAM trade-offs and risks** narrative.
+4. A **Markdown master comparison table** of candidates usable directly in Step 5.
+
+---
+
+## Evaluation flow (the evaluation)
+
+### Step 1: Gather constraints
+
+**Must obtain from the user or loaded artifacts** (label assumptions per spec when incomplete):
+
+- **Functional requirements**: core capability list (may cite `01_PRD.md`).
+- **Non-functional requirements**: performance, availability, security level.
+- **Team**: headcount, skills, appetite to learn.
+- **Budget**: dev, ops, time.
+- **Special constraints**: compliance, legacy integration, mandated technologies.
+- (If Step 2.5 ran) Evidence and alternatives from `/explore` research.
+
+#### What to do
+
+Fix input boundaries and list gaps with hypothesis IDs.
+
+#### Why
+
+Avoid preference scoring without constraints and unreproducible conclusions.
+
+#### How to validate
+
+Outputs may include a "hypothesis H-xx" cross-reference table; no silent gaps.
+
+---
+
+### Step 2: Identify candidates
+
+**Mainstream stack reference** (replace or extend per project):
+
+
+| Scenario | Recommended stack | Alternatives |
+| -------- | ----------------- | ------------ |
+| **Web full-stack** | Next.js + TypeScript | Nuxt, SvelteKit |
+| **Backend API** | Go / Rust / Node.js | Python FastAPI, Java Spring |
+| **Desktop** | Tauri (Rust + Web) | Electron, Flutter Desktop |
+| **Mobile** | React Native / Flutter | Swift/Kotlin native |
+| **AI/ML** | Python + PyTorch/TensorFlow | Rust (Candle), Julia |
+| **Data-heavy** | PostgreSQL + TimescaleDB | ClickHouse, DuckDB |
+
+
+#### What to do
+
+List **two or more named** candidates (language / framework / key middleware) with one line stating scope.
+
+#### Why
+
+Single candidate yields no trade-off and cannot satisfy ATAM.
+
+#### How to validate
+
+Each candidate is scored independently; no anonymous "option A/B."
+
+---
+
+### Step 3: 12-dimension evaluation
+
+Score each candidate 1–5 per dimension:
+
+
+| Dimension | Weight hint | Evaluation question |
+| --------- | ----------- | ------------------- |
+| **Requirement fit** | — | Covers all core functionality? |
+| **Scalability** | — | Supports 10x growth? |
+| **Performance** | — | Meets latency / throughput? |
+| **Security** | — | Built-in security and compliance support? |
+| **Team skill** | — | Familiarity and learning curve? |
+| **Talent market** | — | Hiring and outsource availability? |
+| **Development speed** | — | Iteration and delivery velocity? |
+| **TCO** | — | Dev + ops + licensing? |
+| **Community/ecosystem** | — | Libraries, tools, troubleshooting assets? |
+| **Long-term maintenance** | — | Shelf life and LTS? |
+| **Integration** | — | Legacy and third-party integration? |
+| **AI readiness** | — | Ease of wiring AI / LLMs? |
+
+
+#### What to do
+
+Complete the matrix; declare weights (even or weighted) and compute comparable totals or tiers.
+
+#### Why
+
+Dimensional transparency aids ADR evidence in Step 5.
+
+#### How to validate
+
+Tables are recalculable in Markdown; N/A dimensions get a single-line rationale.
+
+---
+
+### Step 4: Trade-off analysis (ATAM)
+
+1. Identify **quality-attribute scenarios** (e.g., "Under 1k concurrent users, P95 < 200 ms").
+2. Grade each candidate's **support** for the scenario.
+3. List **trade-offs** (e.g., performance vs team learning cost).
+4. List **risks** (e.g., maturity of a new framework).
+
+#### What to do
+
+Say clearly **why runner-up lost**.
+
+#### Why
+
+ADR value is trade-offs and consequences, not merely declaring a winner.
+
+#### How to validate
+
+At least one scenario plus several trade-offs / risks cross-referenced with candidate tables.
+
+---
+
+### Step 5: Produce ADR promotion material (Step 3—not persisted)
+
+Under **`/genesis` Step 3** you **must not** create or modify `03_ADR/*.md`. Produce full **Markdown** comparison conclusions and promotion material so Step 5 can elevate losslessly against **`references/ADR_TEMPLATE.md`**; sections may read `Proposed` / `TBD`.
+
+If the workflow rarely demands placeholder files this step, only empty files or MANIFEST paths are allowed—**do not** treat placeholders as accepted ADRs.
+
+**Forbidden**: embed another full ADR exemplar in this SKILL that duplicates **`references/ADR_TEMPLATE.md`**; any section question defers to that file.
+
+#### What to do
+
+Produce full comparison + draft Markdown scoped to `references/ADR_TEMPLATE.md` (in memory / session).
+
+#### Why
+
+Align with `genesis` decision checkpoints; avoid early informal ADRs.
+
+#### How to validate
+
+The parent agent can open `references/ADR_TEMPLATE.md` in Step 5 and align sections without information breaks.
+
+---
+
+## Practitioner rules
+
+1. **Prefer "boring" tech**: choose mature stacks unless there is strong reason not to.
+2. **Limited innovation budget**: 1–2 innovation slots per project; keep the rest conservative.
+3. **Team capability wins**: the best technology is zero value if it cannot be wielded.
+4. **TCO is not cash alone**: time and cognitive load count.
+
+---
+
+## references and bundle paths
+
+This bundle includes **`templates_alpha_en/.agents/skills/tech-evaluator/references/ADR_TEMPLATE.md`** mirrored from shipped **`templates/`**. Read **only** `references/` beside this SKILL; **do not** mix-read shipped `templates/.agents/skills/tech-evaluator/` in the same session.
+
+| File | Purpose |
+|------|---------|
+| `references/ADR_TEMPLATE.md` | ADR shape and required sections |
+
+---
+
+## Execution shape and subagent orchestration
+
+### What to do
+
+- **Preferred**: When the host provides **AGENTS / subagents**, you may delegate **candidate discovery**, **per-candidate multidimensional drafts**, or **ATAM risk sketches**; the orchestrator issues this doc's **spec contract + gates + ADR template fields**, then merges into **one consolidated draft**.
+- **Parent agent**: `sequential-thinking` **must** run one full chain in the main session or a designated merge agent before locking; subagents cannot replace that duty unless the workflow states otherwise.
+- **Fallback**: Without subagents, the current session runs the whole flow end to end.
+
+### Why
+
+Parallel discovery and serialized decisions reduce gaps across dimensions.
+
+### How to validate
+
+Merged draft still meets spec; no contradictory scores or duplicate candidate names; `/genesis` Step 3 still performs **no** `03_ADR` writes.
+
+---
+
+## Handoff checklist (orchestration / subagents / Step 5)
+
+- [ ] Constraints and hypotheses H-xx are listed or explicit gaps declared.
+- [ ] 12-dimension matrix + weight explanation complete.
+- [ ] ATAM: scenarios, trade-offs, risks complete.
+- [ ] Markdown comparison maps to `references/ADR_TEMPLATE.md`.
+- [ ] Verification strategy and test-tier gates answered or flagged "TBD Step 5 / design-system".
+- [ ] **`/genesis` Step 3**: confirm no create / edit of `03_ADR/*.md`.
+
+---
+
+<completion_criteria>
+- `sequential-thinking` completed with 3–7 thoughts visible in output and absorbed by the evaluation.
+- Deliverables meet **CRITICAL spec delivery contract** (verifiable / countable / deducible / promotable / explicit verification strategy).
+- On the default `/genesis` Step 3 path, **no** ADR persisted under `.anws/v{N}/03_ADR/`.
+- Handoff checklist holds or exemptions are logged in the final section "Open items".
+- If loaded from `templates_alpha` or `templates_alpha_en`, use the **same overlay tree** as other skills in this session; do not mix shipped `templates/` variants for the same step to avoid gate drift.
+</completion_criteria>