create-docs.md

You are working on the current project. The user has requested to create or regenerate documentation with the arguments: "$ARGUMENTS"

Auto-Loaded Project Context:

@/CLAUDE.md @/docs/ai-context/project-structure.md @/docs/ai-context/docs-overview.md

CRITICAL: AI-Optimized Documentation Principles

All documentation must be optimized for AI consumption and future-proofing:

• Structured & Concise: Use clear sections, lists, and hierarchies. Provide essential information only.
• Contextually Complete: Include necessary context, decision rationale ("why"), and cross-references.
• Pattern-Oriented: Make architectural patterns, conventions, and data flow explicit.
• Modular & Scalable: Structure for partial updates and project growth.
• Cross-references: Link related concepts with file paths, function names, and stable identifiers

---

Step 1: Analyze & Strategize

Using the auto-loaded project context, analyze the user's request and determine the optimal documentation strategy.

1.1. Parse Target & Assess Complexity

Action: Analyze $ARGUMENTS to identify the target_path and its documentation tier.

Target Classification:

• Tier 3 (Feature-Specific): Paths containing /src/ and ending in /CONTEXT.md
• Tier 2 (Component-Level): Paths ending in component root /CONTEXT.md

Complexity Assessment Criteria:

• Codebase Size: File count and lines of code in target directory
• Technology Mix: Diversity of languages and frameworks (Python, TypeScript, etc.)
• Architectural Complexity: Dependency graph and cross-component imports
• Existing Documentation: Presence and state of any CLAUDE.md files in the area

1.2. Select Strategy

Think deeply about this documentation generation task and strategy based on the auto-loaded project context. Based on the assessment, select and announce the strategy.

Strategy Logic:

• Direct Creation: Simple targets (< 15 files, single tech, standard patterns)
• Focused Analysis: Moderate complexity (15-75 files, 2-3 techs, some novel patterns)
• Comprehensive Analysis: High complexity (> 75 files, 3+ techs, significant architectural depth)

---

Step 2: Information Gathering (Analysis Phase)

Based on the chosen strategy, gather the necessary information.

Strategy A: Direct Creation

Proceed directly to Step 3.1. Perform lightweight analysis during content generation.

Strategy B: Focused or Comprehensive Analysis (Sub-Agent Orchestration)

2.1. Sub-Agent Roles

Select from these specialized roles based on complexity assessment:

• Code_Analyzer: File structure, implementation patterns, logic flow, coding conventions
• Tech_Stack_Identifier: Frameworks, libraries, dependencies, technology-specific patterns
• Architecture_Mapper: Cross-component dependencies, integration points, data flow
• Doc_Validator: Existing documentation accuracy, gaps, valuable insights, content overlap analysis

2.2. Launch Sub-Agents

Execution Plan:

• Focused Analysis (2-3 agents): Code_Analyzer + Tech_Stack_Identifier + Doc_Validator (if existing docs)
• Comprehensive Analysis (3-4 agents): All agents as needed

CRITICAL: Launch agents in parallel using a single message with multiple Task tool invocations for optimal performance.

Task Template:

Task: "As the [Agent_Role], analyze the codebase at `[target_path]` to support documentation generation.

Your focus: [role-specific goal, e.g., 'identifying all architectural patterns and dependencies']

Standard workflow:
1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
2. Analyze the target path for your specialized area
3. Return structured findings for documentation generation

Return a comprehensive summary of your findings for this role."

---

Step 3: Documentation Generation

Think deeply about synthesizing findings and generating comprehensive documentation. Using gathered information, intelligently synthesize and generate the documentation content.

3.1. Content Synthesis & Generation

For Direct Creation (No Sub-Agents)

Code-First Analysis Methodology:

1. Directory Structure Analysis: Map file organization and purposes using Glob/LS
2. Import Dependency Analysis: Use Grep to identify integration patterns and dependencies
3. Pattern Extraction: Read key files to identify architectural patterns and coding conventions
4. Technology Usage Analysis: Detect frameworks, libraries, and technology-specific patterns
5. Existing Documentation Assessment: Read any current CLAUDE.md files for valuable insights

For Sub-Agent Strategies

Synthesis Integration Process:

1. Compile Core Findings: Merge agent findings for immediate documentation generation
2. Extract Cross-Tier Patterns: Identify system-wide patterns that may impact foundational documentation
3. Resolve Information Conflicts: When code contradicts existing docs, use code as source of truth
4. Identify Content Gaps: Find areas needing new documentation based on analysis
5. Apply Project Conventions: Use coding standards and naming conventions from the auto-loaded /CLAUDE.md
6. Content Overlap Identification: From Doc_Validator findings, identify existing documentation that overlaps with target content for later migration analysis

Content Generation Process

For Both Approaches:

1. Select Template: Choose Tier 2 or Tier 3 based on target classification
2. Apply Content Treatment Strategy:
   • Preserve: Validated architectural insights from existing documentation
   • Enhance: Extend existing patterns with newly discovered implementation details
   • Replace: Outdated content that conflicts with current code reality
   • Create: New documentation for undocumented patterns and decisions
3. Populate Sections: Fill template sections with synthesized findings
4. Ensure Completeness: Include architectural decisions, patterns, dependencies, and integration points
5. Follow AI-Optimized Principles: Structure for AI consumption with clear cross-references

3.2. Template Guidelines

Tier 2 (Component-Level):

# [Component Name] - Component Context

## Purpose
[Component purpose and key responsibilities]

## Current Status: [Status]
[Status with evolution context and rationale]

## Component-Specific Development Guidelines
[Technology-specific patterns and conventions]

## Major Subsystem Organization
[High-level structure based on actual code organization]

## Architectural Patterns
[Core patterns and design decisions]

## Integration Points
[Dependencies and connections with other components]

Tier 3 (Feature-Specific):

# [Feature Area] Documentation

## [Area] Architecture
[Key architectural elements and integration patterns]

## Implementation Patterns
[Core patterns and error handling strategies]

## Key Files and Structure
[File organization with purposes]

## Integration Points
[How this integrates with other parts of the system]

## Development Patterns
[Testing approaches and debugging strategies]

---

Step 4: Finalization & Housekeeping

4.1. Write Documentation File

Action: Write the generated content to the target path.

4.2. Update Documentation Registry

Update docs-overview.md

For new documentation files:

• Add to appropriate tier section (Feature-Specific or Component-Level)
• Follow established entry format with path and description
• Maintain alphabetical ordering within sections

For updated existing files:

• Verify entry exists and description is current
• Update any changed purposes or scopes

Update Project Structure (if needed)

If new directories were created:

• Update file tree in /docs/ai-context/project-structure.md
• Add directory comments explaining purpose
• Maintain tree structure formatting and organization

4.3. Quality Validation

Action: Verify tier appropriateness, code accuracy, cross-reference validity, and consistency with existing documentation patterns.

4.4. Tier 1 Validation & Recommendations

Action: Compare discovered code patterns against foundational documentation to identify inconsistencies and improvement opportunities.

Process

1. Discover Tier 1 Files: Read /docs/ai-context/docs-overview.md to identify all foundational documentation files
2. Read Foundational Docs: Load discovered Tier 1 files to understand documented architecture
3. Cross-Tier Analysis: Using analysis findings from previous steps, compare:
   • Technology Stack: Discovered frameworks/tools vs documented stack
   • Architecture Patterns: Implementation reality vs documented decisions
   • Integration Points: Actual dependencies vs documented integrations
4. Generate Recommendations: Output evidence-based suggestions for foundational documentation updates

4.5. Content Migration & Redundancy Management

Action: Intelligently manage content hierarchy and eliminate redundancy across documentation tiers.

Cross-Reference Analysis

1. Identify Related Documentation: Using Doc_Validator findings from Step 3.1 synthesis and target tier classification, identify existing documentation that may contain overlapping content
2. Content Overlap Detection: Compare new documentation content with existing files to identify:
   • Duplicate Information: Identical content that should exist in only one location
   • Hierarchical Overlaps: Content that exists at wrong tier level (implementation details in architectural docs)
   • Cross-Reference Opportunities: Content that should be linked rather than duplicated

Smart Content Migration Strategy

Content Classification Framework:

• Tier-Appropriate Duplication: High-level architectural context can exist at both Tier 2 and Tier 3 with different detail levels
• Migration Candidates: Detailed implementation patterns, specific code examples, feature-specific technical details
• Reference Targets: Stable architectural decisions, design rationale, cross-cutting concerns

Migration Decision Logic:

1. For Tier 3 Creation (Feature-Specific):

   • Extract from Tier 2: Move feature-specific implementation details to new Tier 3 file
   • Preserve in Tier 2: Keep high-level architectural overview and design decisions
   • Add Cross-References: Link Tier 2 overview to detailed Tier 3 implementation

2. For Tier 2 Creation (Component-Level):

   • Consolidate from Multiple Tier 3: Aggregate architectural insights from existing feature docs
   • Preserve Tier 3 Details: Keep implementation specifics in feature documentation
   • Create Navigation Structure: Add references to relevant Tier 3 documentation

Content Migration Execution

Migration Process:

1. Identify Source Content: Extract content that should migrate from existing files
2. Content Transformation: Adapt content to appropriate tier level (architectural vs implementation focus)
3. Update Source Files: Remove migrated content and add cross-references to new location
4. Preserve Context: Ensure source files maintain coherence after content removal
5. Validate Migrations: Confirm no broken references or lost information

Safety Framework:

• Conservative Defaults: When uncertain, preserve content in original location and add references
• Content Preservation: Never delete content without creating it elsewhere first
• Migration Reversibility: Document all migrations to enable rollback if needed

---

Step 5: Generate Summary

Provide a comprehensive summary including:

Documentation Creation Results

• Documentation type and location (Tier 2 or Tier 3)
• Strategy used (Direct Creation, Focused Analysis, or Comprehensive Analysis)
• Key patterns documented (architectural decisions, implementation patterns)
• Registry updates made (docs-overview.md, project-structure.md entries)

Tier 1 Architectural Intelligence

Based on Step 4.4 analysis, provide structured recommendations:

Critical Updates Needed

• File: [specific foundational doc path]
• Issue: [specific inconsistency with evidence]
• Recommendation: [specific update needed]
• Evidence: [code references supporting the recommendation]

Architecture Enhancement Opportunities

• Gap Identified: [missing foundational documentation area]
• Scope: [what should be documented]
• Rationale: [why this deserves foundational documentation]
• Implementation Evidence: [code patterns discovered]

Documentation Health Assessment

• Alignment Score: [overall consistency between code and docs]
• Most Accurate Areas: [foundational docs that match implementation well]
• Areas Needing Attention: [foundational docs with significant gaps/inconsistencies]
• Systematic Improvement Priority: [recommended order for addressing issues]

Content Migration Results

Document all content hierarchy changes and redundancy eliminations:

• Content Migrated From: [source file path] → [target file path]

  • Content Type: [e.g., "implementation patterns", "technical details", "architectural decisions"]
  • Rationale: [why this content belongs at the target tier]
  • Cross-References Added: [navigation links created between tiers]

• Content Preserved At: [broader tier file]

  • Content Type: [e.g., "architectural overview", "design decisions", "integration patterns"]
  • Rationale: [why this content remains at the broader tier]

• Redundancies Eliminated:

  • Duplicate Content Removed: [specific duplications eliminated]
  • Hierarchical Corrections: [content moved to appropriate tier level]
  • Reference Consolidations: [areas where links replaced duplication]

• Migration Safety:

  • Content Preserved: [confirmation that no information was lost]
  • Rollback Information: [documentation of changes for potential reversal]
  • Validation Results: [confirmation of no broken references]

Next Documentation Steps (Optional Recommendations)

• Feature-Specific Documentation Candidates: [suggest additional Tier 3 docs that would be valuable]
• Cross-Component Documentation Needs: [identify other components needing similar analysis]
• Documentation Debt Eliminated: [summary of redundancies and inconsistencies resolved]

---

Now proceed to create/regenerate documentation based on the request: $ARGUMENTS