Karpathy's Version

• One Python file (630 lines)
• AI trains neural networks overnight
• 700 experiments, 20 discoveries, 11% speedup
• Needs expensive GPU hardware
• Only works for AI training

Udit's AutoResearch

• Claude Code skill (9 commands)
• AI improves anything measurable
• Code, docs, security, marketing, SEO...
• No special hardware needed
• Works for any domain

autoresearch/
  claude-plugin/
    commands/
      autoresearch.md      # core loop
      autoresearch/
        debug.md           # 8 subcommands
        fix.md
        learn.md
        plan.md
        predict.md
        scenario.md
        security.md
        ship.md
    skills/
      autoresearch/
        SKILL.md           # main skill def
        references/
          autonomous-loop-protocol.md
          results-logging.md
          core-principles.md
          *-workflow.md    # 8 workflows
  guide/                   # docs + walkthroughs
  scripts/                 # release tooling

Key Design Decisions

• Pure Markdown -- the entire system is defined in .md files, no compiled code
• Claude Code Skill -- installs via plugin marketplace or manual copy
• Reference separation -- core protocol, logging spec, and workflows are isolated reference docs
• Language: Shell -- only scripting is for release automation

Seven Universal Principles

• Constraints enable -- limits create focus
• Strategy != tactics -- humans set direction; AI executes
• Mechanical metrics -- numbers, never feelings
• Fast verification -- enables bold exploration
• Iteration costs shape behavior
• Git = memory -- commits encode experiments
• Honest limits -- system knows its boundaries

Required Configuration

Phase 0: Precondition Checks

• Clean git working tree?
• No lock files or detached HEAD?
• No interfering hooks?
• Baseline metric established (iteration #0)

Phase 1: Rebuild Awareness

• Read all in-scope files
• Parse git log --oneline -20
• Read results log for pattern recognition

Phase 2: Strategic Selection

Priority order when choosing next experiment:

• Crash fixes -- highest priority
• Success exploitation -- extend what worked
• Exploration -- try untested approaches
• Combination -- merge successful changes
• Simplification -- less code, same result
• Radical experiments -- last resort

Commit = Experiment

# Every change gets committed BEFORE verify
git add <specific-files>  # never git add -A
git commit -m "experiment: add batch norm"

# On failure: revert preserves history
git revert HEAD  # NOT git reset --hard

# Reading memory before each iteration
git log --oneline -20
git show <commit-hash> --stat

Why Revert, Not Reset?

• git revert preserves the failed attempt in history
• Agent can later read why something failed
• git reset --hard destroys the lesson
• Pattern recognition across 100s of commits

Status Categories

Pattern Recognition

• Summary every 10 iterations
• Cross-references keeps with descriptions
• 5 consecutive discards triggers stuck-state escalation
• Agent reads log in Phase 1 to avoid repeating failures

Guard Commands

Optional parallel check that prevents regressions:

# Metric improves BUT guard fails?
# System tries to rework (max 2 attempts)

if metric_improved && guard_failed:
    # Attempt 1: modify implementation
    # (NEVER modify tests/guard)
    rework_change()
    if guard_still_fails:
        # Attempt 2: different approach
        rework_change()
        if guard_still_fails:
            git_revert()  # discard entirely

Atomicity Enforcement

• One logical change per iteration
• Must pass the "one-sentence test"
• Changes spanning 5+ files trigger re-evaluation

Crash Recovery

• Syntax errors: 3 auto-fix attempts
• Runtime exceptions: revert + retry differently
• Resource exhaustion: graceful degradation
• Infinite loops: timeout detection
• Dependency failures: revert + skip

Noisy Metric Handling

STRIDE Threat Model

• Spoofing identity
• Tampering with data
• Repudiation of actions
• Information disclosure
• Denial of service
• Elevation of privilege

Red-Team Personas

• Security Adversary
• Supply Chain Attacker
• Insider Threat
• Infrastructure Attacker

Composite Metric

score = (owasp_tested/10) * 50
      + (stride_tested/6)  * 30
      + min(findings, 20)

Output Structure

security/YYMMDD-HHMM-slug/
  overview.md
  threat-model.md
  attack-surface-map.md
  findings.md
  owasp-coverage.md
  dependency-audit.md
  recommendations.md
  security-audit-results.tsv

Flags

--diff delta mode | --fix auto-fix critical | --fail-on CI gate

Expert Personas

• Architect -- system design perspective
• Security Analyst -- threat surface
• Performance Engineer -- bottlenecks
• Reliability Engineer -- failure modes
• Devil's Advocate -- mandatory dissent

Adversarial Variant

With --adversarial flag:

• Red Team vs Blue Team
• Insider Threat persona
• Supply Chain attacker
• Judge synthesizer

Chaining

# Predict finds issues, debug hunts them,
# fix resolves them
/autoresearch:predict \
  --chain debug,fix \
  --depth deep

/autoresearch:ship

8-phase universal shipping workflow:

Supports: code PRs, releases, deployments, content, marketing emails, campaigns, sales, research, design

ship_score = (passing/total)*80
  + (dry_run_passed? 15:0)
  + (no_blockers?    5:0)
# Score 100 = ready; <80 = not shippable

/autoresearch:debug

7 investigation techniques:

• Binary search isolation
• Differential analysis
• Minimal reproduction
• Trace execution
• Pattern matching
• Backward reasoning
• Collaborative problem-solving

/autoresearch:fix

Iterative repair loop that auto-detects broken states (tests, types, lint, builds). Loops until zero errors remain. Prioritizes blockers first.

/autoresearch:scenario

Explores edge cases across 12 dimensions:

metric = scenarios*10 + edge_cases*15
       + (dimensions/12)*30
       + unique_actors*5

Flags: --domain --depth --focus --format

/autoresearch:learn

Autonomous documentation engine with 4 modes:

Lifecycle: Scout → Analyze → Map → Generate → Validate → Fix (max 3 retries) → Finalize → Log

Critical Validation Gates

• Scope must resolve to at least 1 real file
• Metric must be mechanical (numeric output)
• Verify command must pass a dry-run on current codebase
• No subjective assessments allowed

Example Session

# User types:
/autoresearch:plan
Goal: Reduce bundle size below 200KB

# Wizard auto-detects:
Stack: React + Webpack
Scope: src/**/*.{ts,tsx}
Metric: Bundle size (KB)
Direction: lower
Verify: npm run build && stat dist/
Guard: npm test

Installation

# Option 1: Plugin marketplace
/plugin marketplace add uditgoenka/autoresearch
/plugin install autoresearch@autoresearch

# Option 2: Manual
git clone github.com/uditgoenka/autoresearch
cp -r claude-plugin/* .claude/

Quick Start Examples

# Improve test coverage overnight
/autoresearch
Goal: Increase test coverage to 90%
Scope: src/**/*.ts
Verify: npm test -- --coverage

# Security audit with auto-fix
/autoresearch:security --diff --fix
Iterations: 15

# Debug a flaky endpoint
/autoresearch:debug
Issue: API returns 500 intermittently
Scope: src/api/**

Real-World Scenario Walkthroughs

The repo includes 10 detailed guides in guide/scenario/:

• Healthcare scheduling optimization
• Real-time messaging platform
• Multi-tenant SaaS onboarding
• Fintech transaction processing
• IoT device management
• E-commerce recommendation engine
• Social media content pipeline
• And more...