voyage/templates/trekreview-template.md

type	review_version	created	task	slug	project_dir	brief_path	scope_sha_start	scope_sha_end	reviewed_files_count	verdict	findings
trekreview	1.1	YYYY-MM-DD	{Task description from brief.md}	project-slug	.claude/projects/{YYYY-MM-DD}-{slug}/	.claude/projects/{YYYY-MM-DD}-{slug}/brief.md	sha-from-progress.json/session_start_sha-OR-null-if-mtime-fallback	sha-of-HEAD-at-review-time	N	BLOCK	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.

{
  "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 ..."
    }
  ]
}