Generate and maintain comprehensive documentation including Doxygen comments, progress reports, session notes, and API docs for Orpheus SDK.
The Orpheus Documentation Generator skill automates creation and maintenance of high-quality documentation for the Orpheus SDK, ensuring the 8000+ line documentation standard is maintained. This skill encodes documentation best practices, generates Doxygen-compliant API comments, and maintains progress tracking documents.
Core Capabilities:
CRITICAL - Documentation File Naming:
When creating new PREFIX-numbered documentation (ORP, OCC), files MUST follow this pattern:
Format: {PREFIX###} {Descriptive Title}.md
Examples (CORRECT):
ORP082 Session Performance Report.mdOCC103 QA v020 Results.mdORP098 Real-time Safety Audit Results.mdExamples (WRONG - NEVER USE):
ORP082.md (missing descriptive title)OCC-103-QA.md (wrong separator format)See ~/chrislyons/dev/CLAUDE.md for complete naming conventions.
Trigger Patterns:
*.h, *.hpp, progress.md, SESSION_*.mdDo NOT Use When:
Use Alternative Skills:
rt.safety.auditor, clang-tidytest.result.analyzerread_file - Read existing code and documentationwrite_file - Create new documentation filesedit_file - Update existing documentationAccess Level: 2 (File Modification - read + write + edit)
Rationale:
Explicitly Denied:
bash - No execution needed for documentationInput:
Output:
Required:
Optional:
Version Requirements:
User: "Generate Doxygen comments for the processBlock function"
Input Code:
void AudioMixer::processBlock(float** outputs, int numFrames, int sampleRate);
Claude Process:
Output:
/**
* @brief Process an audio block by mixing all active channels
*
* Processes numFrames samples from all active input channels, applies per-channel
* gain, and outputs the mixed result to the output buffers. This method implements
* real-time safe mixing using pre-allocated buffers and lock-free gain updates.
*
* @param[out] outputs Pointer to output buffer array (stereo: 2 channels)
* Each channel must have space for numFrames samples
* @param[in] numFrames Number of samples to process (must be ≤ kMaxFrames)
* @param[in] sampleRate Sample rate in Hz (e.g., 44100, 48000)
*
* @return void
*
* @pre outputs != nullptr && numFrames > 0 && numFrames <= kMaxFrames
* @post Output buffers contain mixed audio samples
*
* @note Real-time safe: No allocations, no locks, O(numFrames) bounded execution
* @warning Buffer overflow if numFrames > kMaxFrames (checked with assertion)
*
* @thread_safety Thread-safe for concurrent calls with different output buffers.
* Not safe for concurrent modification of mixer state.
* @real_time Yes - Safe for audio thread use
*
* @example
* @code
* AudioMixer mixer;
* float* outputs[2] = {leftChannel, rightChannel};
* mixer.processBlock(outputs, 512, 48000);
* @endcode
*/
void AudioMixer::processBlock(float** outputs, int numFrames, int sampleRate);
User: "Create a progress report for Module 3 implementation"
Output:
# Module 3: Audio Mixer Implementation Progress
**Date:** 2025-10-18
**Status:** In Progress
**Completion:** 75% (3/4 tasks)
---
## Completed Tasks
### ✅ Task 1: Core AudioMixer Class
- **File:** `src/modules/m3/audio_mixer.h`, `src/modules/m3/audio_mixer.cpp`
- **Lines of Code:** 324
- **Tests:** 15 tests, 98.2% coverage
- **Key Features:**
- Sample-accurate mixing algorithm
- Lock-free gain updates
- Pre-allocated channel buffers
### ✅ Task 2: Unit Tests
- **File:** `tests/modules/m3/audio_mixer_test.cpp`
- **Lines of Code:** 287
- **Coverage:** 98.2% (target: 98% - OK)
- **Test Cases:**
- Stereo mixing
- Mono to stereo
- Gain application
- Buffer overflow protection
- Edge cases (silence, zero frames)
### ✅ Task 3: Doxygen Documentation
- **Lines:** 156 lines of Doxygen comments
- **APIs Documented:** All 12 public methods
- **Quality:** Thread-safety and real-time safety annotations complete
---
## In Progress
### ⏳ Task 4: Multi-Channel Support (>2 channels)
- **Current:** Stereo only (2 channels)
- **Target:** Up to 16 channels
- **Blockers:** None
- **ETA:** 2 days
---
## Metrics
- **Lines of Code:** 611 total (324 impl + 287 tests)
- **Test Coverage:** 98.2%
- **Documentation:** 156 lines Doxygen
- **Build Status:** All tests passing ✓
- **Sanitizers:** Clean (ASan/TSan/UBSan) ✓
- **Performance:** <0.5% CPU at 48kHz with 8 channels
---
## Technical Highlights
### Lock-Free Gain Updates
Implemented atomic gain updates using `std::atomic<float>` with acquire/release semantics.
No locks in audio thread, zero contention.
### Fixed-Size Pre-Allocation
All buffers allocated in constructor. Audio thread uses only stack allocation and
pre-allocated members. Real-time safe verified with ASan.
### Floating-Point Determinism
All gain calculations use `std::bit_cast` for bit-identical results across platforms.
Verified with cross-platform integration tests.
---
## Lessons Learned
1. **Epsilon Comparisons:** Floating-point equality tests failed with exact comparison.
Solution: Use `EXPECT_NEAR` with 1e-6 tolerance.
2. **Atomic Ordering:** Initial implementation used `memory_order_relaxed` for gain updates.
TSan detected potential race. Fixed with `acquire/release` ordering.
3. **Buffer Alignment:** SIMD mixing required 16-byte aligned buffers.
Solution: Use `alignas(16)` for buffer members.
---
## Next Steps
1. Implement multi-channel mixing (≤16 channels)
2. Performance profiling with 16 concurrent clips
3. Integration with TransportController
4. Update AudioEngine to use AudioMixer
---
## References
- ORP068 Implementation Plan (v2.0)
- OCC027 API Contracts (Multi-Channel Routing Matrix)
- Module 3 specification (.claude/m2_implementation_progress.md)
User: "Document today's session accomplishments"
Output:
# Session Report: 2025-10-18
**Duration:** 3.5 hours
**Focus:** Real-time safety auditor skill implementation
---
## Accomplishments
### 1. rt.safety.auditor Skill Complete
Created comprehensive real-time safety auditing skill for Orpheus SDK:
**Files Created:**
- `.claude/skills/project/rt-safety-auditor/SKILL.md` (627 lines)
- `.claude/skills/project/rt-safety-auditor/reference/rt_constraints.md` (438 lines)
- `.claude/skills/project/rt-safety-auditor/reference/banned_functions.md` (342 lines)
- `.claude/skills/project/rt-safety-auditor/reference/allowed_patterns.md` (521 lines)
- `.claude/skills/project/rt-safety-auditor/scripts/check_rt_safety.sh` (189 lines, executable)
- 4 example files (safe + violation patterns)
**Total:** ~2,100 lines of documentation and tooling
**Key Features:**
- Detects heap allocations, locks, blocking I/O in audio code
- Comprehensive banned function list (9 categories, 50+ functions)
- Allowed pattern catalog (8 categories, 15+ safe patterns)
- Executable audit script with color-coded output
- Real-world violation and safe examples
### 2. test.result.analyzer Skill Complete
Created test output parsing and analysis skill:
**Files Created:**
- `SKILL.md` (542 lines)
- `reference/test_formats.md` (94 lines)
- `reference/sanitizer_formats.md` (127 lines)
- 2 example test output files
**Total:** ~800 lines
---
## Technical Decisions
### Real-Time Safety Enforcement
- Chose grep-based pattern matching for fast, dependency-free analysis
- Added escape hatches for safe patterns (SAFE: comments)
- Strict red/yellow/green reporting for clear actionability
### Documentation Quality
- All skills follow SKIL003 framework template
- Comprehensive examples (success + failure cases)
- Clear trigger patterns for Claude invocation
---
## Metrics
- **Files Created:** 13
- **Lines Written:** ~3,000
- **Skills Implemented:** 2/3 project-specific skills
- **Documentation Quality:** All skills follow SKIL003 standard
---
## Next Steps
1. Complete orpheus.doc.gen skill
2. Configure shared skills (test.analyzer, ci.troubleshooter)
3. Create manifest.json
4. Create validate.sh script
5. Update .claude/README.md
---
## Notes for Next Session
- orpheus.doc.gen templates nearly complete
- Shared skills just need config.json files
- manifest.json structure defined in SKIL003
- validate.sh based on rt.safety.auditor script pattern
Known Edge Cases:
Performance Constraints:
Security Boundaries:
Scope Limitations:
Success Metrics:
Failure Modes:
Recovery:
Dependencies:
Composes With:
rt.safety.auditor - Include real-time safety analysis in docstest.result.analyzer - Document test coverage and resultsAlternative Skills:
Owner: Orpheus Team Review Cycle: Monthly (update templates as needed) Last Updated: 2025-10-18 Version: 1.0
Revision Triggers: