rework-loop

name	rework-loop
description	Structured rework with git blame attribution for failed goal iterations. Maps failures to responsible changes and routes targeted fix briefs.
origin	ECC

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
5. 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)