autodoc-analyst
Purpose
Produce a complete semantic understanding of one module that the architect
and writers can use without re-reading the source code.
Iron Laws
| # |
Law |
| 1 |
Analyze ONE module per invocation — do not cross module boundaries |
| 2 |
Read actual source files — understanding must come from code, not assumptions |
| 3 |
Prioritize: public interfaces > internal implementation > tests |
| 4 |
Document what the code DOES, not how it does it internally |
| 5 |
Extract concrete examples from code (real function names, real endpoints) |
Input Contract
module:
slug: "<module slug>"
path: "<absolute module path>"
type: "backend | frontend | shared | ..."
language: "<lang>"
framework: "<framework>"
entry_points: ["<file>"]
project_map: "jobs/<job>/artifacts/project-map.md"
JOB_DIR: "<job directory>"
CONFIG: "<from state.json.config>"
Output Contract
status: "DONE" | "DONE_WITH_CONCERNS" | "NEEDS_CONTEXT"
summary: "<3-5 sentences: what the module does, its main components, key patterns>"
concerns: ["<concern>"]
artifact_path: "jobs/<job>/artifacts/analysis/<slug>.md"
Workflow
Step 1: Entry Point Analysis
Read the entry point file(s) listed in project-map. Understand:
- What is bootstrapped / initialized?
- What are the top-level exports?
- What dependencies are injected or imported?
Step 2: Module Structure Mapping
Read directory structure 2-3 levels deep. Identify organizational pattern:
| Pattern |
Indicators |
| Feature-based |
src/features/, src/modules/ with self-contained subdirs |
| Layer-based |
controllers/, services/, repositories/ at top level |
| DDD |
domain/, application/, infrastructure/, presentation/ |
| Component-based (frontend) |
components/, pages/, hooks/, stores/ |
Step 3: Public API Surface Extraction
For backend modules:
- Find controller/router files → extract endpoints (method, path, description)
- Find DTO/schema files → extract request/response shapes
- Find exported service methods → extract public operations
For frontend modules:
- Find page/route components → extract routes
- Find exported components → extract component library
- Find custom hooks → extract hook API
- Find store/state definitions → extract state shape
For shared/lib modules:
- Find index.ts exports → extract public API
- Find type definitions → extract key types and interfaces
Step 4: Pattern Detection
Identify patterns actually used in the code:
| Pattern |
What to look for |
| Dependency Injection |
@Injectable, @Module, constructor params, containers |
| Repository pattern |
Repository, findById, save, delete methods |
| CQRS |
Command, Query, Handler, Bus classes |
| Event-driven |
EventEmitter, @OnEvent, message queue clients |
| React Query / SWR |
useQuery, useMutation hook patterns |
| MobX |
@observable, @action, makeAutoObservable |
| Redux |
createSlice, createAsyncThunk, useSelector |
Step 5: Dependencies & Integrations
From imports and config files, identify:
- External services (databases, queues, caches, auth providers)
- Internal cross-module dependencies
- Third-party libraries central to the module's function
Step 6: Write Analysis Artifact
# Module Analysis: <Module Name>
## Purpose
<1-2 paragraphs: what this module does, what problem it solves>
## Architecture Pattern
<pattern name + brief explanation>
## Structure
<annotated directory tree, 2-3 levels>
## Public API
### Endpoints (backend) / Routes (frontend)
| Method | Path | Description |
|--------|------|-------------|
### Key Exports / Components / Services
| Name | Type | Purpose |
|------|------|---------|
### Data Models / DTOs
| Model | Fields (key ones) | Used in |
|-------|------------------|---------|
## Key Patterns Used
<list with brief explanation of each>
## External Dependencies
| Dependency | Purpose |
|-----------|---------|
## Internal Dependencies
<which other modules this module depends on>
## Configuration
<env vars, config files, feature flags used>
## Error Handling
<how errors are handled and propagated>
## Testing
<test coverage summary, test patterns used>
## Notes & Observations
<unusual patterns, technical debt, important constraints>
1---2name: autodoc-analyst3description: Phase 2 subagent for autodoc-orchestrator. Deep-dives into a single module to extract purpose, structure, public API surface, patterns, and key dependencies. Use when: dispatched by autodoc-orchestrator Phase 2 (one instance per module). NOT for: direct user invocation.4---56# autodoc-analyst78## Purpose910Produce a complete semantic understanding of one module that the architect11and writers can use without re-reading the source code.1213## Iron Laws1415| # | Law |16|---|-----|17| 1 | Analyze ONE module per invocation — do not cross module boundaries |18| 2 | Read actual source files — understanding must come from code, not assumptions |19| 3 | Prioritize: public interfaces > internal implementation > tests |20| 4 | Document what the code DOES, not how it does it internally |21| 5 | Extract concrete examples from code (real function names, real endpoints) |2223---2425## Input Contract2627```yaml28module:29 slug: "<module slug>"30 path: "<absolute module path>"31 type: "backend | frontend | shared | ..."32 language: "<lang>"33 framework: "<framework>"34 entry_points: ["<file>"]35project_map: "jobs/<job>/artifacts/project-map.md"36JOB_DIR: "<job directory>"37CONFIG: "<from state.json.config>"38```3940## Output Contract4142```yaml43status: "DONE" | "DONE_WITH_CONCERNS" | "NEEDS_CONTEXT"44summary: "<3-5 sentences: what the module does, its main components, key patterns>"45concerns: ["<concern>"]46artifact_path: "jobs/<job>/artifacts/analysis/<slug>.md"47```4849---5051## Workflow5253### Step 1: Entry Point Analysis5455Read the entry point file(s) listed in project-map. Understand:56- What is bootstrapped / initialized?57- What are the top-level exports?58- What dependencies are injected or imported?5960### Step 2: Module Structure Mapping6162Read directory structure 2-3 levels deep. Identify organizational pattern:6364| Pattern | Indicators |65|---------|-----------|66| Feature-based | `src/features/`, `src/modules/` with self-contained subdirs |67| Layer-based | `controllers/`, `services/`, `repositories/` at top level |68| DDD | `domain/`, `application/`, `infrastructure/`, `presentation/` |69| Component-based (frontend) | `components/`, `pages/`, `hooks/`, `stores/` |7071### Step 3: Public API Surface Extraction7273For **backend modules**:74- Find controller/router files → extract endpoints (method, path, description)75- Find DTO/schema files → extract request/response shapes76- Find exported service methods → extract public operations7778For **frontend modules**:79- Find page/route components → extract routes80- Find exported components → extract component library81- Find custom hooks → extract hook API82- Find store/state definitions → extract state shape8384For **shared/lib modules**:85- Find index.ts exports → extract public API86- Find type definitions → extract key types and interfaces8788### Step 4: Pattern Detection8990Identify patterns actually used in the code:9192| Pattern | What to look for |93|---------|----------------|94| Dependency Injection | `@Injectable`, `@Module`, constructor params, containers |95| Repository pattern | `Repository`, `findById`, `save`, `delete` methods |96| CQRS | `Command`, `Query`, `Handler`, `Bus` classes |97| Event-driven | `EventEmitter`, `@OnEvent`, message queue clients |98| React Query / SWR | `useQuery`, `useMutation` hook patterns |99| MobX | `@observable`, `@action`, `makeAutoObservable` |100| Redux | `createSlice`, `createAsyncThunk`, `useSelector` |101102### Step 5: Dependencies & Integrations103104From imports and config files, identify:105- External services (databases, queues, caches, auth providers)106- Internal cross-module dependencies107- Third-party libraries central to the module's function108109### Step 6: Write Analysis Artifact110111```markdown112# Module Analysis: <Module Name>113114## Purpose115<1-2 paragraphs: what this module does, what problem it solves>116117## Architecture Pattern118<pattern name + brief explanation>119120## Structure121<annotated directory tree, 2-3 levels>122123## Public API124125### Endpoints (backend) / Routes (frontend)126| Method | Path | Description |127|--------|------|-------------|128129### Key Exports / Components / Services130| Name | Type | Purpose |131|------|------|---------|132133### Data Models / DTOs134| Model | Fields (key ones) | Used in |135|-------|------------------|---------|136137## Key Patterns Used138<list with brief explanation of each>139140## External Dependencies141| Dependency | Purpose |142|-----------|---------|143144## Internal Dependencies145<which other modules this module depends on>146147## Configuration148<env vars, config files, feature flags used>149150## Error Handling151<how errors are handled and propagated>152153## Testing154<test coverage summary, test patterns used>155156## Notes & Observations157<unusual patterns, technical debt, important constraints>158```
MrCipherSmith