Task Reviewer

task-reviewer

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:

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.

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.

Severity: B1/B3 on P0 tasks → HIGH; on P2 → MEDIUM. B2 always → HIGH.

Pass C: Underspecification

Goal: Find tasks with insufficient information to execute.

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.

Severity: D3 always → CRITICAL (execution will fail). D2 → HIGH. D1 → MEDIUM.

Pass E: Coverage gaps

Goal: Ensure no meaningful omissions.

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.

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.

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

## 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

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.