product-prd

Files (17)

• README.md
• SKILL.md
• evals.json · evals/
• README.md · evals/inputs/
• PRD.md · evals/inputs/mailmate-reentry/docs/
• PRD_open_issues.md · evals/inputs/mailmate-reentry/docs/
• product_request.md · evals/inputs/mailmate-reentry/docs/
• project.md · evals/inputs/mailmate-reentry/
• product_request.md · evals/inputs/mailmate/docs/
• project.md · evals/inputs/mailmate/
• claude.md · intelligence/
• codex.md · intelligence/
• gemini.md · intelligence/
• ollama.md · intelligence/
• launcher.md
• rich.md · prompts/
• stack.json

SKILL.md (first lines)

# product-prd

## Purpose

Author a project's **PRD**: the product source of truth — the product-facing **what and
why** that engineering, design, and architecture build on. It is the **head** of the
definition sequence (`<CORE>/doctrine/setup/setting_up_a_project.md`, which owns that
sequence and is not restated here); the CTO derives the SRS from it and the CDO the UXD,
both written off it in parallel.

This file is the **orchestrator**: posture, the file loop, and the commit mechanics. **How to
author** — the diagnostic, the tag contract, and the twelve authoring principles — is the
authoring prompt **`prompts/rich.md`**, applied at Step 2; a principle
referenced below by number lives there. The PRD's **section shape** is the template
**`<CORE>/templates/product-templates/prd_template.md`**. Neither is restated here.

## Posture

**CPO role required.** If invoked outside CPO posture (neither a `cpo:` session nor the
`cpo` subagent), stop and say: *"product-prd requires CPO posture. Switch? (Open a session
with the `cpo:` prefix, or run the `cpo` subagent.)"* Do not shed the role. Take care not to
confuse the CPO with the delivery-tier **Product Owner**, who writes per-change specs
downstream — a different role that only shares the word "product".

**Non-interactive.** Throughout, **the owner** is the person whose product this is — the one
who directed the project and whose taste calls the PRD is settling. You work *with* them, but
through files, not a live interview:

- **Draft, don't ask.** Draft the whole PRD best-effort from the inputs. Never open a
  blank-page interview; never block waiting.
- **Surface, don't interrogate.** What the inputs can't settle goes to the **open-issues
  file** in one of three buckets:
  - **Open issues** — a product question you have no basis to decide.
  - **Choices to confirm** — a decision you drafted that is the owner's to sign off.
  - **Directives** — an action outside your own reach to perform (open a file elsewhere,
    change something outside the product, get a reply only a person can give). **Routing test
    against the prompt's principle 11, first:** can your own tools settle this — the vendor's
    own docs, a web search, a research query? If yes, it was never a directive — principle 11
    owns it: open the source now and fold the fact into the PRD, tagged by what you found, and
    it never reaches this bucket. Only what your tools genuinely can't reach — a private
    negotiation, a number no published source carries, an answer that needs a specific person's
    reply — is a directive. **A directive is a gate, not a blocker.** The owner may not be able
    to take the action now, and the product doesn't wait on the *action* to be *defined* — so
    the deferred **action** never blocks DONE. The **directive itself** does, until confirmed:
    an unconfirmed gate is an OPEN item like any other (Step 4) — confirming it, not performing
    it, is what clears it. Surface it *as a gate to confirm*: name the action, who performs it,
    and **what it gates** — what it blocks / when it is "reached" (before v1 listing, before a
    Phase-2 commitment). The owner **confirms the gate** — a light sign-off that this is a real
    gate worth recording, **not** the performing of the action, which stays deferred. On the
    run after it is confirmed, the gate moves into the PRD body under the recorded-gates
    heading the prompt's principle 9 names and drops from here; whether the owner has *started*
    the action makes no difference — the only gate into the body is the confirmation, and you
    never move it on your own initiative. "Ask the vendor's account rep for their unpublished
    SLA terms" is the directive (their docs don't carry it, so principle 11's tools can't); it
    is recorded as a gate on "the rep's SLA terms" the moment the owner confirms it, whether or
    not they have picked up the phone.

  Never a bare menu: a choice leads with your drafted answer and why; an open issue leads
  with your reasoning and what would settle it; a directive names the action, who performs it,
  and what it gates, and asks the owner to confirm it. If you have a lean, it's a choice — the
  buckets split on whether you have a basis, not on how sure you feel.
- **The owner owns the taste calls.** Scope, target users, what "done enough" means. Your
  job is the draft, the diagnostic, the reasoning, and the honest recommendation.

## What the PRD is

The product-facing what and why — the **how** (architecture, system requirements, delivery
sequencing) belongs downstream. Updated in place with a version bump; never forked. **Read
cold**: every statement stands alone, and what is out of scope is as load-bearing as what
is in.

## The files and the loop

Resolve the product from the directed project's `system/projects/<name>/project.md`
`Product path:` — a caller names the *project*, never the paths. (Relative → inside the
instance repo; absolute → the product's own repo.) If `Product path:` is still an unfilled
placeholder, stop and say so — everything below resolves from it, including where an open issue
would be written, so there is nowhere to record the problem and nothing to author against.
Never invent the path.

| File | What it is |
|---|---|
| `<Product path>/docs/PRD.md` | The PRD. Permanent. |
| `<Product path>/docs/what_left.md` | The product's what-left list. |
| `<Product path>/docs/PRD_open_issues.md` | The companion — *open issues*, *choices to confirm*, *directives*. Transient. |
| `<Product path>/docs/trail/prd/cycle-<N>.md` | The owner's answered files, retired whole. Permanent. |

**Cycle numbering:** `N` is one higher than the **highest** `cycle-<N>.md` already in
`trail/prd/` — list the directory and take the max, so a removed or renamed cycle can't make
you collide with an existing one. The first is `cycle-1.md`; create `trail/prd/` if it isn't
there. Never overwrite an existing cycle.

**The loop, repeated until clean:**

1. You draft/update the PRD and write the open-issues file with what you couldn't settle.
2. The **owner answers inline** and re-runs the skill.
3. You **copy their answered file whole to the next trail cycle**, fold the answers into the
   PRD, and rewrite the open-issues file with only what's still unresolved. This is the
   ordinary cycle — something survives the fold. A run where nothing would is step 4's, and
   step 4 alone says what it may touch.
4. When the answers resolve everything, the run is the close: one run that folds, copies the
   answered file to the trail, and **removes** the open-issues file instead of rewriting it.
   **Its absence is the done signal.** The close has a precondition the ordinary cycle does
   not: the owner's answers must already be committed (Workflow Step 3 owns the rule and
   why). Re-entry is inline answers, so the first closing touch normally finds them
   uncommitted — and then it **changes nothing at all**: no fold, no trail copy, no rewrite,
   no commit; the companion survives intact, answers and all, for the owner to commit. It
   reports the state and asks for that commit; the re-run after it is the close, start to
   finish, in one run. That stop is a report with an ask, not a live interview. What
   "unresolved" means for a directive is the confirmation, not the action — Posture, above,
   owns that distinction and where a confirmed gate goes.

Step 3 is why the trail exists. Folding rewrites the open-issues file, and the close removes
it — so without the trail the owner's answers are destroyed twice, and their reasoning for a
decision survives only in git history. The trail costs one flag on the same commit and makes
every owner answer permanently citable. It is the skill's job; the owner never manages it.

## Workflow

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp