A reviewer that stays silent never counts as a pass
Every reviewer must fill in a standard results form, not just write prose. If a reviewer skips the form, or blocks the work without listing a single problem, TLM Forge counts that as a CRITICAL instead of a quiet pass. The decision comes from counting serious problems, not from the reviewer's tone.
How to use it
/tlmforge:buildYou do not run this yourself. It applies to every reviewer in the plan review (Stage 3) and the final review (Stage 5) on Medium and Deep tasks inside /tlmforge:build. The form requirement is written into each reviewer's instructions.
Words you will see on this page
- JSON verdict
- A small structured file where a reviewer records its overall call and every finding.
- Severity
- How serious a finding is: critical, high, medium, low, or nit (a style nitpick).
- Converged
- Done: no real CRITICALs and no process CRITICALs are left.
- Meta CRITICAL
- A CRITICAL about the review itself, such as a missing file, rather than about your code.
- Synthetic finding
- A placeholder finding the script adds when a reviewer's form is missing or empty.
- Stage 3 / Stage 5
- The plan review before coding, and the final review of the finished change.
Severity levels: what they mean and what happens
| Severity | What it means | What happens to it |
|---|---|---|
| CRITICAL | Blocks shipping. The only level this check counts. | Fixed right away, failing test first. If it means changing already committed work, is a flaw in the plan, or cannot be fixed, you decide. |
| HIGH | Must fix before launch | Fixed, failing test first, before moving on. If it means changing already committed work, you decide. |
| MEDIUM | Should fix | Goes on the leftover list in STATUS.md. Fixed only if free inside a CRITICAL or HIGH fix in the same file. |
| LOW | Nice to fix | Goes on the leftover list. Fixed during the build only if trivial and in a file already being changed. |
How each reviewer's form is counted
| What the reviewer did | How it is counted |
|---|---|
| Saved a valid form with findings | Each CRITICAL in it counts as a real CRITICAL |
| Saved no form | A placeholder process CRITICAL is added |
| Blocked the work but listed nothing | A placeholder process CRITICAL is added |
| Approved with no findings | Allowed, but logged as a warning |
| Marked skipped (absent, not failed) | Left out of the count, named in the summary |
What it does
Besides its written report, each reviewer saves a JSON verdict (a small structured file) that must match a fixed format. It holds an overall verdict, from approve to do not ship, and a list of findings. Each finding has a severity, a category such as security or data loss, the file it is about and a short description. A CRITICAL finding must also include a concrete suggested fix. Final review files also record the exact commit reviewed.
A small script, check_convergence.py, reads these files. If an expected reviewer saved no file, it adds a placeholder CRITICAL saying so. If a reviewer blocks the work but lists no findings, that also becomes a CRITICAL, because a block with nothing behind it is a broken review. An approval with no findings is allowed but logged as a warning. A reviewer marked skipped, meaning absent rather than failed, is left out of the count and named in the summary.
Real CRITICALs (about your code) and process CRITICALs (about the review machinery, labeled meta) are counted separately. The review has converged only when both are zero. The script caps rounds at three by default and, past the cap, says whether real problems remain, only process problems, or both. TLM Forge runs one plan review round and at most two final review rounds, so the cap is a backstop. This is a rule TLM Forge tells Claude to apply, not a built-in block.
How it works, step by step
Ask every reviewer for the form
Each plan review and final review prompt says where to save the JSON verdict, its format and the severity scale.
Reviewers save two files
A written report for people to read, and a JSON verdict for the script to count.
Fill in the gaps
A missing form, or a block with no findings, is replaced by a placeholder CRITICAL that names what went wrong and how to fix it.
Count real and process CRITICALs
CRITICAL findings are added up across reviewers, with process (meta) ones kept separate. Skipped reviewers are left out but stay listed.
Decide on numbers, not words
Zero of both means converged. Anything else goes to sorting or the fix round, and past the cap the script says whether the problem is your code or the review setup.
What it looks like
What the script adds when the tester saved no JSON verdict: a placeholder CRITICAL labeled meta, with the fix "re-launch the tester". The last line is the status it prints; the real CRITICAL there came from another reviewer. From check_convergence.py, with punctuation simplified.
{"reviewer": "tester", "schema_version": "1.0", "iteration": 1,
"status": "error", "verdict": "needs_revision",
"findings": [{"severity": "critical", "category": "meta",
"file": "architecture", "line": null,
"finding": "reviewer_json_missing: no JSON sidecar for tester at iteration 1",
"suggested_fix": "Re-launch tester with explicit JSON-output instructions."}]}
Iteration 1 of 3: not converged. 1 real CRITICAL, 1 meta CRITICAL.Why it is better
Silence is not approval
Without this rule, a reviewer that crashed or timed out could look like one with nothing to say. With TLM Forge, a missing form shows up as a CRITICAL.
Lazy reviews get caught
Without a form, a reviewer can reject work without saying why. With TLM Forge, a block with no listed problem is flagged as broken, and an empty approval is logged for a person to check.
Process problems stay separate
Without the split, a broken reviewer launch could hide or inflate your defect count. With TLM Forge, problems with the review machinery are counted apart from problems in your code.
Severity, not tone, decides
Without a fixed form, a strongly worded approval could outweigh a listed problem. With TLM Forge, the decision counts each finding's severity; the overall verdict is only for people to read.
Good to know
- This is a rule TLM Forge tells Claude to apply, not a built-in block. The built-in hard stop after the final review is the commit lock, which reads the reviewed commit from these same files.
- Only CRITICAL findings count toward convergence. HIGH findings are still handled: sorted during the build and fixed in the final fix round.
- A reviewer marked skipped (absent, not failed) is left out of the count but always named in the summary, never silently dropped.
- The script expects a set list of reviewers for each stage: the plan reviewers at Stage 3 and the final reviewers at Stage 5, plus the UX reviewer only when UI is in scope.