Your first PRD

Where to begin: goal, design, PRD. Then zurdo scaffold, and the review that clears its marker.

zurdo v1.36.0

A PRD is the last of three artifacts. Start at the tier your work is at now, and a bundled skill takes you down to the next.

  1. Goal → scope.md. zurdo-goal-author turns a goal into objectives, key results and phases. Skip it when the scope already exists.
  2. Phase → design record. zurdo-design-author settles how a phase gets built, on measured evidence. Skip it when the phase is small and clear.
  3. Design → PRD. zurdo-prd-author writes the tasks and criteria with you, or reviews a draft that zurdo scaffold wrote.
  4. PRD → run. zurdo validate, then zurdo run.

Invoke the skills from your agent CLI. zurdo init installed them, and zurdo skills list shows them.

Write it with zurdo-prd-author

Starting from an idea, ask the skill for a PRD. It interviews you evidence first: it drafts each criterion's hint, derives the tasks from them, and pressure-tests every hint until it truly verifies. It also writes a <prd>.trail.md sidecar recording why. Writing PRDs covers the grammar.

Or draft it with zurdo scaffold

When a design record already exists, zurdo can draft the PRD from it. --section picks one heading, matched by its exact text:

zurdo scaffold docs/greeter/design/cli.md \
  --section "Phase 2 — greet by name" \
  --out docs/greeter/prds/prd-02-name.md

What it writes The PRD, its .trail.md, and pre-authored test files: tests committed before the run that makes them pass.

What it checks Each attempt is checked (grammar, analyze --static-only, frozen paths, a pre-run in which each test must fail) and kept or rolled back. Up to --max-iterations, default 3.

What it needs [roles.analyzer] in .zurdo/config.toml (exit 3 without it). --out and its trail must not exist yet (exit 2).

If no attempt is accepted, it exits 6 and keeps the last one under .zurdo/scaffold/, never at --out. Scaffold drafts. It never decides that a PRD is ready.

Review the draft

Every scaffolded PRD opens with this marker, right under its title:

# PRD: Greet by name
<!-- zurdo:scaffold unreviewed — run the zurdo-prd-author skill before zurdo run -->

That's the unreviewed-scaffold lint. zurdo validate and zurdo run warn about it, and zurdo validate --strict fails on it:

zurdo validate --strict
$ zurdo validate --strict docs/greeter/prds/prd-02-name.md
docs/greeter/prds/prd-02-name.md:2: error: this PRD is an unreviewed `zurdo scaffold` draft — run the `zurdo-prd-author` skill on it before `zurdo run`
$ echo $?
2
Without --strict it's a warning, and validation still prints OK.

To clear it, run zurdo-prd-author on the draft. It enters from the draft instead of a blank interview: it loads the PRD, the trail and the test files, then questions every requirement, criterion, frozen path and test. It removes the marker only when its own review reaches ✓ READY TO RUN. Don't delete the marker by hand: it's how a reader knows no human has read the draft yet.

Then commit the PRD, its trail and its tests together, and run it.

Next: The PRD loop