Skip to content
Skills Library
Programming · Automation

error-fixer-loop

/error-fixer-loop

Recursive error-fix loop. Use when a bash command fails with a build/test/typecheck error, when the same class of error appears more than once, or when the harness itself needs a persistent rule so the error does not come back. Detect → root-cause → minimal fix → test → lint/typecheck → persist rule (SKILL.md / AGENTS.md / docs/rules) → audit with evidence. Cross-harness (Claude Code, OpenCode, Codex, Gemini, Agy).

Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
13
Scripts
5
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 5 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: hooks/error-fixer-loop-codex.py, hooks/error-fixer-loop-hook.sh, hooks/error-fixer-loop.ts, scripts/detect-error.sh, scripts/install.sh

What it does and when to use it

Recursive error-fix loop. Use when a bash command fails with a build/test/typecheck error, when the same class of error appears more than once, or when the harness itself needs a persistent rule so the error does not come back. Detect → root-cause → minimal fix → test → lint/typecheck → persist rule (SKILL.md / AGENTS.md / docs/rules) → audit with evidence. Cross-harness (Claude Code, OpenCode, Codex, Gemini, Agy).

Original author description

Recursive error-fix loop. Use when a bash command fails with a build/test/typecheck error, when the same class of error appears more than once, or when the harness itself needs a persistent rule so the error does not come back. Detect → root-cause → minimal fix → test → lint/typecheck → persist rule (SKILL.md / AGENTS.md / docs/rules) → audit with evidence. Cross-harness (Claude Code, OpenCode, Codex, Gemini, Agy).

How it works

  1. Trigger
  2. Protocol (non-negotiable)
  3. Escopo de escrita (write scope)
  4. Anti-patterns (hard no)
  5. Recursive improvement criteria
  6. Hook integration
  7. Layered feedback model
  8. References
Original SKILL.md headings · 211 lines, 1,465 words
SKILL.md preview
---
name: error-fixer-loop
description: Recursive error-fix loop. Use when a bash command fails with a build/test/typecheck error, when the same class of error appears more than once, or when the harness itself needs a persistent rule so the error does not come back. Detect → root-cause → minimal fix → test → lint/typecheck → persist rule (SKILL.md / AGENTS.md / docs/rules) → audit with evidence. Cross-harness (Claude Code, OpenCode, Codex, Gemini, Agy).
---

# Error Fixer Loop

> Every fixed error must reduce the chance of the same error returning.
> If the loop ends at the patch, it failed — even if the patch worked.

Recursive skill: it closes the cycle between **execution**, **verification**, and **harness improvement**. Each run produces evidence (error found, decision made, test run, rule created, harness adjusted) and leaves the system harder to break in the same way.

Reference pattern: [Como Criar uma Skill Recursiva](https://lemon.dev.br/pt/blog/skill-recursiva-feedback-loop-harness).

---

## Trigger

Load this skill when ANY of these is true:

- A `bash`/`shell` tool call returns output matching a known build/test/typecheck error pattern (see `hooks/` — they auto-inject a reminder).
- The user says: "investigate this error", "fix this build", "test failed", "typecheck broken", "error keeps coming back".
- You are about to conclude a fix and have not yet written a persistent rule.

Do **not** load for:

- Transient network/permission errors (one-off, not repeatable).
- Errors in code owned by external vendors (no write access).
- Pure refactors with no failing signal (use `code-smell` or `architecture-deepener` instead).

---

## Protocol (non-negotiable)

Follow the steps in order. Skipping steps is the exact failure this skill prevents.

### 1. Capture the event
- Paste the **exact command** that failed.
- Paste the **exact error output** (trimmed to the relevant 50 lines).
- Note the **working directory** and **exit code**.

### 2. Declare the root cause in one sentence
Format: `<Component> fails because <specific reason>, triggered by <minimal repro>.`

If you cannot write this sentence yet, you are not at root cause — go back to step 1 with a tighter repro (see `bug-diagnostics` for repro-building techniques).

### 3. Classify the failure
Pick exactly one primary class. This decides where the fix lives.

| Class | Symptom | Where the fix belongs |
|---|---|---|
| `procedure` | Skill/agent didn't say to run the check | this `SKILL.md` or the calling skill |
| `missing-rule` | Project convention violated repeatedly | `docs/rules/<topic>.md` or `AGENTS.md` |
| `missing-test` | Bug escaped because no seam | test suite (add regression test) |
| `permission` | Tool denied, sandbox blocked, path forbidden | harness policy (`~/.config/opencode/permission.json`, Claude settings) |
| `observability` | No log, no checkpoint, no evidence | logging/checkpoint layer |
| `documentation` | Agent followed stale doc | doc file referenced by agent |

### 4. Apply the minimal fix
- Touch only what is load-bearing for the error.
- No drive-by improvements. No "while I'm here" refactors.
- Match existing style.

### 5. Run the relevant verification
- If a test exists: run it.
- If no test exists and the bug is repeatable: **write a failing test first**, then fix, then watch it pass.
- Always run `lint` and `typecheck` for TS/JS projects (`tsc --noEmit`, `biome check`, `eslint`).
- Paste the verification output in the final report.

### 6. Persist the rule
If the failure is **repeatable** (same class can appear again), write a rule. Use this decision tree:

```
Is it specific to THIS project?
  ├─ yes → docs/rules/<topic>.md in the project, link from AGENTS.md
  └─ no  → could other projects hit it?
        ├─ yes → this SKILL.md (anti-patterns section) or a new global rule
        └─ no  → record in the final report only; do NOT write a rule
```

Rule format (one line, operational, verifiable):

```markdown
- **<Rule name>**: <imperative sentence>. Verify with: <command or check>.
```

Good: `Never use `as any` to silence a TS error without a `// justified: <reason>` comment. Verify with: grep -rn "as any" src/ | grep -v justified.`
Bad: `Be careful with types.` (not operational, not verifiable)

### 7. Update the harness index
- If you wrote a rule in `docs/rules/`, link it from `AGENTS.md` under the relevant section.
- If you updated this `SKILL.md`, bump the version in `plugin.json` and note the change in the audit.

### 8. Generate the fix-prompt artifact
Write a dynamic fix-prompt file so the fix can be replayed, delegated, or audited later — even in another session or harness.

- **Location:** `.error-fixer-loop/<YYYYMMDD-HHMMSS>-<short-slug>.md` (create the folder if missing; add it to `.gitignore` if the project doesn't want it versioned).
- **Template:** use `templates/fix-prompt.md` from this plugin.
- **Format:** the file MUST follow the `senior-prompt-engineer` output shape — Role/Context, Task, Inputs/files, Constraints, Plan with `→ verify:` per step, Output contract, Feedback DO, Feedback DO NOT, and a closing `EXEC-MAP v1` fenced block.
- **Slug:** 3–6 lowercase words describing the error class (e.g. `ts2322-string-to-number`, `jest-module-not-found`).
- **Fill placeholders** with real values from steps 1–7. Never ship a template with `<...>` still in it.

This artifact is what makes the loop **recursive across sessions**: the next agent (or the same agent next week) can pick up the file and execute the fix without re-doing the investigation.

### 9. Final audit (mandatory)
Produce a short report answering ALL of:

- What was the failure (one sentence)?
- What was the root cause (one sentence)?
- What class (from step 3)?
- What changed (file:line list)?
- What verification ran (command + result)?
- What rule was persisted (file + one-line rule)?
- What fix-prompt was generated (path)?
- What risk remains?

Without the audit AND the fix-prompt, the loop is not closed.

---

## Escopo de escrita (write scope)

This skill MAY propose or edit:

- This `SKILL.md` (anti-patterns, protocol refinements).
- Project rule files: `docs/rules/*.md`, `docs/ai/rules/*.md`, `AGENTS.md`, `CLAUDE.md`.
- Test files that reproduce the original error.
- Evals in this plugin (`evals.json`).
- Fix-prompt artifacts under `.error-fixer-loop/` (always allowed; never requires confirmation).

This skill MUST NOT:

- Rewrite unrelated rules or remove guardrails.
- Change security/permission policy without explicit user confirmation.
- Mask a failing test to make verification pass.
- Delete a pre-existing failing test without documenting why.
- Use `as any`, `@ts-ignore`, `eslint-disable` or equivalent **to silence** an error without an inline `// justified: <reason>` comment and a rule entry.

---

## Anti-patterns (hard no)

- ❌ Concluding with "fixed" but no test run.
- ❌ Concluding without generating the fix-prompt artifact in `.error-fixer-loop/`.
- ❌ Shipping a fix-prompt with unfilled `<placeholders>`.
- ❌ Adding a rule based on personal preference (no evidence).
- ❌ Widening scope because "we might need it later".
- ❌ Removing a guardrail to reach "done" faster.
- ❌ Accepting a green test that does not cover the original failure.
- ❌ Writing a rule longer than one operational sentence.
- ❌ Updating the skill when the learning belongs to the project (and vice-versa).

---

## Recursive improvement criteria

Update **this** `SKILL.md` only when ALL are true:

1. The current protocol allowed a repeatable failure.
2. The new rule is short and generalizable across projects.
3. The change reduces future ambiguity.
4. There is verification or evidence supporting it.

Update a **project** rule file when the learning is project-specific (e.g., "in this repo, blog posts need both `index.md` and `index-pt-br.md`").

Create an **eval** (`evals.json`) when the failure can be simulated (e.g., "agent concludes without running tests", "agent uses `as any`").

---

## Hook integration

Three hooks auto-detect build/test errors in bash output and inject a reminder to run this loop:

- **Claude Code**: `hooks/error-fixer-loop-hook.sh` — register as `PostToolUse` on `Bash`. Plain-text output; Claude Code only.
- **Codex**: `hooks/error-fixer-loop-codex.py` — register as `PostToolUse` on `Bash` in `~/.codex/hooks.json`. Prints nothing when clean, valid `hookSpecificOutput` JSON on error. Never register the `.sh` hook in Codex — Codex rejects plain-text hook output with `hook returned invalid post-tool-use JSON output`.
- **OpenCode**: `hooks/error-fixer-loop.ts` — plugin listening on `tool.execute.after`.

All are passive: they only emit a reminder. They never block, never mutate the tool result, never auto-run the fix.

Detected patterns (extend via `ERROR_PATTERNS` in the TS hook or the regex in the shell hook):

- TypeScript: `error TS\d+`
- Module resolution: `Cannot find module`, `Module not found:`, `Unable to find a specification for`
- Build: `BUILD FAILED`, `GRADLE.*FAILED`, `npm ERR!`, `pod install.*fail`
- Tests: `Test Suites:.*[1-9]\d* failed`, `Tests:.*[1-9]\d* failed`, `jest.*FAIL`
- iOS/RN: `NitroModules.*not found`
- Python: `ModuleNotFoundError`, `ImportError`, `AssertionError`, `FAILED tests/`
- Go: `FAIL\s+\S+`, `undefined:`, `cannot find package`
- Rust: `error\[E\d+\]`, `panicked at`
- Java/Kotlin: `BUILD FAILURE`, `Compilation failure`, `> Task .* FAILED`

Add new patterns only when you have seen them fire in the wild — not speculatively.

---

## Layered feedback model

Do not pile every learning into this file. Four layers:

1. **Execution** — the current task (tools, commands, files).
2. **Verification** — tests, typecheck, lint, evals.
3. **Operational memory** — `docs/rules/`, `AGENTS.md`, this `SKILL.md`.
4. **Harness evolution** — new tools, permission changes, new evals, dispatch tweaks.

Layer 4 is the most sensitive. Changes there must be small, verified, and reversible.

---

## References

- Article: https://lemon.dev.br/pt/blog/skill-recursiva-feedback-loop-harness
- Legacy hook: `~/.claude/hooks/error-fix-loop-hook.sh` (replaced by `hooks/error-fixer-loop-hook.sh`)
- Companion skill: `bug-diagnostics` (deep repro/hypothesis work when step 2 stalls)
- Harness rules: `~/.config/opencode/AGENTS.md` (global), project `AGENTS.md` (local)
Files in this package (13)
  • README.md 4 KB
  • SKILL.md 10 KB
  • evals.json 4 KB
  • plugin.json 1 KB
  • agents/error-fixer-loop-runner.md 4 KB
  • hooks/error-fixer-loop-codex.py 3 KB
  • hooks/error-fixer-loop-hook.sh 2 KB
  • hooks/error-fixer-loop.ts 3 KB
  • scripts/detect-error.sh 1 KB
  • scripts/install.sh 4 KB
  • templates/audit.md 1 KB
  • templates/fix-prompt.md 5 KB
  • templates/rule-entry.md 1 KB

Versions

The database has no other skills named error-fixer-loop.

Database snapshot: 13.11.2026 · package version 418238a8b244 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100gate
    (forwward) Runs lint, typecheck, build, and test in a self-healing loop that reads errors, fixes them, and retries up to 4 times. Triggers on verify, check, make sure it works, pre-commit validation, pre-deploy checks, or any quality gate.
  • 100bugfix
    Use when a bug is reported, something is broken, an error or crash needs fixing, a wrong output appears, or a regression shows up — guides Grimoire's Reproduce → Root-Cause → failing-test-FIRST → Fix → Verify discipline and will not let the fix begin until a failing regression…
  • 100build-until-pass
    Use when a build, typecheck, lint, or test command is failing and you want the agent to drive it to green on its own — run the check, read the errors, apply the smallest fix, re-run, repeat until exit code 0. Stops the human from being the while-loop (run → read error → fix one…
  • 90root-cause-fixer-workflow
    Use when concrete failure evidence requires root-cause analysis, minimal patching, and regression proof as the Root Cause Fixer.
  • 100heal
    Use when build/test/lint/typecheck is failing and the user wants automatic recovery. Self-healing loop — retries with DIFFERENT strategies, not the same one twice. Bounded retry count.
  • 90lint-fixer
    Use this skill to run npm run lint and fix linting issues. Triggers on fixing lint errors after code changes or validating code against project style guidelines.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.