dev-skills

Appearance

Proof of Work ​

Prompt patterns ​

Reusable ways to ask for the artifact:

  • "When you finish, produce a single self-contained review.html for me to verify this. Screenshot every state of the changed screens (default, empty, loading, error, focus) from the running app, lay them out in a grid with the before/after side by side, and render the actual diff below each."
  • "Don't tell me the tests pass, show me. Paste the exact command you ran and its full output (redact any secrets first), and flag any line you're unsure about."
  • "Build me a review page for this PR: render the real diff with inline margin annotations, color-code each finding by severity, and cite file and line for every claim."

Problem ​

As an agent takes on more autonomous work, human review becomes the bottleneck. A long session produces more change than a person will read closely, so the default review degrades into rubber-stamping: a plausible-looking summary gets an approving glance, and the edge case it quietly mishandles ships. Anthropic's own guidance names this "the trust-then-verify gap": "Claude produces a plausible-looking implementation that doesn't handle edge cases."

The fix is to make the agent prove its work, not assert it. Instead of "done, the feature works," the agent produces a concrete proof-of-work artifact whose sole purpose is to let a human verify the change fast: the rendered screens, the real diff, the command it ran and what came back. From the same guidance: "Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result. Reviewing evidence is faster than re-running the verification yourself, and it works for sessions you weren't watching."

This is a human-facing verification layer that sits on top of tests, never in place of them. Tests prove correctness to the machine; the proof-of-work artifact proves it to a person and captures the nuance tests cannot: design intent, trade-offs, what was tried and rejected.

Pattern ​

For anything whose point is "confirm it works," have the agent emit concrete, checkable evidence: screenshots and recordings of the actual UI, the real rendered diff, captured command and test output, before/after states. The agent collects proof; the human (not the agent) decides pass or fail.

Especially for UI work ​

UI changes are where proof of work pays off most, because correctness is visible. A test can assert a button exists; only a screenshot shows it's centered, legible, and not overlapping the field below it. For any UI change, have the agent capture:

  • Each state, not just the happy path: default, empty, loading, error, hover/focus, disabled, and the long-content and tiny-screen extremes.
  • Before and after, side by side: so the reviewer sees exactly what moved.
  • The real rendered page, captured from the running app (e.g. via Playwright), not a mock-up the agent drew. A screenshot of the actual DOM is ground truth; an agent-drawn approximation is just another assertion.
  • A short recording for interactions (a flow, an animation, a drag) where a still frame cannot show that it works.

Lay these into one page the reviewer opens once: a grid of states, before/after pairs, the diff that produced them. The reviewer confirms the change by looking, without pulling the branch.

Still useful for non-UI work ​

The same move applies when there is no UI. The evidence is just different:

  • Captured command and test output: the exact command, its exit code, and what it printed, quoted verbatim rather than summarized.
  • Data and transformations as tables: before/after rows, a migration's row counts, a query's actual results.
  • Request/response pairs for an API change; log excerpts for a behavior change; a rendered diff with the risky lines annotated.
  • A walkthrough of the reasoning: what the agent tried, what it rejected, and why, which a passing test never captures.

Make the artifact self-contained and honest ​

  • One self-contained file. Inline the CSS and SVG; no CDN dependencies and no network fetches, so it opens straight from disk and survives being attached to a PR or archived.
  • JS-light, ideally JS-free. See the security guardrail below.
  • Point back at checkable reality. Every claim should cite the ground truth it rests on: a real file-and-line reference, the actual command output, the screenshot of the real page. The artifact argues toward the source of truth; it never substitutes for it.
  • Mark evidentiary status. Distinguish what was verified from what was assumed. Tag claims (verified, assumed, not checked) so the reviewer knows where to spend their scrutiny.
  • Redact secrets before sharing. Captured output can carry tokens, cookies, private URLs, or customer data. Scrub sensitive values from auth, deploy, CI, and env/config output before it enters the artifact. See the security guardrail below.

Examples ​

Example 1: A UI feature ​

An agent adds an inline-edit affordance to a settings row. Asserting "added inline editing, works as expected" gives the reviewer nothing to check short of pulling the branch and clicking around.

With proof of work: the agent produces review.html, a grid of the row in each state (read, editing, saving, validation-error), each a real Playwright screenshot of the running app; the before/after of the row side by side; a 4- second recording of the click-edit-save flow; and the diff that produced it, with the new event-handler lines annotated. The reviewer confirms the feature in under a minute by looking, and tests still guard the behavior underneath.

Example 2: A non-UI change ​

An agent rewrites a date-bucketing query. "Refactored the query, same results" is an assertion.

With proof of work: the agent emits a page showing the old and new SQL side by side, a table of the actual output rows from both run against the same fixture (identical, highlighted), and the captured EXPLAIN output showing the new plan no longer does a full scan. The correctness claim is now inspectable, not trusted.

Anti-patterns ​

Treating the artifact as proof of correctness ​

A polished page is persuasive, not correct, and that is the central risk. The same visual richness that makes a good review readable makes a fabricated or subtly-wrong one more convincing. An agent can render a fabricated diff or a made-up chart with full visual authority, and a reviewer can read a beautiful page and feel they verified something they only looked at. Guard against it: the evidence must be real (captured from the running app, quoted from actual output, citing real lines), and reading it is not the same as confirming it against the repo and tests. The artifact directs scrutiny; it does not replace it.

Letting it stand in for tests ​

Proof of work is the human-facing layer; it complements machine-checkable verification, it does not replace it. If a correctness claim can be a test, make it a test, and let the artifact show that test passing. "Here's a nice report" is not a substitute for "here's a green suite."

Auto-executing agent-generated HTML ​

Treat agent-generated HTML as untrusted code. It can carry arbitrary JavaScript, a real prompt-injection and exfiltration surface. Prefer no-JS artifacts (or a strict CSP), open them in a sandboxed context, and do not wire up a reflexive "auto-open it in the browser when done." Convenience here is an attack surface.

Leaking secrets into the evidence ​

The push to "paste the full output verbatim" collides with secret hygiene. Output from auth, deploys, CI logs, or env/config dumps can contain tokens, cookies, session IDs, private URLs, or customer data, and once it lands in an artifact attached to a PR or archived, it is published. Keep the evidence requirement, but redact before sharing: scrub or mask sensitive values, prefer fixtures and synthetic data, and never paste real credentials to prove a command ran. Verbatim means faithful, not unredacted.

Letting the artifact rot ​

HTML is harder to hand-edit than Markdown, so an evidence page drifts from the code it described. Keep it a throwaway tied to one review, regenerate it rather than maintaining it, and offer a "copy as Markdown" round-trip so the content is not trapped in a format no one updates.

Generic "AI slop" styling ​

Purple gradients, everything centered, emoji headers, and inaccessible contrast make every artifact look the same and bury the content. Derive styling from the project's own design tokens where possible, and meet basic accessibility (real contrast, semantic structure): the page exists to be read, not admired.

Why this matters ​

The bottleneck in agentic development is no longer writing the code; it is a human confidently verifying it. A proof-of-work artifact moves review from "trust the agent's summary" to "inspect the agent's proof," which is both faster and safer, and it works for the sessions you were not watching. The discipline that keeps it honest is the same one tests rely on: the artifact must point at checkable ground truth, never stand in for it.

Sources ​

See also ​