Initial commit

skills/cross-cutting-concerns/reference/configuration-best-practices.md

@@ -0,0 +1,6 @@
+# Configuration Best Practices
+- External config files (not hardcoded)
+- Environment-specific overrides
+- Validation at startup
+- Secure secrets (vault, env vars)
+- Document all config options

skills/cross-cutting-concerns/reference/cross-cutting-concerns-methodology.md

@@ -0,0 +1,3 @@
+# Cross-Cutting Concerns Methodology
+Universal patterns that apply across codebase: logging, error handling, config, security.
+**Approach**: Identify → Centralize → Standardize → Validate

skills/cross-cutting-concerns/reference/error-handling-best-practices.md

@@ -0,0 +1,6 @@
+# Error Handling Best Practices
+- Wrap errors with context
+- Log at boundary (not everywhere)
+- Return errors, don't panic
+- Define error taxonomy
+- Provide recovery hints

skills/cross-cutting-concerns/reference/file-tier-prioritization.md

@@ -0,0 +1,5 @@
+# File Tier Prioritization
+**Tier 1**: Changed often, high complexity → High priority
+**Tier 2**: Changed often OR complex → Medium priority
+**Tier 3**: Stable, simple → Low priority
+**Tier 4**: Dead/deprecated code → Remove

skills/cross-cutting-concerns/reference/go-adaptation.md

@@ -0,0 +1,5 @@
+# Go-Specific Adaptations
+- Error wrapping: fmt.Errorf("context: %w", err)
+- Logging: slog (structured logging)
+- Config: viper or env vars
+- Middleware: net/http middleware pattern

skills/cross-cutting-concerns/reference/javascript-adaptation.md

@@ -0,0 +1,5 @@
+# JavaScript-Specific Adaptations
+- Error handling: try/catch with async/await
+- Logging: winston or pino (structured)
+- Config: dotenv or config files
+- Middleware: Express/Koa middleware pattern

skills/cross-cutting-concerns/reference/logging-best-practices.md

@@ -0,0 +1,6 @@
+# Logging Best Practices
+- Structured logging (JSON)
+- Consistent levels (DEBUG/INFO/WARN/ERROR)
+- Include context (request ID, user, etc.)
+- Avoid PII in logs
+- Centralized logging configuration

skills/cross-cutting-concerns/reference/overview.md

@@ -0,0 +1,95 @@
+# Cross-Cutting Concerns Management - Reference
+
+This reference documentation provides comprehensive details on the cross-cutting concerns standardization methodology developed in bootstrap-013.
+
+## Core Methodology
+
+**Systematic standardization of**: Error handling, Logging, Configuration
+
+**Three Phases**:
+1. Observe (Pattern inventory, baseline metrics, gap analysis)
+2. Codify (Convention selection, infrastructure creation, linter development)
+3. Automate (Standardization, CI integration, documentation)
+
+## Five Universal Principles
+
+1. **Detect Before Standardize**: Automate identification of non-compliant code
+2. **Prioritize by Value**: High-value files first (ROI-based classification)
+3. **Infrastructure Enables Scale**: Build sentinels before standardizing call sites
+4. **Context Is King**: Enrich errors with operation + resource + type + guidance
+5. **Automate Enforcement**: CI blocks non-compliant code
+
+## Knowledge Artifacts
+
+All knowledge artifacts from bootstrap-013 are documented in:
+`experiments/bootstrap-013-cross-cutting-concerns/knowledge/`
+
+**Best Practices** (3):
+- Go Logging (13 practices)
+- Go Error Handling (13 practices)
+- Go Configuration (14 practices)
+
+**Templates** (3):
+- Logger Setup (log/slog initialization)
+- Error Handling Template (sentinel errors, wrapping, context)
+- Config Management Template (centralized config, validation)
+
+## File Tier Prioritization
+
+**Tier 1 (ROI > 10x)**: User-facing APIs, public interfaces, error infrastructure
+- **Strategy**: Standardize 100%
+- **Example**: capabilities.go (16.7x ROI, 25.5% value gain)
+
+**Tier 2 (ROI 5-10x)**: Internal services, CLI commands, data processors
+- **Strategy**: Selective standardization 50-80%
+- **Example**: Internal utilities (8.3x ROI, 6% value gain)
+
+**Tier 3 (ROI < 5x)**: Test utilities, stubs, deprecated code
+- **Strategy**: Defer or skip 0-20%
+- **Example**: Stubs (3x ROI, 1% value gain) - deferred
+
+## Effectiveness Validation
+
+**Error Diagnosis Speed**: 60-75% faster with rich context
+
+**ROI by Tier**:
+- Tier 1: 16.7x ROI
+- Tier 2: 8.3x ROI
+- Tier 3: 3x ROI (deferred)
+
+**CI Enforcement**:
+- Setup time: 20 minutes
+- Regression rate: 0%
+- Ongoing maintenance: 0 hours (fully automated)
+
+## Transferability
+
+**Overall**: 80-90% transferable across languages
+
+**Language-Specific Adaptations**:
+- Go: 90% (log/slog, fmt.Errorf %w, os.Getenv)
+- Python: 80-85% (logging, raise...from, os.environ)
+- JavaScript: 75-80% (winston, Error.cause, process.env)
+- Rust: 85-90% (tracing, anyhow, thiserror)
+
+**Universal Components** (100%):
+- 5 universal principles
+- File tier prioritization framework
+- ROI calculation method
+- Context enrichment structure (operation + resource + type + guidance)
+
+**Language-Specific** (10-20%):
+- Specific libraries/tools
+- Syntax variations
+- Error wrapping mechanisms
+
+## Experiment Results
+
+See full results: `experiments/bootstrap-013-cross-cutting-concerns/` (in progress)
+
+**Key Metrics**:
+- Error handling: 70% → 90% consistency (Tier 1)
+- Logging: 0.7% → 90% adoption
+- Configuration: 40% → 80% centralized
+- ROI: 16.7x for Tier 1, 8.3x for Tier 2
+- Diagnosis speed: 60-75% improvement

skills/cross-cutting-concerns/reference/pattern-extraction-workflow.md

@@ -0,0 +1,6 @@
+# Pattern Extraction Workflow
+1. Identify repeated code (≥3 occurrences)
+2. Extract commonality
+3. Create reusable component
+4. Replace all usages
+5. Add tests for component

skills/cross-cutting-concerns/reference/python-adaptation.md

@@ -0,0 +1,5 @@
+# Python-Specific Adaptations
+- Error handling: try/except with logging
+- Logging: logging module (structured with extra={})
+- Config: python-decouple or pydantic
+- Decorators for cross-cutting (e.g., @retry, @log)

skills/cross-cutting-concerns/reference/rust-adaptation.md

@@ -0,0 +1,5 @@
+# Rust-Specific Adaptations
+- Error handling: Result<T, E> with thiserror/anyhow
+- Logging: tracing crate (structured)
+- Config: config-rs or figment
+- Error wrapping: context() from anyhow

skills/cross-cutting-concerns/reference/universal-principles.md

@@ -0,0 +1,6 @@
+# Universal Principles
+1. **Consistency**: Same pattern everywhere
+2. **Centralization**: One place to change
+3. **Observability**: Log, trace, measure
+4. **Fail-safe**: Graceful degradation
+5. **Configuration**: External, not hardcoded