fpf.tools
Library / First Principles Framework (FPF) - Core Conceptual Specification
Jump to passage
In this reading
Source · lines 84787–84903

Link to current text

Published source confirmed at last check

Source changed 2026-10-03 08:25:59 UTC · snapshot created 2026-10-03 08:26:43 UTC · last check 2026-10-03 09:25:05 UTC

E.8:4.1 - Canonical Pattern Template

Within each pattern, the canonical section headings SHALL appear in the order below. For each canonical content section heading (1–12), the <Title> component (after the heading separator, e.g. -) MUST start with the canonical section title or its explicitly accepted alias (case-insensitive match; canonical capitalisation preferred); an optional clarifier after an em dash is allowed (e.g., Solution — …). The mandatory Footer marker (section 13) is the final sentinel and is governed by H-9 rather than the standard <FullId> - <Title> shape.

Extensibility. Authors MAY add additional sections. Prefer expressing them as subsections under the nearest canonical section (e.g., 4.1, 4.1.1 under Solution). If an additional pattern-level section is necessary, it MUST NOT delete or reorder the canonical sections and its title MUST NOT shadow a canonical title.

Mandatory vs optional.

  • Canonical sections 1–13 are mandatory in every pattern.
  • Canonical sections carry content. Authors must not use omission placeholders as section substitutes; when a section is intrinsically small, write the smallest content-bearing grounding, misuse, boundary, or reduced-case statement that preserves the section’s function.
  • First substantive authoring seed. The first non-empty authored body of a pattern SHALL already instantiate the canonical section frame by value: title line, header block, canonical sections 1–13, and the footer marker.
  • Seed is not maturity. The canonical frame is a minimum authoring seed, not a mature pattern claim. Before a pattern is used for public, teaching, enterprise, reliance-bearing, landing-input, release-input, or ordinary practitioner guidance, each canonical section must carry enough recognition, action guidance, worked material, source/SoTA use, boundary, consequence, and relation content for the declared use. A material maturity, readiness, admission, or landing claim also needs the independent complete E.21 result selected for that conclusion; an author-side provisional pass or focused repair check does not supply it. A file with correct headings, thin bullets, scenario labels, or compressed DRR recap remains a pattern seed until that content is present or the package explicitly marks it as seedOnly.
  • Recognition openings and first-minute working guidance belong inside that canonical frame. Any retained pre-template entry material must also stay inside that same canonical frame rather than appearing as one pre-template opening memo. Authors MUST NOT seed one pre-template opening memo and postpone canonical sectioning, Conformance Checklist, or footer-marker installation to one separate E.19, assembly, or review-repair pass.

Template:

  • Title line: Hashes + FullId + - + Pattern Title; optional (informative) note.
  • Header block: Type, Status; optional Normativity override.
  1. Problem frame
  2. Problem
  3. Forces
  4. Solution
  5. Archetypal Grounding (Tell-Show-Show; at least one content-bearing grounding slice, reduced grounding case, or ordinary/non-use boundary)
  6. Bias‑Annotation
  7. Conformance Checklist
  8. Common Anti‑Patterns and How to Avoid Them (grounded misuse, text-invited misreading, or a decision-relevant non-use boundary under CC-SG.11)
  9. Consequences
  10. Architectural Rationale (Rationale is an accepted title for the same function)
  11. SoTA-Echoing (current-best problem answer; by-value comparison at comparable effort; explicit trade-off and adopt/adapt/reject decision whenever external or internal practice changes the Solution)
  12. Relations
  13. Footer marker

Footer marker. End each pattern with a single visible sentinel heading line by itself: ### <PatternId>:End. This makes truncation detectable even when HTML comments are stripped or shown by editors. The footer marker is intentionally content-free: do not place prose under it.

Note. Pattern boundaries are still parseable by scanning for the next pattern heading (## …), but an explicit :End marker helps retrieval pipelines (and LLM prompts) distinguish “this chunk is the whole pattern” from “this chunk was cut mid‑pattern”.

E.8:4.1.1 - Heading & ID discipline (human tooling + retrieval)

FPF is often consumed through full‑text search and retrieval (RAG). A reader or an LLM may see a subsection without its parent headings, so headings must be self‑identifying.

The following grammar governs Markdown publication forms authored under this E.8 edition. Its heading levels, separator and sentinel spellings are necessary subject conditions under E.5.1; they do not make the represented conceptual objects depend on Markdown.

H-1 (Heading shape). Every pattern heading and every subsection heading inside a pattern SHALL follow: <hashes> <FullId> - <Title> (optional note of non‑normativity)

Exception. The Footer marker is a sentinel heading and is governed by H-9, not by the standard <FullId> - <Title> shape.

H-2 (Heading separator). The canonical separator between <FullId> and <Title> is - (ASCII, space-hyphen-space). Previously authored text may use Unicode dash variants such as – or — as separators; tooling SHOULD treat those variants as migration candidates, and authors SHOULD migrate touched headings to -.

H-3 (FullId). FullId is the complete address used by this heading grammar. For a pattern heading it is the PatternID (e.g., A.2, E.10.D1). For headings inside a pattern, append dot-separated ordinal section numbers after the colon (:) (e.g., A.2:4.4, E.10.D2:3). Exception: the Footer marker uses the reserved sentinel token :End as defined in H-9. The colon (:) is reserved for section paths and MUST NOT appear in PatternIDs.

Retained published addresses. When repairing an already published heading, preserve its established address and the contribution it denotes. An existing non-ordinal address is a compatibility exception, not a form for new addresses. Establish that exception from the exact earlier publication and its target; a permissive parser match does not establish it. An absent address receives a new ordinal address chosen by the source author. A local component, clause or extension name remains its own declaration under H-10; it does not by itself supply the missing subsection address.

PatternID segments may be numeric or mnemonic. When the surrounding text identifies the framework, the complete PatternID identifies one pattern in that framework; the shape of its segments does not by itself state the pattern’s title, meaning, Part, publication position, dependency, Method relation, or use order. A mnemonic segment may help recognition but does not define the pattern.

Whether a PatternID stays with a changed pattern is an authoring decision, not a grammar decision. For a DPF, use E.4.DPF; use E.11.PFP to show current publication position separately. When the surrounding text does not already identify the framework, name the framework together with the PatternID. Add the edition when the reference must select the body published in one edition.

H-4 (Ordinals). Ordinals in section paths SHOULD track the canonical template numbering (1 = Problem frame, …, 13 = Footer marker) to maximise cross‑pattern comparability. During refactors or in previously authored patterns, ordinals MAY be local. In that case, the canonical section title at the start of <Title> is the semantic key; readers and tools MUST NOT infer section semantics from the ordinal alone. Architectural Rationale is the preferred title of the Rationale function; Rationale remains an accepted alias. Both identify one canonical content section, so a pattern carries exactly one of them. When an existing heading is retitled, repair title-dependent links and direct consumers under E.8:4.1.2; retaining its ordinal alone does not preserve a Markdown return.

Keep addresses through change. Inserting, moving or retitling a subsection does not assign its address to a different contribution. Keep existing addresses when their contributions continue; give a new contribution an unused address. Do not renumber unaffected subsections to restore display order or reuse a retired address for different content. For a genuine replacement, split or merge, decide which contribution continues and make changed or unresolved returns explicit.

For example, when a new explanation is inserted between existing sections 4.1 and 4.2, an available 4.3 can name the insertion while 4.2 still names its former explanation. Before publication, compare the earlier and revised targets, preserve the earlier carrier fragments with declared compatibility aliases where supported, and update direct links. Test duplicate-title suffixes and alias collisions as well as visible FullIds. A saved link must return to its intended contribution or expose that the return is unresolved; reaching a different heading silently is a failure. The author judges the contribution; a link checker can verify the declared correspondence.

Note: the Footer marker itself is exempt from ordinal encoding; it uses the reserved token :End (see H-9).

H-5 (Where kind and normativity are declared). Pattern kind (for example, Architectural or Definitional) MUST be declared in the Header block, not encoded into the heading text. Normativity (normative or informative) MUST also be declared in the Header block when it deviates from the default. If a reminder is needed for readers, authors MAY add a short parenthetical note at the end of the heading, for example (informative) or (non‑normative), but headings MUST NOT use square‑bracket tags.

H-6 (Heading levels). Heading levels MUST preserve a fixed offset between structural layers (Part or Cluster (flat) → Pattern → Pattern sections):

  • Part and Cluster headings MUST use # (level 1) across the file.
  • A Pattern heading MUST use ## (level 2).
  • Inside a pattern, each nested section MUST add exactly one # per level (e.g., ## A.2 - …, ### A.2:2 - …, #### A.2:2.1 - …).

H-7 (Ellipsis discipline). Authors MUST NOT use three consecutive full stops/dots (...) as punctuation in headings or narrative prose. Authors MUST use the Unicode ellipsis … (U+2026) instead. For editorial elisions in quotations, authors SHOULD prefer […] to make the omission explicit and distinguish it from retrieval truncation. Exception: literal three‑dot sequences that are part of an external language’s syntax MAY appear only inside code spans or fenced code blocks.

H-8 (Normative keywords). The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119, as clarified by RFC 8174 (only when capitalised). Authors SHOULD avoid informal deontic phrasing (“need to”, “is required to”) in normative clauses.

Deontics vs admissibility. Use RFC keywords only for deontic obligations (requirements on authors, reviewers, implementers/tooling, or published pattern or companion texts) — i.e., things an agent can choose to do or omit. Do not use RFC keywords to state definitions, structural invariants, typing rules, or other admissibility conditions of the modeled world.

When you need an enforceable constraint that is mathematical rather than deontic, express it as a non‑deontic predicate using one of: Definition:, Invariant:, or Well‑formedness constraint: (optionally with formal quantifiers). Prefer mathematical terms like cardinality 1..1 (total), 0..1 (partial), or 0..n over deontic adjectives like “mandatory or optional” when the intent is cardinality, not duty.

Admissibility predicate discipline (recommended shape). When expressing admissibility or validity constraints as predicates (Definition:, Invariant:, or Well‑formedness constraint:):

  • Authors MUST NOT use RFC keywords inside the predicate block.
  • Authors SHOULD give each predicate a stable identifier and short name (e.g., RA‑1 (Locality), RE‑3 (Method gate)), so that Conformance Checklist items can reference it without re‑authoring the rule.
  • Authors SHOULD write the constraint as a declarative predicate with a truth condition (optionally quantified), for example “every selected interval lies within the declared qualification window”, rather than as “X MUST …”.
  • If the constraint needs to be checked as part of pattern conformance, authors SHOULD reference the predicate identifier from the Conformance Checklist, and call out validator behaviour when relevant, rather than duplicating the predicate with RFC keywords.

H-9 (Footer marker sentinel). Footer marker SHALL be a single heading line whose FullId is the pattern ID followed by the reserved sentinel token :End (no ordinals, no title, no square‑bracket tags): ### <PatternId>:End Apart from a retained published address under H-3, it is the only allowed heading inside a pattern whose section token is non‑numeric. It MUST be the final line of the pattern and MUST NOT carry any prose. Tooling and readers MUST treat it as a boundary sentinel, not as a semantic section.

H-10 (Publication-token classification and addressability). Before emitting an FPF-governed token as a reference, authors MUST classify it under exactly one of these seven E.8-local publication-token classes and use the matching form:

  • PatternRef uses one PatternID to name a pattern that continues across editions of the framework identified by the surrounding text. In the assembled publication being checked, it resolves to one complete H2 body, one matching :End, and a truthful ToC status for that PatternID. A reference intended to select the body published in one edition also names that framework edition. A structural checker may verify and report publication conformance but does not establish the pattern’s identity, status, or authority.
  • PlannedCatalogEntry names an explicit future catalogue commitment. It has no current pattern semantics, governing force, prerequisite force, or addressable body; a useful prose mention MUST say planned or future, and a current semantic dependency MUST cite existing content that supplies the needed definition, constraint, test, method, or other rule, or state the current gap.
  • SectionRef names one exact heading path inside one current pattern or one framework publication unit declared under E.11.PFP. Authors and tooling MUST read the complete section identifier and its declared scope before examining any substring. For example, STR.Preface:1 returns to the Strategy Preface; it does not declare a pattern named STR.Preface.
  • LocalDeclaredId names an exact declaration within one pattern, such as a conformance clause, component, interface row, or predicate. Its scope is local unless an explicit stable anchor or a separate promotion decision establishes wider use.
  • LocalAlias names an explicitly declared compatibility alias and resolves to its declared canonical local target.
  • PatternFamilySelector selects a navigable pattern family using canonical spelling <base>.*. It requires a current base pattern and at least one current matching member and MUST NOT stand in for one exact governing target.
  • NonReferenceToken classifies a schematic example or ordinary local prose/code that neither occupies a reference-bearing position nor declares a local public ID. It explicitly denotes no reference; key-like typography or backticks alone do not change that class.

Resolution and checking are declaration-first and context-sensitive. Authors and tooling MUST NOT split complete SectionRefs, strip a local-ID prefix, promote a local symbol by visual resemblance, or replace these classes with an ignore list. An unresolved token in a reference-bearing authoring form is an error; ordinary code or local wording is not silently upgraded to a reference.

H-11 (Assembled Part boundaries and title agreement). In the assembled publication, every compact ToC Part label MUST be a bold separator with a blank line on both sides, not a duplicate structural Part heading. Its title and ASCII - separator MUST agree exactly with the corresponding # Part <letter> - <title> body heading. A reserved body Part that has no compact ToC table, including current Part H, does not require an empty compact label or table.

Unification note: historic A‑ and D‑templates differed only by the presence/absence of Bias‑Annotation and Relations; the unified template keeps the headings everywhere and requires every heading to carry content-bearing grounding, boundary, consequence, rationale, source-use, relation, or reduced-case material rather than an omission placeholder. The Alexandrian pattern canon historically calls Problem frame “Context”. FPF uses Problem frame because generic Context and universal U.BoundedContext do not identify the actual value a claim needs.

Route each use directly. Recover source-local meaning through F.0.1, use F.1 to select answer-changing sources, state ClaimScope through A.2.6, and use A.1.1 for an admitted bounded-model use. Add F.17 only when a durable address or basis relation is needed, F.9 only for an obtaining Bridge between two exact local senses, and the applicable plane relation for a ReferencePlane claim. Otherwise leave the relation unasserted rather than inferring it from a shared word, source, or context.