Deep domain analysis to generate or update documentation
Performs deep analysis of a domain to generate comprehensive documentation, detect patterns, identify issues, and update schema. Use when exploring codebase structure, updating stale docs, investigating drift, or preparing for refactoring.
/plugin marketplace add olioapps/claude-code-plugins/plugin install codebase-documentation@olio-plugins<domain-name> [--compare] [--update-schema] [--update-docs] [--interactive] [--verbose] [--quiet] [--focus <area>]Perform deep analysis of a specific domain to generate detailed documentation, identify patterns, and detect organizational issues.
Arguments: /codebase-documentation:map-domain <domain-name> [FLAGS]
Required:
Optional Flags:
Use this command to:
If domain name matches schema entry:
.claude/docs/codebase-schema.yamldomain.location as target pathIf domain name is a path (starts with /, ./, or contains /):
Error cases:
Thoroughly explore the domain using Read, Glob, and Grep tools.
# List all files recursively
Glob: {domain_location}/**/*
# Count by file type
Glob: {domain_location}/**/*.{ext} for common extensions
# Find subdirectories
Glob: {domain_location}/*/
Collect:
File Naming Patterns: Sample 10-15 files across directory and identify:
PascalCase, camelCase, kebab-case, snake_case.service.ts, .controller.js, .model.ts, .test.tsuse-, with-, get-, _Directory Organization: Classify as:
Module Structure:
For 5-10 representative files, Read and extract:
Dependency Analysis:
# Find test files
Glob: {domain_location}/**/*.test.{js,ts,jsx,tsx}
Glob: {domain_location}/**/*.spec.{js,ts,jsx,tsx}
Glob: {domain_location}/__tests__/**/*
Calculate:
# Find README files
Glob: {domain_location}/**/README.md
# Find inline docs (sample)
Grep: /\*\*/ in sample files for JSDoc/TSDoc
Assess:
useAuth hook, getAuth util, withAuth HOC in different directoriesCreate comprehensive markdown report:
# Domain Map: {domain_name}
> **Generated**: {ISO 8601 timestamp}
> **Purpose**: {from schema if exists, else inferred from analysis}
---
## Summary
| Metric | Value |
|--------|-------|
| **Location** | `{path}` |
| **Total Files** | {X} files |
| **Directories** | {X} directories |
| **Approx. Lines** | ~{XX,XXX} |
| **File Types** | {list with counts} |
| **Test Coverage** | {X}/{Y} files ({Z}%) |
| **Last Modified** | {most recent file date if detectable} |
---
## Directory Structure
{domain}/ ├── subdirectory1/ ({X} files) │ ├── file1.ext │ └── file2.ext ├── subdirectory2/ ({X} files) │ └── ... └── README.md
---
## File Categorization
{Organize files by purpose, structure, or type - adapt to what makes sense for this domain}
### {Category 1} ({X} files)
| File | Purpose | Exports | Dependencies |
|------|---------|---------|--------------|
| `file1.ts` | {brief description} | {key exports} | {key deps} |
### {Category 2} ({X} files)
{Similar table}
### Uncategorized ({X} files)
{Files that don't fit clear categories - may indicate organizational issues}
---
## Patterns & Conventions
### Naming Conventions
- **Consistency**: {High|Medium|Low}
- **Primary Pattern**: {describe dominant pattern}
- **Variations**: {list any variations observed}
- **Inconsistencies**: {list if any - these are potential issues}
**Examples:**
- ✅ Follows pattern: `{example file following convention}`
- ❌ Violates pattern: `{example file not following convention}` (if any)
### File Organization
- **Structure**: {Flat|Nested|Feature-based|Type-based|Mixed}
- **Rationale**: {observed logic for organization}
- **Depth**: {max directory depth}
### Module Pattern
- **Type**: {Single-file|Multi-file|Mixed}
- **Index/Barrel Files**: {Yes/No - list locations if yes}
- **Export Style**: {Named|Default|Mixed}
### Code Patterns (if detected)
{List any recurring code patterns observed in sampled files}
- Pattern 1: {description}
- Pattern 2: {description}
---
## Test Coverage
| Metric | Value |
|--------|-------|
| **Files with Tests** | {X}/{Y} ({Z}%) |
| **Test Pattern** | `{pattern}` |
| **Test Location** | {Co-located|Separate __tests__|Mixed} |
### Untested Files (Priority Review)
{List files without corresponding tests, prioritize by apparent importance}
1. `{file}` - {why it should be tested / what it does}
2. `{file}` - {why it should be tested}
---
## Dependencies
### Internal Dependencies (This domain imports from)
| Domain/Path | Import Count | Description |
|-------------|--------------|-------------|
| `{domain}` | {X} imports | {brief description} |
### External Dependencies (npm/pip packages)
| Package | Usage | Count |
|---------|-------|-------|
| `{package}` | {how it's used} | {X} files |
### Reverse Dependencies (Other code imports this domain)
{If detectable via Grep - may require scanning outside domain}
- `{other_domain}` imports from this domain
### Coupling Assessment
- **Level**: {High|Medium|Low}
- **Rationale**: {explanation based on import analysis}
---
## Issues & Recommendations
### 🔴 High Priority
#### {Issue Title}
- **Type**: {Pattern Violation|Quality Issue|Organizational Issue}
- **Location**: `{file or directory}`
- **Description**: {what's wrong}
- **Impact**: {why it matters}
- **Recommendation**: {specific action to take}
### 🟡 Medium Priority
{Similar format}
### 🟢 Low Priority / Nice-to-Have
{Similar format}
---
{If --compare flag or existing docs found:}
## Comparison with Documentation
### Drift Detected: {TRIVIAL|MINOR|SIGNIFICANT|NONE}
#### Changed
| Item | Documented | Actual | Drift |
|------|------------|--------|-------|
| File count | {X} | {Y} | {+/- Z} ({N}%) |
| Key file | `{file}` | Moved to `{new_path}` | Location changed |
#### New (Not in docs)
- `{new_subdirectory}/` - {X} files, {purpose}
- `{new_file}` - {purpose}
#### Removed (In docs, not found)
- `{missing_file}` - {possible reason}
---
{If --update-schema flag:}
## Proposed Schema Updates
```yaml
{domain_name}:
location: {path}
purpose: {updated purpose description}
count: {updated file count}
confidence: {high|medium|low}
key_files:
- {updated key file 1}
- {updated key file 2}
Changes from current schema:
/codebase-documentation:map-domain {domain} --update-schema/codebase-documentation:map-domain {domain} --update-docs/codebase-documentation:audit-docs --domain {domain}
### 5. Interactive Mode (if `--interactive` flag)
Use AskUserQuestion for key decisions:
**Before Analysis Starts:**
- Question: "Focus areas for analysis?"
- Options: "Full analysis" (default) | "Patterns only" | "Dependencies only" | "Tests only" | "Structure only"
**After Issues Detected (for HIGH priority only):**
- Question: "Issue detected: {title}. How should we handle this?"
- Options: "Document as-is" | "Flag for refactor" | "Investigate now" | "Ignore"
**Before Schema Update (if `--update-schema`):**
- Question: "Update codebase-schema.yaml with these changes?"
- Show: YAML diff of proposed changes
- Options: "Update" | "Save draft" | "Skip"
**Before Docs Update (if `--update-docs`):**
- Question: "Update domain documentation?"
- Show: Summary of changes
- Options: "Update" | "Create new version" | "Skip"
### 6. Compare Mode (if `--compare` flag)
**Requires existing domain documentation.**
1. Check if `.claude/docs/domains/{domain}.md` exists
2. If not found: Warning "No existing documentation found for comparison", proceed with normal analysis
3. If found:
- Parse existing doc to extract documented structure
- Compare findings with documented state
- Generate drift analysis using same classification as audit-docs (TRIVIAL/MINOR/SIGNIFICANT)
- Include "Comparison with Documentation" section in report
### 7. Update Schema (if `--update-schema` flag)
1. Read current `.claude/docs/codebase-schema.yaml`
2. Update domain section with findings:
- File count
- Purpose (if initial generation or significantly changed)
- Key files (add new important files, remove missing ones)
- Confidence level based on analysis clarity
3. If domain didn't exist in schema, add new domain section
4. Preserve all other schema content unchanged
5. Update `metadata.documentation.generated_at` timestamp if field exists
6. Write updated schema
7. Report changes made
### 8. Update Domain Docs (if `--update-docs` flag)
1. Check if `.claude/docs/domains/{domain}.md` exists
2. **If exists:**
- Read current doc
- Identify custom sections (non-template content)
- Regenerate template sections with new data
- Preserve custom sections in their original positions
- Add "Last Updated" timestamp
3. **If doesn't exist:**
- Create new domain doc using standard template
- Fill with all findings from analysis
4. Write documentation file
5. Report action taken (created vs updated)
### 9. Focus Mode (if `--focus <area>` provided)
Limit analysis to specific area:
- `--focus patterns` - Only naming conventions, file organization, code patterns
- `--focus dependencies` - Only internal/external imports, coupling analysis
- `--focus tests` - Only test coverage, untested files
- `--focus structure` - Only filesystem enumeration, directory organization
Generate abbreviated report with only relevant sections.
### 10. Output Control
**Default:** Display full markdown report
**With `--quiet`:** Only show summary table, skip detailed sections
**With `--verbose`:** Include:
- Full file listings (not just counts)
- All sampled file contents
- Complete import analysis for every file
## Error Handling
### Domain Not Found
- **Error**: "Domain '{name}' not found in schema and path doesn't exist"
- **List**: Available domains from schema
- **Suggest**: "Provide a valid domain name or directory path"
### Path Not Accessible
- **Error**: "Cannot access path: `{path}`"
- **Check**: Permissions, path validity, typos
### Empty Domain
- **Warning**: "Domain `{path}` contains no files"
- **Action**: Generate minimal report noting empty state, suggest removal from schema
### Schema Update Failed
- **Error**: "Failed to update schema: {reason}"
- **Fallback**: Display proposed changes for manual application
- **Suggest**: "Check file permissions or manually update schema"
### Docs Update Failed
- **Error**: "Failed to write documentation: {reason}"
- **Fallback**: Display full report for manual saving
### Compare Mode Without Existing Docs
- **Warning**: "No existing documentation found at `.claude/docs/domains/{domain}.md`"
- **Action**: Proceed with normal analysis (no comparison section)
## Sampling Strategy
For large domains (>100 files):
1. Sample 10-15 representative files for deep analysis
2. Select files from different subdirectories
3. Include mix of file types
4. Use Glob counts for statistics
5. Note sampling approach in report summary
## Examples
```bash
# Basic domain mapping
/codebase-documentation:map-domain components
# Map with comparison against existing docs
/codebase-documentation:map-domain services --compare
# Interactive mapping with updates
/codebase-documentation:map-domain authentication --interactive --update-schema --update-docs
# Map arbitrary directory (not in schema)
/codebase-documentation:map-domain src/custom/area --verbose
# Focused analysis on patterns only
/codebase-documentation:map-domain utils --focus patterns
# Quick summary only
/codebase-documentation:map-domain models --update-schema --quiet
# Full interactive workflow
/codebase-documentation:map-domain api --interactive --compare --update-docs
A successful domain map should: