scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
veritas-kanban/docs/SOP-cross-model-code-review.md

5.7 KiB
Raw Blame History

SOP: Cross-Model Code Review (Claude ↔ GPT)

Cross-model review is an optional independent-review workflow. Use it only when the task, configured review gate, issue owner, or release owner explicitly requires a different model.

When to Trigger

Work Type Review Required?
Application code, infra, scripts When explicitly required
Docs/content When explicitly required
Research summaries When explicitly required

If no review requirement is present, use focused self-verification and the normal human/CI review path.

Workflow

  1. Authoring task completes (status remains in-progress).
  2. Create review task referencing the original:
    • Title: Review: <orig task title>
    • Type: code
    • Sprint/project identical
    • Description includes acceptance criteria + diff link(s)
  3. Assign to opposite model (via OpenClaw or other orchestrator): 
    Hey Codex, review PR for task_1234. Checklist below.
  4. Reviewer steps:
    • Pull branch / run tests (if applicable)
    • Use docs/SOP-agent-task-workflow.md for lifecycle
    • Log findings as subtasks or checklist entries
    • Severity tagging: High / Medium / Low / Nit
  5. Outcomes:
    • ✅ No issues → comment summary + mark review task done → original task can go to done
    • ❌ Issues → create fix subtasks on original task, set status blocked until resolved
  6. Comms: Reviewer leaves structured comment: 
    ## Findings
- [High] Path traversal (see notes)
- [Low] Missing aria-label
## Verdict
Changes required.
  7. Audit trail: Update commit message or PR description with [author: claude-sonnet-4-5][reviewed-by: gpt-5.1-codex].

Review Checklist

Category Questions
Security Auth enforced? Input validated? Path traversal? Secrets handled?
Reliability Error handling? Race conditions? Timeouts? File locking?
Performance Avoid O(n²)? Streaming vs buffering? Caching appropriate?
Accessibility Keyboard support? aria-labels? Color contrast?
Docs README/docs updated? Migration notes? Tests updated?

Adapt per task type.

Prompt Template (Reviewer)

You are the cross-model reviewer. The code was authored by <model>. Apply the checklist:
1. Pull latest branch <branch>.
2. Run tests (if any).
3. For each issue, note severity (High/Medium/Low/Nit) + file/line + fix suggestion.
4. Summarize verdict: Approve or Changes Required.
5. Update task <id> with findings and completion summary.

Store in prompt-registry/cross-model-review.md.

Recording Findings

  • Add subtasks under the original task for each confirmed bug.
  • Reference GitHub issues if they existed.
  • Use Lessons Learned to capture systemic insights (e.g., “Always use withFileLock() when touching JSON stores”).

Escalation

Scenario Action
Reviewer disagrees with author but fix is minor Leave comment + request change.
Reviewer finds high severity bug Block task, ping human immediately.
Author disputes reviewer findings Create triage meeting or ask human to adjudicate.

Review Gates (Veritas Kanban Enforcement)

VK's built-in enforcement gates can make this optional workflow a structural requirement for selected workspaces or tasks:

  1. reviewGate — Blocks task completion unless all four reviewScores (security, reliability, performance, accessibility) are 10. This is the automated enforcement layer that ensures the cross-model review checklist has been completed rigorously.

  2. closingComments — Requires a substantive review comment (≥20 characters) before task completion. Ensures the reviewer leaves documented findings, not just scores.

  3. How they work together:

    • Author (Model A) completes code; task remains in-progress
    • Reviewer (Model B) runs the cross-model review checklist
    • Reviewer scores all 4 dimensions via the API: PATCH /api/tasks/{id} with reviewScores
    • Reviewer leaves findings as comments (must be ≥20 chars if closingComments enabled)
    • If reviewGate is enabled, task cannot move to done until all scores are 10
    • If closingComments is enabled, at least one substantive comment is required

  4. Enabling gates:

    curl -X PATCH http://localhost:3001/api/settings/features \
  -H 'Content-Type: application/json' \
  -d '{"enforcement": {"reviewGate": true, "closingComments": true}}'

  5. Handling gate failures — If task completion returns a 400 error with REVIEW_GATE_FAILED or CLOSING_COMMENT_REQUIRED, the reviewer must address the deficiency (raise a score, add a comment) and retry.

  6. Recommendation: Enable reviewGate and closingComments only when the workspace deliberately requires independent scored review. Leave them off when normal task verification and human/CI review are sufficient.

  7. Full documentation: See Enforcement Gates for all available gates, configuration options, and API reference.

RF-002 recorded a 91% accuracy rate for this review method. That result supports using the method when selected; it does not make it a universal gate.