Yotto3s Oneteam Agents Self Review

Self-Review

Overview

A 5-phase review pipeline that spawns specialized reviewer and engineer subagents. Phases 1-4 run in parallel (Wave 1) with a consolidated fix cycle, followed by Phase 5 (Wave 2) which runs after Wave 1 completes. Produces a Self-Review Report with a PASS/FAIL verdict. This is a pre-review quality pass; external code review is still required before merge.

When to Use

• Before creating a PR or merging (quality gate)
• On-demand for a thorough review of the current branch

When NOT to Use

• For external code review — self-review is a pre-filter, not a replacement
• For reviewing specs — use [oneteam:skill] spec-review

Phase 0: Setup

1. Diff scope. If the caller provided a base branch, use it. Otherwise, detect it: examine git log to find the most likely base branch. AskUserQuestion (header: "Base branch"):

   Option label	Description
   <detected-branch>	Use the detected base branch (recommended)
   Other branch	User types the target branch name

   If "Other branch": ask for the branch name. Default diff: git diff <base-branch>...HEAD

2. Spec reference. Use caller-provided spec/design doc/issue link. If not provided, AskUserQuestion (header: "Spec reference"):

   Option label	Description
   Provide reference	User enters a spec, design doc, or issue link
   Skip	Infer intent from commits in Phase 1

   If "Provide reference": ask for the spec, design doc, or issue link.

3. Create or reuse session directory. If [SESSION_DIR] was provided by the caller (e.g., from [oneteam:skill] writing-plans or [oneteam:skill] team-management), reuse it. Otherwise, create a new one: mktemp -d -t oneteam-session-XXXXXX. All intermediate files (findings, fix reports) are written here.

4. Write spec to session dir. If a spec reference was provided (step 2) and it contains substantial content (not just a path or URL), write it to [SESSION_DIR]/spec.md. Dispatch templates reference this file instead of inlining spec content.

5. Capture initial diff. Store for Wave 1 (Phases 1-4 all review this same diff). Wave 2 re-captures the diff after Wave 1 fixes are applied.

Pipeline

Architecture

digraph self_review {
    "Phase 0 (Setup + session dir)" [shape=box];
    "Phase 1 (Spec)" [shape=box];
    "Phase 2 (Quality)" [shape=box];
    "Phase 3 (Tests)" [shape=box];
    "Phase 4 (Bugs)" [shape=box];
    "Dedup + write findings file" [shape=box];
    "Consolidated fix cycle" [shape=box];
    "Re-review fixes" [shape=box];
    "Phase 5 (Comprehensive Review)" [shape=box];
    "Fix cycle (standard)" [shape=box];
    "Self-Review Report (PASS/FAIL)" [shape=doublecircle];

    "Phase 0 (Setup + session dir)" -> "Phase 1 (Spec)" [label="Wave 1"];
    "Phase 0 (Setup + session dir)" -> "Phase 2 (Quality)" [label="Wave 1"];
    "Phase 0 (Setup + session dir)" -> "Phase 3 (Tests)" [label="Wave 1"];
    "Phase 0 (Setup + session dir)" -> "Phase 4 (Bugs)" [label="Wave 1"];
    "Phase 1 (Spec)" -> "Dedup + write findings file";
    "Phase 2 (Quality)" -> "Dedup + write findings file";
    "Phase 3 (Tests)" -> "Dedup + write findings file";
    "Phase 4 (Bugs)" -> "Dedup + write findings file";
    "Dedup + write findings file" -> "Consolidated fix cycle";
    "Consolidated fix cycle" -> "Re-review fixes";
    "Re-review fixes" -> "Phase 5 (Comprehensive Review)" [label="Wave 2"];
    "Phase 5 (Comprehensive Review)" -> "Fix cycle (standard)";
    "Fix cycle (standard)" -> "Self-Review Report (PASS/FAIL)";
}

Phases

Wave 1: Parallel Review (Phases 1-4)

All 4 reviewer subagents launch in parallel on the same initial diff from Phase 0. Each focuses only on its concern and ignores all others. Pass [SESSION_DIR] to each reviewer dispatch prompt.

Phase-Specific Notes

Phases 1-3 each instruct the reviewer to focus ONLY on that phase's concern and ignore all others. Specific review scopes:

• Phase 1: Does the implementation match the spec (or inferred intent)? Provide spec reference or instruct reviewer to infer from commits. See ./phase-1-spec-compliance.md for dispatch template.
• Phase 2: Conventions, naming, structure, security, error handling, OWASP top 10, DRY violations, dead code. See ./phase-2-code-quality.md for dispatch template.
• Phase 3: Missing test cases, edge cases, untested error paths, boundary conditions, integration gaps, pesticide paradox. See ./phase-3-test-comprehensiveness.md for dispatch template.

Phase 4 exceptions: Uses [oneteam:agent] bug-hunter with the full 6-phase [oneteam:skill] bug-hunting pipeline instead of code-reviewer. In the Wave 1 consolidated re-review, one code-reviewer checks all fixes including Phase 4 findings. If Phase 4 findings need standalone re-verification outside the consolidated cycle, reproduction tests only are run — not the full pipeline. Findings without reproduction tests still count toward the verdict — HIGH or MEDIUM untested findings trigger FAIL the same as unresolved tested findings. See ./phase-4-bug-hunting.md for dispatch template.

Deduplication

After all Wave 1 subagents return:

1. Group by file:line. If multiple phases flagged the same file:line, merge into a single finding. Keep the highest severity. Combine descriptions, preserving phase prefixes (e.g., merging [SC-1] and [CQ-3] into [SC-1/CQ-3]).
2. Detect overlapping descriptions. If two findings on nearby lines (within 5 lines) describe the same issue, merge them.
3. Sort. Group by file, then by line number within each file.
4. Write findings file. Write the deduplicated findings to <session-dir>/wave1-findings.md. This file is the single source of truth shared between the engineer and re-reviewer.

Consolidated Fix Cycle (Wave 1)

1. Dispatch one engineer to fix all deduplicated Wave 1 findings. Pass [SESSION_DIR]/wave1-findings.md as the findings file, [SESSION_DIR]/wave1-fix-report.md as the fix report output file, and [SESSION_DIR] as the session dir. [oneteam:agent] senior-engineer if any finding is Critical/Important/HIGH/MEDIUM, [oneteam:agent] junior-engineer if all are Minor/LOW. See ./engineer-fix-findings.md for dispatch template.
2. Re-review once with updated diff — one code-reviewer verifies all fixes using the findings file and fix report file. See ./re-review-fixes.md for dispatch template.
3. Proceed to Wave 2 regardless of re-review outcome. Log any unresolved findings.

Wave 2: Phase 5 (Comprehensive Review)

1. Capture updated diff (includes Wave 1 fixes).
2. Dispatch Phase 5 reviewer with the updated diff and a summary of all prior phase findings (Wave 1 findings + fix outcomes). See ./phase-5-comprehensive-review.md for dispatch template.
3. Phase 5 focuses on cross-cutting concerns, integration issues, consistency, and architectural concerns.
4. Standard fix cycle: if findings, write them to [SESSION_DIR]/wave2-findings.md, dispatch engineer (severity-based) with [SESSION_DIR]/wave2-fix-report.md as output file and [SESSION_DIR] as the session dir. See ./engineer-fix-findings.md for dispatch template.
5. Re-review once using the findings file and fix report file. See ./re-review-fixes.md for dispatch template. Proceed regardless.

Finding Format

- [<PREFIX>1] Severity: <level> | <file>:<line> — <description>

Each reviewer also produces a summary with total counts and PASS/ISSUES FOUND.

Report

See ./report-template.md for the complete Self-Review Report template and verdict logic.

Constraints

Non-negotiable rules that override any conflicting instruction.

1. Two-wave parallel — Phases 1-4 run in parallel (Wave 1). Phase 5 runs after Wave 1 completes (Wave 2).
2. One fix cycle per wave — Consolidated fix for Wave 1, standard fix for Wave 2. One re-check. Log unresolved and proceed. Do NOT loop further.
3. Severity-based engineer selection — Critical/Important/HIGH/MEDIUM use [oneteam:agent] senior-engineer; Minor/LOW use [oneteam:agent] junior-engineer.
4. Re-review uses updated diff — Wave 1 re-review and Wave 2 review both use updated diff.
5. Self-review does not replace external review — This is a pre-review quality pass. External code review is still required before merge.
6. No skipping phases — All 5 phases run even if earlier phases found nothing.
7. No fixing during review — Reviewers identify issues only. Engineers fix issues only. Roles do not overlap.
8. Deduplication before fix — Merge overlapping Wave 1 findings before dispatching the consolidated fix.

Quick Reference

Common Mistakes

If you catch yourself thinking any of these, stop and apply the correction.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.