Autoresearch

Claude Autoresearch — Autonomous Goal-directed Iteration

Inspired by Karpathy's autoresearch. Applies constraint-driven autonomous iteration to ANY work — not just ML research.

Core idea: You are an autonomous agent. Modify → Verify → Keep/Discard → Repeat.

MANDATORY: Interactive Setup Gate

CRITICAL — READ THIS FIRST BEFORE ANY ACTION:

For ALL commands (/autoresearch, /autoresearch:plan, /autoresearch:debug, /autoresearch:fix, /autoresearch:security, /autoresearch:ship, /autoresearch:scenario, /autoresearch:predict, /autoresearch:learn):

1. Check if the user provided ALL required context inline (Goal, Scope, Metric, flags, etc.)
2. If ANY required context is missing → you MUST use AskUserQuestion to collect it BEFORE proceeding to any execution phase. DO NOT skip this step. DO NOT proceed without user input.
3. Each subcommand's reference file has an "Interactive Setup" section — follow it exactly when context is missing.

YOU MUST NOT start any loop, phase, or execution without completing interactive setup when context is missing. This is a BLOCKING prerequisite.

Subcommands

/autoresearch:security — Autonomous Security Audit

Runs a comprehensive security audit using the autoresearch loop pattern. Generates a full STRIDE threat model, maps attack surfaces, then iteratively tests each vulnerability vector — logging findings with severity, OWASP category, and code evidence.

Load: references/security-workflow.md for full protocol.

What it does:

1. Codebase Reconnaissance — scans tech stack, dependencies, configs, API routes
2. Asset Identification — catalogs data stores, auth systems, external services, user inputs
3. Trust Boundary Mapping — browser↔server, public↔authenticated, user↔admin, CI/CD↔prod
4. STRIDE Threat Model — Spoofing, Tampering, Repudiation, Info Disclosure, DoS, Elevation of Privilege
5. Attack Surface Map — entry points, data flows, abuse paths
6. Autonomous Loop — iteratively tests each vector, validates with code evidence, logs findings
7. Final Report — severity-ranked findings with mitigations, coverage matrix, iteration log

Key behaviors:

• Follows red-team adversarial mindset (Security Adversary, Supply Chain, Insider Threat, Infra Attacker)
• Every finding requires code evidence (file:line + attack scenario) — no theoretical fluff
• Tracks OWASP Top 10 + STRIDE coverage, prints coverage summary every 5 iterations
• Composite metric: (owasp_tested/10)*50 + (stride_tested/6)*30 + min(findings, 20) — higher is better
• Creates security/{YYMMDD}-{HHMM}-{audit-slug}/ folder with structured reports: overview.md, threat-model.md, attack-surface-map.md, findings.md, owasp-coverage.md, dependency-audit.md, recommendations.md, security-audit-results.tsv

Flags:

Usage:

# Unlimited — keep finding vulnerabilities until interrupted
/autoresearch:security

# Bounded — exactly 10 security sweep iterations
/autoresearch:security
Iterations: 10

# With focused scope
/autoresearch:security
Scope: src/api/**/*.ts, src/middleware/**/*.ts
Focus: authentication and authorization flows

# Delta mode — only audit changed files since last audit
/autoresearch:security --diff

# Auto-fix confirmed Critical/High findings after audit
/autoresearch:security --fix
Iterations: 15

# CI/CD gate — fail pipeline if any Critical findings
/autoresearch:security --fail-on critical
Iterations: 10

# Combined — delta audit + fix + gate
/autoresearch:security --diff --fix --fail-on critical
Iterations: 15

Inspired by:

• Strix — AI-powered security testing with proof-of-concept validation
• /plan red-team — adversarial review with hostile reviewer personas
• OWASP Top 10 (2021) — industry-standard vulnerability taxonomy
• STRIDE — Microsoft's threat modeling framework

/autoresearch:ship — Universal Shipping Workflow

Ship anything — code, content, marketing, sales, research, or design — through a structured 8-phase workflow that applies autoresearch loop principles to the last mile.

Load: references/ship-workflow.md for full protocol.

What it does:

1. Identify — auto-detect what you're shipping (code PR, deployment, blog post, email campaign, sales deck, research paper, design assets)
2. Inventory — assess current state and readiness gaps
3. Checklist — generate domain-specific pre-ship gates (all mechanically verifiable)
4. Prepare — autoresearch loop to fix failing checklist items until 100% pass
5. Dry-run — simulate the ship action without side effects
6. Ship — execute the actual delivery (merge, deploy, publish, send)
7. Verify — post-ship health check confirms it landed
8. Log — record shipment to ship-log.tsv for traceability

Supported shipment types:

Flags:

Usage:

# Auto-detect and ship (interactive)
/autoresearch:ship

# Ship code PR with auto-approve
/autoresearch:ship --auto

# Dry-run a deployment before going live
/autoresearch:ship --type deployment --dry-run

# Ship with post-deployment monitoring
/autoresearch:ship --monitor 10

# Prepare iteratively then ship
/autoresearch:ship
Iterations: 5

# Just check if something is ready to ship
/autoresearch:ship --checklist-only

# Ship a blog post
/autoresearch:ship
Target: content/blog/my-new-post.md
Type: content

# Ship a sales deck
/autoresearch:ship --type sales
Target: decks/q1-proposal.pdf

# Rollback a bad deployment
/autoresearch:ship --rollback

Composite metric (for bounded loops):

ship_score = (checklist_passing / checklist_total) * 80
           + (dry_run_passed ? 15 : 0)
           + (no_blockers ? 5 : 0)

Score of 100 = fully ready. Below 80 = not shippable.

Output directory: Creates ship/{YYMMDD}-{HHMM}-{ship-slug}/ with checklist.md, ship-log.tsv, summary.md.

/autoresearch:scenario — Scenario-Driven Use Case Generator

Autonomous scenario exploration engine that generates, expands, and stress-tests use cases from a seed scenario. Discovers edge cases, failure modes, and derivative scenarios that manual analysis misses.

Load: references/scenario-workflow.md for full protocol.

What it does:

1. Seed Analysis — parse scenario, identify actors, goals, preconditions, components
2. Decomposition — break into 12 exploration dimensions (happy path, error, edge case, abuse, scale, concurrent, temporal, data variation, permission, integration, recovery, state transition)
3. Situation Generation — create one concrete situation per iteration from unexplored dimensions
4. Classification — deduplicate (new/variant/duplicate/out-of-scope/low-value)
5. Expansion — derive edge cases, what-ifs, failure modes from each kept situation
6. Logging — record to scenario-results.tsv with dimension, severity, classification
7. Repeat — pick next unexplored dimension/combination, iterate

Key behaviors:

• Adaptive interactive setup: 4-8 questions based on how much context the user provides
• 12 exploration dimensions ensure comprehensive coverage
• Domain-specific templates (software, product, business, security, marketing)
• Every situation requires concrete trigger, flow, and expected outcome — no vague "something goes wrong"
• Composite metric: scenarios_generated*10 + edge_cases_found*15 + (dimensions_covered/12)*30 + unique_actors*5
• Creates scenario/{YYMMDD}-{HHMM}-{slug}/ with: scenarios.md, use-cases.md, edge-cases.md, scenario-results.tsv, summary.md

Flags:

Usage:

# Unlimited — keep exploring until interrupted
/autoresearch:scenario

# Bounded with context
/autoresearch:scenario
Scenario: User attempts checkout with multiple payment methods
Domain: software
Depth: standard
Iterations: 25

# Quick edge case scan
/autoresearch:scenario --depth shallow --focus edge-cases
Scenario: File upload feature for profile pictures

# Security-focused
/autoresearch:scenario --domain security
Scenario: OAuth2 login flow with third-party providers
Iterations: 30

# Generate test scenarios
/autoresearch:scenario --format test-scenarios --domain software
Scenario: REST API pagination with filtering and sorting

/autoresearch:predict — Multi-Persona Swarm Prediction

Multi-perspective code analysis using swarm intelligence principles. Simulates 3-5 expert personas (Architect, Security Analyst, Performance Engineer, Reliability Engineer, Devil's Advocate) that independently analyze code, debate findings, and reach consensus — all within Claude's native context. Zero external dependencies.

Load: references/predict-workflow.md for full protocol.

What it does:

1. Codebase Reconnaissance — scan files, extract entities, map dependencies into knowledge .md files
2. Persona Generation — create 3-5 expert personas from codebase context
3. Independent Analysis — each persona analyzes code from their unique perspective
4. Structured Debate — 1-2 rounds of cross-examination with mandatory Devil's Advocate dissent
5. Consensus — synthesizer aggregates findings with confidence scores + anti-herd check
6. Knowledge Output — write predict/ folder with codebase-analysis.md, dependency-map.md, component-clusters.md
7. Report — generate findings.md, hypothesis-queue.md, overview.md
8. Handoff — write handoff.json for optional --chain to debug/security/fix/ship/scenario

Key behaviors:

• File-based knowledge representation: .md files ARE the knowledge graph, zero external deps
• Git-hash stamping: every output embeds commit SHA for staleness detection
• Incremental updates: only re-analyzes files changed since last run
• Anti-herd mechanism: Devil's Advocate mandatory, groupthink detection via flip rate + entropy
• Empirical evidence always trumps swarm prediction when chained with autoresearch loop
• Composite metric: findings_confirmed*15 + findings_probable*8 + minority_preserved*3 + (personas/total)*20 + (rounds/planned)*10 + anti_herd_passed*5
• Creates predict/{YYMMDD}-{HHMM}-{slug}/ folder with: overview.md, codebase-analysis.md, dependency-map.md, component-clusters.md, persona-debates.md, hypothesis-queue.md, findings.md, predict-results.tsv, handoff.json

Flags:

Usage:

# Standard analysis
/autoresearch:predict
Scope: src/**/*.ts
Goal: Find reliability issues

# Quick security scan
/autoresearch:predict --depth shallow --chain security
Scope: src/api/**

# Deep analysis with adversarial debate
/autoresearch:predict --depth deep --adversarial
Goal: Pre-deployment quality audit

# CI/CD gate
/autoresearch:predict --fail-on critical --budget 20
Scope: src/**
Iterations: 1

# Chain to debug for hypothesis-driven investigation
/autoresearch:predict --chain debug
Scope: src/auth/**
Goal: Investigate intermittent 500 errors

# Multi-chain: predict → scenario → debug → fix (sequential pipeline)
/autoresearch:predict --chain scenario,debug,fix
Scope: src/**
Goal: Full quality pipeline for new feature

/autoresearch:learn — Autonomous Codebase Documentation Engine

Scouts codebase structure, learns patterns and architecture, generates/updates comprehensive documentation — then validates and iteratively improves until docs match codebase reality.

Load: references/learn-workflow.md for full protocol.

What it does:

1. Scout — parallel codebase reconnaissance with scale awareness and monorepo detection
2. Analyze — project type classification, tech stack detection, staleness measurement
3. Map — dynamic doc discovery (docs/*.md), gap analysis, conditional doc selection
4. Generate — spawn docs-manager with structured prompt template and full context
5. Validate — mechanical verification (code refs, links, completeness, size compliance)
6. Fix — validation-fix loop: re-generate failed docs with feedback (max 3 retries)
7. Finalize — inventory check, git diff summary, size compliance
8. Log — record results to learn-results.tsv

4 Modes:

Key behaviors:

• Fully dynamic doc discovery — scans docs/*.md, no hardcoded file lists
• State-aware mode detection — auto-selects init/update based on docs/ state
• Project-type-adaptive — creates deployment-guide.md only if deployment config exists
• Validation-fix loop capped at 3 retries — escalates to user if unresolved
• Scale-aware scouting — adjusts parallelism for 5k+ file codebases
• Composite metric: learn_score = validation%×0.5 + coverage%×0.3 + size_compliance%×0.2
• Creates learn/{YYMMDD}-{HHMM}-{slug}/ with: learn-results.tsv, summary.md, validation-report.md, scout-context.md

Flags:

Usage:

# Auto-detect mode and learn
/autoresearch:learn

# Initialize docs for new project
/autoresearch:learn --mode init --depth deep

# Update docs after changes
/autoresearch:learn --mode update
Iterations: 3

# Read-only health check
/autoresearch:learn --mode check

# Quick summary
/autoresearch:learn --mode summarize --scan

# Selective update of one doc
/autoresearch:learn --mode update --file system-architecture.md

# Scoped learning
/autoresearch:learn --scope src/api/**
Iterations: 5