Claude Code Build Error Triage Loop: Narrow the Cause in 15 Minutes

Split the build error before asking for a fix

When a Node or Astro build fails, it is tempting to paste the full log and ask Claude Code to fix everything. That often mixes the first failing line, the likely cause, and unrelated cleanup.

This loop applies the bug report template and the review workflow checklist to build failures. The target is a narrowed cause, a small diagnostic, and proof after the fix.

Capture evidence in the same order

Use the same order every time: state, build, and test when needed.

git status --short
npm.cmd run build
npm.cmd run test -- --runInBand

The goal is not to make the first run pass. The goal is to preserve the first failing line. The first failure is usually closer to the root cause than the final stack trace noise.

Classify the log into four buckets

The classifier does not need to be perfect. Dependency/import path, runtime shape mismatch, test expectation drift, and permission boundary cover many daily failures.

const patterns = [
  [/Cannot find module|ERR_MODULE_NOT_FOUND/i, "dependency or import path"],
  [/TypeError:.*undefined|undefined is not/i, "runtime null or shape mismatch"],
  [/Expected.*received|AssertionError/i, "test expectation drift"],
  [/EACCES|permission denied/i, "permission or sandbox boundary"],
];

export function classifyBuildLine(line) {
  const hit = patterns.find(([regex]) => regex.test(line));
  return hit ? hit[1] : "needs manual reading";
}

Even this small split changes the prompt. You can ask Claude Code for the smallest diagnostic instead of a broad repair.

Copyable triage prompt

Read this failing build log.
Do not suggest broad refactors.
Return:
1. first failing line
2. likely cause
3. smallest diagnostic command
4. smallest code or config fix
5. proof command after the fix

The key line is “Do not suggest broad refactors.” Build triage works best when each change has one hypothesis and one proof command.

Failure case: upgrading dependencies too early

A common failure is adding a package after “Cannot find module”, or sprinkling null checks after “undefined”. If the true cause is an import path, frontmatter mismatch, or generated file issue, those fixes add noise.

For public content sites, another failure is stopping at a successful local build. A revenue path needs public URL, correct h1, canonical, CTA, and Gumroad link checks.

Revenue path

Use the free cheatsheet for command recall. Buy 50 Prompt Templates if you want reusable debugging and review prompts now. Use the Setup Guide and consultation when CI/CD, deploy gates, and production verification need a stronger operating system.