Design-Rationale Record (DRR) for FPF Content Decisions
About this pattern
This is a generated FPF pattern page projected from the published FPF source. It is canonical FPF content for this ID; it is not a FPF Reference product feature page.
How to use this pattern
Read the ID, status, type, and normativity first. Use the content for exact wording, the relations for adjacent concepts, and citations to keep active work grounded without pasting the whole specification.
Type: Governance and authoring pattern Status: Stable Normativity: Normative
- A proposed normative change needs a statement of what FPF should say, why that answer is preferred, and which neighboring patterns or selected non-pattern FPF kind-reference pairs it affects.
- Several such loci must change together. An external record must keep the complete content decision available while authors distribute enduring text across Core.
- Authors would otherwise have to settle the same consequential question separately in several patterns or selected non-pattern FPF kind-reference pairs.
- Authors need to review a deprecation, narrowing, or cross-pattern amendment without reconstructing its rationale from patches, conversations, or scattered notes.
Relations
Content
Use this when
- A proposed normative change needs a statement of what FPF should say, why that answer is preferred, and which neighboring patterns or selected non-pattern FPF kind-reference pairs it affects.
- Several such loci must change together. An external record must keep the complete content decision available while authors distribute enduring text across Core.
- Authors would otherwise have to settle the same consequential question separately in several patterns or selected non-pattern FPF kind-reference pairs.
- Authors need to review a deprecation, narrowing, or cross-pattern amendment without reconstructing its rationale from patches, conversations, or scattered notes.
Not this pattern when. Normative Core rules belong in their selected loci. Keep campaign and process briefs outside the DRR. If a purely editorial Delta-0 or Delta-1 change needs a decision record, use the lightweight variant in CC-DRR.5 when it fits. Use E.9.DA when a DRR already exists and you need to judge its answer, obligations at selected loci, source use, lexical closure, and drafting actionability for a declared downstream authoring use.
What goes wrong if missed
- Later readers cannot recover why Core changed, which alternatives were rejected, or which exclusions were intentional.
- Coordinated amendments drift apart when the selected answer survives only in patches, handoffs, or a reviewer's memory.
- Later repairs can fit local wording while losing the constraints supplied by Pillars, taxonomy lenses, the impact graph, practical use, or pattern placement.
What this buys
- An external record states the content of a bounded FPF change before authors rewrite Core.
- Four components keep the Problem frame, Decision, Rationale, and Consequences available for later review and replay.
- For a distributed change, the record holds the selected answer while authors draft the enduring Core text at the selected loci.
First useful move. State the working FPF problem, selected answer, practical change, selected loci, first substantive drafting action, and nearest boundary in plain, precise language before drafting or landing Core text.
Cheap stop. If local wording repair, application of an accepted pattern, or editorial cleanup preserves FPF semantics, obligations, boundaries, names, admissible uses, and normative force, it needs no full DRR.
Use F.19 for kind-preserving plain rewriting and E.10 for an unresolved FPF wording-use question. Use E.17.AUD.LHR for an overloaded local lexical head inside one publication unit and C.2.P for an episteme, publication, or source-use distinction still unresolved after E.10. Use F.18 only for minting a durable reusable name and E.8 for an authoring-form correction. Use E.9 when a bounded content decision needs its rationale stated.
Kind-or-boilerplate diagnostic. Before proposing wording from a DRR as pattern prose, use F.19 to separate boilerplate from substantive content. If the remaining wording still obscures its use, name, relation, claim, admissible use, selected locus, user action, or flow position, name the contribution applied: E.10, E.10.ARCH, F.18, or the pattern that defines the object or relation. Keep process, architecture, review, and reference boilerplate in the material it belongs to.
Before using proposed wording in a pattern, establish from the selected answer which object, relation, claim, slot, use, admissibility condition, or scope would change, or that none would change. Use F.19 and the pattern that defines or constrains the distinction. Introduce Method, Work, application, or ClaimGraph details into ordinary wording only when that distinction changes the decision or a later reliance.
Primary EntityOfConcern in plain terms. The external decision-rationale record for one bounded FPF content decision or coordinated change set. The author must be able to recover the problem, selected answer, reasons, consequences, practical change, selected loci, and boundary without inventing them. Add exact C.2.1 identity only when the decision or a named later reliance needs it.
Primary working reader. An FPF author, reviewer, or steward uses the DRR to evaluate, challenge, or land a bounded content decision. Downstream pattern readers can use the guidance once it has been incorporated into Core.
Problem frame
Under Pillar P‑10 Open‑Ended Evolution, FPF's normative rules must adapt as new calculi and insights arrive. Changes whose answers and reasons cannot be recovered erode those rules. A formally detailed record can still defer the decision or distribute a harmful rule. A Design‑Rationale Record (DRR) preserves the selected answer and its reasons for one bounded change before authors distribute its normative content.
Problem
Either a direct edit to Core or a DRR that documents the apparatus but leaves the answer unusable can expose the following risks.
- Lost decision grounds – future authors cannot recover why the answer was selected, which alternative or boundary mattered, or when to reopen it.
- Decision deferral – a polished record leaves the answer, affected loci, or first drafting action for each later author to invent again.
- Proxy-led fanout – an abstract rule passes a schema, checklist, or unrelated replay while making an actual predecessor/proposed host harder to understand or use.
- Conceptual and authority drift – incremental edits blur the framework's foundations, or the temporary rationale record becomes a shadow Core law, process brief, or authorization source.
Forces
Solution — state the decision before distributing it
Present the Decision account first in plain, precise language. Before a reader meets a DRR identity schema, a Method or Work account, or a catalogue of alternatives, they must be able to recover, in this order:
- the working FPF problem and why it matters now;
- the selected answer stated positively;
- what changes in practitioner or authoring use;
- the selected loci and the positive obligation each one carries;
- the first substantive drafting action; and
- the nearest boundary, blocker, or reopen condition.
If the answer is unsettled, develop it through a working expression under §4.2. The order above is for readers of the resulting decision; inquiry can start with an open question.
Once supported, the short decision account is the primary source for drafting. Add exact Method, Work, application, episteme identity, source use, assessment, or authority only when the decision or a named later reliance depends on that distinction.
A nontrivial DRR must make the four components below recoverable. They form the minimum decision kernel. CC-DRR.5 gives the lightweight editorial variant.
In this pattern, a bounded coordinated change set brings together mutually dependent content-decision questions within one decision boundary. Several patterns or selected non-pattern FPF kind-reference pairs carry the enduring FPF expression of that decision.
The selected answer is what FPF should say, which selected loci carry it, what practical action changes, what stays outside, and which source-use, evidence, validation, or loss/recoverability conditions remain live.
A selected non-pattern FPF kind-reference pair is a content-distribution instruction, not a new kind. It names an admitted FPF kind and one exact reference by value—for example a U.View, source map, source-use note, evidence-path record, review-finding record, or architecture-decision record. The selected patterns and such non-pattern items are the selected loci of the decision.
A temporary convergence record holds the selected answer while authors update several selected loci. Enduring normative rules belong in Core, and process state belongs outside the DRR.
Keep a rejected alternative only when it explains the selected answer, a live boundary, or a reopen condition. Pillars and taxonomy lenses may inform the decision, but the DRR records their load-bearing effects rather than rehearsing every lens or preserving the history of discussion.
Before adopting a language, ontology, or authoring rule for wider use, apply it to at least one real host and its proposed replacement, including their dependencies. At comparable effort, compare the recognizable entry, required inputs, first action, practitioner vocabulary, formality and assurance burden, first useful result, stop or return, preserved useful ideas, and direct consumers.
The proposed wording must pass the E.8 first screen and the F.19 kind-preserving plain-rewrite test. A schema, invented fact pack, unrelated lane test, checklist, or promised review cannot replace this comparison. If the pilot makes the host harder to use without a compensating semantic gain, repair or reject the rule before applying it elsewhere.
A DRR records the selected answer. When exact identity or reliance makes the distinction material, separately identify the decision work and method, selected-answer result, C.2.1 DRR episteme, source-use relations, assessment and result, any acceptance or authority, and later realization work. An exact DRR episteme then follows C.2.1 identity by <ClaimGraph, EntityOfConcern, effective ReferenceScheme>; ordinary use does not require materializing that whole account.
Minimum decision-inspection content blocks
A nontrivial DRR must also make the following parts of the decision available for inspection. Authors may present them within the four kernel components or in a dedicated Decision grounds used or decision-inspection block. They are part of an adequate decision before it reaches a later review.
These blocks supply the content of the decision. Four headings cannot tell a later author the grounds, first-minute working situation, naming choice, distribution, sufficiency or necessity of a pattern or non-pattern FPF kind-reference pair, treatment of overlap, impact, or remaining uncertainty. Make those answers recoverable in the DRR without creating separate process paperwork.
For a coordinated change, settle the common answer in the DRR before drafting. Each author can then express that answer at the selected locus without having to decide it again.
When a decision connects several selected loci or mutually dependent edits to patterns and non-pattern FPF kind-reference pairs, its DRR MAY include more than the minimum kernel. It can state obligations at each locus, the choice between a new and an existing pattern, how impacts or non-goals map across the selected loci, coverage or agreement across them, and whether overlapping changes converge. A provisional account of the decision rule can hold the full bounded answer until its enduring content is distributed in Core.
These additions leave the DRR's kind unchanged. It conforms only while it records what FPF should say and why, what is excluded, how the selected loci are affected, and what improves in practice or authoring. A record with richer coordination content MUST NOT become a campaign plan, process script, baton carrier, packet checklist, staging log, or other development-process brief.
If an existing pattern or selected non-pattern kind-reference pair might suffice, or a new locus might be needed, the DRR must settle that choice. A tentative list leaves the choice to the next author.
Classify each pattern or non-pattern kind-reference pair that the accepted grounds or the DRR bring into the distribution question. State its obligation if selected. Otherwise identify it as an unchanged boundary neighbour, inherited unchanged, or outside the current decision with a named pattern, kind-reference pair, or decision record. Saying it may need local hardening leaves that choice open.
If the grounds reveal a potentially reusable non-pattern carrier or a related source-use, evidence, assurance, validation, or architecture-decision mechanism, the decision must classify it as generalized now, kept local with a reason, rejected, or outside with a named locus or decision record. The DRR records the choice; mentioning an artifact does not decide its use.
For source loss, simplification, redaction, summarization, or other declared loss, the DRR must state which distinctions survive and which are lost. Identify each admissible branch reading and its selected non-pattern FPF kind-reference pair, the uses without an admissible carrier or evidence path, the recoverability class, and the stop or reopen rule when the use exceeds the declared loss or narrower scope.
Before another author can use a nontrivial DRR to draft the selected changes, it must settle the material choices about its EntityOfConcern, selected loci, outside boundary, reusable content, and loss or recoverability regime. Each is selected, rejected, inherited unchanged, or placed outside with a named locus or decision record. While any of these choices is missing, the work is still establishing the decision grounds; it has not produced an accepted DRR.
The DRR episteme lives outside normative Core. A separately governed acceptance, authority, or realization decision may rely on it, but the word accepted, a record status, review mark, or publication does not make its claims true or authorize change.
Once realization is separately authorized, authors apply the selected answer to its loci in dated authoring work. The changed Core content, authoring work, result claims, checks, witnesses, publications, and any landing or release record remain distinct; apply the relevant pattern to each claim. The DRR remains external provenance and temporary convergence support; after realization, the enduring semantics must be available in Core.
Authors using a separately accepted selected answer may elaborate examples, SoTA-Echoing, recognition sections, local wording, and neighboring fit inside its declared stability boundary. A change to the selected answer, selected loci, outside boundary, reusable-content disposition, or loss/recoverability regime requires a successor decision result and DRR episteme rather than a silent edit to downstream prose.
Improvement work may apply E.23 to a DRR episteme. That work, its method applications, quality-result claims, and witnesses are separate from the DRR and do not turn the record into a pattern draft. When a successor decision relies on SoTA, its result must show what changed in the selected answer, locus obligation, boundary, example, validation obligation, or reopen condition; otherwise the source use remains rationale-only or lineage-only.
When a campaign changes route-shaped, unfolding-shaped, first-entry, DPF or multi-pattern path material, make the connection from its actual starting situation to the selected solution and next use recoverable. The following optional form can carry those contents; include only fields that describe the current decision:
After host drafting, identify any enduring selected content that remains available only in the DRR. Move it into the selected pattern body, unfolding block, README seed, E.11 expansion or concrete relation locus so that the public reader can obtain and use the solution.
To preserve P-2 Didactic Primacy without duplicating meta-text, realization work using a separately accepted selected answer should distill stable Rationale, Consequences, SoTA-Echoing, Grounding, and other valid convergence content into the selected informative pattern loci under E.8. The DRR episteme remains external provenance; it is not itself landed or transformed into Core.
A substantive DRR is one claim-bearing episteme about one bounded current content-decision question/change set. It may carry selected obligations only in its Decision or Consequences, but no route, gate, handoff, packet, monolith, mutable status, or future-campaign state. Any undecided remainder is explicitly outside the decision with a named pattern, kind-reference pair, or successor decision record.
Process-source method admission into FPF
When an author considers a stable method described in a process source, the author decides the FPF-admission disposition by value. The DRR records that decision and any source-use relation that matters; neither the source passage nor the record becomes a second canon.
Record the following when deciding whether to admit the method:
- the content of the passage or accepted decision ground being considered from the process source;
- the reusable FPF method recovered from that passage;
- the current FPF pattern, section, or accepted
DRRthat already carries the method, if any; - the contribution still missing from FPF;
- the FPF pattern selected to carry that contribution;
- process-control material excluded from FPF pattern prose, such as task dispatch, seam state, helper behavior, Git recovery, packet transport, review transport, chat cadence, and mutable release state;
- how the passage or decision-ground item was used: quoted by value, narrowed in scope, instantiated as a case, used as decision grounds or drafting guidance, retained only as an example, or retired;
- any meaning loss or addition created by that source-use result: changed scope, relation, evidence path, admissible use, non-admissible use, reader use, or recoverability condition;
- the first improved FPF use that the admitted method gives to an author, reviewer, or downstream FPF user;
- the disposition: selected now, inherited and sufficient, rejected now, or outside this decision. For an outside item, name the evaluation pattern or accepted
DRRthat carries it, or state the content of the accepted decision ground that does so.
Reusable process-source methods may contribute beyond semio wording or pattern-authoring language. Admit the contribution when it is separable from local process mechanics, improves the selected FPF use, and has adequate grounds for the claims being made. Apply E.19 to pattern admission and E.21 when a pattern-quality conclusion is required. After the method lands in FPF, process documents should cite the selected FPF pattern instead of keeping a parallel long-form rule.
Develop an unsettled decision through a working expression
If the answer is unknown, start with the difficulty and the material available. Use §4's order to present the answer once selected. Filling the Decision block in advance would require the author to guess what the inquiry is meant to establish.
Use a provisional expression to bring a consequential relation into view: juxtapose two cases, arrange competing explanations, trace a dependency, or compare an intended use with the result currently available. E.8:4.2.1.2 and A.6.3.RT.OE supply the expression construction. Identify what the arrangement lets you infer and what remains unsupported. A question mark can make an unresolved interpretation visible; it supplies no premise for choosing one answer.
Let the result change the decision question when it reveals that the original question conflated different work. Retain live alternatives only for the comparison they support. Replace a classification by format, tool or package name when the deciding difference concerns the operation or conditions of use. A working table can therefore be revised or discarded after it has produced the useful distinction.
Before another author relies on the selected answer, resolve each premise that can change its selected obligation, or bound the result so that the remaining uncertainty does not defeat that obligation. If neither is possible, state where the decision must stop. Use the four kernel components and the applicable inspection content in §4.1 to inspect that closure. Material already recoverable in the account need not be copied into another answer column. A source pointer without the needed substantive contribution is not recoverable decision content.
Keep this difference visible in the writing. “The source order for this row is unknown” can be a valid investigation result. “Convert this row using day/month/year” would require the missing premise. Conversely, a settled decision to stop such rows and request their interpretation can be supported even while their dates remain unknown. What remains open must be compared with the decision being made.
The record carries the resulting problem, selection, reasons and consequences, not every discarded worksheet or the chronology of deciding. Retain a working expression when a later use needs its reasoning or recoverability; otherwise carry its useful result and source return into the decision.
Archetypal Grounding (System / Episteme)
Decide what support a conversion pattern should carry
An author is revising the date-conversion explanation in E.8:4.2.1.1. The explanation already supplies the essential rule: use the applicable supplier guarantee to choose the date order before running the converter. North guarantees month/day/year, South day/month/year for the files at issue. The same text, 03/04/2026, accordingly yields March 4 or April 3. The intended practitioner can run a converter with a supplied order. The author can follow that reasoning but has yet to decide whether the public method should prescribe a table, a per-row card or prose alone.
A first working note says: “Choose a standard date card; include source, raw value, order and converted value.” It proposes a form before establishing whether all four entries are independent user inputs or what their arrangement must let the reader do. Turning those words into a completed Decision would hide the open question.
The author constructs the raw/result expression and its unresolved cell shown in E.8:4.2.1.2. It keeps both possible results visible. Trying to select an output from the raw text alone fails. The supplier difference leads to the source-qualified comparison. This yields a more useful decision question: which source-to-interpretation connection must the pattern explain, and which expression makes that connection usable without requiring unnecessary repeated entry? The comparison shows which information must be available and which the user must enter. Removing repeated entry still requires access to the source information.
The author now compares three alternatives for practitioners with the same preparation:
The comparison does not demonstrate that every reader is faster with a table. It establishes different supported operations and context dependencies. The author selects the third alternative for the explanatory example, retains the first as a sufficient compact use, and rejects the universal manual-card requirement. The selected pattern account has to teach the conditions of reducing the view and restoring the missing context.
A short decision account can now carry the useful result:
- Problem frame: the existing conversion method is available, but authors lack the worked choice between explanatory comparison and a mandatory record for each conversion.
- Decision: develop the expression-construction explanation in E.8:4.2.1.2, with the source-qualified comparison and a conditional reduced view. Preserve §4.2.1.1's source-to-order selection and stop when the date order is unknown. Do not prescribe a card for every row or change the converter's subject method.
- Rationale: the different outputs for identical raw text require an interpretation supplied by the applicable source. A juxtaposed comparison teaches this relation. Re-entering a value already supplied by the session is a separate burden with no additional contribution to that local operation. Detached reuse changes that judgement.
- Consequences: keep the guarantee's scope and source return beside the operation; restore row-level context for mixed or separated use. First draft the explanation and the expressions being compared at the named locus. Examine whether the intended reader can recover and apply the selection under the stated preparation. Do not claim observed learning, speed or universal usability from this construction.
These paragraphs supply the bounded content decision; they are not answers copied into every inspection row. Its exact grounds are the existing E.8 explanation, the stipulated supplier guarantees and the performed comparison. The related conversion operation remains unchanged. No new date kind, source-independent interpretation or general record schema is selected. A changed supplier guarantee reopens the affected interpretation; an actual reader failure would reopen the explanation or its support.
Now South changes to mixed orders without row-level information. The author can still settle the content decision to preserve the earlier results, represent the new unknown and stop that row's conversion pending a trustworthy interpretation. The missing date order does not prevent explaining that boundary. It does prevent selecting a particular converted date. If the proposed public method instead promised to convert every row without obtaining such information, the author would have to change that promise or stop the dependent decision.
E.9's four components and inspection content remain stable aids for making the final selection recoverable. The provisional card is not preserved merely because it was the first form used. Its useful source-to-interpretation distinction survives in the selected account, while unnecessary per-row manual entries are removed. Here E.9 applies to the choice of support for an author: the working expressions helped form the question and select an answer; the record preserves that supported answer for the next author.
Bias-Annotation
This bias annotation applies to every FPF semantic change governed by E.9. It does not turn project-management state, helper state, or review logistics into DRR content.
Conformance Checklist
Common Anti-Patterns and How to Avoid Them
Consequences
Rationale
FPF evolves through explicit, reviewable decisions rather than silent edits. The DRR is the minimum structured argument and, when several loci must move together, a temporary convergence record. This keeps P-10 Open-Ended Evolution compatible with P-1 Cognitive Elegance and P-2 Didactic Primacy. Exact method, work, result, episteme, assessment, and authority distinctions remain available when a current claim depends on them; they do not precede or replace the readable decision.
Every nontrivial conforming DRR must make Problem frame, Decision, Rationale, and Consequences recoverable. It may also carry the coordination content that prevents shadow documents or new decisions being invented during distribution to Core patterns and selected non-pattern FPF kind-reference pairs.
The minimum includes what authors and reviewers would otherwise have to reconstruct: exact grounds, use-value, the first-minute working situation, scenario, alternatives and current dispositions, naming or ontology obligations, content distribution, whether an existing pattern suffices or a new one is needed, overlap, stability of the answer, the graph of impacts and boundaries, practical payoff, and uncertainties that could change the decision.
Pointer-based DRRs (CC‑DRR.1a) prevent duplicated prose, and distribution into Core patterns and selected non-pattern FPF kind-reference pairs (CC‑DRR.4) keeps the specification itself learnable without turning the DRR into a permanent shadow canon. Process-law ordering, gate, and handoff records stay outside because they are not part of the content answer that FPF is selecting.
SoTA-Echoing
E.9 draws on established decision-record and design-rationale practices. A cited standard or template does not establish current SoTA for every FPF decision. The DRR selects current problem-owning evidence under E.8 when that evidence is load-bearing. Its distinctive contribution is a decision-rationale record for one bounded FPF content decision, with enough by-value rationale to distribute durable content without making the record a shadow specification.
MADR's template connects context, considered options, a justified decision and consequences; its confirmation section is optional. E.9 retains this concise rationale function. When one FPF decision changes several loci, it additionally assigns their content obligations and the conditions under which authors can use the selected answer. A longer record is useful only for those remaining dependencies.
ISO/IEC/IEEE 42010:2022 distinguishes an entity's architecture from its description and leaves architecting processes and recording media outside its scope. E.9 likewise keeps its decision record distinct from the selected architecture and the work that realizes it; the standard does not supply the FPF content decision or its admission result.
To improve the choice of content when a decision has substantial semantic consequences, the deciding work settles the answer, alternatives, losses, boundary, and loci. The DRR episteme lets another author replay that selection before drafting. Any durable rule, example, or obligation useful after realization belongs in the selected FPF pattern or non-pattern kind-reference pair, not in the DRR as permanent shadow canon.
When an identified source shapes the answer—for example a prior decision, standard, plan, or review packet—the DRR records how it is used and which payload is selected or left behind, including any material loss, destination locus, stop or return, reopen condition, and non-use boundary admitted by F.19's grounded-contribution test. Name the exact source episteme, publication, and source-use relation when the decision or a named later reliance depends on those identities. A citation supplies traceability; every stronger receiving claim needs its direct result or relation.
Relations
-
Instantiates: P‑10 Open‑Ended Evolution, P‑2 Didactic Primacy
-
Pattern publication form governed by: E.8.
-
Interacts with: E.5.4 for the lens check.
-
Complemented by:
E.9.DAwhen a particular DRR must be checked for a declared downstream authoring use. An ordinary bounded review judges the decision and returns precise findings or repaired text; a complete coordinate result and its exact assessment identities are added only when expressly requested or needed by a named later reliance. E.9.DA is not a second DRR form, review gate, acceptance status, or mandatory editorial step. E.12 separately governs didactic clarity, rationale and review of cognitive workload. -
Coordinates with:
E.23for repeated improvement work on a DRR; C.2.1 for DRR and evaluation-result episteme identity; C.2.P/A.10/G.6 for exact source use and provenance; A.15.1 for performed decision, assessment, and realization Work; A.6.1 when a claim depends on an independently identified application of a declared mechanism operation; F.10/G.11 for status and currentness; E.24.PUB for publication; and C.29 for a mathematical-lens use when such a lens is used. None of these neighboring records or results changes the E.9 selected answer by implication.
E.9:End
Last Updated: 2026-09-25 — this section last modified in upstream FPF commit 3dae70bd (github.com/ailev/FPF)