Therapeutic Sound Space Design

Therapeutic Sound-Space Design Skill

Overview

This is a production-grade Claude Code skill for Therapeutic Sound-Space Design & Applied Psychoacoustics. It transforms Claude into a domain expert that delivers structured, evidence-backed outputs by combining real-time data aggregation, recognized domain methods, and academic research into a single orchestrated workflow.

What This Skill Does

When invoked, this skill executes a 6-step analytical pipeline:

1. Requirements Gathering — Clarify therapeutic goals, user profiles, space constraints, and analysis language
2. Evidence Collection — Fetch authoritative real-time data from domain sources, standards, and recent research
3. Core Analysis — Design sound-therapy protocols, playlists, acoustic treatments, and spatial audio configurations
4. Knowledge Query — Surface academic evidence from the living knowledge base with tier labels
5. Advisory Synthesis — Generate risk-disclosed conclusions with evidence chains and remediation roadmaps
6. Quality Gate Enforcement — Verify 10 quality criteria with automatic fixes and graceful degradation

Key Features

Production-Grade Capabilities

• State Management: Persistent session state with recovery and context budget management
• Error Handling: Circuit breakers, retry mechanisms, and structured error classification
• Monitoring: Prometheus metrics, health checks, and performance monitoring
• Configuration Management: Environment variable support, validation, and secrets management
• Bilingual Support: Full English/Vietnamese language detection and output
• Self-Improving: Weekly academic crawl pipeline continuously updates the knowledge base

Quality Assurance

• 10 Quality Gates: Universal (U1-U6) plus domain-specific (G1-G4) validation
• Evidence Hierarchy: 4-tier system (Tier 1: Peer-reviewed → Tier 4: General references)
• Graceful Degradation: 5 degradation levels with explicit limitation notices
• Auto-Recovery: Automatic fixes with 2-retry maximum per gate

When to Use This Skill

Invoke this skill when the user asks about:

Core Design Tasks:

• Design a therapeutic sound space for [goal] (relaxation, focus, sleep, pain management, etc.)
• Create a curated playlist for [therapeutic outcome]
• Analyze the acoustic properties of [space] for therapy use
• Design room acoustics for [clinical/wellness setting]
• Select frequency protocols for [specific therapeutic goal]

Technical Applications:

• Binaural beat protocols for [state/condition]
• Solfeggio frequency applications for [purpose]
• Spatial audio configuration for therapy spaces
• RT60 and acoustic treatment recommendations
• Sound isolation requirements for therapy spaces

Clinical & Evidence-Based:

• Music therapy interventions for [condition/population]
• Psychoacoustic applications for [wellness goal]
• Evidence-based sound environment design
• Outcome measurement protocols for sound therapy
• Safety guidelines for therapeutic sound applications

Research & Analysis:

• Current research on [specific sound therapy topic]
• Compare acoustic treatment options for [space type]
• Academic evidence for [frequency/protocol]
• Best practices for [therapeutic sound scenario]

Input/Output Schema

Input Format

The skill accepts natural language queries. Examples:

{
  "query": "Design a relaxation room for stress reduction in a corporate wellness center",
  "context": {
    "space": "20x15 ft room with 10 ft ceiling",
    "users": "adult employees, 18-65, mixed experience",
    "constraints": ["budget: $5000", "existing HVAC noise present"],
    "language": "en"
  }
}

Output Format

The skill delivers a structured report following this template:

# [Analysis Report Title]

## Executive Summary
[Brief overview of findings and recommendation]

## Inputs & Scope
[Requirements, space parameters, user profile]

## Evidence Base
[Sources with tier labels, citation counts]

## Sound-Space Design
[Frequency protocols, playlist architecture]

## Room Acoustics
[RT60 analysis, absorption strategy, treatment recommendations]

## Spatial Audio Configuration
[Speaker layout, imaging, localization parameters]

## Outcome Measurement
[Clinical instruments, assessment protocols]

## Safety & Limitations
[Risk assessment, contraindications, usage guidelines]

## Evidence Chain
[All claims traced to sources with tier labels]

## Recommendation
[Primary verdict with confidence level]

## Implementation Roadmap
[Step-by-step guidance with timelines]

## Appendix
[Technical calculations, reference tables]

Skill Architecture

Modular Sub-Skills

The skill orchestrates 6 specialized sub-skills:

| Sub-Skill | Purpose | Key Outputs | |----------|---------|-------------| | sub-gather-requirements | Intake specialist | Structured requirements object | | sub-evidence-collector | Data librarian | Evidence bundle with tier labels | | sub-core-analysis | Sound-space designer | Protocols, playlists, acoustics | | sub-knowledge-updater | Research librarian | Academic citations with coverage | | sub-advisor | Senior advisor | Risk-disclosed verdicts |

State Management

The skill maintains a session state object throughout execution:

session:
  id: "tsd-{timestamp}-{random4}"
  lang: "vi" | "en"
  degradation_level: 0-4
  steps_completed: []
  errors_encountered: []
  retry_counts: {}
  gate_results: {}

This enables:

• Context passing between pipeline steps
• Error recovery with degradation tracking
• Token budget management
• Session persistence and recovery

Quality Gates

Universal Gates (U1-U6)

| Gate | Criterion | Purpose | |------|-----------|---------| | U1 | ≥3 sources cited, ≥1 academic/authoritative | Evidence breadth | | U2 | Safety/risk/limitation disclosure present | User protection | | U3 | Evidence hierarchy stated per source | Transparency | | U4 | Language matches user preference | Localization | | U5 | Complete output template | Completeness | | U6 | Claims traceable to sources | Accountability |

Domain Gates (G1-G4)

| Gate | Criterion | Purpose | |------|-----------|---------| | G1 | Goal-aligned frequency protocol selection | Clinical alignment | | G2 | Room acoustics designed with RT60 | Technical rigor | | G3 | Outcome measurement with safety limits | Evidence-based practice | | G4 | Music-therapy academic evidence cited | Domain grounding |

Auto-Fix Mechanisms

Each gate has defined auto-fix procedures:

• U1: Fetch additional sources if

Clean old sessions

python tools/state_manager.py cleanup --days 7

### Monitoring
```bash
# Health check
python tools/monitoring.py health --export health.json

# Metrics export
python tools/monitoring.py metrics --format prometheus --export metrics.prom

# Performance monitoring
python tools/monitoring.py performance --threshold 5000

Configuration

# Validate configuration
python tools/config_manager.py validate

# Export configuration
python tools/config_manager.py export --include-secrets

# Test environment
python tools/config_manager.py test-env

Testing

# Integration tests
python tools/integration_tests.py --output test_results.json

# Performance tests
python tools/performance_tests.py --quick

# Scenario tests
python tools/run_test_scenarios.py --all

Bilingual Support

The skill automatically detects and supports English and Vietnamese:

Detection Triggers

• Vietnamese characters: à á ả ã ạ ă â đ è é ê ì í ò ó ô ơ ù ú ư ý
• Vietnamese words: "thiết kế", "âm thanh", "trị liệu", "không gian", "tần số"
• English: Default when no Vietnamese detected

Translation Coverage

All output sections, field labels, verdict categories, and limitation banners are translated:

• Report structure (14 sections)
• Verdict taxonomy (4 categories)
• Quality gate messages
• Error recovery procedures
• Technical terminology

Development & Extension

Adding New Sub-Skills

1. Create skills/sub-.md with frontmatter
2. Define role, workflow, tools, output format, quality gates
3. Add to skills/main.md sub-skills list
4. Update harness flow to invoke the sub-skill
5. Add test scenarios to tests/test-scenarios.md

Modifying Quality Gates

1. Update gate definitions in skills/main.md
2. Add auto-fix procedures
3. Update enforcement logic
4. Add test coverage for new gate
5. Document in CLAUDE.md

Extending Knowledge Base

1. Add new section to SECOND-KNOWLEDGE-BRAIN.md
2. Update KNOWLEDGE_CONFIG in tools/knowledge_updater.py
3. Add crawl sources for new domain
4. Update scoring weights if needed
5. Test with --dry-run flag

Testing

Unit Tests

python tools/test_knowledge_updater.py

25+ tests covering hash dedup, scoring, formatting, config validation.

Integration Tests

python tools/integration_tests.py

End-to-end testing of all system components with real data flows.

Performance Tests

python tools/performance_tests.py --quick

Load testing, resource monitoring, and benchmarking.

Scenario Tests

python tools/run_test_scenarios.py --all

6 comprehensive scenarios covering all therapeutic goals, verdict categories, and degradation levels.

Deployment

Docker Deployment

# Build image
docker build -t therapeutic-sound-space-design:latest .

# Run container
docker run -p 8080:8080 -p 9090:9090 \
  -e TSD_STATE_DIR=/state \
  -e TSD_METRICS_ENABLED=true \
  therapeutic-sound-space-design:latest

Systemd Service

# Install service
sudo cp systemd/therapeutic-sound-space-design.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable therapeutic-sound-space-design
sudo systemctl start therapeutic-sound-space-design

See docs/DEPLOYMENT_GUIDE.md for comprehensive deployment procedures.

Monitoring & Observability

Health Endpoints

• /health — Overall system health
• /health/{check} — Specific health check (disk_space, memory, api)
• /metrics — Prometheus metrics

Key Metrics

• Session success rate
• Average execution time
• Gate failure rates
• Knowledge update success
• API circuit breaker state
• Token usage per session

Logging

Structured logs with levels (DEBUG, INFO, WARNING, ERROR, CRITICAL):

• logs/knowledge_update.log — Knowledge pipeline
• logs/session.log — Session execution
• logs/error.log — Error events

See docs/MONITORING_RUNBOOK.md for operational procedures.

Documentation

• [API Documentation](docs/API_DOCUMENTATION.md) — Complete API reference
• [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) — Production deployment
• [Monitoring Runbook](docs/MONITORING_RUNBOOK.md) — Operations guide
• [Contributing Guide](CONTRIBUTING.md) — Development guidelines
• [Architecture](PROJECT-detail.md) — Technical specification

License

MIT License — see [LICENSE](LICENSE).

Citation

@software{therapeutic-sound-space-design,
  title = {therapeutic-sound-space-design: Sound Therapy Space Design},
  author = {therapeutic-sound-space-design contributors},
  year = {2026},
  version = {1.0.0},
  url = {https://github.com/contributors/therapeutic-sound-space-design}
}

---

Version: 1.0.0 | Status: Production Ready | Last Updated: 2026-07-27

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dungnotnull
• Source: dungnotnull/therapeutic-sound-space-design-agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.