The Algorithm System
The Algorithm System
The gravitational center of PAI — everything else exists to serve it.
The Algorithm is PAI’s universal engine for accomplishing any task. It transitions from Current State to Ideal State through verifiable iteration, using Ideal State Criteria (ISC) as the quality gate. Every interaction — memory capture, hook execution, learning synthesis — feeds back into improving the Algorithm itself.
Current version: v3.26.0
Spec location: PAI/ALGORITHM/v3.26.0.md
Goal: Euphoric Surprise — 9-10 user ratings on every response.
Core Concept
The Algorithm applies at every scale — fixing a typo, building a feature, launching a company. The pattern is always the same:
Current State → [7 Phases] → Ideal State
↑
ISC verification at each stepPAI is not a static tool. The Algorithm continuously upgrades itself based on accumulated evidence from ratings, reflections, and knowledge capture.
The 7 Phases
| Phase | Icon | Purpose |
|---|---|---|
| OBSERVE | Eye | Reverse-engineer the request. Set effort level. Select capabilities. Write ISC criteria. Run preflight gates. |
| THINK | Brain | Identify risks, assumptions, failure modes. Check prior knowledge. Refine ISC. Predict satisfaction score. |
| PLAN | Clipboard | Determine scope strategy (depth/breadth). Decide session splitting. Run isolation gate for parallel agents. |
| BUILD | Hammer | Invoke selected capabilities via tool calls. Preparation work. Write decisions to PRD. |
| EXECUTE | Lightning | Do the work. Check off ISC criteria as each passes. Update PRD progress in real-time. |
| VERIFY | Checkmark | Verify every criterion with evidence. Confirm capability invocations met tier minimums. Check preflight compliance. |
| LEARN | Book | Reflect on what worked and what didn’t. Flag knowledge worth archiving. Write reflection JSONL. |
Each phase transition requires a voice announcement and PRD update. Phase headers are mandatory output. Dual-source phase tracking (2026-04-16; extended 2026-04-18): The voice curl body now includes phase and slug fields, and hooks/lib/prd-utils.ts::appendPhase() merges voice-sourced and PRD-sourced entries in work.json phaseHistory (dedup via upgrade to source: "merged"). Both sources also write top-level session.phase and drive setPhaseTab() for the terminal tab icon, so /agents UI and kitty tabs reflect the live phase even when only one source fires. Missing a voice call still records the phase via PRD edit; missing a PRD edit still records via voice.
Effort Levels
| Tier | Shortcut | Budget | ISC Floor | Min Capabilities | When |
|---|---|---|---|---|---|
| Standard | /e1 | <2min | 12 | 1-2 | Normal request (default) |
| Extended | /e2 | <8min | 24 | 3-5 (3+ thinking) | Quality must be extraordinary |
| Advanced | /e3 | <16min | 36 | 5-8 (5+ thinking, 2+ delegation) | Substantial multi-file work |
| Deep | /e4 | <32min | 56 | 8-12 (5+ thinking, 3+ delegation) | Complex design |
| Comprehensive | /e5 | <120min | 80 | 10-15 (5+ thinking, 4+ delegation) | No time pressure |
Min Capabilities = distinct skills/agents actually invoked via tool call. Text-only references do not count.
ISC Quality System
ISC (Ideal State Criteria) are the atomic verification units. Every criterion must be binary-testable, 8-12 words, one verifiable end-state.
Category Tags
| Tag | Meaning | Constraint |
|---|---|---|
[F] | Functional — core behavior | No limit |
[S] | Structural — files, patterns | Max 40% of total |
[B] | Behavioral — runtime output | Min 20% of total |
[N] | Negative — must NOT happen | Min 2 items always |
[E] | Edge — error handling, boundaries | Min 10% of total |
Splitting Test
Apply to every criterion before finalizing:
- “And”/“With” joins two verifiable things — split
- Independent failure — part A can pass while B fails — split
- Scope words (“all”, “every”, “complete”) — enumerate
- Domain boundary crosses UI/API/data/logic — one per boundary
Quality Gates (must pass before leaving OBSERVE)
- Count >= tier floor
- Category diversity: 3+ distinct tags,
[S]<= 40% - Testability: tool-verifiable, max 2 human-judgment items
- Anti-criteria: 2+
[N]items - Capabilities: 1+ named with reason (Extended+: 1+ thinking capability)
Mode System
The Algorithm supports multiple execution modes detected during OBSERVE.
| Mode | Trigger | Phase Compression |
|---|---|---|
| Standard | Default | All 7 phases |
| Fast-path | Verbatim command, single tool call (Standard tier only) | OBSERVE -> EXECUTE -> VERIFY |
| Research | Analysis/review, no code changes (Standard tier only) | OBSERVE -> THINK -> EXECUTE -> VERIFY -> LEARN |
| Ideate | ideate [problem], id8, generate ideas for | All 7, with ideate-loop.md overlay |
| Optimize | optimize [target] | All 7, with optimize-loop.md overlay |
Mode detection logic: PAI/ALGORITHM/mode-detection.md
Tunable Parameters (Ideate & Optimize)
Both modes accept tunable parameters resolved via preset, focus value, individual overrides, or tone inference. Parameters are stored in PRD algorithm_config: frontmatter.
Presets: dream, explore, directed, surgical (ideate) | cautious, aggressive (optimize)
Knowledge Archive Integration (v3.17.0 + v2.0 redesign)
The Algorithm’s THINK and LEARN phases integrate with the Knowledge Archive (3 entity types: People, Companies, Ideas):
- THINK phase: Searches
MEMORY/KNOWLEDGE/for prior work on the current topic. Prevents re-researching known entities. - LEARN phase: Writes knowledge directly to
MEMORY/KNOWLEDGE/{Type}/— classifies as Person, Company, or Idea using the schemas defined in_schema.md. Topic (security, AI, business) is a tag on the entity, not a separate domain. If the knowledge doesn’t fit one of the three entity types, it stays in WORK/ or LEARNING/ — not everything is knowledge.
The lookup test: “Would the user look this up by name?” — if yes, write to KNOWLEDGE/. If not, skip.
Most sessions will SKIP knowledge capture — that’s correct behavior. Only capture what’s genuinely novel and reusable.
PRD as System of Record
Every Algorithm run creates a PRD (Product Requirements Document) in ~/.claude/PAI/MEMORY/WORK/{slug}/PRD.md. The AI writes all PRD content directly — no hook writes to PRDs.
Frontmatter: task, slug, effort, phase, progress, mode, started, updated
Body sections: ## Context, ## Criteria, ## Decisions, ## Verification
Full PRD format spec: PAI/DOCUMENTATION/PrdFormat.md
Supporting Files
| File | Purpose |
|---|---|
PAI/ALGORITHM/v3.26.0.md | Full execution spec — the definitive Algorithm reference |
PAI/ALGORITHM/capabilities.md | Capability selection tables (thinking, code quality, delegation, research) |
PAI/ALGORITHM/mode-detection.md | Mode and parameter detection logic |
PAI/ALGORITHM/ideate-loop.md | Ideate mode overlay (evolutionary ideation) |
PAI/ALGORITHM/optimize-loop.md | Optimize mode overlay (metric/eval optimization) |
PAI/DOCUMENTATION/PrdFormat.md | PRD format specification v2.0 |
Version History
| Version | Key Changes |
|---|---|
| v3.26.0 | Doctrine tightening: Deliverable Manifest (PLAN), Inline Verification mandate (EXECUTE), Reproduce-First blocking gate (OBSERVE) — three failure modes from 871-reflection mining |
| v3.25.0 | Capability expansion: SystemsThinking and RootCauseAnalysis skills added to the thinking lattice |
| v3.24.0 | Five hardening patches (P1-P5) closing RedTeam-identified escape hatches in v3.23 verification doctrine |
| v3.23.0 | Verification Doctrine: three rules (Live-Probe, Commitment-Boundary Advisor, Conflict-Surfacing); Feedback Memory Auto-Consult; Parallelism Opportunity Scan |
| v3.19.0-v3.22.0 | Refinement of effort tiers, capability minimums, agent systems |
| v3.18.0 | E-level shortcuts (/e1-/e5) for explicit effort control; enhanced capability minimums |
| v3.17.0 | LEARN phase writes knowledge directly to KNOWLEDGE/ archive (no harvester intermediary) |
| v3.16.0 | Knowledge Archive integration (THINK reads, LEARN flags in PRDs for harvester) |
| v3.15.0 | Tunable parameters, ideate/optimize mode presets, parameter-schema.md |
| v3.14.x | ISC category tags, splitting test, quality gates |
| Earlier | Phase structure established, PRD system, effort tiers |
Context Recovery
Mid-session (after compaction):
- Read most recent PRD — has phase, progress, all ISC state
- Check TaskList for in-flight work
- Re-verify auth tokens if needed
- Jump to current phase — don’t re-run earlier phases
Cold-start (new session on existing work):
- Read PRD from
~/.claude/PAI/MEMORY/WORK/ ~/.claude/PAI/MEMORY/STATE/work.jsonhas the session registry
Rules
- No freeform output — every response uses the Algorithm’s summary format
- No phantom capabilities — every selected capability must be invoked via tool
- PRD is the AI’s responsibility — no hook writes to it
- ISC quality gates must pass before leaving OBSERVE
- No silent stalls — hung execution is failure
Full execution spec: PAI/ALGORITHM/v3.26.0.md | PRD format: PAI/DOCUMENTATION/PrdFormat.md