Algorithm

THE ALGORITHM - Universal Execution Engine

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.

Visual Display & Voice Notifications

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/Algorithm/Tools/AlgorithmDisplay.ts start THOROUGH -r "your request"

# Transition phases (updates display + voice announcement)
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts phase THINK
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts phase EXECUTE

# Show current status anytime
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts show

# Show just the effort banner
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts effort DETERMINED

Phase Icons: OBSERVE -> THINK -> PLAN -> BUILD -> EXECUTE -> VERIFY -> LEARN

Quick Start

# 1. START WITH VISUAL DISPLAY (shows banner + voice announcement)
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts start STANDARD -r "your request"

# 2. CLASSIFY EFFORT (if not using display start)
bun run ~/.claude/skills/Algorithm/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/Algorithm/Tools/CapabilityLoader.ts --effort STANDARD

# 4. CREATE ISC
bun run ~/.claude/skills/Algorithm/Tools/ISCManager.ts create --request "your request"

# 5. TRANSITION PHASES (voice + visual update)
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts phase THINK
bun run ~/.claude/skills/Algorithm/Tools/AlgorithmDisplay.ts phase PLAN
# ... continues through EXECUTE, VERIFY, LEARN

# 6. MANAGE ISC during EXECUTE
bun run ~/.claude/skills/Algorithm/Tools/ISCManager.ts capability --row 1 -c research.perplexity
bun run ~/.claude/skills/Algorithm/Tools/ISCManager.ts update --row 1 --status DONE
bun run ~/.claude/skills/Algorithm/Tools/ISCManager.ts show

Effort to Capability Matrix

ISC Scale (CRITICAL)

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:

ISC rows come from:

• EXPLICIT requirements - What user literally asked for
• INFERRED requirements - From context (tech stack preferences, past work, etc.)
• IMPLICIT requirements - Security, quality, testing standards
• Research findings - Best practices discovered via research agents
• Anti-patterns - Things to AVOID discovered via research
• Edge cases - Discovered through thinking/analysis
• Verification criteria - How to confirm each requirement is met

The 7 Phases

Execute IN ORDER. Each phase mutates the ISC:

The ISC Table

## ISC: Request Summary

**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 | research.perplexity | PENDING |
| 2 | Toggle component works | EXPLICIT | execution.engineer | ACTIVE |
| 3 | Theme state persists | EXPLICIT | execution.engineer | PENDING |
| 4 | Uses TypeScript | INFERRED | - | DONE |
| 5 | Tests pass | IMPLICIT | verification.qa | PENDING |

Source types:

• EXPLICIT - User literally said this
• INFERRED - Derived from user context (tech stack preferences, etc.)
• IMPLICIT - Universal standards (security, quality)

Status progression:

• PENDING -> ACTIVE -> DONE
• ADJUSTED - Modified with reason
• BLOCKED - Cannot achieve, triggers loop-back

Iteration Loop

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

Integration

Uses

• Agents Skill - AgentFactory for dynamic agent composition
• CORE Skill - User context for ISC inference
• Browser Skill - Web verification in VERIFY phase
• DeepPlan Skill - Persistent planning integration

Memory

• ISC artifacts: ~/.claude/MEMORY/Work/{session}/ISC.md
• Learnings: ~/.claude/MEMORY/Learning/ALGORITHM/
• State: ~/.claude/MEMORY/State/algorithm-state.json

Workflow Routing

Files

Learning Loop

The Algorithm captures four signal types that feed back into improvement:

Signal Types

Phase-Based Learnings

Learnings are organized by Algorithm phase:

~/.claude/MEMORY/Learning/
├── OBSERVE/    # Context gathering insights
├── THINK/      # Analysis insights
├── PLAN/       # Planning insights
├── BUILD/      # Success criteria insights
├── EXECUTE/    # Implementation insights
├── VERIFY/     # Verification insights
└── ALGORITHM/  # Meta-learnings about the Algorithm itself

Capturing Learnings

# Capture a learning from VERIFY phase
bun run ~/.claude/skills/Algorithm/Tools/LearningCapture.ts capture \
  -p VERIFY -i "Always check async state before assertions" -w "auth-bug"

# Capture meta-learning about the Algorithm
bun run ~/.claude/skills/Algorithm/Tools/LearningCapture.ts meta \
  --pattern "VERIFY fails on concurrent scenarios" \
  --recommendation "Add concurrent test setup to BUILD phase"

# View learning statistics
bun run ~/.claude/skills/Algorithm/Tools/LearningCapture.ts stats

Loopback Detection

When a phase transition goes backward (e.g., VERIFY → THINK), the system:

1. Increments the iteration counter
2. Writes to loopbacks.jsonl with context
3. Announces via voice "Loopback iteration N"

Analyzing Signals

Run /atlas:analyze-signals to see patterns and recommendations based on accumulated signals.

The Purpose

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.