A Fix Report is the fix agent's accounting — a structured handoff that documents what was resolved, what wasn't, and why, so the re-review agent can focus its audit instead of re-reading the entire diff.

Primitive

Fix Report

The artifact

A structured markdown file produced after every fix pass.

app_fix_reports/fix_20240917T143022Z.md

# Fix Report

Status:PARTIAL

Review Report:app_review_reports/review_20240917T130000Z.md

Timestamp:2024-09-17T14:30:22Z

Agent:fix-agent / claude-sonnet-4-5

---

## Resolved Issues (1 of 2)

### Issue #1

Tier:BLOCKER

File:src/api.ts

Before:

Missing null check at line 47 — `user.profile` dereferenced

before existence confirmed. Runtime crash on new user signup.

After:

Null guard added: `if (!user?.profile) return defaultProfile(user.id)`

Early-return pattern consistent with surrounding handlers.

Verification:

grep -n "if.*null\|?\." src/api.ts

---

## Unresolved Issues (1 of 2)

### Issue #2

Tier:HIGH

File:src/cache.ts

Reason Unresolved:

Architectural conflict — stale-read fix requires modifying cache

invalidation strategy, which is shared by three other subsystems.

Partial fix would introduce data consistency regression.

Recommended Next Step:

Refactor cache invalidation layer first (see ADR-014),

then revisit stale-read guard in a dedicated pass.

---

## Summary

Resolved:1Unresolved:1Total:2

The report references its source Review Report by path. The re-review agent opens both files and skips Issue #1 — it is already verified resolved.

Resolved vs unresolved

Every issue is explicitly accounted for — one way or the other.

Resolved

Tier

BLOCKER

Before

Null deref crash on new signup

After

Null guard — early return added

Verification

grep -n "if.*null" src/api.ts

Re-review agent sees this and skips re-checking.

Unresolved

Tier

HIGH

Reason Unresolved

Architectural conflict with cache layer

Recommended Next Step

Refactor cache invalidation first (ADR-014)

Silently skipping is not an option.

The Before/After/Verification structure gives the re-review agent a checkable claim, not just an assertion. Unresolved issues carry rationale — the fix agent is on record.

Status field

COMPLETE, PARTIAL, or BLOCKED — declared up front.

COMPLETE

All issues resolved

When to use

• Every issue from the Review Report was addressed
• All verifications pass
• No open items remain

PARTIAL

Some resolved, some not

When to use

• At least one issue resolved
• Remaining issues are explicitly documented with rationale
• Each unresolved item has a recommended next step

BLOCKED

Cannot proceed

When to use

• Architectural blocker prevents any fix
• Dependency not yet available
• Scope conflict — fix is out of bounds for this agent

PARTIAL is the honest default for real-world fix passes. BLOCKED surfaces systemic issues before they silently derail re-review.

The artifact chain

Fix Report is the handoff node between fix and re-review.

With Fix Report

📋

Review Report produced

Review agent writes issues with tier, location, and description to app_review_reports/review_*.md

↓

🔧

Fix Agent reads it, fixes what it can

Resolves issues in priority order. Documents blockers and architectural constraints it cannot address in this pass.

↓

📄

Fix Report written

Before/After/Verification for each resolved issue. Reason + Next Step for each unresolved. Status: COMPLETE / PARTIAL / BLOCKED.

↓

🔍

Re-review Agent reads Fix Report first

Skips re-checking resolved issues. Audit is scoped to what changed — unresolved items, and any regressions introduced by the fix pass.

vs

Without Fix Report

Re-review agent must re-read the entire diff with no signal about what changed intentionally vs incidentally. Resolved issues get re-examined. Unresolved issues may be silently missed. The loop produces no traceable artifact pair — iteration history is invisible.

Each Review-Fix iteration produces an artifact pair. The pair makes the loop traceable, resumable, and auditable from any point in the history.

The discipline

Every fix pass ends with a written accounting. Not a commit message — a report.

Resolved issues have verifiable before/after state. Unresolved issues have rationale and a next step. The re-review agent reads the Fix Report, not the diff. The loop becomes traceable — and fixable — one artifact pair at a time.