# Tech Evaluator

> Technical Evaluator Handbook — Genesis Step 3

- Skill: `haaaiawd/tech-evaluator-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add haaaiawd/tech-evaluator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/tech-evaluator-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/haaaiawd/tech-evaluator-2

---


# Technical Evaluator Handbook — 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 **`/genesis`** it binds as **Step 3**; formal **ADR authoring** and numbering are governed by **Step 5** and `genesis.md`.

---

## CRITICAL /genesis gates (this track only)

> [!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 ships **`references/ADR_TEMPLATE.md`** beside this SKILL. Read **only** `references/` next to this SKILL.

| 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".
- Use the workspace **`.agents/skills/`** tree consistently with other skills in the session.
</completion_criteria>

