diff --git a/plugins/ultraplan-local/templates/ultrareview-template.md b/plugins/ultraplan-local/templates/ultrareview-template.md new file mode 100644 index 0000000..24d07a3 --- /dev/null +++ b/plugins/ultraplan-local/templates/ultrareview-template.md @@ -0,0 +1,138 @@ +--- +type: ultrareview +review_version: "1.0" +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} +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 /ultraplan-local" +- 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. + +## 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 `/ultraplan-local --brief review.md`, the planner will consume +the BLOCKER + MAJOR findings as plan goals (their `recommended_action` +becomes the step intent). MINOR + SUGGESTION are skipped for v1.0 +plan-input. + +```json +{ + "verdict": "BLOCK", + "counts": { "BLOCKER": 1, "MAJOR": 1, "MINOR": 1, "SUGGESTION": 1 }, + "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 ..." + } + ] +} +```