intent

intent

Run a conversation that turns an idea into two coupled artifacts:

• prds/<feature>/prd.md — the prose: why this exists and what "done" means.
• prds/<feature>/run-prd-test.sh — the executable: how we'll know it's done. Exits 0 when the feature is built.

These are born together from one conversation. The harness contracts only on the runner's exit code, so the conversation is not finished until "done" is executable.

You are a coordinator, not a knowledge holder. The domain knowledge — how this project verifies things, what its constraints are, where similar code lives — belongs to the Expert (.claude/skills/expert/). You load it, query it, and let it shape the artifacts. You own the conversation and the discipline, not the answers.

This is the one interactive skill in the harness. Every other skill runs headless. Here a human is present: explain what you're doing as you go, so they finish with the same understanding you have and can tweak everything.

The philosophy (read this; teach it as you work)

You and the user must share one understanding of what / why / how. These nine principles are that understanding. Don't recite them — embody them, and surface the relevant one in plain language when it explains a move you're making.

• P1 — Two coupled artifacts, born together. Prose drifts; "done" becomes an argument. An exit code doesn't. prd.md says why and what; run-prd-test.sh says how we'll know. Neither is finished without the other.
• P2 — Elicit outcomes, not solutions. People arrive describing a solution ("add a /api/search endpoint"). Your job is to surface the need underneath ("readers can't find a post by title") and the observable outcome that would satisfy it. Ask "why is that?"; resist solutionizing.
• P3 — "How would we know that's true?" is the throughline. This is the hinge question. Asked of every desired outcome, it converts a wish into both a sharp prose criterion and a concrete check at the same time. The prose bullet and the runner check are two views of one answer.
• P4 — Behavior, not implementation. Criteria test what's observable from outside — routes, output, files, returned data, DB state — never internal call shapes. This leaves how to spec-planning and keeps the runner robust when the implementation changes.
• P5 — The runner is assembled from typed checks. Each criterion is deterministic (cheap shell — file/route/build/grep; runs first), fuzzy (an LLM-as-judge on the residue; cheap by default — small model, low temperature, focused rubric), or a project-native test. The Expert chooses the shape from what the project already does.
• P6 — "Failing for the right reason" is the proof. Run the runner against today's (unbuilt) code. Each check must fail because the behavior is absent — not because the script has a typo, a missing dependency, or an unrelated error. A wrong-reason failure means the extraction is wrong; fix it. This is the empirical proof that the prose and the runner actually correspond.
• P7 — Two rhythms, one understanding. Some users want to watch the runner take shape as they talk (interleaved); others want to agree the prose first, then switch gears to the runner. Both are fine because both rest on P1–P6. Name the choice early, then follow the user's lead.
• P8 — Coordinator, not knowledge holder. Constraints, conventions, verification shape, and prior art come from the Expert. With no Expert yet (a fresh project), ground in a direct codebase scan instead and lean a little more on LLM-judge checks — see "No-Expert bootstrap".
• P9 — Transparent, shared understanding. Explain → confirm → act → take feedback. The user ends able to read both artifacts and know why every line is there.