prove-it-works

name	prove-it-works
description	Survey observable paths, run the real system, capture evidence, and surface gaps. TRIGGER when asked to prove a change works or write a QA plan.
argument-hint	Scope to check (e.g. "current branch", "the /login endpoint", "the retry logic in src/queue.ts") [optional]

Scope: $ARGUMENTS (if empty, assume the current change).

Step 1 — Survey: what paths exist?

Before running anything, produce a short report:

• Entry points: how can this code be reached? (CLI flag, HTTP endpoint, import, event, etc.)
• Branches: what distinct paths does execution take? (happy path, error case, edge inputs, etc.)
• Observable outputs: what does the system emit that you can check? (stdout, log lines, HTTP response, file on disk, UI state, exit code, etc.)
• Gaps: what paths exist that you cannot observe directly, and why?

This is a planning artifact, not prose — use a list.

Step 2 — Run: execute against the real system

Pick the real entry point. Real inputs. Real outputs. Not a test runner.

If you find yourself reaching for a test file, stop and ask: how would I observe this behaviour if I had no test suite at all? That's the question to answer.

Cover every branch from Step 1 that you can reach. For each run, record:

• What you ran (exact command, request, or interaction)
• What you observed (stdout, response, file content, UI — not "it seemed fine")

❌ "The tests pass and the logic looks correct." ✅ "I ran npm run dev, navigated to /settings, toggled the feature, and saw the config update in the network response."

Step 3 — Gap audit

After running, answer two questions:

1. What remains unobserved? List any paths from Step 1 you couldn't reach, and why (missing fixture, needs live infra, too slow to set up locally, etc.)
2. What tests are missing? Focus on integration tests and black-box tests that run the real system and assert from outside — not unit tests that mock internals. A good integration test here would reproduce what you just ran manually. If a gap from #1 could be closed by adding such a test, say so explicitly.

Don't let this section distract from Steps 1–2. The primary goal is live evidence, not test design. Surface the gap, name the test type, move on.

Step 4 — Decide (internal, do not output yet)

Before writing the report, decide what you'll recommend. Ask yourself:

• Are any unobserved paths blockers to shipping?
• Which missing tests from Step 3 are highest priority?
• Is anything only verifiable in staging/prod — and if so, what should the user watch for?

Produce a private prioritized list (3–5 bullets). Use these categories:

• Ship it — all critical paths observed, no blockers
• Fix before shipping — specific gap is a blocker; name it
• Add tests — specific integration tests worth writing; name them
• Needs live infra — name what to watch for in staging/prod

Hold this list. Output nothing yet.

Step 5 — Report

Now output the summary table followed immediately by the recommendations from Step 4:

Path	Observed?	Evidence	Notes
Happy path	✅	npm run dev → navigated to /settings → saw config update in network response
Invalid input	✅	curl -X POST /api/foo -d '{}' → 400 response with expected error body
DB unreachable	❌	Can't simulate locally without stopping the DB container	Missing integration test

Recommended next steps:

• Add integration test: ...
• Ship it / Fix X before shipping / Watch for Y in staging

What would you like to do?