chore(agents): add CI-log-reading and doc-vs-enforcement rules

Author: ChipWolf

home/dot_agents/AGENTS.md

@@ -15,6 +15,8 @@ These constraints are unconditional. Apply them without being asked.
 - **Verify a dependency supports the target platform before designing around it.** Before locking in a spec that depends on a third-party tool on a specific OS, confirm artifacts and source actually support that OS: run `gh release view --json assets` to see what's published, check the upstream CI matrix for the OSes it builds, and grep the source for OS-specific imports or build tags. Project names and descriptions don't imply cross-platform binaries; many "general" tools are Linux-only at the artifact level even when the README sounds portable.
 - **Diagnose from logs, not theory.** When investigating a failure (CI, runtime, hang, regression), the last lines of output before the failure are ground truth, not a guess based on which script's name matches your current hypothesis or which prior bug looked similar. If the visible log doesn't pin the cause, add a diagnostic and re-run rather than speculate further. When reporting findings, mark claims as observed ("log line N says X") versus suspected ("I think Y because…") and never let suspicion harden into assertion without evidence.
 - **Contradictory observations mean a bad instrument, not a new theory.** When two measurements of the same thing disagree (a value healthy at line N but "null" at line N+1, a passing run and a failing run of identical code), stop hypothesising and instrument the exact divergent reads side by side in one run; the discrepancy is the bug's address. Treat tool-reported metadata as suspect until verified: logcat's tid column is the logger thread, not the caller (log gettid() yourself), and addr2line on optimised binaries misattributes merged inlined frames, so confirm the throw/crash site with a direct probe before acting on it.
+- **A quoted error string in a log is not proof the error fired.** CI runners echo the script before executing it (GitHub Actions prints the whole `##[group]Run` body, `echo "::error ..."` conditionals included, often ANSI-highlighted), so a line containing an error template may just be the source of an un-taken branch. Identify where the annotation was actually emitted (the bare `##[error] ...` line, or the failing command's own stderr) before naming a cause, not where the text merely appears. Mis-reading an echoed conditional as a fired error sends you fixing the wrong thing.
+- **When a project's prose and its enforcement disagree, the enforcement wins.** A skill, README, or comment can drift from the CI gate, linter, or schema that actually rejects your change (e.g. a documented file layout that a CI guard now forbids adding). Before following a documented process that touches generated or tool-owned files, confirm it against the mechanism that will gate the PR; if they conflict, satisfy the gate and fix the stale doc in the same effort.
 - **Make the failure reproduce without a human before iterating on fixes.** When verification needs a human round-trip (someone wearing a headset, clicking a UI, plugging in hardware), build an autonomous repro first: a self-test that runs the failing path at startup, auto-dismissal of interactive gates, retry loops around known-flaky launches, and a streamed log capture started before launch so rotation can't eat the evidence. Each fix-then-ask-the-human cycle costs minutes and goodwill; the harness pays for itself by the second iteration.
 - **Stub APIs permissively, capture narrowly.** When a loopback or mock server intercepts an API client to capture requests, return a permissive default (`200 {}` or a minimal valid response object) for unhandled paths, and only persist the body for the specific path you care about. Real clients often probe other endpoints (capability checks, model lookups, version handshakes) before sending the request you want to intercept; a 404 on a pre-flight probe makes them bail before reaching the target path. Reserve 404 for paths that genuinely must not exist.
 - **One sample isn't a measurement.** A single run, repro, or test pass doesn't characterise a noisy phenomenon. Before claiming X differs from Y (faster, more reliable, fixed, broken), gather enough samples to see variance, then report it. Applies anywhere outcomes vary: perf benchmarks, flaky tests, network calls, CI on managed infra, A/B comparisons. If you've only got one data point, mark the conclusion provisional, do not open a PR or change production on it.