Library / First Principles Framework (FPF) - Core Conceptual Specification
Jump to passage
In this reading

Link to current text

Published source confirmed at last check

Source changed 2026-10-03 10:39:28 UTC · snapshot created 2026-10-03 10:40:04 UTC · last check 2026-10-03 11:25:15 UTC

C.32.ADR:4 - Solution

Create ArchitectureDecisionRecordProjection@Project from an existing ArchitectureDecisionRelation@Project and ArchitectureDecisionDescription@Project. If the decision relation is missing, require C.32.PAD before writing the record.

Work in this order:

  1. Name the publication carrier and intended readers. Use a file or other carrier for the Markdown ADR, decision memo, trade-study record, engineering change note, certification rationale, design-review record, or other decision-description form.
  2. Cite the decision relation and decision description. If the record cannot cite them, draft them first.
  3. Choose the smallest record scope that lets intended readers use the decision. Avoid copying architecture descriptions or full method descriptions; cite them by value where possible.
  4. Map section functions to headings or carrier slots. Use local headings if needed, but keep the function rows recoverable.
  5. Carry the candidate basis. Record candidate options from C.32 or the reason no candidate-set question is live. Do not invent options in the ADR after the decision.
  6. Carry the decision outcome. State the selected architecture option, bounded exception, or supersession relation from PAD.
  7. Carry rationale, accepted losses, and consequences. Include architecture-characteristic trade-offs and guardrails, not only benefits.
  8. Carry method-use instruction and work split when the decision guides developer work. Cite A.15, method descriptions, pattern-use refs, readiness exits, and expected structure effects rather than burying them in prose.
  9. Carry confirmation, eval, or violation-detection exits. Use C.32.ACE, C.16, A.10, B.3, A.21, or governance patterns when those claims are live.
  10. Carry publication and source-return boundaries. Use E.17 for source-backed publication faces and source return, E.24.PUB for publication occurrences and audience availability, and C.30.AD for architecture-description claims.
  11. Carry status, supersession, and update conditions. Old records remain useful as history when superseded; the active decision relation tells which one governs current work.

C.32.ADR:4.1 - Required section functions

The following section functions are required unless the decision relation states why the function is not live for this record use.

Section functionWhat the record must let the reader recover
Identity and statusRecord id, title, status, date or version, relation to superseded or superseding records.
Problem frame and decision questionThe bounded architecture question, described holon, context, and current reader use.
Forces and architecture characteristicsThe architecture characteristics, constraints, concerns, and trade-offs that made the decision nontrivial.
Candidate optionsCandidate options, rejected options, bounded exception, or stated reason no candidate-set question is live.
Decision outcomeThe selected architecture option and affected selected structures.
RationaleWhy this outcome is acceptable now, including accepted losses and protected guardrails.
ConsequencesExpected effects on structures, methods, teams, costs, risks, evidence, operation, and later change.
Method-use instructionRequired style, pattern use, method description, or work practice, when the decision changes developer work.
Work splitProspective allocation or instruction content through the plan, policy, commitment, permission, decision, responsibility, authority, or other direct relation that actually states it; otherwise the exact missing governor. Also show readiness or gate exits and the source-return condition. Professional titles are audience cues, not ownership predicates.
Confirmation or eval exitHow the decision can be checked, evaluated, monitored, or found violated.
Publication boundaryLinks to architecture descriptions, views, evidence, assurance, and source material without making the ADR the source object.

C.32.ADR:4.2 - ADR package use

When several records form a package, create a package map that names active, proposed, superseded, and related records. A package map is a publication navigation aid. It does not merge decisions, replace PAD relations, or decide record priority by file order alone.

When one decision changes another, use explicit supersession or amendment links. Do not rewrite history by deleting the old record unless the project has a governed archival policy.