claude-mpm 4.17.0__tar.gz → 4.20.2__tar.gz

claude_mpm-4.20.2/BUILD_NUMBER

@@ -0,0 +1 @@
+493

{claude_mpm-4.17.0 → claude_mpm-4.20.2}/MANIFEST.in

@@ -18,6 +18,12 @@ recursive-include src/claude_mpm/agents *.md *.json
 recursive-include src/claude_mpm/agents/templates *.json
 recursive-include src/claude_mpm/framework *.md *.json
 
+# Include skills (bundled markdown files)
+recursive-include src/claude_mpm/skills/bundled *.md
+
+# Include all command files
+recursive-include src/claude_mpm/commands *.md
+
 # Include scripts
 include scripts/ticket
 include scripts/run_mpm.py

{claude_mpm-4.17.0 → claude_mpm-4.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.17.0
+Version: 4.20.2
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -31,7 +31,7 @@ Requires-Dist: requests>=2.25.0
 Requires-Dist: flask>=3.0.0
 Requires-Dist: flask-cors>=4.0.0
 Requires-Dist: watchdog>=3.0.0
-Requires-Dist: python-socketio>=5.11.0
+Requires-Dist: python-socketio>=5.14.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0
 Requires-Dist: python-engineio>=4.8.0
@@ -75,7 +75,7 @@ Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
 Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
 Provides-Extra: monitor
-Requires-Dist: python-socketio>=5.11.0; extra == "monitor"
+Requires-Dist: python-socketio>=5.14.0; extra == "monitor"
 Requires-Dist: aiohttp>=3.9.0; extra == "monitor"
 Requires-Dist: aiohttp-cors<0.8.0,>=0.7.0; extra == "monitor"
 Requires-Dist: python-engineio>=4.8.0; extra == "monitor"
@@ -160,6 +160,7 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 - 🎯 **Skills System**: 20 bundled skills with auto-linking, three-tier organization (bundled/user/project), and interactive configuration
 - 🧠 **Persistent Knowledge System**: Project-specific kuzu-memory integration for intelligent context retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume`
+- 📋 **Resume Log System**: Proactive context management with automatic 10k-token session logs at 70%/85%/95% thresholds
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 🔌 **Smart MCP Services**: Interactive auto-install for mcp-vector-search on first use (pip/pipx choice)
 - 🔍 **Semantic Code Search**: Optional vector search with graceful fallback to grep/glob
@@ -280,11 +281,26 @@ Claude MPM includes 15 specialized agents:
 
 #### Core Development
 - **Engineer** - Software development and implementation
-- **Research** - Code analysis and research  
+- **Research** - Code analysis and research
 - **Documentation** - Documentation creation and maintenance
 - **QA** - Testing and quality assurance
 - **Security** - Security analysis and implementation
 
+#### Language-Specific Engineers
+- **Python Engineer (v2.3.0)** - Type-safe, async-first Python with SOA patterns for non-trivial applications
+  - Service-oriented architecture with ABC interfaces for applications
+  - Lightweight script patterns for automation and one-off tasks
+  - Clear decision criteria for when to use DI/SOA vs simple functions
+  - Dependency injection containers with auto-resolution
+  - Use for: Web applications, microservices, data pipelines (DI/SOA) or scripts, CLI tools, notebooks (simple functions)
+
+- **Rust Engineer (v1.1.0)** - Memory-safe, high-performance systems with trait-based service architecture
+  - Dependency injection with traits (constructor injection, trait objects)
+  - Service-oriented architecture patterns (repository, builder)
+  - Decision criteria for when to use DI/SOA vs simple code
+  - Async programming with tokio and zero-cost abstractions
+  - Use for: Web services, microservices (DI/SOA) or CLI tools, scripts (simple code)
+
 #### Operations & Infrastructure
 - **Ops** - Operations and deployment with advanced git commit authority and security verification (v2.2.2+)
 - **Version Control** - Git and version management
@@ -363,6 +379,72 @@ claude-mpm cleanup-memory
 claude-mpm cleanup-memory --days 7
 ```
 
+### Resume Log System
+
+**NEW in v4.17.2** - Proactive context management for seamless session continuity.
+
+The Resume Log System automatically generates structured 10k-token logs when approaching Claude's context window limits, enabling you to resume work without losing important context.
+
+**Key Features**:
+- 🎯 **Graduated Thresholds**: Warnings at 70% (60k buffer), 85% (30k buffer), and 95% (10k buffer)
+- 📋 **Structured Logs**: 10k-token budget intelligently distributed across 7 key sections
+- 🔄 **Seamless Resumption**: Automatically loads previous session context on startup
+- 📁 **Human-Readable**: Markdown format for both Claude and human review
+- ⚙️ **Zero-Configuration**: Works automatically with sensible defaults
+
+**How It Works**:
+1. Monitor token usage continuously throughout session
+2. Display proactive warnings at 70%, 85%, and 95% thresholds
+3. Automatically generate resume log when approaching limits
+4. Load previous resume log when starting new session
+5. Continue work seamlessly with full context preservation
+
+**Example Resume Log Structure**:
+```markdown
+# Session Resume Log: 20251101_115000
+
+## Context Metrics (500 tokens)
+- Token usage and percentage
+
+## Mission Summary (1,000 tokens)
+- Overall goal and purpose
+
+## Accomplishments (2,000 tokens)
+- What was completed
+
+## Key Findings (2,500 tokens)
+- Important discoveries
+
+## Decisions & Rationale (1,500 tokens)
+- Why choices were made
+
+## Next Steps (1,500 tokens)
+- What to do next
+
+## Critical Context (1,000 tokens)
+- Essential state, IDs, paths
+```
+
+**Configuration** (`.claude-mpm/configuration.yaml`):
+```yaml
+context_management:
+  enabled: true
+  budget_total: 200000
+  thresholds:
+    caution: 0.70   # First warning - plan transition
+    warning: 0.85   # Strong warning - wrap up
+    critical: 0.95  # Urgent - stop new work
+  resume_logs:
+    enabled: true
+    auto_generate: true
+    max_tokens: 10000
+    storage_dir: ".claude-mpm/resume-logs"
+```
+
+**QA Status**: 40/41 tests passing (97.6% coverage), APPROVED FOR PRODUCTION ✅
+
+See [docs/user/resume-logs.md](docs/user/resume-logs.md) for complete documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 

{claude_mpm-4.17.0 → claude_mpm-4.20.2}/README.md

@@ -12,6 +12,7 @@ A powerful orchestration framework for **Claude Code (CLI)** that enables multi-
 - 🎯 **Skills System**: 20 bundled skills with auto-linking, three-tier organization (bundled/user/project), and interactive configuration
 - 🧠 **Persistent Knowledge System**: Project-specific kuzu-memory integration for intelligent context retention
 - 🔄 **Session Management**: Resume previous sessions with `--resume`
+- 📋 **Resume Log System**: Proactive context management with automatic 10k-token session logs at 70%/85%/95% thresholds
 - 📊 **Real-Time Monitoring**: Live dashboard with `--monitor` flag
 - 🔌 **Smart MCP Services**: Interactive auto-install for mcp-vector-search on first use (pip/pipx choice)
 - 🔍 **Semantic Code Search**: Optional vector search with graceful fallback to grep/glob
@@ -132,11 +133,26 @@ Claude MPM includes 15 specialized agents:
 
 #### Core Development
 - **Engineer** - Software development and implementation
-- **Research** - Code analysis and research  
+- **Research** - Code analysis and research
 - **Documentation** - Documentation creation and maintenance
 - **QA** - Testing and quality assurance
 - **Security** - Security analysis and implementation
 
+#### Language-Specific Engineers
+- **Python Engineer (v2.3.0)** - Type-safe, async-first Python with SOA patterns for non-trivial applications
+  - Service-oriented architecture with ABC interfaces for applications
+  - Lightweight script patterns for automation and one-off tasks
+  - Clear decision criteria for when to use DI/SOA vs simple functions
+  - Dependency injection containers with auto-resolution
+  - Use for: Web applications, microservices, data pipelines (DI/SOA) or scripts, CLI tools, notebooks (simple functions)
+
+- **Rust Engineer (v1.1.0)** - Memory-safe, high-performance systems with trait-based service architecture
+  - Dependency injection with traits (constructor injection, trait objects)
+  - Service-oriented architecture patterns (repository, builder)
+  - Decision criteria for when to use DI/SOA vs simple code
+  - Async programming with tokio and zero-cost abstractions
+  - Use for: Web services, microservices (DI/SOA) or CLI tools, scripts (simple code)
+
 #### Operations & Infrastructure
 - **Ops** - Operations and deployment with advanced git commit authority and security verification (v2.2.2+)
 - **Version Control** - Git and version management
@@ -215,6 +231,72 @@ claude-mpm cleanup-memory
 claude-mpm cleanup-memory --days 7
 ```
 
+### Resume Log System
+
+**NEW in v4.17.2** - Proactive context management for seamless session continuity.
+
+The Resume Log System automatically generates structured 10k-token logs when approaching Claude's context window limits, enabling you to resume work without losing important context.
+
+**Key Features**:
+- 🎯 **Graduated Thresholds**: Warnings at 70% (60k buffer), 85% (30k buffer), and 95% (10k buffer)
+- 📋 **Structured Logs**: 10k-token budget intelligently distributed across 7 key sections
+- 🔄 **Seamless Resumption**: Automatically loads previous session context on startup
+- 📁 **Human-Readable**: Markdown format for both Claude and human review
+- ⚙️ **Zero-Configuration**: Works automatically with sensible defaults
+
+**How It Works**:
+1. Monitor token usage continuously throughout session
+2. Display proactive warnings at 70%, 85%, and 95% thresholds
+3. Automatically generate resume log when approaching limits
+4. Load previous resume log when starting new session
+5. Continue work seamlessly with full context preservation
+
+**Example Resume Log Structure**:
+```markdown
+# Session Resume Log: 20251101_115000
+
+## Context Metrics (500 tokens)
+- Token usage and percentage
+
+## Mission Summary (1,000 tokens)
+- Overall goal and purpose
+
+## Accomplishments (2,000 tokens)
+- What was completed
+
+## Key Findings (2,500 tokens)
+- Important discoveries
+
+## Decisions & Rationale (1,500 tokens)
+- Why choices were made
+
+## Next Steps (1,500 tokens)
+- What to do next
+
+## Critical Context (1,000 tokens)
+- Essential state, IDs, paths
+```
+
+**Configuration** (`.claude-mpm/configuration.yaml`):
+```yaml
+context_management:
+  enabled: true
+  budget_total: 200000
+  thresholds:
+    caution: 0.70   # First warning - plan transition
+    warning: 0.85   # Strong warning - wrap up
+    critical: 0.95  # Urgent - stop new work
+  resume_logs:
+    enabled: true
+    auto_generate: true
+    max_tokens: 10000
+    storage_dir: ".claude-mpm/resume-logs"
+```
+
+**QA Status**: 40/41 tests passing (97.6% coverage), APPROVED FOR PRODUCTION ✅
+
+See [docs/user/resume-logs.md](docs/user/resume-logs.md) for complete documentation.
+
 ### Real-Time Monitoring
 The `--monitor` flag opens a web dashboard showing live agent activity, file operations, and session management.
 

claude_mpm-4.20.2/VERSION

@@ -0,0 +1 @@
+4.20.2

{claude_mpm-4.17.0 → claude_mpm-4.20.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.17.0"
+version = "4.20.2"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
 keywords = [ "claude", "orchestration", "multi-agent", "ticket-management",]
 classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12",]
-dependencies = [ "ai-trackdown-pytools>=1.4.0", "pyyaml>=6.0", "python-dotenv>=0.19.0", "click>=8.0.0", "pexpect>=4.8.0", "psutil>=5.9.0", "requests>=2.25.0", "flask>=3.0.0", "flask-cors>=4.0.0", "watchdog>=3.0.0", "python-socketio>=5.11.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "aiofiles>=23.0.0", "websockets>=12.0", "python-frontmatter>=1.0.0", "mistune>=3.0.0", "tree-sitter>=0.21.0", "ijson>=3.2.0", "toml>=0.10.2", "packaging>=21.0", "pydantic>=2.0.0", "pydantic-settings>=2.0.0", "rich>=13.0.0", "pyee>=13.0.0", "importlib-resources>=5.0; python_version < '3.9'", "pathspec>=0.11.0", "kuzu-memory>=1.1.5",]
+dependencies = [ "ai-trackdown-pytools>=1.4.0", "pyyaml>=6.0", "python-dotenv>=0.19.0", "click>=8.0.0", "pexpect>=4.8.0", "psutil>=5.9.0", "requests>=2.25.0", "flask>=3.0.0", "flask-cors>=4.0.0", "watchdog>=3.0.0", "python-socketio>=5.14.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "aiofiles>=23.0.0", "websockets>=12.0", "python-frontmatter>=1.0.0", "mistune>=3.0.0", "tree-sitter>=0.21.0", "ijson>=3.2.0", "toml>=0.10.2", "packaging>=21.0", "pydantic>=2.0.0", "pydantic-settings>=2.0.0", "rich>=13.0.0", "pyee>=13.0.0", "importlib-resources>=5.0; python_version < '3.9'", "pathspec>=0.11.0", "kuzu-memory>=1.1.5",]
 [[project.authors]]
 name = "Bob Matsuoka"
 email = "bob@matsuoka.com"
@@ -31,7 +31,7 @@ Documentation = "https://github.com/bobmatnyc/claude-mpm/blob/main/README.md"
 mcp = [ "mcp>=0.1.0", "mcp-vector-search>=0.1.0", "mcp-browser>=0.1.0", "mcp-ticketer>=0.1.0",]
 dev = [ "pytest>=7.0", "pytest-asyncio", "pytest-cov", "black", "flake8", "flake8-import-order", "flake8-tidy-imports", "flake8-bugbear", "ruff>=0.1.0", "pylint>=3.0.0", "pre-commit", "mypy>=1.0.0", "types-PyYAML>=6.0.0", "types-requests>=2.25.0",]
 docs = [ "sphinx>=7.2.0", "sphinx-rtd-theme>=1.3.0", "sphinx-autobuild>=2021.3.14",]
-monitor = [ "python-socketio>=5.11.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "aiofiles>=23.0.0", "websockets>=12.0",]
+monitor = [ "python-socketio>=5.14.0", "aiohttp>=3.9.0", "aiohttp-cors>=0.7.0,<0.8.0", "python-engineio>=4.8.0", "aiofiles>=23.0.0", "websockets>=12.0",]
 agents = [ "bandit>=1.7.5", "black>=23.0.0", "commitizen>=3.13.0", "dask>=2023.12.0", "detect-secrets>=1.4.0", "diagrams>=0.23.0", "docstring-parser>=0.15.0", "faker>=20.0.0", "gitlint>=0.19.0", "gitpython>=3.1.40", "hypothesis>=6.92.0", "isort>=5.12.0", "lizard>=1.17.0", "mermaid-py>=0.2.0", "mkdocs>=1.5.0", "mutmut>=2.4.0", "mypy>=1.8.0", "pandas>=2.1.0", "pre-commit>=3.5.0", "prometheus-client>=0.19.0", "pydoc-markdown>=4.8.0", "pydriller>=2.5.0", "pygments>=2.17.0", "pytest>=7.4.0", "pytest-benchmark>=4.0.0", "pytest-cov>=4.1.0", "radon>=6.0.0", "rope>=1.11.0", "sphinx>=7.2.0", "sqlalchemy>=2.0.0", "sqlparse>=0.4.4", "tree-sitter>=0.21.0", "tree-sitter-python>=0.21.0", "tree-sitter-javascript>=0.21.0", "tree-sitter-typescript>=0.21.0", "tree-sitter-go>=0.21.0", "tree-sitter-rust>=0.21.0", "tree-sitter-java>=0.21.0", "tree-sitter-cpp>=0.21.0", "tree-sitter-c>=0.21.0", "tree-sitter-ruby>=0.21.0", "tree-sitter-php>=0.21.0",]
 data-processing = [ "pandas>=2.1.0", "openpyxl>=3.1.0", "xlsxwriter>=3.1.0", "numpy>=1.24.0", "pyarrow>=14.0.0", "dask>=2023.12.0", "polars>=0.19.0", "xlrd>=2.0.0", "xlwt>=1.3.0", "csvkit>=1.3.0", "tabulate>=0.9.0", "python-dateutil>=2.8.0", "lxml>=4.9.0", "sqlalchemy>=2.0.0", "psycopg2-binary>=2.9.0", "pymongo>=4.5.0", "redis>=5.0.0", "beautifulsoup4>=4.12.0", "jsonschema>=4.19.0",]
 
@@ -84,7 +84,7 @@ ignore-imports = false
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.17.0"
+version = "4.20.2"
 version_files = [ "VERSION", "src/claude_mpm/VERSION", "package.json:version",]
 tag_format = "v$version"
 update_changelog_on_bump = true
@@ -97,7 +97,7 @@ changelog_incremental = true
 "src/claude_mpm/skills/skill_manager.py" = [ "PTH123",]
 
 [tool.setuptools.package-data]
-claude_mpm = [ "VERSION", "BUILD_NUMBER", "scripts/*", "scripts/*.sh", "commands/*.md", "dashboard/*.html", "dashboard/templates/*.html", "dashboard/static/*.css", "dashboard/static/*.js", "dashboard/static/css/*.css", "dashboard/static/js/*.js", "dashboard/static/js/components/*.js", "agents/*.md", "agents/*.json", "agents/*.yaml", "agents/templates/*.json", "agents/schema/*.json", "hooks/**/*.py", "hooks/**/*.sh", "hooks/claude_hooks/*", "hooks/claude_hooks/**/*",]
+claude_mpm = [ "VERSION", "BUILD_NUMBER", "scripts/*", "scripts/*.sh", "commands/*.md", "skills/bundled/*.md", "dashboard/*.html", "dashboard/templates/*.html", "dashboard/static/*.css", "dashboard/static/*.js", "dashboard/static/css/*.css", "dashboard/static/js/*.js", "dashboard/static/js/components/*.js", "agents/*.md", "agents/*.json", "agents/*.yaml", "agents/templates/*.json", "agents/schema/*.json", "hooks/**/*.py", "hooks/**/*.sh", "hooks/claude_hooks/*", "hooks/claude_hooks/**/*",]
 
 [tool.pytest.ini_options]
 testpaths = [ "tests",]

claude_mpm-4.20.2/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.20.2

{claude_mpm-4.17.0 → claude_mpm-4.20.2}/src/claude_mpm/agents/BASE_ENGINEER.md

@@ -262,6 +262,292 @@ Before writing ANY fix or optimization, you MUST:
 - **Test Coverage**: Minimum 80% for new code
 - **Documentation**: All public APIs must have docstrings
 
+## Engineering Quality Documentation Standards
+
+All engineers must provide comprehensive documentation for implementations. These standards ensure maintainability, knowledge transfer, and informed decision-making for future modifications.
+
+### Design Decision Documentation (MANDATORY)
+
+Every significant implementation must document:
+
+**Architectural Choices and Reasoning**
+- Explain WHY you chose this approach over alternatives
+- Document the problem context that influenced the decision
+- Link design to business requirements or technical constraints
+
+**Alternatives Considered**
+- List other approaches evaluated during design
+- Explain why each alternative was rejected
+- Note any assumptions that might invalidate the current choice
+
+**Trade-offs Analysis**
+- **Performance vs. Maintainability**: Document speed vs. readability choices
+- **Complexity vs. Flexibility**: Note when simplicity was chosen over extensibility
+- **Memory vs. Speed**: Explain resource allocation decisions
+- **Time vs. Quality**: Acknowledge technical debt taken for deadlines
+
+**Future Extensibility**
+- Identify extension points for anticipated changes
+- Document which parts are designed to be stable vs. flexible
+- Note refactoring opportunities for future consideration
+
+**Example**:
+```python
+class CacheManager:
+    """
+    Design Decision: In-memory LRU cache with TTL
+
+    Rationale: Selected in-memory caching for sub-millisecond access times
+    required by API SLA (<50ms p99 latency). Rejected Redis to avoid
+    network latency and operational complexity for this use case.
+
+    Trade-offs:
+    - Performance: O(1) access vs. Redis ~1-2ms network round-trip
+    - Scalability: Limited to single-node memory vs. distributed cache
+    - Persistence: Loses cache on restart vs. Redis durability
+
+    Alternatives Considered:
+    1. Redis: Rejected due to network latency and ops overhead
+    2. SQLite: Rejected due to disk I/O bottleneck on writes
+    3. No caching: Rejected due to database query load (2000+ QPS)
+
+    Extension Points: Cache backend interface allows future Redis migration
+    if horizontal scaling becomes necessary (>10K QPS threshold).
+    """
+```
+
+### Performance Analysis (RECOMMENDED)
+
+For algorithms and critical paths, provide:
+
+**Complexity Analysis**
+- **Time Complexity**: Big-O notation for all operations
+  - Best case, average case, worst case
+  - Explain what factors influence complexity
+- **Space Complexity**: Memory usage characteristics
+  - Auxiliary space requirements
+  - Scalability limits based on input size
+
+**Performance Metrics**
+- Expected performance for typical workloads
+- Benchmarks for critical operations
+- Comparison to previous implementation (if refactoring)
+
+**Bottleneck Identification**
+- Known performance limitations
+- Conditions that trigger worst-case behavior
+- Scalability ceilings and their causes
+
+**Example**:
+```python
+def binary_search(arr: list, target: int) -> int:
+    """
+    Find target in sorted array using binary search.
+
+    Performance:
+    - Time Complexity: O(log n) average/worst case, O(1) best case
+    - Space Complexity: O(1) iterative implementation
+
+    Expected Performance:
+    - 1M elements: ~20 comparisons maximum
+    - 1B elements: ~30 comparisons maximum
+
+    Bottleneck: Array must be pre-sorted. If frequent insertions/deletions,
+    consider balanced tree structure (O(log n) insert vs. O(n) array insert).
+    """
+```
+
+### Optimization Suggestions (RECOMMENDED)
+
+Document future improvement opportunities:
+
+**Potential Performance Improvements**
+- Specific optimizations not yet implemented
+- Conditions under which optimization becomes worthwhile
+- Estimated performance gains if implemented
+
+**Refactoring Opportunities**
+- Code structure improvements identified during implementation
+- Dependencies that could be reduced or eliminated
+- Patterns that could be extracted for reuse
+
+**Technical Debt Documentation**
+- Shortcuts taken with explanation and remediation plan
+- Areas needing cleanup or modernization
+- Test coverage gaps and plan to address
+
+**Scalability Considerations**
+- Current capacity limits and how to exceed them
+- Architectural changes needed for 10x/100x scale
+- Resource utilization projections
+
+**Example**:
+```python
+class ReportGenerator:
+    """
+    Current Implementation: Synchronous PDF generation
+
+    Optimization Opportunities:
+    1. Async Generation: Move to background queue for reports >100 pages
+       - Estimated speedup: 200ms -> 50ms API response time
+       - Requires: Celery/RQ task queue, S3 storage for results
+       - Threshold: Implement when report generation >500/day
+
+    2. Template Caching: Cache Jinja2 templates in memory
+       - Estimated speedup: 20% reduction in render time
+       - Effort: 2-4 hours, low risk
+
+    Technical Debt:
+    - TODO: Add retry logic for external API calls (currently fails fast)
+    - TODO: Implement streaming for large datasets (current limit: 10K rows)
+
+    Scalability: Current design handles ~1000 reports/day. For >5000/day,
+    migrate to async architecture with dedicated worker pool.
+    """
+```
+
+### Error Case Documentation (MANDATORY)
+
+Every implementation must document failure modes:
+
+**All Error Conditions Handled**
+- List every exception caught and why
+- Document error recovery strategies
+- Explain error propagation decisions (catch vs. propagate)
+
+**Failure Modes and Degradation**
+- What happens when external dependencies fail
+- Graceful degradation paths (if applicable)
+- Data consistency guarantees during failures
+
+**Error Messages**
+- All error messages must be actionable
+- Include diagnostic information for debugging
+- Suggest remediation steps when possible
+
+**Recovery Strategies**
+- Automatic retry logic and backoff strategies
+- Manual intervention procedures
+- Data recovery or rollback mechanisms
+
+**Example**:
+```python
+def process_payment(payment_data: dict) -> PaymentResult:
+    """
+    Process payment through external gateway.
+
+    Error Handling:
+    1. NetworkError: Retry up to 3 times with exponential backoff (1s, 2s, 4s)
+       - After retries exhausted, queue for manual review
+       - User receives "processing delayed" message
+
+    2. ValidationError: Immediate failure, no retry
+       - Returns detailed field-level errors to user
+       - Logs validation failure for fraud detection
+
+    3. InsufficientFundsError: Immediate failure, no retry
+       - Clear user message: "Payment declined - insufficient funds"
+       - No sensitive details exposed in error response
+
+    4. GatewayTimeoutError: Single retry after 5s
+       - On failure, mark transaction as "pending review"
+       - Webhook reconciliation runs hourly to check status
+
+    Failure Mode: If payment gateway is completely down, transactions
+    are queued in database with "pending" status. Background worker
+    processes queue every 5 minutes. Users notified of delay via email.
+
+    Data Consistency: Transaction state transitions are atomic. No partial
+    payments possible. Database transaction wraps payment + order update.
+    """
+```
+
+### Usage Examples (RECOMMENDED)
+
+Provide practical code examples:
+
+**Common Use Cases**
+- Show typical usage patterns for APIs
+- Include complete, runnable examples
+- Demonstrate best practices
+
+**Edge Case Handling**
+- Show how to handle boundary conditions
+- Demonstrate error handling in practice
+- Illustrate performance considerations
+
+**Integration Examples**
+- How to use with other system components
+- Configuration examples
+- Dependency setup instructions
+
+**Test Case References**
+- Point to test files demonstrating usage
+- Explain what each test validates
+- Use tests as living documentation
+
+**Example**:
+```python
+class DataValidator:
+    """
+    Validate user input against schema definitions.
+
+    Common Usage:
+        >>> validator = DataValidator(schema=user_schema)
+        >>> result = validator.validate(user_data)
+        >>> if result.is_valid:
+        >>>     process_user(result.cleaned_data)
+        >>> else:
+        >>>     return {"errors": result.errors}
+
+    Edge Cases:
+        # Handle missing required fields
+        >>> result = validator.validate({})
+        >>> result.errors  # {"email": "required field missing"}
+
+        # Handle type coercion
+        >>> result = validator.validate({"age": "25"})
+        >>> result.cleaned_data["age"]  # 25 (int, not string)
+
+    Integration with Flask:
+        @app.route('/users', methods=['POST'])
+        def create_user():
+            validator = DataValidator(schema=user_schema)
+            result = validator.validate(request.json)
+            if not result.is_valid:
+                return jsonify({"errors": result.errors}), 400
+            # ... process valid data
+
+    Tests: See tests/test_validators.py for comprehensive examples
+    - test_required_fields: Required field validation
+    - test_type_coercion: Automatic type conversion
+    - test_custom_validators: Custom validation rules
+    """
+```
+
+## Documentation Enforcement
+
+**Mandatory Reviews**
+- Code reviews must verify documentation completeness
+- PRs without proper documentation must be rejected
+- Design decisions require explicit approval
+
+**Documentation Quality Checks**
+- MANDATORY sections must be present and complete
+- RECOMMENDED sections encouraged but not blocking
+- Examples must be runnable and tested
+- Error cases must cover all catch/except blocks
+
+**Success Criteria**
+- ✅ Design rationale clearly explained
+- ✅ Trade-offs explicitly documented
+- ✅ All error conditions documented
+- ✅ At least one usage example provided
+- ✅ Complexity analysis for non-trivial algorithms
+- ❌ "Self-documenting code" without explanation
+- ❌ Generic/copied docstring templates
+- ❌ Undocumented error handling
+
 ### Implementation Patterns
 
 #### Technical Patterns