--- title: "First Principles Framework (FPF) Plugin" description: "Structured reasoning plugin that makes AI decision-making transparent and auditable through hypothesis generation, logical verification, and evidence-based validation." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/readme-293 source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:36:20.768Z license: CC-BY-4.0 attribution: "First Principles Framework (FPF) Plugin — Claudary (https://claudary.paisolsolutions.com/skills/readme-293)" --- # First Principles Framework (FPF) Plugin Structured reasoning plugin that makes AI decision-making transparent and auditable through hypothesis generation, logical verification, and evidence-based validation. ## Overview # First Principles Framework (FPF) Plugin Structured reasoning plugin that makes AI decision-making transparent and auditable through hypothesis generation, logical verification, and evidence-based validation. Focused on: - **Transparent reasoning** - All decisions documented with full audit trails - **Hypothesis-driven analysis** - Generate competing alternatives before evaluating - **Evidence-based validation** - Computed reliability scores, not estimates - **Human-in-the-loop** - AI generates options; humans decide (Transformer Mandate) ## Plugin Target - Make AI reasoning auditable - full trail from hypothesis to decision - Prevent premature conclusions - enforce systematic evaluation of alternatives - Build project knowledge over time - decisions become reusable knowledge - Enable informed decision-making - trust scores based on evidence quality ## Overview The FPF plugin implements structured reasoning using [the First Principles Framework](https://github.com/ailev/FPF) methodology developed by Anatoly Levenchuk a methodology for rigorous, auditable reasoning. The killer feature is turning the black box of AI reasoning into a transparent, evidence-backed audit trail. The core cycle follows three modes of inference: - Abduction — Generate competing hypotheses (don't anchor on the first idea). - Deduction — Verify logic and constraints (does the idea make sense?). - Induction — Gather evidence through tests or research (does the idea work in reality?). Then, audit for bias, decide, and document the rationale in a durable record. The framework addresses a fundamental challenge in AI-assisted development: making decision-making processes transparent and auditable. Rather than having AI jump to solutions, FPF enforces generating competing hypotheses, checking them logically, testing against evidence, then letting developers choose the path forward. > **Warning:** This plugin loads the core FPF specification into context, which is large (~600k tokens). As a result it loaded into a subagent with Sonnet[1m] model. But such agent can consume your token limit quickly. Implementation based on [quint-code](https://github.com/m0n0x41d/quint-code) by m0n0x41d. ## Quick Start ```bash # Install the plugin /plugin install fpf@NeoLabHQ/context-engineering-kit # Start a decision process /propose-hypotheses What caching strategy should we use? # Commad will perform majority of orcestration and launch subagents to perform the work. # Additionaly you will be asked to add your own hypotheses and review the results. ``` ## Workflow Diagram ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. Initialize Context │ │ /propose-hypotheses │ │ (create .fpf/ directory structure) │ └────────────────────────┬────────────────────────────────────────┘ │ │ problem context captured ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Abduction: Generate Hypotheses │ ◀── add your own ───┐ │ (create L0 hypothesis files) │ │ └────────────────────────┬────────────────────────────────────────┘ │ │ │ │ 3-5 competing hypotheses │ ▼ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ 3. User Input │ │ │ (present summary, allow additions) │─────────────────────┘ └────────────────────────┬────────────────────────────────────────┘ │ │ all hypotheses collected ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Deduction: Verify Logic (Parallel) │ │ (check constraints, promote to L1 or invalidate) │ └────────────────────────┬────────────────────────────────────────┘ │ │ logically valid hypotheses (L1) ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 5. Induction: Validate Evidence (Parallel) │ │ (gather empirical evidence, promote L1 to L2) │ └────────────────────────┬────────────────────────────────────────┘ │ │ evidence-backed hypotheses (L2) ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 6. Audit Trust (Parallel) │ │ (compute R_eff using Weakest Link principle) │ └────────────────────────┬────────────────────────────────────────┘ │ │ trust scores computed ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 7. Decision │ │ (present comparison, user selects winner, create DRR) │ └────────────────────────┬────────────────────────────────────────┘ │ │ decision recorded ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 8. Summary │ │ (DRR, winner rationale, next steps) │ └─────────────────────────────────────────────────────────────────┘ ``` ## Commands Overview ### /propose-hypotheses - Decision Cycle Execute the complete FPF cycle from hypothesis generation through evidence validation to decision. - Purpose - Make architectural decisions with full audit trail - Output - `.fpf/decisions/DRR--.md` with winner and rationale ```bash /propose-hypotheses [problem or decision to make] ``` #### Arguments Natural language description of the decision or problem. Examples: "What caching strategy should we use?" or "How should we deploy our application?" #### How It Works - ADI Cycle The workflow follows three inference modes: 1. **Initialize Context** - Creates `.fpf/` directory structure and captures problem constraints 2. **Abduction: Generate Hypotheses** - FPF agent generates 3-5 generate plausible, diverse, and competing hypotheses in L0 folder. **How it works:** - You pose a problem or question - The AI (as *Abductor* persona) generates 3-5 candidate explanations or solutions - Each hypothesis is stored in `L0/` (unverified observations) - No hypothesis is privileged — anchoring bias is the enemy **Output:** Multiple L0 claims, each with: - Clear statement of the hypothesis - Initial reasoning for plausibility - Identified assumptions and constraints 3. **User Input** - Presents hypothesis table, allows user to add alternatives 4. **Deduction: Verify Logic (Parallel)** - Checks each hypothesis against constraints and typing, promotes to L1 or invalidates **How it works:** - The AI (as *Verifier* persona) checks each L0 hypothesis for: - Internal logical consistency - Compatibility with known constraints - Type correctness (does the solution fit the problem shape?) - Hypotheses that pass are promoted to `L1/` - Hypotheses that fail are moved to `invalid/` with explanation **Output:** L1 claims (logically sound) or invalidation records. 5. **Induction: Validate Evidence (Parallel)** - Gather empirical evidence through tests or research, promotes L1 hypotheses to L2 **How it works:** - For **internal** claims: run tests, measure performance, verify behavior - For **external** claims: research documentation, benchmarks, case studies - Evidence is attached with: - Source and date (for decay tracking) - Congruence rating (how well does external evidence match our context?) - Claims that pass validation are promoted to `L2/` **Output:** L2 claims (empirically verified) with evidence chain. 6. **Audit(Parallel)** - Compute trust score R_eff using - **WLNK (Weakest Link):** Assurance = min(evidence levels) - **Congruence Check:** Is external evidence applicable to our context? - **Bias Detection:** Are we anchoring on early hypotheses? 7. **Make Decision**: Presents comparison table, selects winner, creates Design Rationale Record (DRR) which captures: - decision - alternatives considered - evidence - expiry conditions 8. **Present Summary**: Shows DRR, winner rationale, and next steps #### Usage Examples ```bash # Caching strategy decision /propose-hypotheses What caching strategy should we use? # Deployment approach /propose-hypotheses How should we deploy our application? # Architecture decision /propose-hypotheses Should we use microservices or monolith? # Technology selection /propose-hypotheses Which database should we use for high-write workloads? ``` #### When to Use **Use it for:** - Architectural decisions with long-term consequences - Multiple viable approaches requiring systematic evaluation - Decisions that need an auditable reasoning trail - Building up project knowledge over time Skip it for: Quick fixes with obvious solutions Easily reversible decisions Time-critical situations where the overhead isn't justified #### Best practices - Frame as decisions - "What X should we use?" or "How should we Y?" - Be specific about constraints - Include performance, cost, or time requirements - Add your own hypotheses - Don't rely only on AI-generated options - Review verification failures - Failed hypotheses reveal hidden constraints - Document for future reference - DRRs become project knowledge --- ### /status - Check Progress Show current FPF phase, hypothesis counts, and any warnings about stale evidence. - Purpose - Understand current state of reasoning process - Output - Status table with phase, counts, and warnings ```bash /status ``` #### Arguments None required. #### How It Works 1. **Phase Detection**: Identifies current ADI cycle phase (IDLE, ABDUCTION, DEDUCTION, INDUCTION, DECISION) 2. **Hypothesis Count**: Reports counts per knowledge layer (L0, L1, L2, Invalid) 3. **Evidence Status**: Lists evidence files and their freshness 4. **Warning Detection**: Identifies stale evidence, orphaned hypotheses, or incomplete cycles #### Usage Examples ```bash # Check current status /status ``` **Example Output:** ```markdown ## FPF Status ### Current Phase: DEDUCTION You have 3 hypotheses in L0 awaiting verification. Next step: Continue the FPF workflow to process L0 hypotheses. ### Hypothesis Counts | Layer | Count | |-------|-------| | L0 | 3 | | L1 | 0 | | L2 | 0 | | Invalid | 0 | ### Evidence Status No evidence files yet (hypotheses not validated). ### No Warnings All systems nominal. ``` #### Best practices - Check before continuing - Know your current phase before proceeding - Address warnings - Stale evidence affects trust scores - Review invalid hypotheses - Understand why they failed --- ### /query - Search Knowledge Base Search the FPF knowledge base for hypotheses, evidence, or decisions with assurance information. - Purpose - Find and review stored knowledge with trust scores - Output - Search results with layer, R_eff, and evidence counts ```bash /query [keyword or hypothesis name] ``` #### Arguments Keyword to search for, specific hypothesis name, or "DRR" to list decisions. #### How It Works 1. **Keyword Search**: Searches hypothesis titles, descriptions, and evidence 2. **Hypothesis Details**: Returns full hypothesis info including layer, kind, scope, and R_eff 3. **DRR Listing**: Shows all Design Rationale Records with winner and rejected alternatives #### Usage Examples ```bash # Search by keyword /query caching # Query specific hypothesis /query redis-caching # List all decisions /query DRR ``` **Example Output (keyword search):** ```markdown Results: | Hypothesis | Layer | R_eff | |------------|-------|-------| | redis-caching | L2 | 0.85 | | cdn-edge-cache | L2 | 0.72 | | lru-cache | invalid | N/A | ``` **Example Output (specific hypothesis):** ```markdown # redis-caching (L2) Title: Use Redis for Caching Kind: system Scope: High-load systems R_eff: 0.85 Evidence: 2 files ``` **Example Output (DRR listing):** ```markdown # Design Rationale Records | DRR | Date | Winner | Rejected | |-----|------|--------|----------| | DRR-2025-01-15-caching | 2025-01-15 | redis-caching | cdn-edge | ``` #### Best practices - Search before starting new decisions - Reuse existing knowledge - Check R_eff scores - Higher scores indicate more reliable hypotheses - Review DRRs - Past decisions inform future choices --- ### /decay - Manage Evidence Freshness Check for stale evidence and choose how to handle it: refresh, deprecate, or waive. - Purpose - Maintain evidence validity over time - Output - Updated evidence status and trust scores Evidence expires. A benchmark from six months ago might not reflect current performance. `/decay` shows you what's stale and gives you three options: - Refresh — Re-run tests to get fresh evidence - Deprecate — Downgrade the hypothesis if the decision needs rethinking - Waive — Accept the risk temporarily with documented rationale ```bash /decay waive the benchmark until February, we'll re-test after launch ``` #### Arguments None required. Command is interactive. #### How It Works 1. **Staleness Check**: Identifies evidence files past their freshness threshold 2. **Options Presented**: For each stale evidence: - **Refresh**: Re-run tests for fresh evidence - **Deprecate**: Downgrade hypothesis, flag decision for review - **Waive**: Accept risk temporarily with documented rationale 3. **Trust Recalculation**: Updates R_eff scores based on evidence changes #### Usage Examples ```bash # Check for stale evidence /decay # Natural language waiver # User: Waive the benchmark until February, we'll re-run after migration. # Agent response: # Waiver recorded: # - Evidence: ev-benchmark-2024-06-15 # - Until: 2025-02-01 # - Rationale: Will re-run after migration ``` #### Best practices - Run periodically - Evidence expires; benchmarks from 6 months ago may not reflect current performance - Document waivers - Always include rationale and expiration date - Refresh critical evidence - High-impact decisions deserve fresh data --- ### /actualize - Reconcile with Codebase Update the knowledge base to reflect codebase changes that may affect existing hypotheses. - Purpose - Keep knowledge synchronized with implementation - Output - Updated hypothesis validit --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-293) · https://claudary.paisolsolutions.com