Atomizer/.claude/skills/DEV_DOCUMENTATION.md

# Developer Documentation Skill

**Version**: 1.0
**Purpose**: Self-documenting system for Atomizer development. Use this skill to systematically document new features, protocols, extractors, and changes.

---

## Overview

This skill enables **automatic documentation maintenance** during development. When you develop new features, use these commands to keep documentation in sync with code.

---

## Quick Commands for Developers

### Document New Feature

**Tell Claude**:
```
"Document the new {feature} I just added"
```

Claude will:
1. Analyze the code changes
2. Determine which docs need updating
3. Update protocol files
4. Update CLAUDE.md if needed
5. Bump version numbers
6. Create changelog entry

### Document New Extractor

**Tell Claude**:
```
"I created a new extractor: extract_thermal.py. Document it."
```

Claude will:
1. Read the extractor code
2. Add entry to SYS_12_EXTRACTOR_LIBRARY.md
3. Add to extractors-catalog.md module
4. Update __init__.py exports
5. Create test file template

### Document Protocol Change

**Tell Claude**:
```
"I modified Protocol 10 to add {feature}. Update docs."
```

Claude will:
1. Read the code changes
2. Update SYS_10_IMSO.md
3. Bump version number
4. Add to Version History
5. Update cross-references

### Full Documentation Audit

**Tell Claude**:
```
"Audit documentation for {component/study/protocol}"
```

Claude will:
1. Check all related docs
2. Identify stale content
3. Flag missing documentation
4. Suggest updates

---

## Documentation Workflow

### When You Add Code

```
┌─────────────────────────────────────────────────┐
│  1. WRITE CODE                                  │
│     - New extractor, hook, or feature           │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│  2. TELL CLAUDE                                 │
│     "Document the new {feature} I added"        │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│  3. CLAUDE UPDATES                              │
│     - Protocol files                            │
│     - Skill modules                             │
│     - Version numbers                           │
│     - Cross-references                          │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│  4. REVIEW & COMMIT                             │
│     - Review changes                            │
│     - Commit code + docs together               │
└─────────────────────────────────────────────────┘
```

---

## Documentation Update Rules

### File → Document Mapping

| If You Change... | Update These Docs |
|------------------|-------------------|
| `optimization_engine/extractors/*` | SYS_12, extractors-catalog.md |
| `optimization_engine/intelligent_optimizer.py` | SYS_10_IMSO.md |
| `optimization_engine/plugins/*` | EXT_02_CREATE_HOOK.md |
| `atomizer-dashboard/*` | SYS_13_DASHBOARD_TRACKING.md |
| `atomizer-field/*` | SYS_14_NEURAL_ACCELERATION.md |
| Any multi-objective code | SYS_11_MULTI_OBJECTIVE.md |
| Study creation workflow | OP_01_CREATE_STUDY.md |
| Run workflow | OP_02_RUN_OPTIMIZATION.md |

### Version Bumping Rules

| Change Type | Version Bump | Example |
|-------------|--------------|---------|
| Bug fix | Patch (+0.0.1) | 1.0.0 → 1.0.1 |
| New feature (backwards compatible) | Minor (+0.1.0) | 1.0.0 → 1.1.0 |
| Breaking change | Major (+1.0.0) | 1.0.0 → 2.0.0 |

### Required Updates for New Extractor

1. **SYS_12_EXTRACTOR_LIBRARY.md**:
   - Add to Quick Reference table (assign E{N} ID)
   - Add detailed section with code example

2. **skills/modules/extractors-catalog.md** (when created):
   - Add entry with copy-paste code snippet

3. **optimization_engine/extractors/__init__.py**:
   - Add import and export

4. **Tests**:
   - Create `tests/test_extract_{name}.py`

### Required Updates for New Protocol

1. **docs/protocols/system/SYS_{N}_{NAME}.md**:
   - Create full protocol document

2. **docs/protocols/README.md**:
   - Add to navigation tables

3. **.claude/skills/01_CHEATSHEET.md**:
   - Add to quick lookup table

4. **.claude/skills/02_CONTEXT_LOADER.md**:
   - Add loading rules

5. **CLAUDE.md**:
   - Add reference if major feature

---

## Self-Documentation Commands

### "Document this change"

Claude analyzes recent changes and updates relevant docs.

**Input**: Description of what you changed
**Output**: Updated protocol files, version bumps, changelog

### "Create protocol for {feature}"

Claude creates a new protocol document following the template.

**Input**: Feature name and description
**Output**: New SYS_* or EXT_* document

### "Verify documentation for {component}"

Claude checks that docs match code.

**Input**: Component name
**Output**: List of discrepancies and suggested fixes

### "Generate changelog since {date/commit}"

Claude creates a changelog from git history.

**Input**: Date or commit reference
**Output**: Formatted changelog

---

## Protocol Document Template

When creating new protocols, use this structure:

```markdown
# {LAYER}_{NUMBER}_{NAME}.md

<!--
PROTOCOL: {Full Name}
LAYER: {Operations|System|Extensions}
VERSION: 1.0
STATUS: Active
LAST_UPDATED: {YYYY-MM-DD}
PRIVILEGE: {user|power_user|admin}
LOAD_WITH: [{dependencies}]
-->

## Overview
{1-3 sentence description}

## When to Use
| Trigger | Action |
|---------|--------|

## Quick Reference
{Tables, key parameters}

## Detailed Specification
{Full content}

## Examples
{Working examples}

## Troubleshooting
| Symptom | Cause | Solution |

## Cross-References
- Depends On: []
- Used By: []

## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | {DATE} | Initial release |
```

---

## Changelog Format

When updating protocols, add to Version History:

```markdown
## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.2.0 | 2025-12-05 | Added thermal gradient support |
| 1.1.0 | 2025-12-01 | Improved error handling |
| 1.0.0 | 2025-11-20 | Initial release |
```

---

## Integration with Git

### Commit Message Format

When documenting:
```
docs: Update SYS_12 with thermal extractor

- Added E11 thermal gradient extractor
- Updated Quick Reference table
- Added code example in Detailed section
- Bumped version to 1.1.0
```

### Pre-Commit Checklist

Before committing code changes:
- [ ] Related docs updated
- [ ] Version numbers bumped
- [ ] Cross-references valid
- [ ] Examples tested
- [ ] CLAUDE.md updated if major feature

---

## Example: Document New Extractor

**You say**:
```
"I just created extract_thermal_gradient.py in optimization_engine/extractors/.
It extracts thermal gradients from temperature fields. Document it."
```

**Claude does**:

1. Reads `extract_thermal_gradient.py`
2. Updates `SYS_12_EXTRACTOR_LIBRARY.md`:
   ```markdown
   | E11 | Thermal Gradient | `extract_thermal_gradient()` | .op2 | K/mm |
   ```
3. Adds detailed section with code example
4. Updates `__init__.py`:
   ```python
   from .extract_thermal_gradient import extract_thermal_gradient
   __all__ = [..., 'extract_thermal_gradient']
   ```
5. Bumps SYS_12 version: 1.0 → 1.1
6. Reports what was updated

---

## Example: Document Protocol Change

**You say**:
```
"I added a new stopping criterion to Protocol 10 based on improvement rate.
Update the documentation."
```

**Claude does**:

1. Reads relevant code changes
2. Updates `SYS_10_IMSO.md`:
   - Adds to Configuration section
   - Updates Architecture diagram if needed
   - Adds to Quick Reference
3. Bumps version: 2.1 → 2.2
4. Adds Version History entry:
   ```markdown
   | 2.2 | 2025-12-05 | Added improvement rate stopping criterion |
   ```
5. Updates cross-references if needed

---

## Keeping Docs in Sync

### Daily Development

```
Morning: Start coding
  │
  ├─► Write new feature
  │
  ├─► Test feature
  │
  ├─► "Claude, document the {feature} I just added"
  │
  └─► Commit code + docs together
```

### Weekly Audit

```
Friday:
  │
  ├─► "Claude, audit documentation for recent changes"
  │
  ├─► Review flagged issues
  │
  └─► Fix any stale documentation
```

### Release Preparation

```
Before release:
  │
  ├─► "Claude, generate changelog since last release"
  │
  ├─► "Claude, verify all protocol versions are consistent"
  │
  └─► Final review and version bump
```

---

## Summary

**To keep documentation in sync**:

1. **After coding**: Tell Claude what you changed
2. **Be specific**: "I added X to Y" works better than "update docs"
3. **Commit together**: Code and docs in same commit
4. **Regular audits**: Weekly check for stale docs

**Claude handles**:
- Finding which docs need updates
- Following the template structure
- Version bumping
- Cross-reference updates
- Changelog generation

**You handle**:
- Telling Claude what changed
- Reviewing Claude's updates
- Final commit