First Principles Framework (FPF)

repository·main·Indexed 19 days ago

https://github.com/ailev/fpf

A standards-style pattern language designed to make complex engineering, research, and AI-integrated work explicit, reviewable, and coherent. FPF provides a structured approach to managing reasoning across multi-team or multi-tool environments, particularly when projects involve slow feedback loops, high-risk actions, or the need for durable audit trails. It includes specific patterns for shaping architecture, creating working documents, comparing options, and defining improvement frameworks.

Tokens
37.6K
Snippets
27
Records
93
Agent score
16%

What's inside FPF

  1. Overview of the First Principles Framework (FPF)

    main

    The First Principles Framework (FPF) is a standards-style pattern language designed to transform complex engineering, research, management, and AI-assisted work into explicit, reviewable, and improvable reasoning. It is used to maintain coherence across people, teams, tools, time, or AI agents when a project's complexity outgrows simple conversation.

    Key Use Cases:

    • Maintaining coherence in multi-team or multi-tool environments.
    • Managing work where real-world testing is slow, expensive, or risky.
    • Providing different views (reports, dashboards, decisions) for different stakeholders based on the same underlying work.
    • Preventing the blurring of names, roles, responsibilities, and quality criteria.
    • Documenting durable reasons for decisions.

    Target Users:

    • Engineers & Systems Engineers: Working with complex products or operations.
    • Researchers: Building claims for inspection and reuse.
    • Platform & AI Teams: Coordinating humans, models, and tools.
    • Safety & Compliance Leads: Managing evidence and responsibility boundaries.
    • Managers & Product Leaders: Comparing options, risks, and budgets without hiding trade-offs.
  2. Identify the Narrativization and Narrative Studies Principles Framework (NSTD) package

    main

    The Narrativization and Narrative Studies Principles Framework is a Domain Principle Framework (DPF) that specializes the FPF Core structure-to-narrative rendering for narrative studies and teaching.

    Key Identifiers:

    • Public Prefix: NSTD.* (Note: This is a package-local prefix and not an FPF Core ID).
    • Edition Reference: NarrativizationAndNarrativeStudiesPrinciplesFramework@2026-06-30.

    Dependencies: This framework depends on FPFCorePatternSet@current. It reuses core patterns for relation, source, coarsening, explanation, language-state, precision-restoration, constraint-governed unfolding, ethics, evidence, assurance, quality, publication, generated-carrier, and refresh. It is not permitted to redefine Core patterns such as A.6.3.NAR, A.22.CGUS, E.17.EFP, etc.

  3. Understand the scope of the Narrativization and Narrative Studies Principles Framework

    main

    This package is a Domain Principle Framework (DPF) designed to help practitioners solve recurring narrative-work problems. It focuses on rendering selected source structures into narrative renderings for a declared reader or listener use.

    Core Capabilities:

    • Preserving source return.
    • Ethics routing and evidence routing.
    • Managing generated-carrier admission.
    • Evaluation and refresh discipline.

    Relationship to FPF Core:

    • This package does not redefine FPF Core.
    • A.6.3.NAR remains the Core owner for the source-to-narrative relation.
    • NSTD.* patterns specialize the Core relation for specific domains like narratology, narrative communication, storycraft, teaching, and generated-narrative work.
    • It adds domain methods, cases, and evaluation scales but does not create new Core U.* kinds.

    Intended Users: FPF authors, teachers, technical communicators, architects, researchers, and tool builders who need to make narrative renderings useful without letting narrative fluency override source authority.

  4. Use Practical-Use Cards to navigate FPF

    main

    Instead of following an ordinal sequence, start with your current project question. FPF uses fifteen semantic keys as stable identifiers for different situations.

    Workflow:

    1. Identify the situation: Match your current project pressure to one of the semantic keys (e.g., ARCHITECTURE, WORKING-DOCUMENTS, PROBLEM-SHAPING).
    2. Compare plausible cards: If multiple cards seem applicable, compare their first-result differences, stop conditions, and return conditions.
    3. Inspect the pattern: Once a card is selected, examine its specific Problem frame, Forces, Solution, Consequences, and ordinary boundary.
    4. Materialize results: Only create comparison or candidate records when a named receiving use specifically requires them.

    Note on Templates: The conditional template lists within cards are walkthroughs for specific branches. You should only inspect the branch whose stated condition is currently met, apply its Solution, and stop at the card's boundary.

  5. Determine the temporal posture of a narrative rendering

    main

    Before drafting or evaluating a narrative, you must define its temporal posture. Different postures carry different obligations regarding uncertainty, evidence, telemetry, and source-return.

    Common temporal postures include:

    • Historical reconstruction
    • Reverse-engineering account
    • Live match commentary
    • Prospective project scenario
    • Future event preview
    • Fictional continuation
  6. Design a Learning-Route Narrative Rendering and Reconstruction Return (NSTD.8)

    main

    Use the NSTD.8 pattern when a complex source structure must be taught or learned through a narrative route. The goal is to ensure the learning route preserves enough structure for learners to reconstruct and apply the source later, rather than just remembering an engaging story or analogy.

    Core Principles

    • Separate Carrier from Pattern: A DPF pattern body should not contain the actual lesson, seminar script, or explainer text. It governs how the publication carrier (slides, scripts, exercises) is designed, tested, and repaired. The carrier is the implementation; the pattern is the specification.
    • Avoid the 'Reference Manual' Trap: Do not simply copy the source architecture (e.g., Topic A $\rightarrow$ Topic B $\rightarrow$ Topic C) into the learning route. This creates 'blocked topic' instruction where learners can follow a block locally but fail to choose the right pattern when cues are mixed.
    • Architecture Split: Maintain a distinction between the Source Architecture (how the knowledge is organized in the corpus) and the Learning-Route Architecture (how the knowledge is sequenced for teaching, using interleaving and spaced retrieval).
    • Prioritize Reconstruction: Success is measured by whether a learner can rebuild the source structure, not just recall the narrative highlights or slogans.
    LearningNarrativeRoute@Context:
      learnerUse:
      sourceStructureSpineRefs:
      unfoldingStructureRefs?:
      demonstrativeSliceRefs?:
      sourceArchitectureRef?:
      learningRouteArchitectureRule:
      learningStepOrderingRule:
      interleavingPlanRefs?:
      spacingOrRetrievalScheduleRefs?:
      recurringAnchorRefs?:
      sourceReturnLinkRefs:
      learnerReconstructionTaskRefs:
      applicationTaskRefs?:
      engagementBoundaryRef?:
      narrativeRenderingQualityEvaluationRef:
      improvementLoopInputRef?:
      learningPublicationCarrierRefs:
      blockedTopicOverread?:
      nonAdmissibleUse:
      refreshCondition:
  7. What FPF is and is not

    main

    What FPF Is

    A pattern language for disciplined thinking that helps teams:

    • Maintain stable meanings across teams, tools, and time.
    • Separate the project object from its representations (diagrams, dashboards, decisions, etc.).
    • Define the intended use of a claim before others rely on it.
    • Compare alternatives without premature bias.
    • Define quality criteria before starting improvements.
    • Keep evidence, assurance, decisions, and implementation work as distinct, visible questions.
    • Bridge the gap between problem pressure and real-world structures.

    What FPF Is Not

    • A shrink-wrapped project methodology.
    • A checklist bureaucracy.
    • A quick-answer cheat sheet.
    • A replacement for domain expertise.
    • A requirement to study the entire specification before starting work.
    • A requirement that every project must use every pattern.
  8. Bridge Narrative Problems to Semiotic and Language Precision

    main

    Narrative work often involves changing signs, carriers, and reader interpretation. When a narrative problem can be addressed by an existing FPF pattern, use the FPF owner and add only the narrative-specific discipline (selection, ordering, engagement, and reception).

    Practical Rule: FPF Core patterns do not depend on this DPF. If a narrative problem is actually a source relation, language-state move, or quality-term problem, identify the FPF owner first.

    | Narrative-studies wording or problem | FPF owner to use | DPF consequence |
    | --- | --- | --- |
    | "make it more interesting", "more literary", etc. | `NSTD.5` (engagement), `C.2.LS` + `C.2.4`-`C.2.7` (language-state), `NSTD.6` (quality) | Artistic wording is only for use support/language-state; it does not increase source truth or ethics. |
    | early hook, vibe, image, tension, etc. | `A.16.1` (pre-articulation cue pack), then `NSTD.1` and `NSTD.2` | Preserve the cue without pretending purpose or quality endpoints already exist. |
    | preconceptual or dynamic-quality pull | `C.16.Q` as `QS.PreconceptualFit` or related signal-pack, `A.16.1`, `C.2.LS` | Treat as a real cue/signal under explicit witness/articulation; not yet a proof of quality. |
    | overcommitted plot frame, failed explanatory frame | `A.16.2` (reopen, sketch-backoff, respecify, retire); `A.6.P`/`C.16.Q` | Back off the narrative route honestly instead of hiding retreat behind "nuanced" prose. |
    | simplified, didactic, redacted, or audience-safe retelling | `A.6.3.CSC`, with `E.17.EFP` (explanation-facing) | State narrower admissible use, source-loss mode, and source-return condition. |
    | clearer explanation, tutorial, or source-linked retelling | `E.17.EFP` plus `A.6.3.NAR` | Classify as source-pinned, source-linked reconstruction, didactic, or speculative; do not let it become a second semantic rule track. |
    | "same story", adaptation fidelity, canon continuity | `C.34`, with `NSTD.2` and `NSTD.6` | State same-enough relation, preserved/lost relations, and non-admissible use. |
    | "quality", "good narrative", "better style" | `C.16.Q` (quality wording), `A.19.ECS`/`C.16`/`NSTD.6` (evaluation), `F.18` (durable names) | Recover bearer, evaluation frame, and value meaning before using as guidance. |
    | relation words ("supports", "grounds", "maps", etc.) | `A.6.P` and direct relation owners (`A.6.6`, `C.34`, `A.10`, `B.3`) | Restore relation kind, endpoints, qualifiers, and blocked overread. |
    | style, genre, technique, voice, or tone | `E.10` (trigger scan), `F.18` (durable names), `NSTD.4` and `NSTD.5` | Keep craft vocabulary useful, but do not let style words mint ontology or authority. |
  9. How NSTD.1 prevents purpose-primacy drift

    main

    The NSTD.1 pattern is designed to block purpose-primacy drift, where a message, theme, or desired memory is allowed to choose source structures after the fact.

    In FPF, a purpose is not the owner of the source; it is a relation between an EntityOfConcern, a reader role, and selected source structures. If a narrative's purpose (e.g., "make it inspiring") is allowed to absorb the source basis, readers lose the ability to recover which structures were selected, which uncertainties were retained, or which claims require source return.

    Key Principle: A purpose can guide the aim of a narrative, but it cannot widen evidence, assurance, ethics, policy, or work authority. If a claim depends on a cited source basis, the claim must stay within the boundary of that source, regardless of the narrative's purpose.

  10. Bridge Architecture Work to Narrative Studies

    main

    When performing narrative-language work that involves structural or architectural tasks, use the following mapping to decide whether to use First Principles Framework (FPF) architecture discipline or the Narrativization and Narrative Studies (DPF) terminology.

    Key Decision Rule: Use DPF terminology for reader/listener roles, ordering, and engagement. Use FPF architecture terminology when the work involves load-bearing structural claims, holon architecture carry-through, or formal architecture decisions.

    | Architecture-work locus | Narrative-studies wording | FPF use in this DPF |
    | --- | --- | --- |
    | architecture-relevant problem pressure in `C.32.P2S` | narrative problem, communicative pressure, audience confusion, etc. | Use `NSTD.1` to name reader/listener use; use `C.32.P2S` only for holon architecture carry-through. |
    | selected structure or unknown structure | admitted source basis, storyworld, event field, etc. | Name selected source structures explicitly; use `A.22`, `C.30`, or domain owners for load-bearing claims. |
    | architecture structural view and viewpoint in `C.30.ASV` | focalization, narrative viewpoint, perspective, lens, etc. | Use `NSTD.4` for voice/focalization; cite `C.30.ASV` for architecture-relevant selected structures. |
    | architecture description in `C.30.AD` | synopsis, outline, story bible, learning route, etc. | Use `A.6.3.NAR` for structure-to-sequence rendering and `E.17` for publication; use `C.30.AD` only for architecture descriptions. |
    | candidate structure set and trade-off in `C.32` | alternative plots, possible story plans, scenario branches, etc. | Keep alternatives visible; use `NSTD.2` for ordering and `NSTD.6` for declared-use quality. Use `C.32` for architecture candidate synthesis. |
    | project architecture decision in `C.32.PAD` | chosen narrative route, selected plot, editorial commitment, etc. | Treat as DPF-local unless it is also an architecture decision. Do not let narrative commitment authorize architecture decisions. |
    | developer or transformer role receiving architecture work | writer, narrator, teacher, commentator, etc. | Name the worker in `NSTD.1`; use A.15-family owners only for live method/work claims. |
    | structural information capture and source return in `C.33` | how much structure got into the story, what is hidden, epiplexity | Use `NarrativeRenderingEpiplexity` in `NSTD.6`; use `C.33` for architecture-relevant structural information. |
    | structural correspondence in `C.34` | canon fidelity, adaptation faithfulness, etc. | Use `C.34` when preservation matters for architecture; otherwise keep local to DPF and state lost structure. |
    | realized structure, operation, telemetry, feedback in `C.32.P2S` and `G.11` | reader reception, learner reconstruction, field test, etc. | Use `NSTD.6`, `NSTD.8`, `E.23`, and `G.11` for evaluation/improvement. Use architecture feedback owners only for holon structure checks. |
  11. Use the NSTD.7 pattern for Automated Narrativization

    main

    Use the NSTD.7 pattern when using LLMs, NLG, graph-to-text, data-to-text, story-planning, schema-governed generation, or search to produce or repair narrative renderings.

    The Core Problem: Automated systems produce fluent, coherent-looking narratives that may fail source grounding, plot consistency, schema constraints, or ethical boundaries. The goal is to prevent 'generated fluency' from being mistaken for 'source authority.'

    The Solution: Use a kind-splitting record (AutomatedNarrativizationAdmissionCase@Context) to separate the generated carrier from the admitted source basis and the human responsibility for admission. This ensures that automation helps produce candidates without prematurely admitting them as source-grounded truths.

    AutomatedNarrativizationAdmissionCase@Context:
      sourceMaterialOrSourcePackRef:
      generatedCarrierRef:
      generationMethodOrMethodDescriptionRef:
      sourcePlanRef?:
      plotOrEventPlanRef?:
      schemaConstraintRefs?:
      c35AdmissionRef:
      narRelationRef:
      structureCaptureLossRef:
      correspondenceRef:
      evaluationRef:
      evidenceOwnerRefs?:
      assuranceOwnerRefs?:
      humanAdmissionResponsibilityRef:
      nonAdmissibleUse:
      repairOrRejectCondition:
  12. Use Heterogeneous Acceptance Cases to test the DPF

    main

    The DPF (Design Principles Framework) includes several 'Heterogeneous Acceptance Cases' to verify that the framework handles diverse narrative domains without incorrectly importing domain-specific materials into pattern bodies.

    To pass an acceptance case, a worker must follow a specific construction route using the defined patterns. A pass is not merely a 'good narrative,' but a demonstration that the pattern set successfully guides a worker from source structures to a draftable narrative route, followed by successful evaluation and repair.

    Key domains covered include:

    • Learning Routes (e.g., teaching FPF via slides or seminars).
    • Franchise Storycraft (e.g., planning continuation stories for established fictional universes).
    • Mathematical Theory Explanation (e.g., rendering graph-heavy theory into sequential narratives).
    • Live Event Commentary (e.g., real-time orientation for unfolding events like sports).