PRDuck

Paste the spec you're about to hand an AI agent. Three agents plan it independently. See where they split.

This repo is plan only — no implementation yet. It is deliberately separate from the prduck repo (the open-paxel fork that analyzes Claude Code sessions); the two share a name and nothing else.

The premise

Agents don't fail on hard specs, they fail on ambiguous ones — where the same sentence supports several readings and each run picks a different one. Run the same spec N times in plan mode with structured output, and the disagreement between runs localizes the ambiguity.

Two failure modes this does not catch, stated up front because they decide who it's for:

• Convergent wrongness. All runs can agree and all be wrong, because the spec confidently says something dumb. This measures underspecification, not incorrectness.
• Codebase legibility. An agent with your repo loaded converges more regardless of spec quality. The MVP runs without repo context so the instrument stays pointed at the spec.

What's here

| Path | What it is | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- | | docs/plan.md | The build plan — schema, scoring, screens, cuts, signals, kill criteria | | docs/prototype.html | Five annotated screens, open in a browser | | docs/decision-record.schema.json | The structured output contract each run must return |

Shape of the MVP

One page, one input, no accounts. A run produces two artifacts because the viral unit and the habit unit are different objects:

• Share card — a number, a claim, and the offending line. Legible to a stranger in a feed.
• Hardened spec — clarification lines resolving each confirmed split. Copying it is the habit.

The bridge is the re-run: paste the hardened version back, watch drift fall. That drop is the proof, the dopamine, and the better second screenshot.

Kill criterion

15 runs in front of real users. If nobody pastes a second spec unprompted, stop. Two weeks to find out, not two quarters.

Running it locally

cp .env.example .env   # leave every value blank
./run.sh               # http://localhost:3000

The hosted app wants Neon, Cloudflare R2 and Resend. With those unset, and only outside production, each seam falls back to a local equivalent (lib/dev/local-mode.ts):

| Service | Local stand-in | | ------- | ----------------------------------------------------------------------------- | | Neon | Embedded Postgres (PGlite) in .prduck-local/pg, running the real migrations | | R2 | A blob directory in .prduck-local/blobs | | Resend | Mail printed to the dev server's terminal |

That makes everything behind the sign-in reachable with no accounts. To sign in, either submit the form and click the link the terminal prints, or open /api/dev/[email protected] — that route runs the real requestLogin and redirects into the real /auth/verify, so the one-shot token, user upsert and session cookie are all the production path. It 404s the moment a mail provider is configured, and never runs in production.

To get a real report in, point the CLI at your own machine:

PRDUCK_SITE_URL=http://localhost:3000 node cli/prduck.mjs upload

For CLI diagnostics on stderr (phase timings, retry reasons, correlation ids) without changing stdout or exit codes:

PRDUCK_DEBUG=1 PRDUCK_SITE_URL=http://localhost:3000 node cli/prduck.mjs upload

Then open the claim link it prints while signed in. Delete .prduck-local/ for a clean slate. One caveat: PGlite is single-writer, so a script cannot open the database while the dev server holds it — stop the server first.

Reading what the models did

Every LLM operation — corpus reading, each axis grade, classification, narrative, rules — can write a markdown transcript of its own run:

PRDUCK_TRACE=both ./run.sh

Files land in .prduck-local/traces/, one per operation, named <timestamp>-<operation>-<id>.md so a report's traces sort together; both also streams them to stderr, which run.sh captures in .prduck-local/trigger-dev.log. Use file or console for one channel only. PRDUCK_TRACE_MAX_CHARS (default 4000) caps each prompt, tool result and reply body; 0 keeps them whole. PRDUCK_TRACE_DIR moves the directory.

Traces are dev-only and off unless you ask for them — they are forced off in production — because they contain the full system prompt and the full text of the sessions being read. Review one before pasting any of it into a bug report.