agentleFS
syntropic137syntropic137/harness-app-template/.claude/skills/before-after-evidence/SKILL.md

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).

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
  1. Very specific:

    Every "fix verified" claim produces a directory .harness/artifacts/<iso_key>/ with:

    line 10
  2. Distinctive:

    Use the template inspector dispatcher:

    line 42

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 attributes

This is the highest-leverage debug bridge: browser-visible failure to backend-resolved root cause.

Decision matrix: which recipe to use

Bug typeRecipe
Static UI difference (text, color, layout)A (screenshot pair)
Modal/toast/form interactionA (screenshot pair, post-action)
Animation, transition, loading stateB (recording + keyframe grid)
Backend 4xx/5xx caused by frontendA + C (screenshots + trace correlation)
Performance regressionSee 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
![](screenshots/before.jpg)

## After
![](screenshots/after.jpg)

## Trace correlation
<contents of trace-correlation.md if present>

## Verdict
<pass | fail | uncertain>
<one-paragraph rationale>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.