proxysql/doc/AI-DOCUMENTATION-FRAMEWORK.md

# AI Documentation Framework

## Overview

ProxySQL uses AI-generated documentation to accelerate developer onboarding and codebase exploration while maintaining transparency about accuracy limitations.

## Documentation Tiers

### 🔬 AI-Generated (Tier 1)
- **Purpose**: Exploration guides and starting points
- **Verification**: NON-VERIFIED
- **Maintenance**: Community contributions encouraged
- **Update**: As needed when codebase changes significantly

### 📋 Human-Verified (Tier 2)
- **Purpose**: Critical operational documentation
- **Verification**: REQUIRED
- **Maintenance**: Maintainer-reviewed
- **Update**: With each relevant change

### 🔧 Living Documentation (Tier 3)
- **Purpose**: Auto-generated from source
- **Verification**: Automated validation
- **Maintenance**: CI/CD integration
- **Update**: Continuous

## AI Documentation Standards

### Required Disclaimer
Every AI-generated document must include:

```markdown
> **⚠️ Important Notice**: This documentation was generated by AI and may contain inaccuracies.
> It should be used as a starting point for exploration only. Always verify critical information
> against the actual source code.
>
> **Last AI Update**: [DATE]
> **Status**: NON-VERIFIED
> **Maintainer**: [ASSIGNED]
```

### File Organization
```
doc/
├── ai-generated/          # AI-generated exploration guides
│   ├── architecture/      # Architecture documentation
│   └── DOCUMENTATION-INDEX.md
├── internal/              # Human-verified technical docs
├── release_notes/         # Official release notes
└── README.md              # This guide
```

## Verification Process

### When to Verify
- Security-related documentation
- Build and installation instructions
- API contracts and interfaces
- Performance-critical information

### Verification Checklist
- [ ] Code references are accurate
- [ ] File paths are correct
- [ ] Technical details match implementation
- [ ] Examples work as described

## Maintenance Guidelines

### AI Documentation Updates
1. Review after major feature changes
2. Update when architectural patterns shift
3. Community corrections welcome
4. Maintain disclaimer format

### Automated Validation
Where possible, include validation commands:
```markdown
**Validation Command**:
```bash
grep -n "class MySQL_Handler" src/protocol/mysql/protocol_mysql.cpp
```
```

## Contributing

### Improving AI Documentation
1. Identify inaccuracies
2. Submit corrections via PR
3. Add validation commands
4. Update disclaimer date

### Adding New AI Documentation
1. Follow the template format
2. Include required disclaimer
3. Place in appropriate `ai-generated/` subdirectory
4. Update main documentation index

## Benefits

- **Faster Onboarding**: Developers get immediate guidance
- **Reduced Burden**: Critical verification focused on essential docs
- **Transparency**: Clear status indicators for all documentation
- **Community-Driven**: Easy contribution process for improvements

## Limitations

- AI documentation may contain technical inaccuracies
- Not suitable for critical operational procedures
- Requires human verification for security-sensitive information
- May become outdated between major updates

---

This framework balances the productivity benefits of AI-generated documentation with the accuracy requirements of a critical database proxy system.