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:

# {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:

## 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:

   | E11 | Thermal Gradient | `extract_thermal_gradient()` | .op2 | K/mm |
   

3. Adds detailed section with code example
4. Updates __init__.py:

   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:

   | 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