From 545c213f887469cb32ff790fdd9bfb9228a38a6f Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Fri, 31 Jul 2026 11:55:42 +0200 Subject: [PATCH] docs(skills): fetch CI artifacts before theorising A job log usually names an artifact path and stops there; the assertion text, server exception and state dumps live inside the artifact. Both triage and dialectic now require downloading them before forming a thesis, since theorising from the log alone while an unread artifact holds the answer is the most expensive mistake in the loop. Co-Authored-By: Claude Opus 5 (1M context) --- skills/dialectic/SKILL.md | 7 +++++++ skills/triage/SKILL.md | 15 +++++++++++---- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/skills/dialectic/SKILL.md b/skills/dialectic/SKILL.md index 42607b0..ec4cfe0 100644 --- a/skills/dialectic/SKILL.md +++ b/skills/dialectic/SKILL.md @@ -26,6 +26,13 @@ operator holds. git history; the running containers (exec, logs, inspect through whatever make or CLI helpers the project exposes); CI logs and artifacts; tests; docs. Cite `file:line` and command output — never a bare assertion. + **Download the artifacts before theorising.** When the failure comes from a + CI run, list its artifacts and fetch every one that could carry the failure + (`gh run download -n -D `, or the equivalent for the CI in + use). A job log routinely holds only the *path* of a report while the payload + — assertion text, expected vs received, server logs, diagnostic dumps — lives + in the artifact. Theorising from the log alone while an unread artifact + contains the answer is the single most expensive mistake in this loop. 2. **Antithesis.** Spawn MULTIPLE independent skeptics (parallel subagents or a workflow) whose only job is to REFUTE the thesis. Each re-inspects the sources itself and defaults to "refuted" on any concrete hole. Give diverse diff --git a/skills/triage/SKILL.md b/skills/triage/SKILL.md index 4e03d1b..38c7dbc 100644 --- a/skills/triage/SKILL.md +++ b/skills/triage/SKILL.md @@ -17,20 +17,27 @@ root cause is proven. whose conclusion is failure, cancelled, or timed-out. A downstream aggregate job that fails only because an upstream job did is not a separate root cause — note it and move on. -2. **Dialectic per failing job.** For EACH failing job, invoke the `dialectic` +2. **Download the run's artifacts.** Before investigating, list the run's + artifacts and fetch every one belonging to a failing job — reports, rescue + diagnostics, inventories, container logs. The job log usually names an + artifact path and nothing more; the assertion text, the server-side + exception and the state dumps are inside the artifact. Do this even when the + log looks conclusive, because a log that explains the symptom rarely + explains the cause. +3. **Dialectic per failing job.** For EACH failing job, invoke the `dialectic` skill: form a thesis about the root cause from evidence (the job log, its artifacts, the code at the run's commit, git history), attack it with independent skeptics, and iterate to a ~99% thesis. The jobs are independent, so run their investigations in parallel where the tooling allows. -3. **Distinguish shared vs hidden causes.** When several jobs share one root +4. **Distinguish shared vs hidden causes.** When several jobs share one root cause, fix it once. When a job hides a second failure behind the first, keep going until the job is actually green, not just past the first error. -4. **Fix at the root.** Apply the real fix in the repository for each proven root +5. **Fix at the root.** Apply the real fix in the repository for each proven root cause. Never mask a failure — no retry-until-pass, no disabling the check, no soft-skip. If a failure is genuinely external (upstream outage, flaky infra), confirm that with evidence and surface it honestly instead of fixing around it. -5. **Follow the run.** While the run is still in progress, re-check it +6. **Follow the run.** While the run is still in progress, re-check it periodically and triage each newly failed job as it appears. The run is done only when it has finished and every failure has a verified fix.