rework-loop

Rework Loop

Structured rework with blame attribution for failed goal iterations.

When the oracle says "fail," don't blindly retry — identify what broke,

map it to the responsible change, and route a targeted fix.

When to Activate

• Oracle returns fail verdict during a goal iteration
• Code reviewer identifies rework-worthy issues
• Build/test failures after a maker iteration
• Manual invocation for targeted re-implementation

Core Concept: Blame-Attributed Rework

Blind retry is the #1 waste in autonomous loops. A rework loop instead:

1. Parses failure output to extract specific failing locations
2. Blames via git diff / git blame to find the responsible change
3. Constrains the rework to only the affected scope
4. Routes to the right specialist (TS issues → typescript-reviewer, etc.)
5. Tracks rework attempts per location to detect persistent trouble spots

Oracle: FAIL
  │
  ▼
Parse failure → "tests/auth.test.ts:45 — token refresh assertion fails"
  │
  ▼
Blame → "src/auth/refresh.ts:23 changed in this iteration"
  │
  ▼
Rework brief → {file: "src/auth/refresh.ts", constraint: "only fix refresh logic"}
  │
  ▼
Route → backend-engineer or typescript-reviewer
  │
  ▼
Track → attempts[src/auth/refresh.ts] += 1

Rework Brief Format

The rework brief is a structured context packet for the next iteration:

## REWORK BRIEF

**Goal:** {original objective}
**Iteration:** {N} (rework attempt {M} for this location)

**Failing evidence:**
- Test: tests/auth.test.ts:45 — "should refresh expired tokens"
- Error: Expected token.expiresAt to be > now, got 2024-01-01

**Root cause (blame):**
- File: src/auth/refresh.ts:23
- Change: Added early return before expiry check
- Commit: (this iteration, uncommitted)

**Constraint:**
- ONLY modify src/auth/refresh.ts
- DO NOT touch test files (they define correct behavior)
- The refresh logic must handle: valid token, expired token, missing token

**Suggested fix:**
- Remove the early return at line 23
- Ensure expiry check runs before refresh attempt

Escalation Triggers

Rework escalates to triage when:

| Condition | Action |

|-----------|--------|

| 3+ rework attempts on same location | Escalate: "persistent trouble spot" |

| Rework introduces new failures | Escalate: "regression cascade" |

| Blame maps to multiple unrelated files | Escalate: "scope too broad for targeted rework" |

| No clear blame (flaky test, env issue) | Escalate: "non-deterministic failure" |

Blame Attribution Algorithm

1. Parse failure output for file paths and line numbers
2. Get changed files via git diff --name-only (this iteration vs last good)
3. Intersect failing files with changed files
4. For each intersection:

• git diff <file> to extract specific hunks
• Map test failure line to source change via call stack or import chain

1. If no intersection: failure is pre-existing or environmental → escalate

Rework Tracking

Track attempts per file/function to detect patterns:

{
  "src/auth/refresh.ts": {
    "attempts": 3,
    "lastAttempt": "2024-01-15T10:30:00Z",
    "outcomes": ["fail", "fail", "pass"],
    "totalCost": 1.20
  }
}

When attempts >= 3 without convergence: this is a persistent trouble spot.

The loop should escalate rather than keep burning budget.

Integration Points

• /goal: Rework replaces blind retry in the maker-oracle loop
• completion-oracle.js: Oracle's failReasons feed into blame parsing
• /triage: Escalated rework items go to triage inbox
• Specialist agents: Rework briefs route to appropriate specialists
• Cost advisor: Rework attempts count toward goal budget

Hard Bans

• DO NOT retry without blame analysis (blind retry wastes budget)
• DO NOT modify test files during rework (tests define correct behavior)
• DO NOT expand scope beyond blamed files (scope creep = new bugs)
• DO NOT rework indefinitely (3 attempts max per location)
• DO NOT skip tracking (rework history enables pattern detection)