AI is not a tool. It is an agent. — Yuval Noah Harari
A linter runs the same way every time. An AI agent reasons, interprets, and makes judgment calls — just like a human. And like any agent, it can be lazy, biased, or wrong.
Diffract keeps both human and AI reviewers honest — structurally.
Vision: Every review reveals the truth about the artifact — regardless of who reviews it.
Mission: Keep each other honest — structurally, not aspirationally.
Goal: Same artifact + same lenses + different reviewer = same findings.
Diffract emerged from code review, but the lenses apply to anything that can be reviewed: code, documentation, architecture, API designs, or processes.
Honest value proposition: A good senior reviewer does 80% of what Diffract does intuitively. The value is in the other 20% — the lenses you'd skip, the proof you actually looked, and the calibration test that catches what you missed. No single component is original. The value is in the combination.
- Why Diffract?
- How to Use
- Quick Start
- Documentation
- How It Emerged
- Acknowledgments
- Contributing
- References
- License
The moment AI becomes an agent in your review process, you need the same structural honesty mechanisms that aviation, nuclear, and medicine use for their human inspectors:
- Evidence for every claim (not just "looks good")
- Separation of finding from vetting (the agent who finds doesn't decide)
- Testable findings (objective, not opinion)
- Anti-manipulation mechanisms borrowed from aviation, medicine, and other high-stakes industries
Your most important role: Don't just approve the PLAN and wait. Challenge the agent during every phase. The most valuable findings in Diffract's own development came from human interruptions, not from the lenses. The lenses find what's wrong. You find what's missing.
- Open your preferred AI assistant (Claude, Gemini, ChatGPT, or any LLM)
- Paste the contents of
PROMPT.mdinto the chat - Paste the artifact you want to review (code, documentation, design)
- The AI will propose governors (PLAN) and wait for your confirmation
- Once confirmed, the AI runs all 9 lenses and produces findings
You can also use PROMPT.md as a checklist for human-only reviews.
Start simple: You don't need to master all 9 lenses on day one. Try 🗑️ Subtract and 🛡️ Shield on your next PR. Add lenses as you get comfortable.
Before any analysis, agree on scope, calibration, and evidence rules:
🧭 Compass: "Is this code ready for production?"
🐍 Cobra: Cautious — fix more, skip less.
⚖️ Integrity: file:line evidence per lens. Cognitive anchoring required.
PLAN is a checkpoint. Propose governors, get agreement, then proceed. No agreement = no analysis.
Pick a Compass that fits your situation:
| Compass | Best For |
|---|---|
| "Is this code ready for production?" | Pre-release |
| "Could a junior dev onboard from this in one day?" | Readability |
| "If the author left, could someone else maintain this?" | Bus factor |
| "Does this code respect the user's time and data?" | Ethics / UX |
| "Would this survive a 10x traffic spike at 3am?" | Resilience |
| "Are all ideas properly attributed?" | Intellectual honesty |
Run each lens across the codebase. Collect ALL findings. Do not fix yet.
| # | Lens | Question |
|---|---|---|
| 1 | 🗑️ Subtract | Can I remove this entirely? |
| 2 | ✂️ Simplify | Can this be simpler without losing capability? |
| 3 | 🏷️ Name | Does the name match the thing? |
| 4 | 📌 Truth | Is this knowledge in exactly one place? |
| 5 | 🧱 Boundary | Can an isolated change stay in one boundary? |
| 6 | 🛡️ Shield | Does it neutralize all inputs that violate its invariants? |
| 7 | 🎯 Variety | Does every possible input map to a defined output? |
| 8 | 🔍 Observability | Can I determine system state from its outputs? |
| 9 | ⚡ Efficiency | Is resource use proportional to the work required? |
Then ask W5H1 to find what's missing — especially Why (rationale), Who (ownership), and When (expiry).
Finding
→ ⚖️ Integrity: "Is this objective? Would another reviewer agree?"
→ No → Discard (bikeshedding or bias)
→ Yes →
→ 🧭 Compass: "Is this relevant to our goal?"
→ No → Skip (Compass)
→ Yes →
→ 🐍 Cobra: "Does fixing it cause a new problem?"
→ Yes → Skip (Cobra)
→ No → Fix
- Apply all fixes
- Verify (build + test + lint)
- Retro: what did the framework miss? Update it.
- If fixes were applied → cycle back to PLAN
Done when a full cycle produces zero new Fix outcomes. In our first application, Diffract found 15 issues across 3 PDCA cycles, with Observability and Subtract as the most productive lenses.
| Document | Description |
|---|---|
| Governors | Detailed governor specifications |
| Lenses | Each lens with root principle, evidence format, and examples |
| Anti-Dishonesty | 8 structural mechanisms adapted from high-stakes industries |
| W5H1 | Completeness scan for what's missing |
| Review Prompt | Self-contained instructions for running a Diffract review |
| Calibration | How to validate review consistency across reviewers |
| Example Review | Full Diffract cycle on a web service |
| Research: First Principles | DeepThink analysis validating the lens set |
| Research: High-Stakes Review | Patterns from aviation, nuclear, medicine, law |
| Roadmap | Future: deterministic tooling, MCP integration, v1.0 criteria |
Diffract was developed through a collaboration between a human engineer and AI assistants during a code review session in February 2026. The framework started as 8 review lenses, was challenged against independent first-principles research (DeepThink), cross-validated against high-stakes industry practices (DeepResearch), and refined through multiple PDCA cycles — including applying the framework to itself.
The process was itself an act of Diffract: the human set the Compass, the AI applied the lenses, and both challenged each other's findings. The anti-dishonesty mechanisms emerged from this dynamic — the need to keep both human and AI reviewers honest was not theoretical but experienced firsthand.
The name comes from optics: diffraction splits a wave into its component parts. Diffract splits an artifact into its component concerns.
During development, 8 different compasses were applied to this repo — the same artifact, same lenses, different intent — each producing unique findings:
| Compass | What It Found |
|---|---|
| "Can someone use this from the repo alone?" | Missing "How to Use" section |
| "Can any LLM follow this equally well?" | Missing one-shot mode, no-tool fallback |
| "Would a newcomer feel welcomed?" | Academic jargon in README, no "Start simple" |
| "Is this original? Did we attribute sources?" | Harari unattributed, no bibliography |
| "Are all links and spelling correct?" | Terminology drift (falsifiable vs testable) |
| "Does it guide AI to use tools first?" | No per-lens tooling table |
| "Is it language-neutral?" | Go-specific tools in automation table |
| "Is every sentence clear and kind?" | "Refuse" → "Pause", added kindness rule |
The Compass is the most powerful lever in the framework.
This framework was co-created by Jasper Duizendstra and AI assistants during a collaborative code review session.
The following AI systems contributed to the development of Diffract:
- Antigravity (Google DeepMind) — Primary collaborator. Co-developed the framework structure, applied lenses to real codebases, drafted documentation, and challenged findings across multiple PDCA cycles.
- Google DeepThink (Gemini 3.1 Pro) — Independent first-principles analysis (RQ1) that validated the lens set and identified two missing lenses (Variety, Efficiency).
- Google DeepResearch (Gemini 3.1 Pro) — External research (RQ2) that identified structural anti-manipulation mechanisms from aviation, nuclear, medicine, and legal industries.
All design decisions, research direction, governor calibration, and quality standards were set by the human author. The Compass was always human-set. The AI proposed; the human decided.
This framework contains AI-generated content. While the human author reviewed and approved all material, the documentation, examples, and structural design were produced through human-AI collaboration. We believe in full transparency about AI involvement in intellectual and creative work.
No single component of Diffract is original. The value is in the combination.
| Component | Source |
|---|---|
| "AI is not a tool, it is an agent" | Yuval Noah Harari |
| PDCA cycle | W. Edwards Deming, Toyota Production System |
| Shisa Kanko (cognitive anchoring) | Japanese National Railways |
| Falsifiability | Karl Popper, The Logic of Scientific Discovery |
| Via Negativa | Nassim Nicholas Taleb, Antifragile |
| Requisite Variety | W. Ross Ashby, An Introduction to Cybernetics |
| Ubiquitous Language | Eric Evans, Domain-Driven Design |
| DRY | Andy Hunt & Dave Thomas, The Pragmatic Programmer |
| YAGNI | Kent Beck, Extreme Programming |
| Clean Architecture | Robert C. Martin |
| CRM / Challenge-Response | Aviation industry |
| Dual-reading / Calibration | Radiology |
| Blind seeding | UXO clearance, Radiology, Legal e-discovery |
| "First, do no harm" | Hippocratic tradition |