voyage/templates/trekreview-template.md

---
type: trekreview
review_version: "1.1"
created: {YYYY-MM-DD}
task: "{Task description from brief.md}"
slug: {project-slug}
project_dir: .claude/projects/{YYYY-MM-DD}-{slug}/
brief_path: .claude/projects/{YYYY-MM-DD}-{slug}/brief.md
scope_sha_start: {sha-from-progress.json/session_start_sha-OR-null-if-mtime-fallback}
scope_sha_end: {sha-of-HEAD-at-review-time}
reviewed_files_count: {N}
verdict: BLOCK
findings:
  - 0123456789abcdef0123456789abcdef01234567
  - fedcba9876543210fedcba9876543210fedcba98
---

# Review: {Task description}

## Executive Summary

Two-to-four sentences: how was the brief honored, what is the verdict
(BLOCK / WARN / ALLOW), and what is the most important finding the user
should look at first.

## Coverage

| File | Treatment | Reason |
|------|-----------|--------|
| lib/foo.mjs | deep-review | matched deep-review pattern |
| lib/bar.mjs | summary-only | low-risk, no test patterns matched |
| dist/bundle.js | skip | matches generated-file pattern |
| commands/baz.md `[uncommitted]` | deep-review | working-tree change since session_start_sha |

> **`[uncommitted]` annotation** appears in the treatment column for files
> in the working tree (uncommitted at review time). This is a brief-level
> contract — see `brief.md` Assumptions section.

## Findings (BLOCKER)

### {finding-id-1-40-char-hex}

- file: lib/foo.mjs
- line: 42
- rule_key: BROKEN_SUCCESS_CRITERION
- brief_ref: SC3 — "review.md is parseable as input to /trekplan"
- title: Plan-validator rejects review.md when source_findings is flow-style
- detail: The validator at lib/validators/plan-validator.mjs:N reads
  `source_findings` via parseDocument(), which does not support flow-style
  YAML arrays. The fixture review-run-A.md uses flow-style — Handover 6
  is broken end-to-end.
- recommended_action: Update template to use block-style YAML, regenerate
  fixtures, add explicit test in tests/lib/source-findings.test.mjs.

## Findings (MAJOR)

### {finding-id-2-40-char-hex}

- file: agents/code-correctness-reviewer.md
- line: 34
- rule_key: MISSING_BRIEF_REF
- brief_ref: SC1 — "Every BLOCKER/MAJOR finding has rationale_anchor"
- title: Agent prompt does not require brief_ref in output JSON
- detail: The trailing JSON block in the agent prompt does not list
  brief_ref as a required field. Findings emitted by this agent will fail
  review-validator strict mode.
- recommended_action: Add `brief_ref` to the required-fields list in the
  prompt's JSON template.

## Findings (MINOR)

### {finding-id-3-40-char-hex}

- file: lib/parsers/finding-id.mjs
- line: 18
- rule_key: MISSING_ERROR_HANDLING
- brief_ref: NFR — "Token budget honesty"
- title: TypeError thrown without surrounding context
- detail: When called with bad input, throws bare TypeError. Caller has no
  way to know which field was malformed — error message is informative but
  the error itself has no `cause` chain.
- recommended_action: Optional improvement: wrap error.cause with the
  composite input that caused the throw.

## Findings (SUGGESTION)

### {finding-id-4-40-char-hex}

- file: README.md
- line: 24
- rule_key: PLACEHOLDER_IN_CODE
- brief_ref: Constraint — "Path-guard respect"
- title: TODO comment about cookie path
- detail: README mentions a TODO about cookie regeneration. Not a code
  bug but worth noting for v1.1 cleanup.
- recommended_action: Track in TODO.md if not already.

## Declined to Judge

None.

Trimmed: 0

> One line per finding the coordinator set aside without ruling on it
> (`file:line RULE_KEY — reason`), then `Trimmed: N` — MINOR/SUGGESTION text
> cut, findings kept. No finding is struck for length.

## Remediation Steps

### Step R1: Update the template to use block-style YAML for source_findings

- **Files:** `lib/foo.mjs`
- **Source finding:** `0123456789abcdef0123456789abcdef01234567`
- **Test first:** a test in `tests/lib/source-findings.test.mjs` that feeds a
  flow-style `source_findings` and fails today
- **Verify:** re-run `/trekreview` → finding `0123456789abcdef0123456789abcdef01234567` absent
- **On failure:** escalate — the finding needs the operator, not improvisation

> One numbered step per BLOCKER (required when there is one), so Handover 6
> can append it to a plan unchanged.

## Remediation Summary

- 1 BLOCKER → must address before next plan iteration
- 1 MAJOR → should address before next plan iteration
- 1 MINOR → nice-to-have for v1.1
- 1 SUGGESTION → log and move on

If running `/trekplan --brief review.md`, the planner will consume
the BLOCKER + MAJOR findings as plan goals (their `recommended_action`
becomes the step intent; each BLOCKER's `## Remediation Steps` entry is
ready to append as a plan step). MINOR + SUGGESTION are skipped for
plan-input.

```json
{
  "verdict": "BLOCK",
  "counts": { "BLOCKER": 1, "MAJOR": 1, "MINOR": 1, "SUGGESTION": 1 },
  "allow_blocked_by": [],
  "declined_to_judge": [],
  "trimmed": 0,
  "findings": [
    {
      "id": "0123456789abcdef0123456789abcdef01234567",
      "severity": "BLOCKER",
      "rule_key": "BROKEN_SUCCESS_CRITERION",
      "file": "lib/foo.mjs",
      "line": 42,
      "brief_ref": "SC3",
      "title": "Plan-validator rejects review.md when source_findings is flow-style",
      "detail": "The validator ...",
      "recommended_action": "Update template to use block-style YAML ..."
    },
    {
      "id": "fedcba9876543210fedcba9876543210fedcba98",
      "severity": "MAJOR",
      "rule_key": "MISSING_BRIEF_REF",
      "file": "agents/code-correctness-reviewer.md",
      "line": 34,
      "brief_ref": "SC1",
      "title": "Agent prompt does not require brief_ref in output JSON",
      "detail": "The trailing JSON block ...",
      "recommended_action": "Add brief_ref to the required-fields list ..."
    }
  ]
}
```