# Task Reviewer

> 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 output-contract plus this skill's gates.

- Skill: `haaaiawd/task-reviewer-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add haaaiawd/task-reviewer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/task-reviewer-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/haaaiawd/task-reviewer-2

---


# task-reviewer
<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**: Edits may compress redundant asides only; keep the hard constraints below and each Pass’s **checks, severity binding, and gate semantics** verbatim equivalent to this SKILL body.
</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]
> 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 adds that every finding must map to `REQ-*` / `US-*` / `T*.*.*` / `CONTRACT-*` or a concrete `path:line` / section anchor.

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.