before-after-evidence
Skill0 starsChanged 6 months agoMITView on GitHub
Produce a verifiable evidence bundle for a fix: screenshot pair, optional flow recording, ffmpeg keyframe grid, trace correlation. Use when claiming "fix verified" so the artifacts can be diffed by a reviewer (human or LLM).
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- architectureSkill
- chrome-devtools-deepSkill
- ci-optimizationSkill
- configurationSkill
- continuous-deliverySkill
- dependenciesSkill
- developer-experienceSkill
- documentationSkill
- drySkill
- environmentsSkill
- error-handlingSkill
- loggingSkill
- observability-queriesSkill
- orchestrating-a-vps-agent-swarmSkill
- playwright-debugSkill
- principles-and-patternsSkill
- purpose-and-scopeSkill
- running-experimentsSkill
- securitySkill
- software-complexitySkill
- testingSkill
- typesSkill
- versioningSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Every "fix verified" claim produces a directory .harness/artifacts/<iso_key>/ with:
- Distinctive: line 42
Use the template inspector dispatcher:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Before/after evidence capture
The artifact contract
Every "fix verified" claim produces a directory .harness/artifacts/<iso_key>/ with:
meta.json { run_id, branch, fix_commit, target_url, started_at, finished_at }
screenshots/
before.png full-fidelity archive
before.jpg 1280x720 JPEG quality 80 (for LLM ingestion)
after.png
after.jpg
video/ (only if a flow recording was taken)
flow-before.webm
flow-after.webm
events-before.jsonl console + network events with timestamps
events-after.jsonl
review/ (only if a keyframe grid was generated)
keyframe-grid-before.jpg ffmpeg tile montage, single JPEG
keyframe-grid-after.jpg
trace-correlation.md list of failed requests -> trace_ids -> VictoriaTraces links<iso_key> is the per-worktree key from just stack inspect or
harness/stack/bin/stack inspect. WEB_PORT and VT_PORT come from
just stack ports.
eval "$(just stack ports)"
ISO_KEY="$(just stack inspect | awk '/^Iso key:/ {print $3}')"
TARGET_URL="http://localhost:${WEB_PORT}"Recipe A: screenshot pair (sufficient for 80% of UI fixes)
Use the template inspector dispatcher:
just inspector screenshot-pair --phase=before --url="$TARGET_URL" --isoKey="$ISO_KEY"
# ...apply fix, redeploy via hot reload...
just inspector screenshot-pair --phase=after --url="$TARGET_URL" --isoKey="$ISO_KEY"Direct path equivalent:
node harness/inspector/screenshot-pair.mjs --phase=before --url="$TARGET_URL" --isoKey="$ISO_KEY"
node harness/inspector/screenshot-pair.mjs --phase=after --url="$TARGET_URL" --isoKey="$ISO_KEY"The script writes PNG (full fidelity) + JPEG (LLM-optimized) to .harness/artifacts/<iso>/screenshots/.
Recipe B: flow recording with keyframe grid (for animation/transition/loading-state bugs)
Use the template inspector dispatcher:
just inspector record-flow --phase=before --url="$TARGET_URL" --flow=task-crud --isoKey="$ISO_KEY"
# ...apply fix...
just inspector record-flow --phase=after --url="$TARGET_URL" --flow=task-crud --isoKey="$ISO_KEY"Direct path equivalent:
node harness/inspector/record-flow.mjs --phase=before --url="$TARGET_URL" --flow=task-crud --isoKey="$ISO_KEY"
node harness/inspector/record-flow.mjs --phase=after --url="$TARGET_URL" --flow=task-crud --isoKey="$ISO_KEY"The script does: open browser -> record screencast -> run the named flow -> stop recording -> ffmpeg extract 3x3 keyframe grid -> write events.jsonl from console + network listeners.
Flow selection: --flow=navigate is a built-in generic flow that works against any URL (load, network idle, settle). --flow=task-crud is the example app flow shown above. For app-specific journeys, pass --flowFile=<path> pointing at an ES module that default-exports async (page, baseUrl) => void; see harness/inspector/README.md for an authoring example. --isoKey may be omitted when the stack-manager slot is installed; the scripts auto-detect it via harness/stack/bin/stack inspect.
LLM consumption: send the keyframe grids (1 JPEG each, ~2.7K tokens) plus the screenshot pair, NOT the WebM. Total budget ~8K vision tokens per validation.
Recipe C: trace correlation
For every failed request captured in events.jsonl, extract the traceparent header and produce a trace-correlation.md:
# Pseudocode the agent runs
for failure in events.jsonl where type==network and status>=400:
trace_id = extract_trace_id(failure.traceparent)
trace = curl http://localhost:$VT_PORT/select/jaeger/api/traces/$trace_id
append to trace-correlation.md:
- URL, method, status
- trace_id
- Backend span that failed (look for span with status="ERROR")
- Error message from the span attributesThis is the highest-leverage debug bridge: browser-visible failure to backend-resolved root cause.
Decision matrix: which recipe to use
| Bug type | Recipe |
| Static UI difference (text, color, layout) | A (screenshot pair) |
| Modal/toast/form interaction | A (screenshot pair, post-action) |
| Animation, transition, loading state | B (recording + keyframe grid) |
| Backend 4xx/5xx caused by frontend | A + C (screenshots + trace correlation) |
| Performance regression | See chrome-devtools-deep for Tracing.start |
Reporting template
Output the final validation report to .harness/artifacts/<iso>/REPORT.md:
# Fix validation: <bug-id>
**Branch:** <branch>
**Fix commit:** <sha>
**Target:** http://localhost:<port>
## Before

## After

## Trace correlation
<contents of trace-correlation.md if present>
## Verdict
<pass | fail | uncertain>
<one-paragraph rationale>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

