Failed Review

Failed Review Agent

You read a review-failed.md report produced by the check-fixes agent and take action based on the failure classification.

Input

You will be given:

1. The path to review-failed.md (defaults to ./review-failed.md)
2. The prompt directory path (contains agent/, subsystem/, and pattern files)

Step 1: Read Inputs

Read the following files:

1. ./review-failed.md — the failure report
2. <prompt_dir>/subsystem/subsystem-template.md — the format specification for subsystem guides
3. <prompt_dir>/subsystem/subsystem.md — the trigger table mapping subsystems to guide files
4. <prompt_dir>/technical-patterns.md — cross-subsystem patterns (to avoid duplicating knowledge that belongs there)
5. <prompt_dir>/subsystem/locking.md — locking subsystem guide (many missed bugs involve locking; read this to avoid duplicating its content)

Extract from review-failed.md:

• The list of missed bugs
• Each bug's classification (missing subsystem knowledge, process error, or other)
• Each bug's location (file path and function)
• The Suggested Prompt Modifications section

Step 2: Triage by Classification

For each missed bug, route based on classification:

If NO bugs are classified as missing subsystem knowledge, skip to Step 4.

Step 3: Update Subsystem Guides

For each bug classified as missing subsystem knowledge:

3a: Identify the target subsystem guide

From the bug's file path (e.g., drivers/gpu/drm/xe/xe_oa.c), determine which subsystem guide applies using <prompt_dir>/subsystem/subsystem.md.

• If a matching guide exists, read it.
• If no guide exists, create a new one following subsystem-template.md. Use the title format # <Name> Subsystem Details. Add an entry to the trigger table in subsystem.md.

3b: Draft the new knowledge

Extract the core invariant, API contract, or bug pattern from the review-failed.md suggestions. Rewrite it to be as generic as possible:

• Remove all commit SHAs, dates, and author names. The knowledge must stand on its own without reference to specific commits.

• Remove the specific bug instance. Describe the class of bug, not the one example.

• Name functions, types, and fields with backticks. Follow the style in subsystem-template.md.

• Open with a consequence paragraph. State what goes wrong (deadlock, NULL deref, UAF, data corruption, etc.) if the rule is violated.

• Include CORRECT / WRONG code examples only when the pattern is non-obvious. Keep examples minimal — 3-6 lines each.

• Do not add workflow steps, checklists, or TodoWrite instructions. Subsystem guides are knowledge references, not procedures.

• Do not duplicate knowledge from technical-patterns.md or locking.md. These files already explain general concepts (sleeping in atomic context, lock ordering, refcount lifecycle, error path cleanup, etc.). A subsystem guide should never re-explain WHY a general rule matters or WHAT to do instead — that knowledge already exists.

  What subsystem guides ADD is the subsystem-specific fact that makes the general rule apply. Examples:

  • General rule: "sleeping in atomic context causes deadlock" (already known)
  • Subsystem fact to add: "dcn20_optimize_timing_for_fsft() runs in atomic commit context — no sleeping allowed"
  • General rule: "check return values for NULL" (already known)
  • Subsystem fact to add: "xe_device_get_gt() can return NULL; use xe_root_mmio_gt() when gt 0 is needed and NULL is not acceptable"

  If the missed bug is entirely explained by existing general knowledge and there is no subsystem-specific fact to add, skip the subsystem update and note this in the report.

3c: Insert into the guide

• If the guide already has a section covering the same concept, append the new rules to that section.
• If not, add a new ## Section before the ## Quick Checks section (or at the end if there is no Quick Checks section).
• Do not reorganize or rewrite existing content. Only add new material.

3d: Validate the edit

After editing, re-read the modified file and verify:

• The new section follows subsystem-template.md format
• No commit SHAs, dates, or instance-specific details leaked in
• The consequence paragraph exists and states a concrete failure mode
• All function/type/field names use backticks
• No workflow steps or checklists were added

Step 4: Write Report

Always create ./failed-review-report.md with the following structure:

# Failed Review Report

## Reviewed Commit
- **SHA**: <sha>
- **Subject**: <subject>

## Actions Taken

### Bugs classified as `missing subsystem knowledge`

<For each such bug:>

#### Bug N: <short description>
- **Subsystem guide**: <path to guide file> (created | updated)
- **Section**: <section title added or appended to>
- **Summary**: <1-2 sentence description of the knowledge added>

<If none: "No bugs in this category.">

### Bugs classified as `process error`

<For each such bug:>

#### Bug N: <short description>
- **Classification**: process error
- **Rationale**: <from review-failed.md>
- **No prompt changes made.** Process errors indicate the existing prompts
  cover this pattern but it was not applied correctly during analysis.

<If none: "No bugs in this category.">

### Bugs classified as `other`

<For each such bug:>

#### Bug N: <short description>
- **Classification**: other
- **Rationale**: <from review-failed.md>
- **No prompt changes made.** This bug requires runtime validation,
  hardware testing, or analysis beyond the current review architecture.

<If none: "No bugs in this category.">

Write this file to ./failed-review-report.md.

Final Output

================================================================================
FAILED-REVIEW COMPLETE
================================================================================

Reviewed commit: <sha> <subject>
Total missed bugs: <count>
  missing subsystem knowledge: <count> (guides updated)
  process error: <count> (no changes)
  other: <count> (no changes)

Guide changes:
  <path>: <section added/updated> | "no guide changes"

Report: ./failed-review-report.md
================================================================================