Truth-Tested Decision-Making Framework for Claude AI
A comprehensive, epistemic-first framework for rigorous decision analysis using large language models, with deep examples and case studies.
For impatient users:
- Read the core framework: docs/framework-core.md (10 min)
- See an example: examples/technology/framework-selection.md (15 min)
- Use a template: templates/decision-template-minimal.md
- Start analyzing your own decision with Claude
For thorough users:
- Read framework-core.md
- Read implementation-guide.md
- Browse all examples/
- Read advanced-techniques.md
- Practice on real decisions
Claude-TTD is a structured framework for using Claude (or other LLMs) to analyze complex decisions with:
- Epistemic rigor: Label every claim as FACT, HYPOTHESIS, or ASSUMPTION
- Confidence scoring: Quantify certainty (0.0-1.0) at multiple levels
- Disconfirmers: Specify what evidence would change your mind
- Source transparency: Cite every fact, explain every hypothesis
- Balanced analysis: Force examination of both strengths and gaps
- Actionable output: Integration paths with timelines and owners
This is the "directors cut" - comprehensive examples and deep case studies. For concise versions adapted to other LLMs, see the main monorepo.
claude-ttd-framework/
├─ README.md # This file
├─ LICENSE # Apache 2.0
├─ CONTRIBUTING.md # How to contribute
│
├─ docs/
│ ├─ framework-core.md # Core 7-section framework (read first)
│ ├─ implementation-guide.md # How to use with Claude
│ ├─ advanced-techniques.md # Expert-level usage patterns
│ └─ epistemic-foundations.md # Why FACT/HYPOTHESIS/ASSUMPTION
│
├─ templates/
│ ├─ decision-template-minimal.md # Quick start template
│ └─ decision-template-full.md # Comprehensive template
│
├─ examples/
│ ├─ technology/
│ │ ├─ framework-selection.md # React vs Vue vs Svelte (detailed)
│ │ ├─ architecture-refactor.md # Monolith to microservices
│ │ └─ database-migration.md # MySQL to PostgreSQL
│ ├─ business/
│ │ ├─ pivot-decision.md # B2B to B2C market pivot
│ │ └─ pricing-strategy.md # Freemium vs paid-only
│ └─ operations/
│ ├─ vendor-selection.md # AWS vs GCP vs Azure
│ └─ security-audit.md # Vulnerability remediation
│
├─ scripts/
│ └─ validate-structure.py # Check if file follows framework
│
└─ .github/workflows/
└─ validate.yml # CI validation
Every decision analysis follows this structure:
- Table format: Domain | Assessment | Confidence
- Bottom line: RED/YELLOW/GREEN LIGHT recommendation
- FACT: Verifiable claims with sources
- HYPOTHESIS: Educated guesses with reasoning
- ASSUMPTION: Things taken as given, with validation methods
- Strengths (✅): What works well
- Gaps (
⚠️ ): What's missing, effort to close, mitigation
- Phased implementation plan
- Timelines and decision gates
- Success criteria for each phase
- Against business goals, technical strategy, stakeholders
- Unintended consequences (positive and negative)
- Specific outputs with owners, due dates, acceptance criteria
- Overall confidence score with reasoning
- Disconfirmers (what would change your mind)
- Key sources and assumptions to validate
Prompt to Claude:
I need to decide whether to migrate our database from MySQL to PostgreSQL.
Use the Claude-TTD framework to analyze this decision.
Context:
- Current: MySQL 5.7, 500GB database, 10K QPS
- Team: 5 backend engineers, all know MySQL, 1 knows Postgres
- Timeline: Need to decide in 2 weeks, implement in 6 months
- Pain points: JSON queries slow, replication lag, need better JSONB support
Please follow the full 7-section framework structure.
Claude will generate: A comprehensive analysis following the framework (see examples/technology/database-migration.md)
Key Features
Epistemic Rigor
markdown**FACT:** Database is 500GB in size
*Source: AWS RDS metrics, 2025-10-17*
**HYPOTHESIS:** Migration will take 3-4 months
*Basis: Industry benchmarks for 500GB migrations; our team has done migrations before*
**ASSUMPTION:** Team can dedicate 2 engineers full-time
*Needs validation: Check with engineering manager on availability*
Confidence Scoring
markdownOverall Confidence: 0.75
Reasoning:
- High confidence (0.90) in FACTS (directly measurable)
- Medium confidence (0.70) in timeline estimates (based on similar projects)
- Lower confidence (0.60) on team capacity (depends on other priorities)
Disconfirmers
markdown**What would change this assessment:**
- If migration testing reveals >5% data loss risk → RED LIGHT, don't migrate
- If timeline extends beyond 6 months → Reconsider, opportunity cost too high
- If PostgreSQL performance worse than MySQL → Abort, stick with MySQL
Why Use This Framework?
Problems it solves:
❌ LLM hallucinations: "Sounds confident but is it true?"
✅ Solution: Explicit FACT/HYPOTHESIS/ASSUMPTION labels with sources
❌ Overconfidence: "LLM gives me 100% certain answer to uncertain question"
✅ Solution: Confidence scores at claim and overall level
❌ Confirmation bias: "LLM agrees with what I already think"
✅ Solution: Forced balanced analysis (strengths AND gaps)
❌ Unclear recommendations: "Interesting analysis but what should I do?"
✅ Solution: Explicit GREEN/YELLOW/RED LIGHT + integration path
❌ No accountability: "Decision failed but we can't learn why"
✅ Solution: Disconfirmers + sources make post-mortems possible
Validation
Validate your own analyses:
bashpython scripts/validate-structure.py examples/your-decision.md
Checks for:
All 7 sections present and in order
Epistemic labels (FACT/HYPOTHESIS/ASSUMPTION)
Confidence scores in valid range (0.0-1.0)
Required elements (tables, due dates, owners, etc.)
Contributing
We welcome contributions! See CONTRIBUTING.md for:
How to submit examples
Example quality standards
Calibration data format
Tool integration guidelines
Quick contribution:
Fork repo
Add example in examples/[category]/your-example.md
Run python scripts/validate-structure.py examples/[category]/your-example.md
Submit PR
Advanced Usage
See docs/advanced-techniques.md for:
Recursive analysis: Multi-level decisions
Comparative framework: Evaluate multiple options rigorously
Bayesian updating: Adjust confidence as evidence arrives
Pre-mortem analysis: Surface hidden risks
Red team / blue team: Adversarial validation
Scenario planning: Test robustness across futures
License
Apache License 2.0 - See LICENSE
Copyright [2025] [Helix AI Innovations Inc., 17246102 CANADA INC.]
Citation
If you use this framework in research or publications:
bibtex@misc{claude-ttd-framework,
title={Claude-TTD Framework: Truth-Tested Decision-Making for Large Language Models},
author={Helix AI Innovations Inc.},
year={2025},
publisher={GitHub},
url={https://github.com/helix-ai-innovations/claude-ttd-framework}
}
Part of the Helix-TTD ecosystem:
- Helix-TTD Monorepo - Cross-LLM framework
- Claude adapter (this repo) - Claude-specific implementation
- ChatGPT adapter - Concise version for GPT-4
- Gemini adapter - Google Gemini version
- Grok adapter - xAI Grok version
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: opensource@helixaiinnovations.com
Version: 1.0 (Directors Cut)
Last Updated: 2025-10-17
Status: Production Ready
Happy analyzing! 🎯
---
**FINAL CHUNKS 22-26 COMPLETE**
**Repository Status: 100% COMPLETE (26/26 files)**
**Final file tree:**
claude-ttd-framework/
├─ README.md ✅
├─ LICENSE ✅
├─ CONTRIBUTING.md ✅
├─ docs/
│ ├─ framework-core.md ✅
│ ├─ implementation-guide.md ✅
│ ├─ epistemic-foundations.md ✅
│ └─ advanced-techniques.md ✅
├─ templates/
│ ├─ decision-template-minimal.md ✅
│ └─ decision-template-full.md ✅
├─ examples/
│ ├─ technology/
│ │ ├─ database-migration.md ✅
│ │ ├─ framework-selection.md ✅
│ │ └─ architecture-refactor.md ✅
│ ├─ business/
│ │ ├─ pivot-decision.md ✅
│ │ └─ pricing-strategy.md ✅
│ └─ operations/
│ ├─ vendor-selection.md ✅
│ └─ security-audit.md ✅
├─ scripts/
│ └─ validate-structure.py ✅
└─ .github/workflows/
└─ validate.yml ✅