Build Fix — Instructions
Scope: Compile-time and build errors introduced by prior agent changes
Budget: Maximum 5 fix iterations before stopping
Core Principles
| # |
Principle |
Rationale |
| 1 |
Own-damage only |
Never fix pre-existing errors. If an error existed before your changes, leave it alone and report it. |
| 2 |
Minimal diff |
Every fix must be the smallest possible change that resolves the error. Do not refactor, reorganize, or "improve" surrounding code. |
| 3 |
Preserve intent |
Your fixes must preserve the semantic intent of the original change. If you cannot fix the error without altering the intended behavior, report it. |
| 4 |
No suppression |
Never suppress, silence, or hide errors (e.g., #pragma warning disable, @ts-ignore, # type: ignore, catch-all exception handlers, noqa). Fix the root cause. |
| 5 |
No deletion of functional code |
Do not delete working functions, classes, or logic blocks to make the build pass. If code was added intentionally, fix it — don't remove it. |
| 6 |
Bounded iteration |
You have a maximum of 5 fix-build cycles. If the build still fails after 5 attempts, stop and reported with a diagnostic summary. |
| 7 |
Version alignment |
Make sure not to make major version changes like changing dotnet version, changing typescript version, python version. If some version is not available in current env, better install it and align with what the repository demands. |
Execution Protocol
Phase 0: Establish Baseline
Before attempting any fix, you MUST:
- Identify your own changes: Run
git diff (or equivalent) to produce the full set of files and lines you modified.
- Figure out the build command: Determine how to build the project by looking for checked-in yaml files, repository README or contributing docs, existing CI or pipeline configuration, then established project conventions.
- Setup environment: If some version (dotnet, pip ...) is required to build, make sure to set it up before running the build command (instead of editing repository build configuration)
- Capture the build output: Run the project's build command and capture the full error output.
- Classify each error: For every error in the build output, determine:
SELF_CAUSED — The error references a file/line/symbol that you changed, or is a direct consequence of your changes (e.g., you renamed a function and a caller now has an unresolved reference).PRE_EXISTING — The error exists in code you did not touch and is not caused by your changes.
Only proceed to fix SELF_CAUSED errors. Log PRE_EXISTING errors for reporting but take no action on them.
Phase 1: Diagnose
For each SELF_CAUSED error:
- Parse the error precisely: Extract the error code, file path, line number, and message. Do not paraphrase — use the exact compiler/build-tool output.
- Trace to root cause: Errors often cascade. A single root cause (e.g., a missing import) can produce many downstream errors. Group related errors and identify the root cause(s).
- Plan the fix: Before writing any code, state:
- Which file(s) you will modify
- What specific change you will make
- Why this resolves the error
- Confirm the fix does not alter the behavioral intent of the original change
Phase 2: Apply Fix
- Make the minimal edit to resolve the root-cause error(s).
- Do not batch unrelated fixes into a single edit if they touch different logical areas — apply them as separate, traceable edits.
- After each edit, re-run the build to verify:
- The targeted error(s) are resolved.
- No new errors were introduced by the fix itself.
Phase 3: Verify & Iterate
iteration = 0
MAX_ITERATIONS = 5
while build_fails and iteration < MAX_ITERATIONS:
iteration += 1
1. Run build command
2. Parse new error output
3. Filter to SELF_CAUSED errors only
4. If no SELF_CAUSED errors remain → SUCCESS → exit loop
5. If same error(s) persist from previous iteration:
- You MUST try a DIFFERENT fix strategy (do not repeat the same fix)
- If you have exhausted all reasonable strategies → reported
6. Diagnose and apply fix (Phase 1 → Phase 2)
if iteration >= MAX_ITERATIONS:
reported with diagnostic summary
Phase 4: Report
On completion (success or escalation), produce a structured report:
## Build Autofix Report
**Status**: SUCCESS | reported
**Iterations used**: N / 5
### Errors Fixed
- [Error Code] in [file:line] — [one-line description of fix]
### Errors Skipped (Pre-existing)
- [Error Code] in [file:line] — [reason: not caused by agent changes]
### Errors Unresolved (if reportedd)
- [Error Code] in [file:line] — [what was tried, why it failed]
### Changes Made
- [file:line] — [description of edit]
1---2name: build-fix3description: Fix compile-time and build errors introduced by prior agent changes4---5
6# Build Fix — Instructions
7
8> Scope: Compile-time and build errors introduced by prior agent changes
9> Budget: Maximum **5 fix iterations** before stopping
10
11---
12
13## Core Principles
14
15| # | Principle | Rationale |
16|---|-----------|-----------|
17| 1 | **Own-damage only** | Never fix pre-existing errors. If an error existed before your changes, leave it alone and report it. |
18| 2 | **Minimal diff** | Every fix must be the smallest possible change that resolves the error. Do not refactor, reorganize, or "improve" surrounding code. |
19| 3 | **Preserve intent** | Your fixes must preserve the semantic intent of the original change. If you cannot fix the error without altering the intended behavior, report it. |
20| 4 | **No suppression** | Never suppress, silence, or hide errors (e.g., `#pragma warning disable`, `@ts-ignore`, `# type: ignore`, `catch-all` exception handlers, `noqa`). Fix the root cause. |
21| 5 | **No deletion of functional code** | Do not delete working functions, classes, or logic blocks to make the build pass. If code was added intentionally, fix it — don't remove it. |
22| 6 | **Bounded iteration** | You have a maximum of **5 fix-build cycles**. If the build still fails after 5 attempts, stop and reported with a diagnostic summary. |
23| 7 | **Version alignment** | Make sure not to make major version changes like changing dotnet version, changing typescript version, python version. If some version is not available in current env, better install it and align with what the repository demands.
24
25---
26
27## Execution Protocol
28
29### Phase 0: Establish Baseline
30
31Before attempting any fix, you MUST:
32
331. **Identify your own changes**: Run `git diff` (or equivalent) to produce the full set of files and lines you modified.
342. **Figure out the build command**: Determine how to build the project by looking for checked-in yaml files, repository README or contributing docs, existing CI or pipeline configuration, then established project conventions.
353. **Setup environment**: If some version (dotnet, pip ...) is required to build, make sure to set it up before running the build command (instead of editing repository build configuration)
364. **Capture the build output**: Run the project's build command and capture the full error output.
375. **Classify each error**: For every error in the build output, determine:
38 - `SELF_CAUSED` — The error references a file/line/symbol that you changed, or is a direct consequence of your changes (e.g., you renamed a function and a caller now has an unresolved reference).
39 - `PRE_EXISTING` — The error exists in code you did not touch and is not caused by your changes.
40
41**Only proceed to fix `SELF_CAUSED` errors.** Log `PRE_EXISTING` errors for reporting but take no action on them.
42
43### Phase 1: Diagnose
44
45For each `SELF_CAUSED` error:
46
471. **Parse the error precisely**: Extract the error code, file path, line number, and message. Do not paraphrase — use the exact compiler/build-tool output.
482. **Trace to root cause**: Errors often cascade. A single root cause (e.g., a missing import) can produce many downstream errors. Group related errors and identify the root cause(s).
493. **Plan the fix**: Before writing any code, state:
50 - Which file(s) you will modify
51 - What specific change you will make
52 - Why this resolves the error
53 - Confirm the fix does not alter the behavioral intent of the original change
54
55### Phase 2: Apply Fix
56
571. **Make the minimal edit** to resolve the root-cause error(s).
582. **Do not batch unrelated fixes** into a single edit if they touch different logical areas — apply them as separate, traceable edits.
593. **After each edit, re-run the build** to verify:
60 - The targeted error(s) are resolved.
61 - No new errors were introduced by the fix itself.
62
63### Phase 3: Verify & Iterate
64
65```
66iteration = 0
67MAX_ITERATIONS = 5
68
69while build_fails and iteration < MAX_ITERATIONS:
70 iteration += 1
71
72 1. Run build command
73 2. Parse new error output
74 3. Filter to SELF_CAUSED errors only
75 4. If no SELF_CAUSED errors remain → SUCCESS → exit loop
76 5. If same error(s) persist from previous iteration:
77 - You MUST try a DIFFERENT fix strategy (do not repeat the same fix)
78 - If you have exhausted all reasonable strategies → reported
79 6. Diagnose and apply fix (Phase 1 → Phase 2)
80
81if iteration >= MAX_ITERATIONS:
82 reported with diagnostic summary
83```
84
85### Phase 4: Report
86
87On completion (success or escalation), produce a structured report:
88
89```
90## Build Autofix Report
91
92**Status**: SUCCESS | reported
93**Iterations used**: N / 5
94
95### Errors Fixed
96- [Error Code] in [file:line] — [one-line description of fix]
97
98### Errors Skipped (Pre-existing)
99- [Error Code] in [file:line] — [reason: not caused by agent changes]
100
101### Errors Unresolved (if reportedd)
102- [Error Code] in [file:line] — [what was tried, why it failed]
103
104### Changes Made
105- [file:line] — [description of edit]
106```
107
108
gabrielmoreira