patchrail 0.1.0__tar.gz → 0.1.1__tar.gz

{patchrail-0.1.0 → patchrail-0.1.1}/CHANGELOG.md

@@ -1,7 +1,25 @@
 # Changelog
 
+## 0.1.1 - 2026-06-12
+
+- `ci explain` now ends text and Markdown reports with a `Guide:` link to the
+  matching getpatchrail.com `/fix` remediation page; unknown or unpublished
+  failure classes fall back to the `/fix` index without a network call.
+- Added `funded-issues fresh`, a local read-only radar over the tracker store
+  that surfaces recently posted or recently labeled funded issues for fast
+  solver-side triage.
+- Added `pre_commit_hook_failure` CI classification so pre-commit hook output is
+  recognized directly while the CLI still avoids linking to a missing `/fix`
+  page until that guide exists.
+
 ## 0.2.0 - draft
 
+- `ci explain` now ends every report with a `Guide:` link to the matching
+  remediation write-up on getpatchrail.com (`/fix/<failure-class>`, with
+  `utm_source=cli`). Unknown or unlisted failure classes link to the `/fix`
+  guide index instead. The link appears in both the text and Markdown formats;
+  JSON output is unchanged. Classification stays fully local -- the URL is
+  constructed from the failure class, with no network call.
 - Added a permanent source-level blocklist to the funded-issues tracker:
   owners manually verified as fake-bounty sources are dropped at the
   `merge_into_store` choke point (counted as `blocked` in the merge summary)

{patchrail-0.1.0 → patchrail-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchrail
-Version: 0.1.0
+Version: 0.1.1
 Summary: Local-first maintainer automation for open-source CI triage
 Project-URL: Homepage, https://github.com/patchrail/patchrail
 Project-URL: Documentation, https://github.com/patchrail/patchrail/tree/main/docs
@@ -39,10 +39,27 @@ PatchRail does not auto-submit pull requests, claim funded issues, or comment on
 third-party repositories. It produces evidence and reviewable suggestions so
 maintainers stay in control.
 
+## Companion guide
+
+**CI Failure Triage Patterns** — a field guide covering 31 CI failure classes
+with the signals that distinguish them and the narrow fix for each. It pairs
+directly with the `patchrail ci explain` classifier in this repo:
+[patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage).
+
+Read the per-class fixes here: **[docs/fix/](docs/fix/README.md)** — each page lists
+the literal log signatures, what actually happened, and the step-by-step fix.
+
 ## Quickstart
 
 ### 10-second reviewer demo
 
+![patchrail ci explain reading a failed CI log and emitting root cause, confidence, reproduce command, and a fix Guide URL](docs/assets/ci-explain-demo.gif)
+
+`patchrail ci explain` reads a failed CI log and prints the root cause, a
+confidence score, a one-line reproduce command, and a `Guide:` link to the
+matching fix page. The screenshot above is real output from the bundled
+`examples/ci-triage/typescript-import-type-drift.log` fixture.
+
 No install is required to inspect the current behavior. The versioned demo at
 [examples/ci-triage/demo-output.md](examples/ci-triage/demo-output.md) is real
 CLI output from the bundled `examples/ci-triage/dependency-failure.log` fixture,
@@ -69,8 +86,13 @@ The versioned no-install transcript is available at
 [examples/control-plane-demo/demo-output.md](examples/control-plane-demo/demo-output.md),
 and tests regenerate it to prevent drift.
 
-PyPI publishing is pending, so do not use `pipx install patchrail` yet. Until
-the package is on PyPI, run the public GitHub source directly:
+PatchRail is published on PyPI, so the fastest install is:
+
+```bash
+pipx install patchrail
+```
+
+You can also run the latest source directly without installing:
 
 ```bash
 uvx --from git+https://github.com/patchrail/patchrail patchrail --help
@@ -78,7 +100,7 @@ printf 'python -m pytest -q\nFAILED tests/test_app.py::test_ok - AssertionError\
   | uvx --from git+https://github.com/patchrail/patchrail patchrail ci explain
 ```
 
-That pre-PyPI smoke test prints:
+That smoke test prints:
 
 ```markdown
 # PatchRail CI Report
@@ -88,6 +110,7 @@ That pre-PyPI smoke test prints:
 - Subsystem: Python tests
 - Reproduce: `python -m pytest -q`
 - Suggested action: Reproduce the failing test, patch the narrow behavior drift, and rerun the focused pytest node before broad test runs.
+- Guide: https://getpatchrail.com/fix/python-test-failure?utm_source=cli&utm_campaign=python-test-failure
 
 ## Evidence signals
 
@@ -141,6 +164,28 @@ Example output:
 - Reproduce: `python -m pip install -r requirements.txt`
 - Suggested action: Pin or relax the conflicting dependency range, then rerun
   the same install command and the affected tests.
+- Guide: https://getpatchrail.com/fix/python-dependency-resolution?utm_source=cli&utm_campaign=python-dependency-resolution
+```
+
+Every `ci explain` report ends with a `Guide:` link to the matching
+[getpatchrail.com/fix](https://getpatchrail.com/fix?utm_source=cli) remediation
+page (the guide index when the failure class is `unknown`), so the same command
+that classifies a failure also points to the full write-up.
+
+## GitHub Action
+
+Drop the same triage into any workflow with
+[`patchrail/ci-triage-action`](https://github.com/patchrail/ci-triage-action).
+On a red run it classifies the log locally and links the matching
+[getpatchrail.com/fix](https://getpatchrail.com/fix) guide — no PR, no comment,
+nothing leaves the runner:
+
+```yaml
+- name: PatchRail CI triage
+  if: failure()
+  uses: patchrail/ci-triage-action@v1
+  with:
+    log-path: test.log
 ```
 
 ## Why maintainers use PatchRail

{patchrail-0.1.0 → patchrail-0.1.1}/README.md

@@ -9,10 +9,27 @@ PatchRail does not auto-submit pull requests, claim funded issues, or comment on
 third-party repositories. It produces evidence and reviewable suggestions so
 maintainers stay in control.
 
+## Companion guide
+
+**CI Failure Triage Patterns** — a field guide covering 31 CI failure classes
+with the signals that distinguish them and the narrow fix for each. It pairs
+directly with the `patchrail ci explain` classifier in this repo:
+[patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage).
+
+Read the per-class fixes here: **[docs/fix/](docs/fix/README.md)** — each page lists
+the literal log signatures, what actually happened, and the step-by-step fix.
+
 ## Quickstart
 
 ### 10-second reviewer demo
 
+![patchrail ci explain reading a failed CI log and emitting root cause, confidence, reproduce command, and a fix Guide URL](docs/assets/ci-explain-demo.gif)
+
+`patchrail ci explain` reads a failed CI log and prints the root cause, a
+confidence score, a one-line reproduce command, and a `Guide:` link to the
+matching fix page. The screenshot above is real output from the bundled
+`examples/ci-triage/typescript-import-type-drift.log` fixture.
+
 No install is required to inspect the current behavior. The versioned demo at
 [examples/ci-triage/demo-output.md](examples/ci-triage/demo-output.md) is real
 CLI output from the bundled `examples/ci-triage/dependency-failure.log` fixture,
@@ -39,8 +56,13 @@ The versioned no-install transcript is available at
 [examples/control-plane-demo/demo-output.md](examples/control-plane-demo/demo-output.md),
 and tests regenerate it to prevent drift.
 
-PyPI publishing is pending, so do not use `pipx install patchrail` yet. Until
-the package is on PyPI, run the public GitHub source directly:
+PatchRail is published on PyPI, so the fastest install is:
+
+```bash
+pipx install patchrail
+```
+
+You can also run the latest source directly without installing:
 
 ```bash
 uvx --from git+https://github.com/patchrail/patchrail patchrail --help
@@ -48,7 +70,7 @@ printf 'python -m pytest -q\nFAILED tests/test_app.py::test_ok - AssertionError\
   | uvx --from git+https://github.com/patchrail/patchrail patchrail ci explain
 ```
 
-That pre-PyPI smoke test prints:
+That smoke test prints:
 
 ```markdown
 # PatchRail CI Report
@@ -58,6 +80,7 @@ That pre-PyPI smoke test prints:
 - Subsystem: Python tests
 - Reproduce: `python -m pytest -q`
 - Suggested action: Reproduce the failing test, patch the narrow behavior drift, and rerun the focused pytest node before broad test runs.
+- Guide: https://getpatchrail.com/fix/python-test-failure?utm_source=cli&utm_campaign=python-test-failure
 
 ## Evidence signals
 
@@ -111,6 +134,28 @@ Example output:
 - Reproduce: `python -m pip install -r requirements.txt`
 - Suggested action: Pin or relax the conflicting dependency range, then rerun
   the same install command and the affected tests.
+- Guide: https://getpatchrail.com/fix/python-dependency-resolution?utm_source=cli&utm_campaign=python-dependency-resolution
+```
+
+Every `ci explain` report ends with a `Guide:` link to the matching
+[getpatchrail.com/fix](https://getpatchrail.com/fix?utm_source=cli) remediation
+page (the guide index when the failure class is `unknown`), so the same command
+that classifies a failure also points to the full write-up.
+
+## GitHub Action
+
+Drop the same triage into any workflow with
+[`patchrail/ci-triage-action`](https://github.com/patchrail/ci-triage-action).
+On a red run it classifies the log locally and links the matching
+[getpatchrail.com/fix](https://getpatchrail.com/fix) guide — no PR, no comment,
+nothing leaves the runner:
+
+```yaml
+- name: PatchRail CI triage
+  if: failure()
+  uses: patchrail/ci-triage-action@v1
+  with:
+    log-path: test.log
 ```
 
 ## Why maintainers use PatchRail

patchrail-0.1.1/docs/fix/README.md

@@ -0,0 +1,45 @@
+<!-- Canonical: https://getpatchrail.com/fix -->
+
+# CI Failure Triage — fix index
+
+A red build usually fails for one of a small number of reasons. Find the class that matches the error in your log, and follow the narrow fix for it. Each page lists the literal log signatures, what actually happened, and a step-by-step playbook.
+
+Canonical, formatted versions live at **[getpatchrail.com/fix](https://getpatchrail.com/fix)**.
+
+| Failure class | Top signature |
+| --- | --- |
+| [Runner resource exhaustion](runner-resource-exhaustion.md) | `Process completed with exit code 137` |
+| [Transient network failures](network-transient-failure.md) | `getaddrinfo EAI_AGAIN` |
+| [Job timeouts and cancellations](ci-job-timeout.md) | `has exceeded the maximum execution time of 360 minutes` |
+| [Python dependency resolution](python-dependency-resolution.md) | `Could not find a version that satisfies the requirement` |
+| [Coverage threshold failures](code-coverage-threshold.md) | `Required test coverage of 80% not reached` |
+| [Python type checking](python-type-check.md) | `Found 12 errors in 4 files` |
+| [Python lint and formatting](python-lint.md) | `F401 imported but unused` |
+| [Python test failures](python-test-failure.md) | `FAILED tests/test_x.py::test_name` |
+| [Node package installation](node-dependency-install.md) | `npm ci can only install packages when your package.json and package-lock.json` |
+| [TypeScript type checking](typescript-typecheck.md) | `error TS2339: Property 'x' does not exist on type` |
+| [JavaScript and TypeScript lint](javascript-lint.md) | `error  'x' is defined but never used  no-unused-vars` |
+| [Broken workflow wiring](github-actions-workflow.md) | `Invalid workflow file` |
+| [Artifact and cache failures](artifact-or-cache-failure.md) | `No files were found with the provided path` |
+| [Publish and release conflicts](release-publish-failure.md) | `You cannot publish over the previously published versions` |
+| [Checkout, clone, submodule, and LFS failures](git-checkout-failure.md) | `fatal: Authentication failed` |
+| [Merge and rebase conflicts](git-merge-conflict.md) | `Automatic merge failed; fix conflicts and then commit the result` |
+| [Missing secrets and insufficient permissions](secrets-or-permissions-failure.md) | `Error: Input required and not supplied` |
+| [Security scan failures](security-scan-failure.md) | `found 3 high severity vulnerabilities` |
+| [.NET build failures](dotnet-build-failure.md) | `error NU1605: Detected package downgrade` |
+| [Java build failures](java-build-failure.md) | `Unsupported class file major version 65` |
+| [Docker image build failures](docker-build-failure.md) | `failed to solve` |
+| [C/C++ native build failures](cpp-build-failure.md) | `fatal error: foo.h: No such file or directory` |
+| [Browser end-to-end test failures](browser-test-failure.md) | `Executable doesn't exist at /ms-playwright/chromium` |
+| [Rust test failures](rust-test-failure.md) | `error[E0308]: mismatched types` |
+| [Ruby Bundler failures](ruby-bundle-failure.md) | `Bundler could not find compatible versions for gem` |
+| [PHP Composer failures](php-composer-failure.md) | `Your requirements could not be resolved to an installable set of packages` |
+| [Go test failures](go-test-failure.md) | `--- FAIL: TestName` |
+| [Node test runner failures](node-test-failure.md) | `Tests:       2 failed, 18 passed` |
+| [Rust lint (clippy)](rust-lint.md) | `error: this `if` has identical blocks` |
+| [Go lint (golangci-lint)](go-lint.md) | `main.go:12:6: Error return value is not checked (errcheck)` |
+| [Terraform and IaC failures](terraform-iac-failure.md) | `Error acquiring the state lock` |
+
+---
+
+**Want all of them in one place, offline?** The [*CI Failure Triage Patterns* pack ($19)](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=index) bundles every class with downloadable playbooks plus the `patchrail` CLI.

patchrail-0.1.1/docs/fix/artifact-or-cache-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/artifact-or-cache-failure -->
+
+# Artifact and cache failures — No files were found with the provided path
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/artifact-or-cache-failure](https://getpatchrail.com/fix/artifact-or-cache-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+No files were found with the provided path
+an artifact with this name already exists
+Failed to CreateArtifact
+Cache service responded with 503
+reserveCache failed
+```
+
+## What actually happened
+
+The artifact/cache storage layer failed, for one of four reasons: a wrong path ("No files were found with the provided path" — the build put output somewhere else, or the build silently produced nothing), a name collision ("an artifact with this name already exists" — classic in matrix jobs all uploading "build"), a stale action version (v3→v4 of the artifact actions changed naming semantics and broke many pipelines), or a transient storage outage ("Cache service responded with 503"). Crucially, cache restore failures are non-fatal by design — a failed restore should slow the build down, never break it. If a failed restore breaks your build, the build has a hidden dependency on cache contents, and that's the real bug.
+
+## Fix it
+
+1. Identify which of the four causes you have from the signature.
+2. Wrong path: add ls -laR <path> just before the upload step. Nine times out of ten the build output simply isn't where the workflow thinks it is.
+3. Name collision in a matrix: suffix the artifact name with matrix variables — name: build-${{ matrix.os }}-${{ matrix.version }}.
+4. Storage 5xx: retry. It's their outage, not your bug.
+5. Bump pinned actions/upload-artifact / actions/download-artifact / actions/cache versions if they're more than a major behind. Do not change application code for this class.
+
+## Prevent it
+
+- Treat cache as an optimization, never a dependency: every job must pass from a cold cache. Test it occasionally by changing the cache key prefix.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=artifact-or-cache-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/browser-test-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/browser-test-failure -->
+
+# Browser end-to-end test failures — Executable doesn't exist / Timeout exceeded
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/browser-test-failure](https://getpatchrail.com/fix/browser-test-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+Executable doesn't exist at /ms-playwright/chromium
+browserType.launch: 
+Timeout 30000ms exceeded
+browser exited unexpectedly
+CypressError
+```
+
+## What actually happened
+
+E2E failures split into environment and test problems. Environment: "Executable doesn't exist" / "browserType.launch" errors mean the browser binary isn't installed in CI — for Playwright the classic miss is running npm ci but never npx playwright install --with-deps; "browser exited unexpectedly" is usually missing system libraries (headless Chrome needs a long list) or sandbox/SHM issues in containers. Test problems: "Timeout ...ms exceeded" on a locator(...) means the element never reached the expected state — either the app actually broke, the selector drifted from the DOM, or the test is racing the app (asserting before a network response settles).
+
+## Fix it
+
+1. Environment first: if the browser didn't launch, nothing else in the log matters. Add npx playwright install --with-deps (or the Cypress image) to CI and rerun.
+2. For locator timeouts, get artifacts before theorizing: Playwright traces (--trace on), screenshots and videos on failure. The trace shows the DOM at timeout — the answer is usually visible.
+3. Distinguish "element never appeared" (app or selector issue) from "element appeared then detached" (re-render race). The trace timeline tells you which.
+4. Fix races with web-first assertions that auto-wait (await expect(locator).toBeVisible()), never waitForTimeout(3000) — fixed sleeps are why the suite is flaky and slow.
+5. Selector drift: prefer role/test-id selectors (getByRole, data-testid) over CSS paths coupled to layout.
+
+## Prevent it
+
+- Run E2E against deterministic backends (seeded data, mocked third parties). Most "flaky E2E" is actually nondeterministic test data, not the browser.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=browser-test-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/ci-job-timeout.md

@@ -0,0 +1,41 @@
+<!-- Canonical: https://getpatchrail.com/fix/ci-job-timeout -->
+
+# Job timeouts and cancellations — exceeded the maximum execution time
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/ci-job-timeout](https://getpatchrail.com/fix/ci-job-timeout)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+has exceeded the maximum execution time of 360 minutes
+The operation was canceled
+Too long with no output
+ERROR: Job failed: execution took longer than
+ran longer than the maximum time of 60 minutes
+```
+
+## What actually happened
+
+Three distinct causes share these signatures, and telling them apart matters: a real time limit ("exceeded the maximum execution time") — the job is genuinely too slow, or it hung; matrix fail-fast cancellation ("The operation was canceled" on a job that was passing) — a sibling matrix job failed and CI killed the rest, so your job was innocent; output stall ("Too long with no output") — the process is alive but silent, usually a hung subprocess or a prompt waiting for input that will never come.
+
+## Fix it
+
+1. Check whether this job failed or was canceled because a sibling failed. If sibling: triage the sibling, ignore this log.
+2. If it's a real timeout, compare this run's step durations against the last green run. A step that went from 4 to 40 minutes is a hang, not slowness — look for an interactive prompt, a deadlock, or an unbounded retry loop inside it.
+3. If it's genuinely slow: cache dependencies, split the job, or parallelize the slowest step.
+4. Raise timeout-minutes only deliberately, with a comment saying why. A raised limit without a reason is a future 60-minute hang.
+
+## Prevent it
+
+- Set explicit timeout-minutes per job at a value just above normal duration (e.g. p95 × 2). The default (360 minutes on GitHub Actions) means a hang costs you six hours of runner time before anyone notices.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=ci-job-timeout)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/code-coverage-threshold.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/code-coverage-threshold -->
+
+# Coverage threshold failures — Required test coverage of N% not met
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/code-coverage-threshold](https://getpatchrail.com/fix/code-coverage-threshold)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+Required test coverage of 80% not reached
+fail_under
+Coverage for project (74%) does not meet
+is below the expected minimum coverage
+SimpleCov failed
+```
+
+## What actually happened
+
+All tests passed. The build failed because the coverage percentage fell under a configured threshold (fail_under, jest's coverageThreshold, SimpleCov's minimum, a coverage bot's project target). Mechanically this happens in two ways that feel unfair: you added well-tested code but it shifted file-level percentages, or — more often — you added a small amount of untested code to a small file, where one uncovered branch moves the percentage points. Occasionally the threshold breaks with no code change: a test that silently stopped running (collection error, renamed file not matching the test glob) lowers coverage too — check the test count against the last green run.
+
+## Fix it
+
+1. Confirm tests are green and only the threshold tripped. Compare total test count with the previous green build — a drop means tests went missing, which is the real bug.
+2. Get the uncovered lines, not just the percentage: pytest --cov --cov-report=term-missing or open the HTML report. The gate's summary names files; the report names lines.
+3. Write focused tests for the uncovered branches your PR introduced. Error paths are usually what's uncovered — and error paths are exactly where untested code hurts.
+4. Code that genuinely shouldn't count (debug helpers, platform-specific branches): exclude explicitly (# pragma: no cover with a reason, or config-level exclusions) — visible and reviewable.
+5. Lower the threshold only as a deliberate, stated decision in its own commit — never silently inside a feature PR.
+
+## Prevent it
+
+- Gate on patch/diff coverage (new lines covered) rather than absolute project percentage where your tooling allows it — it measures what the PR author actually controls and ends the ratchet fights.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=code-coverage-threshold)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/cpp-build-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/cpp-build-failure -->
+
+# C/C++ native build failures — undefined reference / No such file
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/cpp-build-failure](https://getpatchrail.com/fix/cpp-build-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+fatal error: foo.h: No such file or directory
+undefined reference to `symbol'
+collect2: error: ld returned 1 exit status
+CMake Error
+use of undeclared identifier
+```
+
+## What actually happened
+
+Triage by phase, which the signatures encode: configure (CMake Error) — CMake couldn't find a dependency, compiler, or generator; nothing compiled at all. Compile ("fatal error: foo.h: No such file or directory", "was not declared in this scope" / "use of undeclared identifier" — GCC and Clang dialects of the same thing) — a missing header is almost always a missing system package or include path on the CI image, not a code bug. Link ("undefined reference to", "collect2: error: ld returned", "undefined symbols for architecture") — every object compiled, but a symbol is missing: an unlinked library, wrong link order, a missing extern "C", or an architecture mismatch (common since CI fleets went multi-arch).
+
+## Fix it
+
+1. Find the first error; make/ninja with parallel jobs interleave output and the bottom of the log is rarely the cause. "ninja: build stopped" and "make: *** [target] Error N" are just the messengers.
+2. Configure phase: read the CMake error — it names the missing package; install its dev package on the runner or pass the right -D<PKG>_ROOT.
+3. Missing header: map header → system package (pg_config.h → libpq-dev etc.) and add it to the CI image. Don't vendor the header to "fix" it.
+4. Linker undefined reference: demangle the symbol (c++filt), find which library provides it, ensure it's in the link line after the objects that use it.
+5. undefined symbols for architecture: print the arch of every linked artifact (lipo -info / file *.o) — clean and rebuild any stale ones from the other architecture.
+
+## Prevent it
+
+- Build in a pinned container image with all dev packages explicit. "The runner image updated" is the top non-code cause of native build breakage.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=cpp-build-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/docker-build-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/docker-build-failure -->
+
+# Docker image build failures — failed to solve / failed to compute cache key
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/docker-build-failure](https://getpatchrail.com/fix/docker-build-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+failed to solve
+failed to compute cache key
+target stage could not be found
+manifest unknown: manifest not found
+service db is unhealthy
+```
+
+## What actually happened
+
+BuildKit's "failed to solve" is a wrapper — the real cause is the line after it. The recurring four: (1) "failed to compute cache key" + "/x: not found" — a COPY source doesn't exist in the build context, usually because .dockerignore excludes it or CI builds from a different context directory than you do locally; (2) "target stage ... could not be found" — a typo'd or renamed FROM ... AS <stage> vs --target <stage>; (3) "manifest ... not found" — the base image tag doesn't exist (deleted upstream, or no build for your platform — check --platform on multi-arch); (4) "service ... is unhealthy" — compose-specific: the image built fine but a healthcheck never went green, so the real log is the service's log, not the build log.
+
+## Fix it
+
+1. Read the line after failed to solve — that's the actual error.
+2. COPY failures: print the context as CI sees it (ls -la in the same directory the build runs from) and check .dockerignore. The file exists in the repo; it doesn't exist in the context.
+3. manifest not found: confirm the tag exists for your platform (docker manifest inspect <image>); pin a digest if the tag churns.
+4. service is unhealthy: get the service's own output (docker compose logs <service>) and triage that — the compose error is just the timeout notification. Check the healthcheck timing.
+5. Reproduce locally with the same context dir, same --target, same --platform as CI before touching the Dockerfile.
+
+## Prevent it
+
+- Pin base images by digest (FROM image@sha256:...) for anything that ships; tags are mutable and latest is a time bomb.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=docker-build-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/dotnet-build-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/dotnet-build-failure -->
+
+# .NET build failures — NU1605 / NETSDK / CS errors
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/dotnet-build-failure](https://getpatchrail.com/fix/dotnet-build-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+error NU1605: Detected package downgrade
+error NETSDK1045: The current .NET SDK does not support targeting
+error CS0246: The type or namespace name could not be found
+Version conflict detected
+Build FAILED
+```
+
+## What actually happened
+
+The error code prefix tells you the layer, and that's the triage: NU____ (NuGet) — restore-time dependency problems; NU1605 package downgrade and Version conflict detected mean two projects in the solution pin different versions of one package. NETSDK____ — SDK/target-framework mismatch, the CI image's .NET SDK can't build the project's TargetFramework (e.g. project targets net9.0, image has SDK 8). CS____ (C# compiler) — a real compile error in your code. Xunit.Sdk / "Failed!  - Failed:" — compilation succeeded; a test failed, a different problem entirely.
+
+## Fix it
+
+1. Grep the log for the first NU, NETSDK, or CS code and route accordingly.
+2. NETSDK errors: check global.json vs the SDK installed in CI (dotnet --list-sdks). Align one of them deliberately.
+3. NU conflicts: consolidate the package version across projects — central package management (Directory.Packages.props) makes the whole class structurally impossible.
+4. CS errors: ordinary compile fix; look up the code (they're well documented) and fix the narrowest site.
+5. Test failures: reproduce with dotnet test --filter "FullyQualifiedName~<TestName>" and treat as a test failure.
+
+## Prevent it
+
+- Commit a global.json pinning the SDK major, and adopt central package management. Both convert "mysterious CI drift" into explicit, reviewable diffs.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=dotnet-build-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```

patchrail-0.1.1/docs/fix/git-checkout-failure.md

@@ -0,0 +1,42 @@
+<!-- Canonical: https://getpatchrail.com/fix/git-checkout-failure -->
+
+# Checkout, clone, submodule, and LFS failures — Authentication failed
+
+> Part of the **CI Failure Triage** field guide. The canonical, formatted version of this page lives at **[getpatchrail.com/fix/git-checkout-failure](https://getpatchrail.com/fix/git-checkout-failure)**.
+
+## Log signatures
+
+These are the literal strings to search for in the failed log:
+
+```text
+fatal: Authentication failed
+fatal: repository not found
+fatal: reference is not a tree
+Failed to clone submodule
+smudge filter lfs failed
+```
+
+## What actually happened
+
+Four distinct failures share this class: auth (could not read Username, Authentication failed, Repository not found — which is what private repos return to unauthorized callers, deliberately indistinguishable from "doesn't exist") — the checkout token can't see the repo, classic with private submodules; missing ref (reference is not a tree, pathspec did not match) — the commit you're trying to check out doesn't exist anymore, from a force-push during a run, or a shallow clone (fetch-depth: 1) that doesn't contain the ref a tool needs; submodule drift (Failed to clone/fetch submodule) — the parent repo pins a submodule commit that was rebased away, or the URL moved; LFS (smudge filter lfs failed, error downloading object) — a pointer file references an object the LFS store doesn't have, or LFS bandwidth quota ran out.
+
+## Fix it
+
+1. Classify into one of the four above from the first error line.
+2. Auth: confirm what token the checkout uses and what it can see. For private submodules pass an explicit token to the checkout step (with: token: / submodules: recursive).
+3. Missing ref: was the branch force-pushed mid-run? Re-trigger on the new head. If a tool needs history or tags, set fetch-depth: 0.
+4. Submodule drift: in the parent repo, git submodule update --remote, commit the new pin, push.
+5. LFS: git lfs fetch --all locally to find the missing object; check the LFS bandwidth quota before assuming corruption.
+
+## Prevent it
+
+- If you don't strictly need submodules, replace them with package dependencies or vendoring — submodules are the single most failure-prone link between repos. If you keep them, document the token each CI consumer needs.
+
+---
+
+**Get all 31 failure classes + the offline classifier.** The complete *CI Failure Triage Patterns* pack ($19) covers every class with downloadable step-by-step playbooks, and pairs with the `patchrail` CLI that classifies a red build locally: [patchrail.gumroad.com/l/ci-failure-triage](https://patchrail.gumroad.com/l/ci-failure-triage?utm_source=github&utm_campaign=git-checkout-failure)
+
+```bash
+pipx install patchrail
+patchrail ci explain --log build.log
+```