trace-first-starter

HL — TFW-8: Reviewer Role and Workflow

Date: 2026-03-12 Author: Coordinator (AI) Status: 🔵 HL — Awaiting review

1. Vision

Executor agents (especially low-cost models) self-review their own work — writing REVIEW files without being asked. This defeats the entire purpose of review as a quality gate. The root cause is structural: TFW v3 doesn’t treat review as a first-class role-locked activity.

“Review must be a separate act by a separate agent. Self-review is not review.”

2. As-Is — Root Cause Analysis

2.1 What’s broken

# Problem Location Impact
P1 handoff.md combines executor (Phases 1-3) and reviewer (Phase 4) in one file .tfw/workflows/handoff.md Executor reads the whole file, sees review instructions, and continues into Phase 4
P2 Role Lock table says “REVIEW files can be written by any role” .tfw/conventions.md §15 Explicitly permits executor self-review
P3 No Reviewer role exists .tfw/glossary.md §Roles Review is a “phase” of Coordinator, not a distinct identity
P4 No dedicated /tfw-review workflow .agent/workflows/ No clear entry point for “I want to review an RF”
P5 Phase 4 of handoff.md says “coordinator (original architect or user)” .tfw/workflows/handoff.md L101 Ambiguous — who exactly reviews?

2.2 What works well

# Good aspect Why keep it
G1 REVIEW template is solid 9-point checklist, verdict system, tech debt collection all work
G2 Tech debt pipeline works Observations → REVIEW triage → TECH_DEBT.md is proven
G3 Status flow has 🔍 REV The status exists, just needs enforcement
G4 Role Lock concept is sound Just needs correct application to review

2.3 Why executors self-review

  1. They read handoff.md → see Phase 4 → no barrier says “stop here, you’re the executor”
  2. conventions.md explicitly allows it → “REVIEW files can be written by any role”
  3. No role switch signal → no /tfw-review command, no “start a new session for review”
  4. Low-cost models follow instructions literally — if Phase 4 is in the same file they were told to read, they execute it

3. To-Be

3.1 Changes overview

# Change From → To
C1 Add Reviewer role 3 roles → 4 roles (User, Coordinator, Executor, Reviewer)
C2 Extract Phase 4 into /tfw-review workflow Embedded in handoff → standalone workflow
C3 Remove Phase 4 from handoff.md 4 phases → 3 phases (executor STOPS after RF)
C4 Fix Role Lock table “REVIEW by any role” → “REVIEW by Reviewer only”
C5 Add explicit STOP instruction at end of handoff.md Implicit → explicit “DO NOT REVIEW”
C6 New .agent/workflows/tfw-review.md Doesn’t exist → adapter workflow

3.2 The Reviewer role

The Reviewer is a coordinator acting in review mode. Not a fundamentally new identity — it’s the coordinator with a locked scope:

This distinction matters because:

3.3 Handoff workflow change

Current handoff.md:

Phase 1: ONB (executor)
Phase 2: Execute (executor)
Phase 3: RF (executor)
Phase 4: Review (coordinator)  ← REMOVE FROM HERE

After:

Phase 1: ONB (executor)
Phase 2: Execute (executor)
Phase 3: RF (executor)
🛑 STOP — executor's job is done. Start /tfw-review.

4. Phases

Phase A: Core extraction 🔴

Extract review into its own workflow and update all role/convention files:

  1. Create .tfw/workflows/review.md — canonical review workflow
  2. Create .agent/workflows/tfw-review.md — adapter copy
  3. Modify .tfw/workflows/handoff.md — remove Phase 4, add STOP
  4. Modify .agent/workflows/tfw-handoff.md — adapter sync (same edits as #3)
  5. Modify .tfw/conventions.md — fix Role Lock table, §8 Workflows table, §14 anti-patterns
  6. Modify .tfw/glossary.md — add Reviewer role, update Workflow definition, update Coordinator
  7. Modify AGENTS.md — add review workflow to the list
  8. Modify .tfw/CHANGELOG.md — add to [Unreleased]

Scope check: 2 NEW + 6 MODIFY = 8 files. Exceeds budget by 1 — acceptable because 2 of the modifications are adapter copies (byte-identical).

Phase B: Documentation sync 🟡

Update all secondary references across docs:

  1. Modify .tfw/README.md — L77 directory tree, L168 workflows table, L281 evolution
  2. Modify .tfw/workflows/plan.md — L76 mention /tfw-review after /tfw-handoff
  3. Modify .tfw/workflows/resume.md — L83 note review step after handoff
  4. Modify .tfw/init.md — L97, L184, L192 workflow lists
  5. Modify .tfw/adapters/antigravity/README.md — L21, L39, L51 adapter setup instructions

Scope check: 0 NEW + 5 MODIFY = 5 files. Within budget.

5. Definition of Done (DoD)

6. Definition of Failure (DoF)

On failure: re-examine the extraction boundary. Check if executor models still see review content.

7. Principles

  1. Separation of execution and review — the person who writes the code does not review it. Even if it’s the same AI model, it must be a different session with a different role lock.
  2. Explicit over implicit — a STOP instruction is better than hoping the executor knows to stop. A dedicated workflow is better than a phase buried in another workflow.
  3. Low-cost model compatibility — the design must work with models that follow instructions literally. No nuance requirement. Clear boundaries are cheaper than clever heuristics.

8. Dependencies

Dependency Status
All prior tasks complete ✅ (TFW-1 through TFW-7 DONE)
REVIEW template stable ✅ (no changes needed)

9. Risks

Risk Probability Impact Mitigation
Existing adapters (Claude Code, Cursor) don’t get the new workflow Low Medium Add to scope — but only Antigravity adapter is maintained here; others are templates
User forgets to run /tfw-review after /tfw-handoff Medium Low Add reminder in the STOP instruction of handoff.md
Over-engineering the Reviewer role Low Medium Keep it simple: Reviewer = Coordinator with locked scope, not a new persona
*HL — TFW-8: Reviewer Role and Workflow 2026-03-12*
This site is open source. Improve this page.