Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Understand how build-failure diagnosis works and how to use it responsibly alongside raw evidence.

​
Prerequisites

  • A failed build to inspect
  • An active paid plan for LLM-backed analysis (pattern matching is always available)

​
Workflow

1
When a build fails, StackShift analyzes it automatically and attaches a diagnosis.
2
Read the root cause, category, stage, and suggested fix steps.
3
Hand the diagnosis to the debug agent to turn it into a confirmable code-fix PR or a redeploy.
4
Cross-check against the raw build logs before acting on anything non-trivial.

​
How diagnosis works

Diagnosis runs in two layers. First a pattern matcher checks the failure against a library of known build-error signatures and StackShift build-error reports, which is fast and deterministic. When patterns are not enough, LLM analysis (Anthropic Claude) reasons over the logs to produce a root cause. Either way the result is a structured diagnosis: a category, the build stage it failed at, a confidence score, the root cause, suggested fix steps, the error location when it can be pinpointed, and related docs.

​
Pattern matching vs LLM analysis

  • Pattern matching is always on and covers common, well-understood failures.
  • LLM analysis handles novel or messy failures and requires an active paid plan.
  • Confidence is reported on every diagnosis — treat low-confidence results as a hint, not a conclusion.

​
What it should not replace

  • Direct build and runtime logs.
  • Resource status and recovery-state evidence.
  • Operator judgment when the diagnosis and the raw evidence disagree.

​
Expected result

You get a fast, structured starting point for a failed build and treat it as evidence to verify, not a guaranteed answer.

​
Common failures

  • LLM-backed analysis is unavailable without an active paid plan — you still get pattern-based diagnosis.
  • Low-confidence diagnoses on unusual failures — fall back to reading the build logs directly.

StackShift AI agents

StackShift runs specialized agents that can create projects, fix failed builds, manage databases, triage incidents, and operate WordPress — each one proposing a confirmable action before anything changes.

Builds, deployments, and logs

Understand the project execution lifecycle: build output, deploy state, rollback behavior, and where to inspect logs.

Project troubleshooting

Common project-side failure modes, especially when the app built successfully but does not come up healthy.