First Principles Framework (FPF)
Structured reasoning for AI coding tools — make better decisions, remember why you made them.
When to Use This Skill
Activate FPF for:
- Architectural decisions with long-term consequences
- Multiple viable approaches requiring systematic evaluation
- Need auditable reasoning trail for team/future reference
- Complex problems requiring hypothesis → verification cycle
- Building up project knowledge base over time
Skip FPF for:
- Quick fixes, obvious solutions
- Easily reversible decisions
- Time-critical situations where overhead isn't justified
Core Concept
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.
Assurance Levels
Knowledge claims are tracked at different assurance levels:
| Level | Name | Description |
|---|---|---|
| L0 | Observation | Unverified hypothesis or note |
| L1 | Reasoned | Passed logical consistency check |
| L2 | Verified | Empirically tested and confirmed |
| Invalid | Disproved | Disproved claims (kept for learning) |
Commands
Use the following slash commands in order:
| # | Command | Phase | What it does |
|---|---|---|---|
| 0 | /q0-init | Setup | Initialize .quint/ structure |
| 1 | /q1-hypothesize | Abduction | Generate hypotheses → L0/ |
| 1b | /q1-add | Abduction | Inject user hypothesis → L0/ |
| 2 | /q2-verify | Deduction | Logical verification → L1/ |
| 3 | /q3-validate | Induction | Test (internal) or Research (external) → L2/ |
| 4 | /q4-audit | Bias-Audit | WLNK analysis, congruence check |
| 5 | /q5-decide | Decision | Create DRR from winning hypothesis |
| S | /q-status | — | Show current state and next steps |
| Q | /q-query | — | Search knowledge base |
| D | /q-decay | — | Check evidence freshness |
Key Concepts
WLNK (Weakest Link)
Assurance = min(evidence), never average. A chain is only as strong as its weakest link.
Congruence
External evidence must match our context (high/medium/low). Evidence from a different context may not apply.
Validity
Evidence expires — check with /q-decay. Stale evidence creates epistemic debt.
Scope
Knowledge applies within specified conditions only. Document the boundaries.
Workflow Example
User: How should we implement caching for our API?
/q0-init # Initialize knowledge base
/q1-hypothesize "API caching" # Generate hypotheses
Hypotheses generated:
- H1: Redis with TTL-based invalidation (Conservative)
- H2: CDN edge caching (Novel)
- H3: In-memory cache with pub/sub invalidation (Hybrid)
/q2-verify H1 # Verify Redis approach logic
/q3-validate H1 # Test Redis in development
/q4-audit # Check for biases, weakest links
/q5-decide H1 # Create Design Rationale Record
Design Rationale Record (DRR)
The /q5-decide command generates a DRR with:
- Context: The initial problem
- Decision: The chosen hypothesis
- Rationale: Why it won (citing evidence and R_eff)
- Consequences: Trade-offs and next steps
- Validity: When should this be revisited?
State Location
All FPF state is stored in .quint/ directory (git-tracked):
.quint/
├── context.md # Project context and constraints
├── knowledge/
│ ├── L0/ # Unverified hypotheses
│ ├── L1/ # Logically verified claims
│ ├── L2/ # Empirically verified claims
│ └── invalid/ # Disproved claims
└── decisions/ # Design Rationale Records
Transformer Mandate
Critical Principle: You (Claude) generate options with evidence. Human decides.
A system cannot transform itself — the human partner makes final architectural decisions. Generate high-quality options, present evidence, but don't autonomously choose major architectural directions.
Integration with Code Review
After FPF-driven implementation:
- Generate hypotheses for approach
- Verify and validate the chosen approach
- Implement with the structured reasoning as documentation
- Code review references the DRR for context
- Future developers understand why decisions were made
Benefits
- Auditability: Every decision has a documented trail
- Reduced Bias: Multiple hypotheses prevent anchoring
- Knowledge Retention: Project learnings persist
- Team Alignment: Clear rationale for decisions
- Technical Debt Prevention: Bad decisions caught early