Universal execution engine using scientific method to achieve ideal state. USE WHEN complex tasks, multi-step work, "run the algorithm", "use the algorithm", OR any non-trivial request that benefits from structured execution with ISC (Ideal State Criteria) tracking.
npxskills add danielmiessler/personal_ai_infrastructure--skill THEALGORITHMLoading…
Before executing, check for user customizations at:
~/.claude/skills/CORE/USER/SKILLCUSTOMIZATIONS/THEALGORITHM/
If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
PURPOSE: Produce euphoric, highly surprising, exceptional results that solve the problem better than expected.
PHILOSOPHY: Move from current state to ideal state using the scientific method. The ISC (Ideal State Criteria) captures what "ideal" looks like, which we execute against, verify against, and iterate against until achieved.
CORE PRINCIPLE: Effort classification determines which capabilities are available. Higher effort unlocks more powerful tools.
The goal of The Algorithm—and indeed of the PAI system overall—is to create Euphoric Surprise at its ability to perform every task in service of helping its principal become the best version of themselves.
This is the north star. Every capability, every phase, every ISC row exists to serve this mission. When the system works correctly, the principal should be genuinely surprised and delighted by how thoroughly, thoughtfully, and effectively their request was fulfilled—not just "done" but done in a way that exceeds expectations and moves them closer to their ideal self.
Use the LCARS-style AlgorithmDisplay for visual feedback and voice announcements:
# Start algorithm with effort level (shows banner + announces via voice)
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts start THOROUGH -r "your request"
# Transition phases (updates display + voice announcement)
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts phase THINK
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts phase EXECUTE
# Show current status anytime
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts show
# Show just the effort banner
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts effort DETERMINED
The display shows:
Phase Icons: 👁️ OBSERVE → 🧠 THINK → 📋 PLAN → 🔨 BUILD → ⚡ EXECUTE → ✅ VERIFY → 📚 LEARN
# 1. START WITH VISUAL DISPLAY (shows banner + voice announcement)
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts start STANDARD -r "your request"
# 2. CLASSIFY EFFORT (if not using display start)
bun run ~/.claude/skills/THEALGORITHM/Tools/EffortClassifier.ts --request "your request"
# Or with override: --override DETERMINED
# Or inline: "algorithm effort THOROUGH: your request"
# 3. LOAD CAPABILITIES for effort level
bun run ~/.claude/skills/THEALGORITHM/Tools/CapabilityLoader.ts --effort STANDARD
# 4. CREATE ISC
bun run ~/.claude/skills/THEALGORITHM/Tools/ISCManager.ts create --request "your request"
# 5. TRANSITION PHASES (voice + visual update)
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts phase THINK
bun run ~/.claude/skills/THEALGORITHM/Tools/AlgorithmDisplay.ts phase PLAN
# ... continues through EXECUTE, VERIFY, LEARN
# 6. MANAGE ISC during EXECUTE
bun run ~/.claude/skills/THEALGORITHM/Tools/ISCManager.ts capability --row 1 -c research.perplexity
bun run ~/.claude/skills/THEALGORITHM/Tools/ISCManager.ts update --row 1 --status DONE
bun run ~/.claude/skills/THEALGORITHM/Tools/ISCManager.ts show
Capabilities.yaml is the source of truth. See Data/Capabilities.yaml.
| Effort | Models | Thinking | Debate | Research | Agents | Parallel |
|---|---|---|---|---|---|---|
| TRIVIAL | — | — | — | — | — | 0 |
| QUICK | haiku | — | — | — | Intern | 1 |
| STANDARD | haiku, sonnet | deep thinking, FirstPrinciples | — | 1 agent | Engineer, QA, Designer | 1-3 |
| THOROUGH | haiku, sonnet | All | Council | parallel | All + Architect, Pentester | 3-5 |
The ISC is NOT limited to a small number of rows. The ISC captures what "ideal" looks like, and for complex problems this can be massive:
| Scale | When | Examples |
|---|---|---|
| 5-10 rows | Quick fixes, simple features | "Fix typo", "Add button" |
| 20-50 rows | Standard development work | "Add dark mode", "Create API endpoint" |
| 50-200 rows | Complex features, refactors | "Redesign auth system", "Add new major feature" |
| 200-1000+ rows | Major projects, DETERMINED effort | "Build entire system", "Security audit" |
ISC rows come from:
The algorithm's capabilities EXPAND the ISC:
Higher effort = larger, higher quality ISC. The DETERMINED level can have thousands of ISC rows because we use ALL capabilities to discover everything that "ideal" looks like.
Execute IN ORDER. Each phase mutates the ISC:
| Phase | Action | ISC Mutation | Gate Question |
|---|---|---|---|
| OBSERVE | Understand request + user context | CREATE rows | Do I have 2+ rows? Used context to infer? |
| THINK | Ensure nothing missing | COMPLETE rows | All rows clear, testable? |
| PLAN | Sequence + assign capabilities | ORDER rows + ASSIGN capabilities | Dependencies mapped? Capabilities assigned? |
| BUILD | Make rows testable | REFINE rows | Each row specific enough to verify? |
| EXECUTE | Do the work (spawn agents per capability) | ADVANCE status | Every row has final status? |
| VERIFY | Test each DONE row (skeptical agent) | CONFIRM status | Tested/confirmed each completion? |
| LEARN | Output for user to rate |
CRITICAL: The LEARN phase does NOT self-rate. User rates outputs for the memory system.
Every non-trivial task has an ISC. Display this prominently throughout execution:
## 🎯 IDEAL STATE CRITERIA
**Request:** Add dark mode to the settings page
**Effort:** STANDARD | **Phase:** EXECUTE | **Iteration:** 1
| # | What Ideal Looks Like | Source | Capability | Status |
|---|----------------------|--------|------------|--------|
| 1 | Research good patterns | INFERRED | 🔬 perplexity | ⏳ PENDING |
| 2 | Toggle component works | EXPLICIT | 🤖 engineer | 🔄 ACTIVE |
| 3 | Theme state persists | EXPLICIT | 🤖 engineer× | ⏳ PENDING |
| 4 | Uses TypeScript | INFERRED | — | ✅ DONE |
| 5 | Tests pass | IMPLICIT | ✅ qa_tester | ⏳ PENDING |
| 6 | Browser-verified | IMPLICIT | ✅ browser | ⏳ PENDING |
**Legend:** 🔬 Research | 💡 Thinking | 🗣️ Debate | 🔍 Analysis | 🤖 Execution | ✅ Verify | × Parallel
Source types:
EXPLICIT - User literally said thisINFERRED - Derived from user context (TECHSTACKPREFERENCES, etc.)IMPLICIT - Universal standards (security, quality)Status progression:
PENDING → ACTIVE → DONEADJUSTED - Modified with reasonBLOCKED - Cannot achieve, triggers loop-backbun run ~/.claude/skills/THEALGORITHM/Tools/EffortClassifier.ts --request "your request"
Override methods:
--override THOROUGH"algorithm effort DETERMINED: build this feature"The effort level determines ALL available capabilities.
bun run ~/.claude/skills/THEALGORITHM/Tools/CapabilityLoader.ts --effort STANDARD
Returns available: models, thinking modes, debate systems, research agents, execution agents, verification.
For each ISC row, select appropriate capability:
bun run ~/.claude/skills/THEALGORITHM/Tools/CapabilitySelector.ts --row "Research best practices" --effort STANDARD
# Returns: research.perplexity as primary, with icon 🔬
bun run ~/.claude/skills/THEALGORITHM/Tools/ISCManager.ts capability --row 1 -c research.perplexity
Execute in phases based on capability assignments:
PHASE A: RESEARCH (parallel for independent queries)
├─ Row with 🔬 research.perplexity → Spawn PerplexityResearcher
├─ Row with 🔬 research.gemini → Spawn GeminiResearcher
└─ Row with 🔬 research.grok → Spawn GrokResearcher
PHASE B: THINKING (for creative/analysis needs)
├─ Row with 💡 thinking.deep thinking → Invoke BeCreative skill
├─ Row with 🔍 analysis.first_principles → Invoke FirstPrinciples skill
└─ Row with 🗣️ debate.council → Invoke Council skill
PHASE C: EXECUTION (parallel agents)
├─ Row with 🤖 execution.engineer → Spawn Engineer agent
├─ Row with 🤖 execution.architect → Spawn Architect agent (THOROUGH+)
└─ Rows marked × → Run in parallel
PHASE D: VERIFICATION (skeptical, different from executor)
├─ Row with ✅ verification.browser → Browser skill validation
└─ All rows → Skeptical verifier agent (skeptical,meticulous,adversarial traits)
Direct response, no ISC, no capability loading. Just answer.
models.haiku - Fast, cheap (QUICK+)models.sonnet - Balanced reasoning (STANDARD+)models.opus - Maximum intelligence (DETERMINED)thinking.deep thinking - BeCreative skill for creative solutions (STANDARD+)thinking.tree_of_thought - Branching exploration (THOROUGH+)thinking.plan_mode - EnterPlanMode for complex implementations (THOROUGH+)debate.council - 4 agents, collaborative analysis (THOROUGH+)debate.redteam - 32 agents, adversarial stress-testing (DETERMINED)analysis.first_principles - Challenge assumptions (STANDARD+)analysis.science - Hypothesis-driven exploration (STANDARD+)research.perplexity - Web research, current events (STANDARD+)research.gemini - Multi-perspective research (STANDARD+)research.grok - Contrarian fact-checking (STANDARD+)research.claude - Academic/scholarly sources (STANDARD+)research.codex - Technical code pattern research (STANDARD+)execution.intern - Parallel grunt work (QUICK+)execution.engineer - Implementation/coding (STANDARD+)execution.qa_tester - Testing/validation (STANDARD+)execution.designer - UX/UI design (STANDARD+)execution.architect - System design (THOROUGH+)execution.pentester - Security testing (THOROUGH+)verification.browser - Web application validation (STANDARD+)verification.skeptical_verifier - Different agent than executor (STANDARD+)When VERIFY finds issues:
BLOCKED row
│
├─ Unclear what ideal looks like? → Loop to THINK
├─ Wrong approach? → Loop to PLAN
└─ Execution error? → Loop to EXECUTE
Iteration count bounded by effort level:
- QUICK: 1 iteration max
- STANDARD: 2 iterations
- THOROUGH: 3-5 iterations
- DETERMINED: Unlimited until success
MEMORY/Work/{session}/ISC.mdMEMORY/Learning/ALGORITHM/MEMORY/Signals/algorithm-patterns.jsonl| Trigger | Action |
|---|---|
| "run the algorithm" | Full execution |
| "use the algorithm" | Full execution |
| "algorithm effort LEVEL" | Force effort level + full execution |
| Complex multi-step request | Auto-invoke if appropriate |
CRITICAL: Every ISC row should have a verification method defined at creation, not after.
# Add row WITH verification (recommended)
bun run ISCManager.ts add -d "Toggle component works" -s EXPLICIT \
--verify-method browser --verify-criteria "Toggle visible in settings"
Verification methods: browser, test, grep, api, lint, manual, agent, inferred
See Data/VerificationMethods.yaml for selection guidance.
Prevents race conditions when multiple agents work on ISC items.
# Claim an item
bun run ISCManager.ts claim --row 1 --agent Engineer
# Release when done
bun run ISCManager.ts release --row 1
# See what's available
bun run ISCManager.ts available
Claims expire after 30 minutes (stale detection).
Research findings can BLOCK user assumptions. User must acknowledge.
# Research agent finds issue
bun run ISCManager.ts research-block --row 2 \
--reason "Best practice is X, not Y" --source research.perplexity
# User acknowledges
bun run ISCManager.ts acknowledge --row 2 --action OVERRIDE # or ACCEPT
Complex items spawn child ISAs.
# Mark item as nested
bun run ISCManager.ts nest --row 5
# Update child status
bun run ISCManager.ts child-status --row 5 --child-status COMPLETE
When ideal state is unclear, use structured questions.
bun run ISCManager.ts interview -r "vague request"
The 5 Questions:
| File | Purpose |
|---|---|
Data/Capabilities.yaml | Source of truth for all capabilities |
Data/VerificationMethods.yaml | Verification method registry |
Tools/AlgorithmDisplay.ts | LCARS visual display + voice announcements |
Tools/EffortClassifier.ts | Classify TRIVIAL→DETERMINED |
Tools/CapabilityLoader.ts | Load + filter capabilities by effort |
Tools/CapabilitySelector.ts |
Produce euphoric, highly surprising, exceptional results that solve the user's problem better than expected.
The ISC captures what "ideal" looks like. Effort determines available capabilities. Execute against it. Verify against it. Iterate until achieved.
This is not documentation. This is a command. Execute the algorithm.
| DETERMINED | all + opus | All | Council + RedTeam | all | unlimited | 10 |
| OUTPUT results |
| User rates for memory system |
| Select capabilities for ISC rows |
Tools/ISCManager.ts | Enhanced: ISC with verification, claims, research, nesting |
Tools/TraitModifiers.ts | Effort → trait mappings |
Phases/*.md | Detailed phase documentation (Observe.md has interview protocol) |
Reference/CapabilityMatrix.md | Effort → capability documentation |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).