# Docs Directory Standards

## Directory Structure
```yaml
Claude_Operational_Docs:
  Base_Directory: .claudedocs/
  
  Structure:
    audit/:          # Audit logs & op history
    reports/:        # Analysis reports, scan results, findings
    summaries/:      # Command summaries, estimates, overviews
    metrics/:        # Perf metrics, coverage reports, benchmarks
    incidents/:      # Troubleshooting RCAs, incident docs
    
  Naming_Conventions:
    Reports: <command>-<type>-<timestamp>.md
    Metrics: <metric>-<date>.md|html|json
    Audit: audit-<YYYY-MM-DD>.log
    
  Examples:
    - .claudedocs/reports/analysis-security-20240115-143022.md
    - .claudedocs/metrics/coverage-20240115.html
    - .claudedocs/audit/audit-2024-01-15.log
    - .claudedocs/incidents/rca-api-timeout-20240115-143022.md

Project_Documentation:
  Base_Directory: /docs
  
  Structure:
    api/:            # API documentation, endpoints, schemas
    guides/:         # User guides, tutorials, how-tos
    architecture/:   # System design, diagrams, decisions
    development/:    # Developer setup, contributing, standards
    references/:     # Quick references, cheat sheets
    
  Organization:
    - README.md at each level
    - index.md for navigation
    - Versioned subdirectories when needed
    - Assets in dedicated folders
    
  Examples:
    - /docs/api/rest-api.md
    - /docs/guides/getting-started.md
    - /docs/architecture/system-overview.md
    - /docs/development/setup.md
```

## Enforcement Rules
```yaml
Directory_Creation:
  Auto_Create: true
  Permissions: 755 for dirs, 644 for files
  
  Pre_Write_Check:
    - Verify parent directory exists
    - Create if missing with proper permissions
    - Validate write access
    - Handle errors gracefully

Report_Generation:
  Required_Headers:
    - Generated by: SuperClaude v4.0.0
    - Command: /user:<command> [flags]
    - Timestamp: ISO 8601 format
    - Duration: Operation time
    
  Format_Standards:
    - Markdown for human-readable reports
    - JSON for machine-readable metrics
    - HTML for coverage reports
    - Plain text for logs

Documentation_Standards:
  Project_Docs:
    - Clear section headers
    - Table of contents for long docs
    - Code examples with syntax highlighting
    - Cross-references to related docs
    
  Operational_Reports:
    - Executive summary first
    - Detailed findings follow
    - Actionable recommendations
    - Severity/priority indicators
```

## Integration Points
```yaml
Commands:
  analyze: → .claudedocs/reports/analysis-*.md
  scan: → .claudedocs/reports/scan-*.md
  test: → .claudedocs/metrics/coverage-*.html
  improve: → .claudedocs/metrics/quality-*.md
  troubleshoot: → .claudedocs/incidents/rca-*.md
  estimate: → .claudedocs/summaries/estimate-*.md
  document: → /docs/[category]/*.md
  
Shared_Resources:
  audit.yml: → .claudedocs/audit/
  performance-monitoring.yml: → .claudedocs/metrics/
  checkpoint.yml: → .claudedocs/summaries/checkpoint-*.md
```

## Output Notifications
```yaml
Report_Created:
  Format: "📄 Report saved to: <path>"
  Example: "📄 Analysis report saved to: .claudedocs/reports/analysis-security-20240115-143022.md"
  
Documentation_Created:
  Format: "📚 Documentation created: <path>"
  Example: "📚 API documentation created: /docs/api/endpoints.md"
  
Directory_Created:
  Format: "📁 Created directory: <path>"
  Show: Only on first creation
```

## Gitignore Recommendations
```yaml
# Add to .gitignore:
.claudedocs/audit/        # Operational logs
.claudedocs/metrics/      # Performance data
.claudedocs/incidents/    # Sensitive RCAs

# Keep in git:
.claudedocs/reports/      # Useful analysis reports
.claudedocs/summaries/    # Important summaries
/docs/                    # All project documentation
```

---
*Documentation Directory Standards: Organizing Claude's output professionally*