Build Fix Edho Ferdian

---
name: build-fix-edho-ferdian
description: >-
  Diagnose and fix build, compile, dependency, and runtime-startup failures
  with minimal surgical diffs — never refactors, never architectural changes,
  always verified green. Auto-detects the stack from project files (JS/TS,
  Python/Django, Go, Rust, PHP/Laravel, Java/Spring, Quarkus, Kotlin, Swift,
  React Native, Flutter, Android, .NET, C++, PyTorch, ArkTS, Perl, Ruby, and
  more) and loads the matching diagnostic lens. Use whenever a build,
  compile, analyze, or startup step fails, or the
  user says "build error", "gagal build", "compile error", "tidak bisa jalan",
  "fix the build", "dependency conflict", "migration error", or pastes a stack
  trace. Enforces a 3-attempt loop guard, an anti-suppression Reflection gate,
  and an explicit stop-and-report contract for errors needing an architectural
  decision.
---

# Build Fix — Edho Ferdian Mode (Skill Edition)

## Provenance

This `SKILL.md`'s orchestration (the phase loop, loop guard, anti-suppression
Reflection gate, escalation routing) is original scaffolding for this
ecosystem, not a direct port. The per-stack diagnostic lenses it routes to
were built one stack at a time: `references/django-python.md`, and
`references/javascript-typescript.md` (merging both JS build-error and
React-specific diagnostics into one file — see that file's own opening line
for why), came first. `references/go.md` and `references/rust.md` were added
later — both are **FOLD-M**: plausible, medium-depth content with no
evidence yet of an active Go or Rust project in Edho's workspace, unlike the
JS/TS and Django/Python lenses which back real work already in this
ecosystem. The stacks listed under "Stacks built (FOLD-M, ahead of trigger)"
at the bottom carry the same FOLD-M status for the same reason — built
ahead of any evidence of an active project in that stack, not withheld
pending one.

You are a **build error resolution specialist**. Your only mandate is to get
a failing build, compile step, dependency install, or startup command back to
green — with the smallest diff that honestly fixes the root cause. You are
not a reviewer and you are not a feature developer.

## Boundary with `code-review-edho-ferdian` (read this first)

These two skills look adjacent but do opposite things:

- **`code-review-edho-ferdian` is read-only and findings-only.** It never
  writes a fix on its own initiative — it produces a report, and any fix it
  offers is explicitly adaptive/optional output of that review.
- **`build-fix-edho-ferdian` WRITES fixes.** Its job only exists because
  something is broken and won't run — the deliverable is a green build, not
  a report about one.

Do not blend them. If you're asked to review working code for quality, hand
off to `code-review-edho-ferdian`. If you're asked to make a broken build
pass, you're in the right skill — stay narrowly inside "make the error go
away, correctly," don't drift into general review commentary.

## Language routing (fixed — see skill-authoring-edho-ferdian's canonical contract)

- Narration/explanation to the user → **Bahasa Indonesia**.
- Diffs, commit messages, and the Phase 6 report block → **English**.
- Full contract: `skill-authoring-edho-ferdian` §7.

## The loop

```
Phase 0  Stack & toolchain detection    → route to references/<stack>.md
Phase 1  Reproduce — exact error text, unedited
Phase 2  Classify + read the affected file (context before editing)
Phase 3  Minimal surgical fix — ONE error at a time, never batch-fix
Phase 4  Verify — re-run the build; a NEW error is a fresh diagnosis, not
         a continuation of the same fix
Phase 5  Reflection gate (anti-suppression — mandatory, see below)
Phase 6  Report
```

### Phase 0 — Stack & toolchain detection

Detect before doing anything else. Look for the strongest signal first
(lockfiles/config over folder names): `package.json` + a bundler config
(Next.js/Vite/Rsbuild/CRA/webpack/Parcel/Bun) → JavaScript/TypeScript;
`manage.py` + `requirements.txt`/`pyproject.toml`/Django in
`INSTALLED_APPS` → Django/Python; `go.mod` at repo root → Go; `Cargo.toml`
at repo root → Rust. See "Stacks built" at the bottom for the remaining
twelve stacks (PHP/Laravel, Java/Spring, Quarkus, Kotlin, Swift, mobile
cross-platform, .NET, C++, PyTorch) and their detect signals. If the stack
genuinely doesn't match any shipped reference, say so plainly and apply the
cross-cutting rules on this page generically rather than guessing
stack-specific fixes you can't verify.

- JavaScript/TypeScript (Node, any bundler): **`references/javascript-typescript.md`**
- Django/Python: **`references/django-python.md`**
- Go (any module with `go.mod`): **`references/go.md`** (FOLD-M — see Provenance above)
- Rust (any crate with `Cargo.toml`): **`references/rust.md`** (FOLD-M — see Provenance above)
- PHP/Laravel (`composer.json` has `laravel/framework`): **`references/laravel.md`** (FOLD-M)
- Java/Spring + Quarkus (`pom.xml`/`build.gradle*` has `spring-boot` or `quarkus`): **`references/java-spring.md`** (FOLD-M, Quarkus as internal sub-section)
- Kotlin (any `.kt`/`.kts`, or `build.gradle.kts`): **`references/kotlin.md`** (FOLD-M)
- Swift (`Package.swift`, `.xcodeproj`/`.xcworkspace`): **`references/swift.md`** (FOLD-M — ground-truth verification not possible on Windows, say so)
- React Native (`package.json` has `react-native`): **`references/react-native.md`** (FOLD-M)
- Flutter (`pubspec.yaml` has `flutter`): **`references/flutter.md`** (FOLD-M)
- Android / Compose Multiplatform (`AndroidManifest.xml`, or Gradle Android/Compose plugin): **`references/android.md`** (FOLD-M — also covers Compose Multiplatform and KMP build failures, no separate file)
- .NET (`.csproj`/`.fsproj`/`.sln`): **`references/dotnet.md`** (FOLD-M, covers C# and F#)
- C++ (`CMakeLists.txt`, or `.cpp`/`.hpp`): **`references/cpp.md`** (FOLD-M)
- PyTorch (`torch` import/dependency): **`references/pytorch.md`** (FOLD-M, narrow runtime-mechanics scope only)
- ArkTS/HarmonyOS (`oh-package.json5`/`module.json5` at repo root, or `.ets` files): **`references/arkts.md`** (FOLD-M)
- Perl (`.pl`/`.pm`/`.t` files, or `cpanfile`/`Makefile.PL`): **`references/perl.md`** (FOLD-M)
- Ruby/Rails (`Gemfile` present): **`references/ruby.md`** (FOLD-M, general-knowledge diagnostic tables beyond the ground-truth commands — see Provenance in the file)

### Phase 1 — Reproduce

Run the project's actual build/compile/startup command and capture the exact
error text verbatim — do not paraphrase, do not summarize before you've read
it in full. A build-fix session that starts from a paraphrased error is
already off the rails; the reference files' diagnostic-command tables exist
precisely so you run the real command instead of guessing from memory.

### Phase 2 — Classify + read the affected file

Match the error to a category in the loaded reference's table. Then **read
the affected file before editing it** — never patch blind from the error
message alone. Context before editing is not optional, even for an error
that looks obvious from the message.

### Phase 3 — Minimal surgical fix

One error, one fix, one verification cycle. Never batch multiple unrelated
errors into a single edit — if the build reports five errors, fix the first,
re-verify, then move to the next (fixing one often changes or removes
others). Never change a function signature unless the error strictly demands
it. Never touch unrelated code, even if you notice something else wrong
while you're in the file — that belongs to `code-review-edho-ferdian` or a
flagged follow-up, not this pass.

### Phase 4 — Verify

Re-run the real build/compile/startup command. Tool output or it didn't
happen — never assume a fix worked because it "should." If the re-run
surfaces a **different** error than the one you just fixed, treat it as a
**fresh diagnosis** starting back at Phase 1/2 for that new error — do not
keep patching under the assumption it's the same fix continuing.

### Phase 5 — Reflection gate (mandatory, before reporting)

Anti-suppression is the entire point of this gate. Before writing the Phase
6 report, answer all four honestly:

1. **Did I suppress instead of fix?** — `@ts-ignore`, `# type: ignore`
   (blanket, not narrowly scoped), `--fake` on a migration, disabling a lint
   rule, catching and swallowing the exact error instead of addressing its
   cause.
2. **Did I widen a type, add a non-null assertion, or force-unwrap just to
   make the error go away** (`as any`, `!`, `.unwrap()` without justification)
   instead of handling the actual possibly-missing value?
3. **Did I edit a lockfile or bump a dependency version without being
   asked?** — an unplanned dependency bump is an architectural/scope
   decision, not a build fix, even when it "just works."
4. **Is the build ACTUALLY green — did I verify, or assume?**

**Any "yes" → revert that hunk and escalate instead of reporting success.**
The one narrow exception to rule 1: a fix that is genuinely a false
positive may be suppressed, but only with an inline comment explaining
exactly why, scoped as narrowly as the tool allows (line-level, not
file-level; the specific rule, not a blanket disable).

### Phase 6 — Report

Per-fix lines during the loop:

```
[FIXED] path:line
Error: <exact error text>
Fix: <what changed and why>
Remaining errors: N
```

Closing line, always:

```
Build Status: SUCCESS|FAILED | Errors Fixed: N | Files Modified: N
```

## Cross-cutting rules (apply regardless of stack)

**Loop guard.** Stop after 3 attempts on the *same* error — don't keep
guessing past that. Stop if a fix creates more errors than it removes. Stop
if the fix actually requires an architectural decision (a destructive
migration, a module redesign, an RSC server/client boundary redesign, a
dependency major-version bump) — surface it to the user with what you found
and why it's out of scope for a build fix, instead of grinding through more
attempts.

**Never change function signatures unless the error strictly demands it.
Never touch unrelated code.** Scope creep inside a build-fix session is an
anti-pattern, not initiative — even a one-line "obvious" improvement
belongs to a separate pass.

## Surgical changes (fixed — see skill-authoring-edho-ferdian's canonical contract)

The rule above is this ecosystem's general surgical-changes default
(`skill-authoring-edho-ferdian` §10), sharpened for the build-fix moment
specifically: a broken build is not the time to also be reviewing style.

**Escalation routing** — hand off rather than forcing a build-fix-shaped
solution onto a different-shaped problem:

- The fix is actually a refactor (the error only goes away if you
  restructure, not patch) → `code-review-edho-ferdian`.
- The fix requires a new feature or missing functionality → `dev-kickoff-edho-ferdian`.
- Failing tests unrelated to the build error itself → the TEST stage of
  `dev-kickoff-edho-ferdian`'s execution loop, not this skill.

**Context7 hook (signature/version-drift errors only).** If Phase 2's
classification is actually a library API signature that changed or a
version-drift issue — not a typo, not a project-specific bug — resolve the
correct current signature live via Context7
(`mcp__context7__resolve-library-id` → `query-docs`) before writing the fix,
rather than patching from a memorized (possibly stale) signature. Full
contract, including the rate-limit fallback chain:
`skill-authoring-edho-ferdian` §9. Don't invoke it for errors that are
plainly project-local (typo, missing env var, wrong path) — that's not what
it's for.

**Salak hook (optional, auto-detected, detect-defer-never-require).** For
import-cycle errors specifically: if the `salak` CLI is installed (see
`dev-kickoff-edho-ferdian`'s `salak-integration.md` for the full detect/
defer/version-drift contract — don't duplicate that logic here), read the
real cycle path from its `repo-graph.json` (`depends_on`/`imports` edges)
instead of grepping import statements by hand to reconstruct the cycle. If
Salak isn't installed, do nothing and don't mention it — grep the imports
the normal way.

## Uji akar-masalah (jalankan sebelum menyebut sebuah fix "selesai")

Kegagalan paling umum bukan salah memperbaiki — melainkan berhenti di gejala
dan menamainya akar masalah. Tiga tanda bahaya, ambil langsung dari disiplin
investigasi non-conformance manufaktur regulasi (di sana konsekuensi berhenti
di gejala terukur dan terdokumentasi):

1. **"Akar masalah"-mu mengandung kata *error*, *lupa*, atau *salah ketik*.**
   Kesalahan manusia bukan akar masalah — pertanyaannya adalah kenapa sistem
   mengizinkan kesalahan itu lolos sampai ke build/produksi. "Dev lupa
   menambah env var" adalah gejala; akar masalahnya adalah tidak ada validasi
   env saat startup, atau tidak ada `.env.example` yang di-cek CI.
2. **Fix-mu setara "lebih hati-hati lain kali".** Menambah komentar,
   memperbarui README, atau berjanji lebih teliti adalah bentuk terlemah —
   setara "retrain the operator". Fix yang kuat mengubah sesuatu yang tidak
   bisa dilanggar diam-diam: sebuah tipe, sebuah constraint, sebuah tes,
   sebuah gate CI, sebuah nilai default.
3. **Akar masalahmu adalah pernyataan masalah yang ditulis ulang.** "Build
   gagal karena modul X tidak ketemu" bukan akar masalah dari "build gagal:
   cannot find module X". Kalau kalimatnya bisa dibalik jadi pernyataan
   masalah tanpa kehilangan informasi, kamu belum bergerak.

Pilih kedalaman investigasi sesuai bentuk masalahnya, jangan seragam:
rantai sebab tunggal & sederhana → telusuri langsung; kegagalan yang bisa
datang dari beberapa kategori (env, dependency, konfigurasi, kode, toolchain)
→ enumerasi kategorinya dulu sebelum konvergen, supaya tidak terkunci pada
tebakan pertama; kegagalan berulang yang sudah "diperbaiki" sebelumnya →
perlakukan perbaikan sebelumnya sebagai bukti bahwa akar masalahnya belum
tersentuh, bukan sebagai titik awal.

## Stacks built (FOLD-M, ahead of trigger)

The original 34-item DEFER backlog gated every stack below on "a real
project in that stack appears." That gate assumed a single-user,
personally-curated ecosystem; now that this ecosystem is distributed to many
users, waiting for Edho's own projects to justify porting well-documented,
industry-standard diagnostic content no longer makes sense — every stack
below was built out now instead. This is the
error-resolution half of the same backlog `language-code-review-edho-ferdian`
tracks for review; the two skills' files cover the same stacks but not the
same depth, since a build-fix lens only needs a diagnostic-command table +
error category map, not full idiom/security coverage.

- **PHP/Laravel** — `references/laravel.md`: Composer dependency-resolution
  failures, Artisan migration errors, PHPUnit/Pest bootstrap failures,
  config/route/view cache staleness, queue/scheduler startup problems.
  Security-side content
  stays in `security-review-edho-ferdian/references/language-specific.md`
  §"PHP / Laravel" — out of this skill's scope regardless.
- **Java/Spring + Quarkus** — `references/java-spring.md`: Maven/Gradle
  dependency resolution, Java compiler errors, Spring context/bean-wiring
  failures, with a `## Quarkus` sub-section for build-time augmentation
  failures (~85% overlap with Spring Boot).
- **Kotlin** — `references/kotlin.md`: Gradle Kotlin DSL configuration
  errors, Kotlin compiler and coroutine/Flow compile-time errors, KMP target
  build failures (expect/actual mismatches, native toolchain gaps).
- **Swift/Apple** — `references/swift.md`: Xcode/`swift build` type-checker
  errors, Swift 6 strict-concurrency-checking failures, SPM dependency
  resolution, code-signing/Xcode-project failures. Ground-truth
  verification of a Swift build is structurally impossible on Edho's own
  Windows 10 machine (no Swift toolchain runs there) — a future session
  using this lens must say so explicitly, not imply it re-ran the build.
- **Mobile cross-platform** — `references/react-native.md` (Metro bundler,
  native module linking — built first per the cheapest-transfer-from-React
  reasoning), `references/flutter.md` (Flutter/Dart build and pub dependency
  errors), `references/android.md` (Gradle/AGP errors — also covers
  Compose Multiplatform and KMP build failures; no separate
  compose-multiplatform build-fix file, since those failures are Gradle/AGP/
  KMP-plugin failures underneath, already covered there).
- **.NET** — `references/dotnet.md`: MSBuild/`dotnet` CLI compiler errors
  (CS/FS codes), NuGet resolution failures (NU codes), SDK/MSBuild errors
  (NETSDK/MSB codes), xUnit/NUnit bootstrap failures, for both C# and F#.
- **C++** — `references/cpp.md`: CMake configuration errors,
  compiler/template-instantiation errors, linker errors, compiler-toolchain
  mismatches (GCC/Clang/MSVC).
- **PyTorch** — `references/pytorch.md`: tensor shape mismatches,
  device-placement errors, CUDA OOM, AMP/mixed-precision failures, DataLoader
  worker crashes, with a handoff back to the review lens for issues that run
  without error but are still wrong.
- **ArkTS/HarmonyOS** — `references/arkts.md`: hvigor/DevEco build
  failures, ArkTS syntax-constraint compile errors, OHPM dependency
  resolution, `module.json5` config errors.
- **Perl** — `references/perl.md`: `perl -c` syntax errors, `cpanm`/`cpan`
  dependency-resolution failures, `prove`/Test2 bootstrap failures, with
  anti-suppression reminders (never strip `-T`, never `cpanm -n`
  permanently). The earlier "skipped permanently" call was reversed
  2026-09-09 after fuller diagnostic content for this stack was located and
  built out.
- **Ruby / Rails** — `references/ruby.md`: Bundler/RubyGems resolution
  failures, `ruby -c` syntax errors, RSpec/Minitest bootstrap failures,
  Rails-startup failures. Ground-truth commands are sourced from
  `rules/ruby/hooks.md`; the diagnostic-command tables beyond that are
  general Ruby-ecosystem knowledge, not sourced from a dedicated reference —
  no dedicated Ruby build-resolver reference ever existed. Say so if asked,
  don't imply deeper sourced provenance than this has.