product-fdr
Principal PM-posture skill that authors a product's FDR — the behavioural contract, written off the settled PRD, SRS and SDD as the foundation step. Requires Principal PM posture (halts if invoked out
SKILL.mdskills/principal-pm/.claude/skills/product-fdr/SKILL.md
GitHubproduct-fdr
Purpose
Author a product's FDR (Functional Design Requirements): the behavioural contract — what the
product does, and the product decisions every change after it is built against. It is written
once per product, from the settled PRD, SRS and SDD, as the foundation step; the ADR
and the NFDR beside it are the Principal Architect's. The sequence and the reason the FDR waits for
the SDD are <CORE>/doctrine/setup/setting_up_a_project.md § The foundation step, which owns them
and is not restated here.
This file is the orchestrator: posture, the file loop, path resolution, staging, and the commit.
How to author — the inputs and their authority order, the altitude test, the FDR-completeness
lens, what makes a rule verifiable, the sorting of what to surface, the provenance gate, the
relation every rule cites, the finish walk, the stability rule, and the tone — is the authoring
prompt prompts/rich.md, applied at Step 2; a rule referenced below
by name lives there. The FDR's section shape is the template
<CORE>/templates/product-templates/fdr_template.md; the companion's shape is
fdr_open_issues_template.md beside it. None of them is restated here.
Non-interactive. The run never blocks on the owner: it derives the whole FDR best-effort, writes
what it can't settle into a companion open-issues file the owner answers on their own time, and a
re-run folds those answers in. That is what lets it run headless (as the principal-pm subagent) as
well as in an interactive principal-pm: session.
There is no machine gate. Nothing publishes a schema or a lint for an FDR, so no step here shells out to a checker and no exit code stands as a verdict. What stands in its place is the prompt's § There is no machine that can check an FDR, and what stands in its place — read it there; the absence is a stated property of this document type, not an omission in this file.
Posture
Principal PM role required. If invoked outside Principal PM posture (neither a principal-pm:
session nor the principal-pm subagent), stop and say: "product-fdr requires Principal PM posture.
Switch? (Open a session with the principal-pm: prefix, or run the principal-pm subagent.)" Do
not shed the role. Where the Principal PM ends and the delivery-tier PM begins is a posture
fact the Principal PM loader stack already owns — the two share a noun and nothing else — so take
the boundary from there, never from a restatement here.
The files and the loop
product-fdr produces the files below under the product's docs/ — the skill resolves the locations
(next section); a caller names the project, never the paths.
| File | What it is | Lifecycle |
|---|---|---|
<Product path>/docs/fdr.md |
The FDR — best-effort complete on every run. | Permanent; one document, revised and versioned in place (the bump-on-material-change rule is the template's own header note), never forked. |
<Product path>/docs/fdr_open_issues.md |
The companion, holding what the run couldn't settle, in the buckets fdr_open_issues_template.md defines — kept distinct, never blurred. Which bucket an item lands in, and how it is led, is the prompt's. |
Transient — exists only while something is unresolved. Its absence is the done signal. |
<Product path>/docs/trail/fdr/cycle-<N>.md |
Each answered companion, retired whole. | Permanent. |
The three names are lowercase, and they match each other on purpose. The document is fdr.md
(<CORE>/doctrine/setup/setting_up_a_project.md § The foundation step names that path), so the
companion and the trail follow it rather than the upper-case spelling a sibling skill's document
carries. A companion written at the upper-case path strands the loop on a case-sensitive
filesystem — the next intake finds no companion and the run reads as a first authoring — and is
silently harmless on a case-insensitive one, which is what lets the wrong spelling survive a
developer's machine and fail somewhere else.
Cycle numbering: N is one higher than the highest cycle-<N>.md already in trail/fdr/ —
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/fdr/ if it isn't there. Never overwrite an
existing cycle.
The loop, repeated until clean:
- The run derives/updates the FDR and writes the companion with what it couldn't settle.
- The owner answers inline — filling the companion's answer slots, whose names and shape are
fdr_open_issues_template.md's, stated there and not here — and re-runs the skill. - The run copies the answered companion whole to the next trail cycle, folds the answers into the FDR, and rewrites the companion with only what is still unresolved — an answer the fold leaves unsettled still drops, its residue re-raised as a fresh unanswered item. 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.
- When the answers resolve everything, the run is the close: one run that folds, copies the
answered companion to the trail, and removes the companion instead of rewriting it — through
the builder, Step 3's
--rm, never a hand-rm. No open-issues file = the FDR is done. The close has a precondition the ordinary cycle does not: the owner's answers must already be committed (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.
Step 3 is why the trail exists. Folding rewrites the companion 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 cp on the same commit and makes every owner answer permanently
citable. It is the skill's job; the owner never manages it.
Inputs and where the files land
- The PRD, the SRS and the SDD — the three documents the FDR is written from. Read each in full,
status line included. Their locations are the skills that wrote them to name — resolve each path
from
<CORE>/../skills/cpo/.claude/skills/product-prd/SKILL.md,<CORE>/../skills/cto/.claude/skills/product-srs/SKILL.mdand<CORE>/../skills/cto/.claude/skills/product-sdd/SKILL.md, never from a path remembered here. All three must exist: if any is missing at its resolved path, halt and report which. The FDR is the foundation step dropped after the SDD settles, and every rule it states carries an upstream trace tag — with a source absent there is nothing to trace to, and a document derived from two of the three is a different document. What each contributes, and which wins where two disagree, is the prompt's § Inputs you work from. What a status line means for the derivation — including one that is missing or carries a value its own template's vocabulary does not hold — is the prompt's rule; whatever it raises reaches the owner through the companion like any other item. system/projects/<name>/agari.md— the project's 上がり Agari, the declared terminus, beside the card below. Read it in full. What it means for the derivation is the prompt's § The terminus bounds the FDR; it is the scope boundary, not a source of behaviour. Its absence does not halt the run — neither does a file still carrying the placeholderproject-stampstamps. The state reaches the owner through the companion.system/projects/<name>/doctrine/— the project's own doctrine, if the folder holds anything. Read what is there. An empty or absent folder is silence, not a halt.- The product's
docs/folder — read it by listing the directory, not by recalling a set of filenames. Beyond the three inputs and the FDR loop files named here, whatever else the folder holds is input the run is entitled to: the trails of owner answers on the upstream documents, the UXD and the product's design and verbal language where they exist, anything a later round adds. What each carries, and which supersedes which, is the prompt's § Inputs you work from. Skip binary assets. Enumerating rather than naming is deliberate — a list of filenames kept here goes stale the day the product gains a document, and the run would never know what it had missed. - Context and constraints — whatever the owner hands you, or the docs it points at.
system/projects/<name>/project.md— the directed project's card. ItsProduct path:field resolves where every output lands; the field is the card template's (<CORE>/templates/project_template.md, the shapeproject-stampstamps the card from), so read it from the card in hand. Every laterProduct path:in this file means that field.
Path resolution. A relative Product path: is inside the instance repo; an absolute one is
outside it, in whatever repo holds the product (which need not be its root — Step 1 resolves that
repo as <repo>). Every instance-relative path this file names (system/…, .claude/…) resolves
from the instance repo root — the directory the session opened in; no step cds away from it. If
Product path: is a placeholder or awaits an owner value, halt and report: both outputs resolve
from it, so there is nowhere to write even an open issue recording the gap. Never invent one.
Workflow
Step 1 — Identify the project, read current state
Identify the target project and read:
system/projects/<name>/project.md— the binding. Resolve the file locations fromProduct path:, and resolve<repo>with it — the repo the commit lands in: the instance repo (.) for a relative path; for an absolute one,git -C "<Product path>" rev-parse --show-toplevel, because a product with its own repo need not sit at that repo's root. If more than one project exists and the target is ambiguous, halt and report the candidates — nothing can be resolved or filed without a project.- the PRD, the SRS and the SDD, at the paths resolved under Inputs and where the files land —
each in full. All three must be on the record: run
git -C <repo> status --porcelain -- <the three resolved paths>; any output halts the run, naming the file, for the owner to commit or discard it before re-running. Settled FDR content is derived from these three and then held stable against re-derivation (the prompt's stability rule), so deriving from an uncommitted source can leave a settled rule traced to text the owner later discards — a behavioural contract whose source was never on the record. Three paths, one question: this asks about no other file, and their existence is established above, so the only states left to tell apart are clean and not-clean. <Product path>/docs/fdr.md— the existing FDR, if any. It is the settled baseline the prompt's stability rule reproduces; no FDR here means this run is a first authoring.<Product path>/docs/fdr_open_issues.md— the existing companion, if any. This is the loop's re-entry point: the owner's inline answers are read here.<Product path>/docs/trail/fdr/— every answer the owner has already given, and their reasoning. Read it: a value the owner set in an earlier cycle is authorized, and changing it needs a fresh authorization (the prompt's stability rule). The prompt's provenance gate cites these files by path, and a citation you have not opened is not one. It also gives you the next cycle number.system/projects/<name>/agari.md— the declared terminus, in full. Absent or still the placeholder: record it as an open issue and derive best-effort; never halt.system/projects/<name>/doctrine/— the project's own doctrine, if any is there.- the rest of
<Product path>/docs/— list the directory and read what the bullets above have not already named. Skip binary assets.
Gather any context and constraints the owner handed you, and read them.
Step 2 — Derive/revise the FDR and write the companion (no interview)
Gate first — detect the first closing touch before you write anything. When a companion existed
at intake, its inline answers would resolve everything unresolved, and the file is uncommitted
(check the companion's git cleanliness in <repo>), this run is the first closing touch and
writes nothing: no derivation or fold, no trail copy, no companion rewrite. Skip the rest of
this step and Step 3, and report CLOSING at Step 4. Why the close needs committed answers is
Step 3's (--rm mechanics); the two touches are the loop's, step 4. Everything below runs only when
this gate passes.
Derive or revise <Product path>/docs/fdr.md by applying the authoring prompt
prompts/rich.md (how to think — the altitude test, the completeness
lens, the verifiability bar, the sorting test, the terminus, the provenance gate, the relation, the
finish walk, the stability rule and the tone) and the template
<CORE>/templates/product-templates/fdr_template.md (the FDR's section shape). Write the
companion from <CORE>/templates/product-templates/fdr_open_issues_template.md (its bucket and
slot shape). The prompt's stability rule reads its baseline where that baseline lives — the FDR on
disk at the FDR path, which Step 1 has already read; no FDR there is a first authoring, and the rule
does not bind it. This step restates none of the prompt's thinking.
Set the template's Status: line from Step 4's DONE condition — the companion's absence — not from
your tally of answers: Settled only when this run ends with no companion on disk (it removed
one, or a first run settled everything from its inputs and never wrote one); Draft otherwise.
The two cannot diverge: the only run that folds every answer is the close itself, which ends with
the companion removed, and the first closing touch writes nothing at all — FDR included — so no FDR
is ever stamped Settled beside a companion still on disk (the loop, step 4). Leave Locked alone
— ratification is the owner's act, not yours. Bump the template's Version: line on any run that
changes the FDR's content.
Do not interview. When anything lands in any bucket, write/update the companion from its
template. When nothing is unresolved, write none — an empty companion would read as OPEN and invert
the done signal: if none existed at intake, this run creates nothing (Step 3's neither); if one
existed, Step 3's --rm removes it.
Consuming an answered companion. A companion that existed at intake with at least one answer
slot filled is consumed — what counts as an answer slot is the companion template's, read from
its current shape, never from a name remembered here, so a template rename cannot make filled
answers read as unfilled. Consuming is three moves, in this order: copy the companion whole (an
ordinary cp) to the next trail cycle, before the fold rewrites it; fold the owner's answers into
the FDR; then drop every answered item from the companion.
An answered item never survives the drop. Where the prompt's fold rule settles the answer, the item is resolved and gone. Where the answer leaves something unsettled, the item still drops and the residue re-enters as a fresh item with an empty answer slot — a new item this run raises, never the old one surviving. Whether an answer settles its item is the prompt's fold rule; this step only moves the files that rule implies. What the drop buys is the invariant the rest of the loop keys on: a filled slot in a surviving companion is always the owner's writing, never this run's, so a run's own rewrite can never re-fire this detection at the next intake.
A companion with no slot filled is not consumed — no trail cycle, nothing to fold. And when the drop
resolves every item, the write none rule above owns the disk: leave the companion as intake
read it (the trail copy already holds it) and let Step 3's --rm remove it. No state of this run — a
halt between Step 2 and Step 3 included — ever leaves an empty companion behind.
Step 3 — Commit through the builder
Commit through the shared builder — read <CORE>/doctrine/governance/commit_via_builder.md and supply
its variables (<repo> from Step 1, the --add/--rm paths, the actor, subject/body, the
directional). The builder stages, derives Role:, and lays the whole trailer block; this step never
hand-writes a git commit, spells a trailer, cds into the repo, or resolves the directional
shape. What follows is only the values product-fdr feeds it.
A run that changes nothing builds no commit — and touches no disk. If this run folded no answer,
changed no FDR content, and has nothing to stage, make no file change at all: don't copy to the
trail, don't rewrite the companion. (This is not the recipe's --allow-empty marker case —
product-fdr makes no commit at all on an empty run.) Report the state (Step 4) and stop.
The stage list — compose it from what this run actually did. Pass every qualifying path in
one --add (and the companion as the one --rm path, when removed) — the recipe's flag rule
owns why. <D> below is the resolved docs directory, <Product path>/docs expressed relative to
<repo> (plain docs when the product is the repo's root; the subpath when it sits deeper; the
instance-relative path when <repo> is .).
--add <D>/fdr.md— always, on any run that builds a commit.- The companion, exactly one of:
--add <D>/fdr_open_issues.md(something is unresolved) ·--rm <D>/fdr_open_issues.md(nothing unresolved and one existed at intake — its removal is the done signal) · neither (nothing unresolved and none existed). The owner answers inside the companion, so the close needs their answers already committed — git won't remove a dirty file, and their words aren't yours to commit. A dirty companion when everything would resolve marks the first closing touch: Step 2's gate stopped that run before any write, so it never reaches this step. --add <D>/trail/fdr/cycle-<N>.md— only if this run consumed an answered companion. The trail copy rides the same commit as the fold it precedes; neither fires without the other.
Actor: --actor principal-pm --skill product-fdr when running as the principal-pm agent (the
usual path — the subagent, or a --bg run launched --agent principal-pm); from an interactive
principal-pm: session with no agent named, --role "Principal PM" --skill product-fdr instead.
Both derive Role: Principal PM; why --skill is explicit is the recipe's to say. Subject/body, the
directional, and the surface / co-author trailers are the recipe's variables — fill them per the
recipe, not from an example copied here.
And --prompt product-fdr/rich, naming the body this skill is the carrier for. A thin skill over a fat prompt is recorded by both lines and neither implies the other (<CORE>/doctrine/governance/commit_format.md § Prompt-Version: trailer); it takes the bare name, never a path.
The directional is Agari: or Shukuba:, resolved against
<CORE>/doctrine/governance/commit_format.md § Directional trailer, whose rule is that the trailer
follows the commit's scope rather than what produced it. The FDR is project-scoped and the
foundation step runs upstream of the delivery loop, so a project with no open station resolves to its
Agari — that file names the Principal PM's FDR as one of the cases it exists for. Read the rule
there; this step does not restate it.
Step 4 — Close / report
Report:
- the FDR path, and the commit SHA (or that the run changed nothing and built no commit);
- on any run that consumed an answered companion, the trail cycle path —
<Product path>/docs/trail/fdr/cycle-<N>.md, the copy Step 2 made. The loop (its step 4) owns why that copy is the surviving record of the owner's answers; the report names it so the owner can verify their answers survived without opening the commit; - the loop status, exactly one of:
- DONE — no open-issues file remains. Nothing is unresolved; the FDR is complete.
- CLOSING — the owner's answers resolve everything, but the companion is dirty, so this run was the first closing touch and changed nothing (the loop, step 4; Step 3's companion rule). Nothing is left to answer; the one ask is: commit the companion, then re-run — that re-run is the close.
- OPEN — something is still unanswered. Give a count per bucket, under the bucket names the
companion on disk carries (its shape is
fdr_open_issues_template.md's, so read the names there, never from a name remembered here), name where they live, and name the next move: the owner answers inline, commits, and re-runs product-fdr.
Do not enumerate downstream steps; authoring the FDR is this skill's whole job.