skills/autoresearch/references/learn-workflow.md

Learn Workflow — $autoresearch learn

Autonomous codebase documentation engine. Scouts codebase structure, learns patterns and architecture, generates/updates comprehensive documentation — then validates and iteratively improves until docs are accurate.

Core idea: Scout → Generate → Validate → Fix → Repeat until docs match codebase reality.

Trigger

• User invokes $autoresearch learn
• User says "learn this codebase", "generate docs", "document this project", "create documentation", "update docs", "check docs health", "docs status"
• User wants to understand or document an unfamiliar codebase

Loop Support

# Default — auto-detect mode and learn
$autoresearch learn

# Specific mode
$autoresearch learn --mode update

# Bounded iterations for validation-fix loop
$autoresearch learn
Iterations: 5

# Scoped learning
$autoresearch learn --scope src/api/**

# Selective single-doc update
$autoresearch learn --mode update --file system-architecture.md

PREREQUISITE: Interactive Setup (when invoked without flags)

CRITICAL — BLOCKING PREREQUISITE: If invoked without --mode or sufficient inline context, you MUST use direct prompting to gather config BEFORE proceeding to Phase 1.

TOOL AVAILABILITY: direct prompting may be a deferred tool. If calling it fails, use ToolSearch to fetch the schema first, then retry. NEVER skip setup because of tool issues.

Pre-scan (before asking questions)

Detect project state for smart defaults:

1. Does docs/ exist? How many .md files? ls docs/*.md 2>/dev/null | wc -l
2. Project type indicators: ls package.json Cargo.toml go.mod pyproject.toml *.sln 2>/dev/null
3. Staleness: git log -1 --format='%ci' -- docs/ 2>/dev/null vs git log -1 --format='%ci' 2>/dev/null
4. Scale: find . -type f -not -path './.git/*' -not -path '*/node_modules/*' | wc -l

Questions (single direct prompting call — 4 questions)

#	Header	Question	Options (from pre-scan)
1	Mode	"What documentation operation?"	"Init — learn codebase from scratch, generate all docs (Recommended)" (if 0 docs), "Update — learn what changed, refresh docs (Recommended)" (if docs exist), "Check — read-only health assessment", "Summarize — quick codebase summary"
2	Scope	"Which parts of the codebase should I learn?"	Detected top-level dirs as globs + "Everything (entire codebase)"
3	Depth	"How comprehensive should documentation be?"	"Quick — overview + summary only", "Standard — all core docs (Recommended)", "Deep — comprehensive with deployment, design, API reference"
4	Launch	"Ready to start learning?"	"Launch", "Edit config", "Cancel"

Skip condition: If user provides --mode + --scope or --depth → skip setup entirely.

State-aware defaults:

• docs/ has 0 files → default Mode = Init
• docs/ has files → default Mode = Update
• User says "check" / "health" → Mode = Check
• User says "summarize" / "summary" → Mode = Summarize

Cancel handling: If user selects "Cancel" → exit: "Learning cancelled. Run $autoresearch learn when ready."

Architecture

$autoresearch learn
  ├── Phase 1: Scout — Parallel codebase reconnaissance
  ├── Phase 2: Analyze — Structure detection + project type classification
  ├── Phase 3: Map — Dynamic doc discovery + gap analysis
  ├── Phase 4: Generate — Spawn docs-manager with structured prompt
  ├── Phase 5: Validate — Mechanical verification (refs, links, completeness)
  ├── Phase 6: Fix — Re-generate failed docs with validation feedback (LOOP)
  ├── Phase 7: Finalize — Size check, inventory, git diff summary
  └── Phase 8: Log — Record results to learn-results.tsv

Phase 1: Scout — Parallel Codebase Reconnaissance

Mode-specific:

• Init / Update / Summarize (with --scan): Execute full scout
• Check: SKIP entirely (read-only mode — jump to Phase 2)
• Summarize (without --scan): SKIP (use existing docs only — jump to Phase 3)

Steps:

1. Scan codebase, calculate files/LOC per directory
2. Exclusion list: .claude, .opencode, .git, node_modules, __pycache__, secrets, vendor, dist, build, .next, .nuxt, coverage, generated, *.min.js, .cache, .tmp
   • Test directories (tests, __tests__) are NOT excluded — scouts should scan test structure (file patterns, frameworks, fixtures) for testing-guide.md generation. Scouts read test metadata, not individual test logic.
3. Scale awareness:
   • Count total files: find . -type f -not -path './.git/*' -not -path '*/node_modules/*' | wc -l
   • If >5000 files: increase scout parallelism, add summarization step for reports
   • If >10000 files: warn user, suggest scoping with --scope
4. Activate ck:scout skill for parallel codebase exploration
5. Scout validation: After scouts return, verify reports contain meaningful data. If all scouts return empty/minimal: STOP → warn: "Scout found minimal code. Verify project has source files or adjust scope with --scope."
6. Monorepo detection: Check for workspaces in package.json, lerna.json, pnpm-workspace.yaml, Cargo.toml with [workspace]. If detected → note workspace structure in context.
7. Merge scout reports. Estimate token count: total_report_lines × 5. If >100K estimated tokens → summarize merged reports before passing downstream.

Incremental scouting (planned):

• If learn/ output directory exists from a previous run, read scout-context.md for cached context
• Compare git log --oneline since the cached scout's commit hash
• If <20 files changed: use cached scout + targeted re-scout of changed dirs only
• If >20 files changed or no cache: full scout as normal
• Note: This is optimization scaffolding — full scout is always the fallback

Update mode optimization — git-diff scoping:

• Run git diff --name-only HEAD~10 -- '*.ts' '*.js' '*.py' '*.go' '*.rs' '*.java' '*.rb' 2>/dev/null | head -30
• If changes concentrated in <3 directories → hint scouts to prioritize those areas
• Additive: scouts still cover full codebase, but changed areas get extra attention

Output: ✓ Phase 1: Scouted — [N] files, [M] directories, [K] LOC analyzed

Phase 2: Analyze — Structure Detection + Classification

1. Detect project type from scout reports: library, web app, CLI tool, API server, infrastructure, monorepo
2. Detect tech stack: languages, frameworks, build tools, test runners
3. Detect existing doc structure: ls docs/*.md 2>/dev/null
4. Calculate staleness gap:
   • Last code commit: git log -1 --format='%ci' -- $(git ls-files '*.ts' '*.js' '*.py' '*.go' '*.rs' '*.java' '*.rb' | head -1) 2>/dev/null
   • Last docs commit: git log -1 --format='%ci' -- docs/ 2>/dev/null
   • Gap in days between the two

Mode-specific behavior:

• Init: Project type determines which docs to create (Phase 3)
• Update: Staleness + changed areas determine update priority
• Check: Staleness + validation = health report (Phase 5 outputs report, then STOP)
• Summarize: Project type shapes summary sections

Output: ✓ Phase 2: Analyzed — [type] project, [N] existing docs, staleness: [X] days

Phase 3: Map — Dynamic Doc Discovery + Gap Analysis

Init Mode — Determine Docs to Create

Always create:

• docs/project-overview-pdr.md — Project overview and PDR
• docs/codebase-summary.md — Codebase summary with file inventory
• docs/code-standards.md — Codebase structure and code standards
• docs/system-architecture.md — System architecture
• README.md at root (create or update, max 300 lines)

Conditional creation (based on project signals from Phase 2):

• docs/deployment-guide.md — if Dockerfile, CI config (.github/workflows, .gitlab-ci.yml), deploy scripts, or cloud config detected
• docs/design-guidelines.md — if UI components, CSS/style files, or frontend framework detected
• docs/project-roadmap.md — if project has milestones, issues, or TODO tracking
• docs/api-reference.md — if API routes, controllers, resolvers, or OpenAPI/Swagger specs detected. Include endpoint catalog with method, path, description, request/response shapes
• docs/testing-guide.md — if test directories (tests/, __tests__/, spec/), test config (jest.config, vitest.config, pytest.ini), or CI test steps detected. Document test strategy, how to run tests, coverage expectations, fixture patterns
• docs/configuration-guide.md — if .env.example, config/ directory, feature flags, or environment-specific configs detected. Document all env vars, config keys, and their purpose
• docs/changelog.md — generate from git log --oneline --no-merges -50 using conventional commit parsing. Group by type (feat, fix, docs, refactor). Only on init; update mode appends new entries

Update Mode — Read Existing Docs in Parallel

You (main agent) must spawn readers — subagents cannot spawn subagents.

1. Discover docs dynamically: ls docs/*.md 2>/dev/null
2. Filter: *.md files only — skip binary files (.pdf, .png, .drawio)
3. Count + LOC: wc -l docs/*.md 2>/dev/null | sort -rn
4. Strategy by count:
   • 0 files: Warn via direct prompting: "No docs found. Switch to init mode? [yes/cancel]". If yes → restart as init. If cancel → STOP.
   • 1-3 files: Skip parallel reading, docs-manager reads directly
   • 4-6 files: Spawn 2-3 Explore agents
   • 7+ files: Spawn 4-5 Explore agents (max 5)
5. Context budget: If total docs LOC >5000 → warn in docs-manager prompt about summarization
6. Distribute by LOC (larger files get dedicated agent)
7. Explore agent output contract:

   "Read these markdown docs. For each file return EXACTLY this format:
   ## {filename}
   **Purpose:** one-line summary
   **Key sections:** bullet list of main headings
   **Needs update:** areas likely stale or incomplete based on content
   
   Files: {list}"
   

8. Merge Explore results into context

Selective update: If --file <name> provided → scope to that single file only, skip parallel reading.

Diff-based doc targeting (update mode optimization):

• After git-diff scoping identifies changed source files, map them to affected docs:
  • src/api/** changes → prioritize api-reference.md, system-architecture.md
  • src/components/** changes → prioritize design-guidelines.md
  • tests/** changes → prioritize testing-guide.md
  • package.json / dependency changes → prioritize codebase-summary.md (dependency section)
  • Config file changes → prioritize configuration-guide.md
  • New files in src/ → prioritize code-standards.md, system-architecture.md
• Instruct docs-manager to focus regeneration effort on mapped docs, light-touch others
• This is advisory, not exclusive — all docs still get reviewed, mapped ones get deeper updates

Check Mode — Inventory Only

1. List all docs with LOC: wc -l docs/*.md 2>/dev/null | sort -rn
2. Get last modified date per file: stat -f '%Sm' -t '%Y-%m-%d' docs/*.md 2>/dev/null (macOS) or stat -c '%y' docs/*.md 2>/dev/null (Linux)
3. Report which standard doc types exist vs missing (informational, not prescriptive)
4. → Proceed directly to Phase 5 for validation (skip Phase 4)

Summarize Mode — Read Summary Context

1. Read docs/codebase-summary.md if exists (will be created if missing)
2. If --scan flag: use merged scout reports from Phase 1
3. If no --scan: read existing docs/*.md for cross-reference context only
4. If --topics <list> provided: focus on those topics

Output: ✓ Phase 3: Mapped — [N] docs to create/update, [M] gaps identified

Phase 4: Generate — Spawn docs-manager Agent

CRITICAL: Spawn docs-manager agent via Task tool with all gathered context. Do not wait for user input.

Mode-specific:

• Init: Create all docs determined in Phase 3
• Update: Update all discovered docs/*.md + user's custom docs
• Check: SKIP (read-only — jump to Phase 5)
• Summarize: Create/update docs/codebase-summary.md only

Pre-generation

Ensure target directory exists: mkdir -p docs/

docs-manager Prompt Template

Include ALL of the following in the agent prompt:

1. Merged scout reports (summarized if >100K est. tokens)
2. Doc reading results (from Phase 3 Explore agents — Update mode only)
3. Git-diff hints (from Phase 1 — Update mode only)
4. Project type + tech stack (from Phase 2)
5. Monorepo structure (if detected in Phase 1)
6. File list: Explicit list of all docs to create/update
7. Constraint: Each doc file must stay under {docs.maxLoc} lines (default: 800)
8. Constraint: README must stay under 300 lines
9. Instruction (Init): "Adapt doc content to the detected project type. Do not generate generic boilerplate."
10. Instruction (Update): "Preserve the user's custom doc structure and content. Update information, don't reorganize."
11. Instruction (Mermaid): "Include Mermaid diagrams in system-architecture.md — at minimum: component relationship diagram, data flow diagram, and service dependency graph. Use ```mermaid code blocks. For API projects, add request flow diagrams. For frontends, add component hierarchy."
12. Instruction (Dependencies): "In codebase-summary.md, include a Key Dependencies section listing the top 10-15 dependencies with: package name, version, purpose (one line), and whether it's a runtime or dev dependency. Parse from package.json/requirements.txt/Cargo.toml."
13. Instruction (Cross-references): "Add 'See also' links between related docs. Example: system-architecture.md should link to api-reference.md for endpoint details, code-standards.md should link to testing-guide.md for test patterns. Use relative markdown links: [API Reference](api-reference.md)."
14. Instruction (Format): If --format flag is set, output in the specified format instead of Markdown. Currently supported: markdown (default). Planned: confluence, rst, html.

Additional Requests Passthrough

<additional_requests>
  $ARGUMENTS (with flags stripped)
</additional_requests>

Output: ✓ Phase 4: Generated — [N] docs created/updated

Phase 5: Validate — Mechanical Verification

Post-generation Inventory

1. List files: ls docs/*.md 2>/dev/null
2. Compare against expected files (from Phase 3 mapping)
3. Flag: missing expected files, unexpected new files (informational)

Script Validation

1. Check script exists: [ -f "$HOME/.claude/scripts/validate-docs.cjs" ]
2. If exists: run node $HOME/.claude/scripts/validate-docs.cjs docs/
3. Checks performed: code references exist, internal links resolve, config keys are real, markdown syntax valid
4. Display validation report (warnings listed)
5. If script missing: skip with note "Validation script not found — skipping script validation"

Size Check

1. wc -l docs/*.md README.md 2>/dev/null | sort -rn
2. Use docs.maxLoc from session context (default: 800)
3. Flag files exceeding limit with delta (e.g., "system-architecture.md: 923 lines, 123 over limit")

Calculate Metric

validation_score = (docs_passing_all_checks / total_docs) × 100

Decision:

• 100% → Skip Phase 6, proceed to Phase 7
• <100% → Proceed to Phase 6 (fix loop)
• --no-fix flag set → Accept current state, proceed to Phase 7

Check Mode: Health Report (then STOP)

If mode is check, output health report and stop:

=== Documentation Health Report ===
Status: [Healthy | Needs attention | Stale]

Files: [N] docs found, [M] total LOC
Staleness: [Fresh (<7d) | Stale (7-30d) | Very stale (>30d)] — [X] days behind code

| File | LOC | Last Modified | Over Limit? | Valid? |
|------|-----|--------------|-------------|--------|
| ... | ... | ... | ... | ... |

Validation: [N] warnings
[list warnings if any]

Coverage: [list present vs missing standard doc types]

Recommendation: [action to take]

STOP after check report. Do not proceed to Phase 6-8.

Output: ✓ Phase 5: Validated — [N]% pass rate, [M] warnings

Phase 6: Fix — Validation-Fix Loop (AUTORESEARCH CORE)

Only entered if validation_score < 100% AND --no-fix is NOT set.

This is the core autoresearch iteration pattern applied to documentation.

Fix Loop

FIX_ITERATION = 0
MAX_FIX_ITERATIONS = 3

LOOP:
  1. Collect validation failures: (file, issue_type, severity, details)
  2. Re-spawn docs-manager with:
     - Original generation context (from Phase 4)
     - Validation report with SPECIFIC issues to fix
     - Instruction: "Fix ONLY the flagged issues below. Do not rewrite entire documents."
  3. Re-run Phase 5 validation checks
  4. FIX_ITERATION += 1
  5. DECIDE:
     - validation_score = 100% → KEEP, proceed to Phase 7
     - validation_score improved AND FIX_ITERATION < MAX → RETRY (loop)
     - validation_score NOT improved OR FIX_ITERATION >= MAX → ACCEPT with warnings, proceed to Phase 7
  6. Log fix attempt to results

Fix Strategies by Issue Type

Issue	Fix Strategy
Broken code reference	Grep codebase for correct path/name, update ref
Broken internal link	Check docs/ for correct filename, fix link
Invalid config key	Search project config files, correct key name
Oversized file	Split into focused sub-docs or trim redundant sections
Missing required section	Generate section from scout context

Output: ✓ Phase 6: Fixed — [N] issues resolved in [M] iterations or ⚠ Phase 6: [N] warnings remaining after 3 attempts

Phase 7: Finalize — Inventory + Summary

1. Git diff summary: git diff --stat docs/ README.md 2>/dev/null
2. Report:
   • Files created (new)
   • Files updated (changed)
   • Files unchanged
   • Total docs count + LOC
3. Size compliance: List any files still over limit
4. Summarize mode special: If codebase-summary.md exceeds maxLoc → trim to essential sections

Output: ✓ Phase 7: Finalized — [N] files ready

Phase 8: Log — Record Results

Results File

Append to learn-results.tsv in the output directory:

iteration	mode	docs_generated	docs_updated	validation_score	fix_iterations	learn_score	duration_s
1	init	7	0	100	1	95	45
2	update	0	5	85	2	78	62

Progress Report (every 5 iterations if bounded)

=== Learn Progress (iteration N) ===
Docs generated: [X] | Docs updated: [Y]
Validation score: [Z]% (target: 100%)
Fix iterations used: [A]/[B]
Coverage: [C]/[D] core docs present
Learn score: [S]

Final Summary (on completion or iteration limit)

Write summary.md to output directory:

• Mode used, scope, depth
• Baseline state → final state
• Docs created/updated with one-line descriptions
• Validation score trajectory
• Learn score
• Remaining warnings (if any)
• Recommended next steps

Flags

Flag	Purpose	Default
--mode <mode>	Operation: init, update, check, summarize	Auto-detect from docs/ state
--scope <glob>	Limit codebase learning to specific dirs/files	Everything
--depth <level>	Doc comprehensiveness: quick, standard, deep	standard
--scan	Force fresh codebase scout (summarize mode)	false
--topics <list>	Focus summarize on specific topics	all
--file <name>	Selective update — target single doc file	all docs
--no-fix	Skip validation-fix loop (accept first-pass)	false
--format <fmt>	Output format: markdown (default). Planned: confluence, rst, html	markdown
--chain <targets>	Chain to downstream tool(s) after completion. Comma-separated for multi-chain. Spaces after commas tolerated. --chain debug or --chain scenario,debug,fix	none

Composite Metric

learn_score = (validation_score% × 0.5)
            + (docs_coverage% × 0.3)
            + (size_compliance% × 0.2)

Where:
  validation_score = passing_docs / total_docs × 100
  docs_coverage = existing_core_docs / expected_core_docs × 100
  size_compliance = docs_under_limit / total_docs × 100

Score	Rating
90-100	Excellent — docs are comprehensive and valid
70-89	Good — minor gaps or warnings
<70	Needs work — significant gaps or validation failures

What NOT to Do — Anti-Patterns

Anti-Pattern	Why Wrong	Do This Instead
Generate docs without scouting first	Produces hallucinated content disconnected from reality	Always scout → learn actual structure → then generate
Hardcode expected doc file list	Misses user's custom docs, breaks when files renamed	Dynamic discovery: scan docs/*.md at runtime
Skip validation on freshly generated docs	"New docs can't have errors" is wrong — LLMs hallucinate references	Always validate. Init and update both run Phase 5
Retry validation-fix loop indefinitely	Diminishing returns after 3 attempts, wastes tokens	Cap at 3 retries, accept with warnings
Scout entire monorepo without scoping	Context overflow, massive token waste	Detect monorepo early, suggest --scope to user
Generate deployment-guide.md for a library	Irrelevant docs erode trust in all generated content	Create conditional docs only when project signals detected
Overwrite user's custom docs on update	Destroys manual work, violates trust	Discover custom docs, preserve their structure, update content only
Run check mode then modify files	Check is strictly read-only diagnostic	Use update mode for modifications

Chain Conversion

When --chain is specified, learn passes results forward after Phase 8 completes. Output includes: documentation files, scout context, validation results.

--chain plan

Documentation gaps or improvement areas revealed by learning — plan implementation to address them.

$autoresearch plan
Goal: Address documentation-revealed gaps — {top gap from validation report}
Context: Learn run completed, validation score: {validation_score}%, coverage: {docs_coverage}%
Scope: {source files related to documentation gaps}

--chain debug

Documentation gaps reveal potential bug areas — investigate before they surface in production.

$autoresearch debug
Scope: {source files with undocumented or stale-doc areas}
Symptom: Documentation gaps indicate untested or undocumented behavior in {area}
Context: Learn validation flagged: {validation_warnings}

--chain scenario

Architecture knowledge from learning → explore edge cases in the documented system.

$autoresearch scenario
Scenario: {key architectural pattern discovered during learn} — explore edge cases
Domain: software
Depth: standard

--chain predict

Codebase patterns discovered during learning → predict issues before they emerge.

$autoresearch predict
Scope: {scope from learn run}
Goal: Predict issues based on patterns discovered during documentation: {top patterns}
Depth: standard

--chain security

Architecture knowledge from learning → audit security implications of documented patterns.

$autoresearch security
Scope: {scope from learn run}
Focus: Security audit informed by documentation: {auth, data handling, and API patterns documented}

--chain fix

Documentation validation failures point to real issues — fix them directly.

$autoresearch fix
Target: {top validation failure description}
Scope: {files flagged in validation report}
Context: Learn validation identified: {specific broken references or invalid links}

--chain reason

Complex patterns discovered in documentation → adversarial refinement of improvement approach.

$autoresearch reason
Task: Reason about best approach to address: {top documentation finding}
Domain: software
Context: Learn run completed with validation score {validation_score}%

--chain ship

Documentation complete and validated → ship docs as a PR or publish them.

$autoresearch ship
Type: code-pr
Target: docs/
Context: Learn run produced {N} docs, validation score: {validation_score}%

--chain probe

Knowledge gaps surfaced during learning → interrogate requirements before the next implementation cycle.

$autoresearch probe
Topic: Requirements and constraints behind: {top undocumented or ambiguous area}
Context: Learn discovered gaps in: {areas from validation report}

Multi-Chain Execution

--chain plan,scenario,fix executes sequentially:

1. Write summary.md after Phase 8 completes
2. Launch first chain target with learn results as context
3. Each stage's output feeds the next via handoff
4. All targets receive: mode used, validation score, docs created/updated, scout context

Empirical evidence rule: Downstream loop results ALWAYS override upstream findings. If a fix or debug loop disproves a documentation claim, log: Learn finding [X] REVISED by empirical [tool] loop — [evidence]. Do NOT revert to pre-loop documentation.

Output Directory

learn/{YYMMDD}-{HHMM}-{slug}/
├── learn-results.tsv     # iteration log (tsv)
├── summary.md            # executive summary
├── validation-report.md  # last validation output
└── scout-context.md      # merged scout reports (reference)

Generated/updated docs go to docs/ directly — not the learn/ output folder. learn/ is the audit trail — records what was learned, validated, and fixed.

Chaining Patterns

# Learn codebase, then security audit
$autoresearch learn --mode init
$autoresearch security

# Learn changes, then predict issues
$autoresearch learn --mode update
$autoresearch predict --scope src/**

# Check health, update if stale
$autoresearch learn --mode check
# If report says "Stale" →
$autoresearch learn --mode update

# Learn then ship docs as PR
$autoresearch learn --mode update
$autoresearch ship --type code-pr

# Full quality pipeline
$autoresearch learn --mode init
$autoresearch scenario --domain software
$autoresearch security
$autoresearch ship