How I Use Proof Artifacts to Keep One-Off Investigations Repeatable

By Vicente Arteaga Gomez

MisLinux · Last updated: May 5, 2026

This is part of my Kubernetes-on-Hetzner-and-operations series on MisLinux. It reflects my own incident and reporting workflow.

I no longer believe in the phrase "I already checked that."

If I checked it and did not preserve the result, what I really have is memory.

Memory is useful. It is not an artifact.

The artifact types I reach for first

Artifact	What it proves
JSON snapshot	machine-readable state at a point in time
Screenshot	the real UI path or rendered state
Before/after manifest	configuration delta
Job log	exact runtime behavior
Run note	why this artifact mattered

The run note is important because raw artifacts without framing can become archaeology instead of evidence.

Why I save them even for small tasks

Because small tasks become big tasks later.

The one-off investigation often becomes:

• the baseline for a later regression
• the model for a new helper script
• the evidence behind a follow-up item
• the reason a CIR note was added

That only works if the evidence still exists.

A folder layout I like

history/20260505-example-run/
  summary.json
  before-state.json
  after-state.json
  browser-proof.jpg
  command-log.txt
  run-notes.md

Nothing about that layout is magical. It is just easy to inspect later.

The mistake I am trying to avoid

The mistake is saving only the "pretty" output.

For example:

• saving the chart but not the raw values
• saving the screenshot but not the route or state summary
• saving the report but not the query window

That creates a result I can cite but not re-derive.

Why this matters with AI agents

AI agents are much more useful when the artifact contract is explicit.

If the output folder has known files, the next run can:

• diff the new result against the old one
• explain what changed
• reuse the same helper path
• avoid re-grepping the whole repo

Without that structure, every investigation starts wide again.

A lightweight command trail

mkdir -p history/20260505-example-run
php collect-state.php > history/20260505-example-run/before-state.json
python3 take-proof-screenshot.py --out history/20260505-example-run/browser-proof.jpg
printf '%s\n' "Why this run exists" > history/20260505-example-run/run-notes.md

That is enough to make the work reusable.

Failure case: artifact-only without explanation

Artifacts alone are not enough if they do not say:

• what the operator was trying to prove
• whether the run was read-only or mutating
• why this snapshot matters

That is why I still like a small summary file or run note next to the raw files.

What I'd do differently now

I used to save artifacts only after a task felt important. What I'd do differently now is decide the artifact contract at the start. The earlier I know what proof I want, the less likely I am to finish with missing evidence.