Score	Mode	Characteristics
1-2	DIRECT	Simple, few files, clear scope
3-5	ORCHESTRATED	Complex, many files, needs phases

See references/complexity-rubric.md for detailed scoring criteria.

Execution Modes

DIRECT Mode (Score 1-2):

Simple iterative loop
Work until done
Evidence gate before completion
No decomposition needed

ORCHESTRATED Mode (Score 3-5):

Decompose into 2-5 phases
Checkpoint after each phase
Evidence gate per phase
Supports multi-session resume

Evidence Gates (MANDATORY)

Every claim MUST include verification:

✅ VALID:
"Implemented feature X [VERIFIED: npm test → 12 passing]"
"Fixed bug Y [VERIFIED: manual test confirms fix]"
"Added component Z [VERIFIED: npm run build → success]"

❌ INVALID:
"I implemented the feature" (no evidence)
"Should work now" (speculation)
"Tests probably pass" (not verified)

Red Flag Words (trigger re-verification):

"should", "probably", "I think", "seems to", "likely"

Failure Recovery

See references/failure-handling.md for complete protocol.

Quick Reference:

PIVOT (first 3 attempts) - Try alternative approach
RESEARCH (next 3 attempts) - Read more code, understand better
CHECKPOINT (after 6 failed attempts) - Save state, report stuck

Protocol

Step 1: Analyze Complexity

Parse the user's request and score 1-5:

Analyze: "<user prompt>"

Factors:
- Estimated files affected: N
- Keywords detected: [list]
- Features mentioned: N
- Complexity signals: [list]

Score: X/5
Mode: DIRECT|ORCHESTRATED
Reasoning: "..."

Step 2: Initialize State

Create .claude/smart-ralph/state.yaml:

version: "1.0"
mode: DIRECT|ORCHESTRATED
phase: ANALYZE|EXECUTE|VERIFY
complexity:
  score: N
  reasoning: "explanation"
  mode_selected: DIRECT|ORCHESTRATED
started_at: "ISO timestamp"
prompt: "original user prompt"
orchestrated_phases: []  # only for ORCHESTRATED
failure_recovery:
  pivot_count: 0
  research_count: 0
  last_error: null

Step 3: Execute (Mode-Dependent)

DIRECT Mode:

Understand task clearly
Implement with TDD when applicable
Verify each change
Collect evidence
Complete when all verified

ORCHESTRATED Mode:

Decompose into 2-5 phases
Execute phase 1
Checkpoint + evidence gate
Continue to next phase
Final verification after all phases

Step 4: Handle Failures

If stuck (same error 3x, no progress):

PIVOT: Identify failure, list alternatives, try different approach
RESEARCH: If pivot fails 3x, read more code, understand context
CHECKPOINT: If research fails 3x, save state, output STUCK

Update state after each recovery attempt:

failure_recovery:
  pivot_count: 2
  research_count: 1
  last_error: "description of what's failing"

Step 5: Verify and Complete

Before outputting COMPLETE:

Run all verification commands (test, build, lint, typecheck)
Document each result with evidence
Ensure NO red flag words in claims
Output structured completion summary

State Management

File Locations

All state in .claude/smart-ralph/:

state.yaml - Machine-readable execution state
progress.md - Human-readable progress report
stuck-report.md - Only created if STUCK (detailed context)

Progress File Format

## Smart Ralph Progress

**Task:** <original prompt>
**Mode:** DIRECT|ORCHESTRATED (Complexity: X/5)
**Started:** <timestamp>
**Status:** in_progress|complete|stuck

### Completed
- [x] Phase/Step 1: Description [VERIFIED: evidence]

### In Progress
- [ ] Phase/Step 2: Description

### Evidence Collected
- `npm test` → 24 passing
- `npm run build` → success

Resume Detection

On session start, check for incomplete state:

Read .claude/smart-ralph/state.yaml
If exists and phase != COMPLETE → resume
Load progress and continue from last checkpoint

Integration with autonomous-dev

Smart Mode reuses:

project-detector skill for tech stack detection
verification-runner skill for test/build/lint
task-decomposer skill (only in ORCHESTRATED mode)
Result filtering patterns for token efficiency

Key Differences from /auto

Aspect	/auto	/auto-smart
Approval gates	Phase 3, Phase 6	None
Complexity detection	Manual classification	Automatic
Failure handling	Manual intervention	Auto pivot/research
Mode selection	Always full workflow	Adaptive
Resume	/auto-continue	Automatic

smart-mode

Smart Mode - Intelligent Autonomous Execution

When This Skill Activates

Core Concepts

Complexity Scoring