Submit
All skills
Skillintermediate

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.

Claude Code Knowledge Pack7/10/2026

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 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 by m0n0x41d.

Quick Start

# 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 <problem>                            │
│    (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-<date>-<topic>.md with winner and rationale
/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

# 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
/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

# Check current status
/status

Example Output:

## 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
/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

# Search by keyword
/query caching

# Query specific hypothesis
/query redis-caching

# List all decisions
/query DRR

Example Output (keyword search):

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):

# 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):

# 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
/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

# 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