pantheon-org/proof-of-work

Proof-of-Work Documentation

When to Use

• "Capture a screenshot after deploying the change."
• "Document what you found in the logs."
• "Show me proof this worked."
• "Save the output of that command."
• After any investigation, audit, or multi-step task where a stakeholder needs to verify the outcome.

When Not to Use

• Purely generative tasks (writing code, drafting text) where no external state was observed.
• Tasks where the user has explicitly said output or artifacts are not needed.

Artifact Types

| Type | Tool | Use For | |---|---|---| | Screenshot | agent-browser or playwright-mcp | UI state, browser-rendered output, visual regressions | | Log capture | shell / ctx_execute | Terminal output, CI logs, service logs | | Script output | shell / ctx_execute | Command results, API responses, test runs |

Workflow

1. Identify evidence scope — determine which artifact type(s) are appropriate for the task. Output: evidence plan (screenshot / log / script output, destination path).

2. Capture the evidence — use the appropriate tool (see below). Output: raw artifact saved to disk or embedded in response.

3. Store artifacts — write to the evidence directory using the naming convention. Output: file path(s) confirmed.

4. Reference in response — include the file path and a one-line description of what it shows. Output: summary block appended to the task response.

Capturing Screenshots

With playwright-mcp

// Navigate and capture
await page.goto('https://example.com/dashboard');
await page.screenshot({ path: '.context/evidence/2026-04-07-dashboard.png', fullPage: true });

With agent-browser (computer use)

Use the screenshot action after performing browser interactions:

action: screenshot
save_to: .context/evidence/2026-04-07-<slug>.png

Capturing Logs

# Tail and save service logs
kubectl logs deploy/my-service --tail=100 | tee .context/evidence/2026-04-07-service-logs.txt

# Save CI step output
cat build.log > .context/evidence/2026-04-07-build-output.txt

Capturing Script Output

# Run and persist output
bun run test 2>&1 | tee .context/evidence/2026-04-07-test-run.txt

# AWS CLI query result
aws cloudwatch get-metric-data ... > .context/evidence/2026-04-07-metrics.json

Artifact Naming Convention

.context/evidence/YYYY-MM-DD-<slug>.<ext>

• YYYY-MM-DD — date the evidence was captured (use today's date)
• <slug> — kebab-case description of what it shows (login-page-after-fix, test-pass, memory-usage-spike)
• <ext> — png for screenshots, txt for logs, json for structured output

Response Summary Block

Always append a summary block to your response when artifacts are created:

## Evidence

| Artifact | Path | Description |
|---|---|---|
| Screenshot | `.context/evidence/2026-04-07-dashboard.png` | Dashboard after deployment — no errors visible |
| Log | `.context/evidence/2026-04-07-test-run.txt` | All 42 tests passed |

Anti-Patterns

NEVER describe what you observed without saving an artifact

WHY: prose summaries are not verifiable; artifacts are. BAD: "The page loaded correctly." GOOD: save a screenshot and reference it.

NEVER use vague slugs

WHY: unidentifiable filenames make evidence useless in audit trails. BAD: screenshot1.png. GOOD: 2026-04-07-checkout-page-post-deploy.png.

NEVER skip evidence capture when the task involves external state

WHY: external state (UI, logs, infrastructure) cannot be re-observed after the fact. BAD: run a migration and report "done". GOOD: capture and save the migration output.

Verification

# Confirm artifacts were written
ls -lh .context/evidence/

# Check screenshots are valid images
file .context/evidence/*.png

References

• Artifact storage paths, naming convention, evidence table template