Initial commit

skills/c4model-observations/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: c4model-observations
+description: Use when documenting observations, architectural findings, or discoveries across C4 Model levels (C1, C2, C3). Triggers include "observations", "findings", "document architecture", "security concerns", "performance issues", "quality attributes". Creates structured observations for c1-systems.json, c2-containers.json, and c3-components.json files with evidence, severity levels, and recommendations.
+---
+
+# C4 Model - Observation Documentation Methodology
+
+## Overview
+
+This skill provides methodology for identifying, categorizing, and documenting architectural observations across all C4 Model levels (C1, C2, C3).
+
+**Mission:** Document WHAT you observe about systems, containers, and components—factual findings that inform architectural understanding.
+
+---
+
+## When to Use
+
+- Documenting architectural findings during code analysis
+- Categorizing security, performance, or quality issues
+- Creating structured observations for C4 model documentation
+- Recording evidence with file paths and code snippets
+
+## When NOT to Use
+
+- Writing C4 diagrams themselves (use c4model-c1/c2/c3)
+- Documenting relationships between entities (use c4model-relations)
+- General code documentation without architectural significance
+
+---
+
+## What is an Observation?
+
+An **observation** is a factual finding about an entity that describes:
+
+- Architectural characteristics, patterns, and decisions
+- Technical details, technologies, frameworks
+- Quality attributes like performance, scalability, maintainability
+- Security concerns and vulnerabilities
+- Design decisions and their rationale
+- Performance patterns and bottlenecks
+
+**Observations are facts, not opinions.** Document what you see in the code, configuration, and architecture.
+
+---
+
+## Observation Structure
+
+### Required Fields
+
+```json
+{
+  "id": "obs-unique-identifier",
+  "category": "architecture|technology|security|...",
+  "severity": "critical|warning|info",
+  "title": "Short descriptive title (max 100 chars)",
+  "description": "Detailed description of what was observed"
+}
+```
+
+### Optional Fields (Recommended)
+
+```json
+{
+  "evidence": [
+    {
+      "type": "file|code|config|pattern|metric|dependency",
+      "location": "path/to/file.js:45-52",
+      "snippet": "code excerpt or config value",
+      "note": "additional context"
+    }
+  ],
+  "tags": ["searchable", "keywords"],
+  "impact": "What this means for the system",
+  "recommendation": "Suggested action (for warnings/critical)"
+}
+```
+
+---
+
+## Severity Levels
+
+**Critical** - Immediate attention required:
+- Security vulnerabilities, data loss risks, system unavailability
+
+**Warning** - Should be addressed:
+- Performance bottlenecks, code quality issues, anti-patterns
+
+**Info** - Informational or positive findings:
+- Design patterns, technology stack, good practices
+
+---
+
+## Evidence Types
+
+| Type | Usage | Example |
+|------|-------|---------|
+| `file` | File paths, directory structure | `package.json` |
+| `code` | Code snippets | `localStorage.setItem('token', jwt)` |
+| `config` | Configuration values | `DATABASE_URL=...` |
+| `pattern` | Architectural patterns | `Repository pattern` |
+| `metric` | Measurements | `Complexity: 45` |
+| `dependency` | Package dependencies | `"express": "^4.18.0"` |
+
+---
+
+## Categories by Level
+
+| Level | Categories |
+|-------|------------|
+| **C1** | `architecture`, `integration`, `boundaries`, `security`, `scalability`, `actors`, `external-dependencies`, `deployment`, `data-flow` |
+| **C2** | `technology`, `runtime`, `communication`, `data-storage`, `authentication`, `deployment`, `scalability`, `performance`, `dependencies`, `configuration`, `monitoring`, `security` |
+| **C3** | `design-patterns`, `code-structure`, `dependencies`, `error-handling`, `testing`, `performance`, `security`, `code-quality`, `documentation`, `complexity`, `coupling`, `cohesion`, `maintainability` |
+
+See [categories.md](categories.md) for detailed definitions.
+
+---
+
+## Quick Examples
+
+**C3 Component (Critical):**
+```json
+{
+  "id": "obs-jwt-localstorage",
+  "category": "security",
+  "severity": "critical",
+  "title": "JWT tokens stored in localStorage",
+  "description": "Tokens in localStorage are vulnerable to XSS attacks.",
+  "evidence": [
+    {"type": "code", "location": "src/auth/storage.ts:45", "snippet": "localStorage.setItem('token', jwt)"}
+  ],
+  "recommendation": "Use httpOnly cookies for token storage"
+}
+```
+
+**C2 Container (Warning):**
+```json
+{
+  "id": "obs-no-connection-pool",
+  "category": "performance",
+  "severity": "warning",
+  "title": "Database connections not pooled",
+  "description": "New connection created for each request, causing overhead.",
+  "evidence": [
+    {"type": "code", "location": "src/db/connection.ts:12", "snippet": "new Client(config)"}
+  ],
+  "recommendation": "Implement connection pooling with pg-pool"
+}
+```
+
+**C1 System Context (Info):**
+```json
+{
+  "id": "obs-event-driven-arch",
+  "category": "architecture",
+  "severity": "info",
+  "title": "Event-driven architecture with message queues",
+  "description": "System uses RabbitMQ for async processing, enabling loose coupling.",
+  "evidence": [
+    {"type": "config", "location": "docker-compose.yml", "snippet": "rabbitmq:..."}
+  ],
+  "impact": "Enables horizontal scaling and resilience"
+}
+```
+
+See [examples.md](examples.md) for 30+ complete examples across all levels.
+
+---
+
+## Best Practices
+
+1. **Be specific** - Detailed descriptions with concrete evidence
+2. **Choose correct severity** - Critical for security/data issues, warning for should-fix, info for neutral
+3. **Provide evidence** - Always include file paths and code snippets
+4. **Use proper categories** - Match category to C4 level (C1/C2/C3)
+5. **Add impact and recommendations** - For warnings and critical issues
+6. **Include tags** - Aid searchability and cross-referencing
+
+---
+
+## Detailed Reference
+
+For comprehensive methodology:
+
+- **[reference.md](reference.md)** - Category definitions, evidence guidelines, best practices
+- **[examples.md](examples.md)** - 30+ examples across C1, C2, C3 levels
+- **[categories.md](categories.md)** - Complete category reference by level
+
+---
+
+## Common Mistakes
+
+1. **Opinion instead of fact** - Document observations, not judgments ("poorly designed" vs "tight coupling between modules")
+2. **Vague descriptions** - Be specific with file paths and evidence
+3. **Wrong severity** - Critical for security/data loss, warning for should-fix, info for neutral findings
+4. **Wrong category level** - Use C1 categories at C1 level, C3 at C3 level
+
+---
+
+## Integration
+
+Observations are used by:
+- **Abstractor agents** (c1/c2/c3) - Generate observations during analysis
+- **c4model-writer** - Convert observations to markdown docs
+- **Validation scripts** - Validate structure and content
+- **basic-memory MCP** - Search and retrieve observations
+
+---
+
+## Related Skills
+
+- **c4model-c1** - C1 System Context methodology
+- **c4model-c2** - C2 Container methodology
+- **c4model-c3** - C3 Component methodology
+- **c4model-relations** - Relationship documentation methodology

skills/c4model-observations/categories.md

@@ -0,0 +1,513 @@
+# Observation Categories Reference
+
+**Quick reference guide for observation categories across C1, C2, and C3 levels.**
+
+---
+
+## Table of Contents
+
+1. [C1 System Context Categories](#c1-system-context-categories)
+2. [C2 Container Categories](#c2-container-categories)
+3. [C3 Component Categories](#c3-component-categories)
+4. [Category Selection Guide](#category-selection-guide)
+
+---
+
+## C1 System Context Categories
+
+**Focus:** System-level architecture, external integrations, and high-level concerns.
+
+### architecture
+**Use for:** Overall system patterns, architectural styles, strategic decisions
+**Examples:**
+- Event-driven architecture with message queues
+- Microservices architecture with API gateway
+- Monolithic layered architecture
+- CQRS pattern implementation
+
+---
+
+### integration
+**Use for:** How systems communicate and integrate with each other
+**Examples:**
+- REST API communication over HTTPS
+- GraphQL gateway for unified access
+- Event-driven integration via message queues
+- Service mesh for inter-service communication
+
+---
+
+### boundaries
+**Use for:** System scope, ownership, organizational limits
+**Examples:**
+- System boundary includes web app and API
+- Frontend team owns UI, backend team owns API
+- Deployment boundary per service
+- Network boundary: public vs private subnets
+
+---
+
+### security
+**Use for:** System-level security, authentication, authorization
+**Examples:**
+- OAuth2 authentication via Auth0
+- JWT-based authentication
+- No rate limiting on public endpoints
+- TLS encryption for all communications
+
+---
+
+### scalability
+**Use for:** System's ability to scale and handle growth
+**Examples:**
+- Horizontally scalable via Kubernetes
+- Auto-scaling based on CPU metrics
+- Database sharding for horizontal scaling
+- Stateless design enables cloud scaling
+
+---
+
+### actors
+**Use for:** User types, roles, external actors
+**Examples:**
+- Three user roles: Customer, Admin, Support
+- External audit system queries via API
+- Mobile app acts as user of REST API
+- Third-party integrations as system actors
+
+---
+
+### external-dependencies
+**Use for:** Third-party systems, critical external services
+**Examples:**
+- Stripe payment gateway (critical)
+- SendGrid email service with AWS SES fallback
+- Auth0 for authentication (no fallback)
+- Snowflake data warehouse for analytics
+
+---
+
+### deployment
+**Use for:** Infrastructure, hosting, deployment strategies
+**Examples:**
+- AWS ECS Fargate deployment
+- Kubernetes with blue-green deployments
+- Multi-region active-active setup
+- Infrastructure as code with Terraform
+
+---
+
+### data-flow
+**Use for:** How data moves between systems
+**Examples:**
+- User data flows: web → API → database
+- Analytics pipeline: app → Kafka → warehouse
+- Batch ETL nightly to data lake
+- Real-time streaming to analytics platform
+
+---
+
+## C2 Container Categories
+
+**Focus:** Deployable units, runtime characteristics, technology stack.
+
+### technology
+**Use for:** Tech stack, frameworks, libraries, languages
+**Examples:**
+- React 18 SPA with Redux Toolkit
+- Node.js 18 with Express.js
+- Python FastAPI with SQLAlchemy
+- .NET 7 with Entity Framework Core
+
+---
+
+### runtime
+**Use for:** Runtime environment and characteristics
+**Examples:**
+- Node.js event loop (single-threaded)
+- JVM with 4GB heap configuration
+- Python 3.11 with uvicorn ASGI server
+- Requires 16 environment variables
+
+---
+
+### communication
+**Use for:** Inter-container protocols and patterns
+**Examples:**
+- REST API with JSON payloads
+- gRPC with Protobuf serialization
+- WebSocket for real-time updates
+- Message queue for async communication
+
+---
+
+### data-storage
+**Use for:** Databases, caches, storage mechanisms
+**Examples:**
+- PostgreSQL 14 for relational data
+- Redis for session and caching
+- MongoDB for document storage
+- S3 for file storage
+
+---
+
+### authentication
+**Use for:** Container-level auth and authorization
+**Examples:**
+- JWT bearer token authentication
+- Session cookies with Redis storage
+- API key for service-to-service auth
+- OAuth2 client credentials flow
+
+---
+
+### deployment
+**Use for:** Containerization, orchestration, deployment
+**Examples:**
+- Docker container on Kubernetes
+- Health check at /health endpoint
+- Blue-green deployment via ArgoCD
+- Auto-scaling 2-10 replicas
+
+---
+
+### scalability
+**Use for:** Container scaling capabilities
+**Examples:**
+- Horizontal pod autoscaling based on CPU
+- Stateless design enables replication
+- Limited by database connection pool
+- Scales independently of other services
+
+---
+
+### performance
+**Use for:** Container performance characteristics
+**Examples:**
+- Average response time: 50ms
+- Code splitting and lazy loading
+- Caching strategy reduces DB load
+- No query optimization with indexes
+
+---
+
+### dependencies
+**Use for:** Container dependencies on others
+**Examples:**
+- Depends on API container and Redis
+- Critical dependency on PostgreSQL
+- Loose coupling via message queue
+- No direct database dependencies
+
+---
+
+### configuration
+**Use for:** Configuration management approaches
+**Examples:**
+- Environment variables for config
+- Kubernetes ConfigMaps and Secrets
+- Feature flags in LaunchDarkly
+- Config validation on startup
+
+---
+
+### monitoring
+**Use for:** Observability, logging, monitoring
+**Examples:**
+- Winston logger with JSON format
+- Prometheus metrics at /metrics
+- OpenTelemetry distributed tracing
+- No structured logging implemented
+
+---
+
+### security
+**Use for:** Container-level security implementation
+**Examples:**
+- Container runs as non-root user
+- Security scanning with Trivy
+- Secrets injected via Kubernetes
+- HTTPS only, no HTTP allowed
+
+---
+
+## C3 Component Categories
+
+**Focus:** Code-level implementation, patterns, quality.
+
+### design-patterns
+**Use for:** Design patterns in code
+**Examples:**
+- Repository pattern for data access
+- Factory pattern for service creation
+- Singleton pattern for configuration
+- Observer pattern for event handling
+
+---
+
+### code-structure
+**Use for:** Code organization and modularity
+**Examples:**
+- Feature-based directory structure
+- Layered architecture: controllers/services/repositories
+- Domain-driven design modules
+- Clean separation of concerns
+
+---
+
+### dependencies
+**Use for:** Component imports and coupling
+**Examples:**
+- Dependency injection via constructor
+- Circular dependency between modules
+- Interface-based dependencies
+- Heavy reliance on utility modules
+
+---
+
+### error-handling
+**Use for:** Error handling strategies
+**Examples:**
+- Try-catch blocks in async operations
+- Global error handler middleware
+- Custom error classes for domain errors
+- No error handling in critical paths
+
+---
+
+### testing
+**Use for:** Test coverage and quality
+**Examples:**
+- 95% unit test coverage with Jest
+- Integration tests for API endpoints
+- No tests for edge cases
+- Tests use mocks appropriately
+
+---
+
+### performance
+**Use for:** Algorithm efficiency, optimization
+**Examples:**
+- O(n²) algorithm for data processing
+- Memoization for expensive calculations
+- N+1 query problem in data loading
+- Efficient caching of computed values
+
+---
+
+### security
+**Use for:** Security implementation in code
+**Examples:**
+- SQL injection vulnerability
+- JWT tokens in localStorage (XSS risk)
+- Input validation with Joi
+- Output encoding prevents XSS
+
+---
+
+### code-quality
+**Use for:** Code quality metrics
+**Examples:**
+- High cyclomatic complexity (>20)
+- Consistent naming conventions
+- Significant code duplication
+- Clean, readable code
+
+---
+
+### documentation
+**Use for:** Code documentation quality
+**Examples:**
+- Comprehensive JSDoc/TSDoc
+- README files for each module
+- No documentation for complex logic
+- Inline comments explain why, not what
+
+---
+
+### complexity
+**Use for:** Code complexity measurements
+**Examples:**
+- Function cyclomatic complexity: 45
+- Deep nesting (6 levels) in conditionals
+- Functions average 150 lines
+- Cognitive complexity manageable
+
+---
+
+### coupling
+**Use for:** Interdependence between components
+**Examples:**
+- Tight coupling to ORM throughout
+- Loose coupling via interfaces
+- Direct database access in UI
+- Service layer properly abstracted
+
+---
+
+### cohesion
+**Use for:** How related component responsibilities are
+**Examples:**
+- High cohesion: single responsibility
+- Low cohesion: mixed concerns
+- Each module has clear focus
+- Service handles auth, logging, config (bad)
+
+---
+
+### maintainability
+**Use for:** How easy to maintain and modify
+**Examples:**
+- High maintainability with clean separation
+- Technical debt: hardcoded values
+- Difficult to modify due to coupling
+- Well-structured, easy to understand
+
+---
+
+## Category Selection Guide
+
+### Decision Tree
+
+**Question 1: What C4 level are you documenting?**
+
+- **C1 (System Context)** → Use C1 categories
+- **C2 (Container)** → Use C2 categories
+- **C3 (Component)** → Use C3 categories
+
+---
+
+**Question 2: What aspect are you observing?**
+
+#### C1 Level
+
+| Observation About | Use Category |
+|-------------------|--------------|
+| Overall architecture pattern | `architecture` |
+| How systems communicate | `integration` |
+| What's in/out of system | `boundaries` |
+| System-level auth/security | `security` |
+| Scaling approach | `scalability` |
+| Who uses the system | `actors` |
+| Third-party services | `external-dependencies` |
+| Where/how deployed | `deployment` |
+| How data moves | `data-flow` |
+
+---
+
+#### C2 Level
+
+| Observation About | Use Category |
+|-------------------|--------------|
+| Languages, frameworks | `technology` |
+| Runtime environment | `runtime` |
+| Container communication | `communication` |
+| Databases, storage | `data-storage` |
+| Auth mechanisms | `authentication` |
+| Containerization | `deployment` |
+| Container scaling | `scalability` |
+| Container performance | `performance` |
+| Container dependencies | `dependencies` |
+| Config management | `configuration` |
+| Logging, metrics | `monitoring` |
+| Container security | `security` |
+
+---
+
+#### C3 Level
+
+| Observation About | Use Category |
+|-------------------|--------------|
+| Design patterns used | `design-patterns` |
+| Code organization | `code-structure` |
+| Imports, dependencies | `dependencies` |
+| Error handling approach | `error-handling` |
+| Tests, coverage | `testing` |
+| Algorithms, optimization | `performance` |
+| Security in code | `security` |
+| Code quality metrics | `code-quality` |
+| Documentation | `documentation` |
+| Code complexity | `complexity` |
+| Component coupling | `coupling` |
+| Component cohesion | `cohesion` |
+| How easy to maintain | `maintainability` |
+
+---
+
+## Common Mistakes
+
+### Using Wrong Level Category
+
+❌ **Wrong:**
+```json
+{
+  "level": "C1",
+  "category": "code-quality"  // C3 category!
+}
+```
+
+✅ **Right:**
+```json
+{
+  "level": "C1",
+  "category": "architecture"  // C1 category
+}
+```
+
+---
+
+### Too Granular for Level
+
+❌ **Wrong (C1):**
+```json
+{
+  "category": "architecture",
+  "title": "Repository pattern in UserService"  // Too detailed!
+}
+```
+
+✅ **Right (C1):**
+```json
+{
+  "category": "architecture",
+  "title": "Microservices architecture with API gateway"
+}
+```
+
+---
+
+### Not Granular Enough
+
+❌ **Wrong (C3):**
+```json
+{
+  "category": "design-patterns",
+  "title": "Microservices architecture"  // Too high-level!
+}
+```
+
+✅ **Right (C3):**
+```json
+{
+  "category": "design-patterns",
+  "title": "Repository pattern for data access"
+}
+```
+
+---
+
+## Category Counts
+
+- **C1 System Context**: 9 categories
+- **C2 Container**: 12 categories
+- **C3 Component**: 13 categories
+
+**Total**: 34 categories across all levels
+
+---
+
+## Related Resources
+
+- **[SKILL.md](SKILL.md)** - Main skill documentation
+- **[reference.md](reference.md)** - Comprehensive methodology
+- **[examples.md](examples.md)** - 30+ examples with categories

skills/c4model-observations/examples.md

@@ -0,0 +1,901 @@
+# Observation Examples
+
+**30+ real-world examples across C1, C2, and C3 levels.**
+
+---
+
+## Table of Contents
+
+1. [C1 System Context Examples](#c1-system-context-examples)
+2. [C2 Container Examples](#c2-container-examples)
+3. [C3 Component Examples](#c3-component-examples)
+
+---
+
+## C1 System Context Examples
+
+### Example 1: Event-Driven Architecture
+
+```json
+{
+  "id": "obs-event-driven-arch",
+  "category": "architecture",
+  "severity": "info",
+  "title": "Event-driven architecture with message queues",
+  "description": "The system uses event-driven architecture with RabbitMQ message queues for asynchronous processing between services. This enables loose coupling and improved scalability.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "docker-compose.yml",
+      "snippet": "rabbitmq:\n  image: rabbitmq:3-management\n  ports:\n    - '5672:5672'\n    - '15672:15672'",
+      "note": "RabbitMQ configured as message broker"
+    },
+    {
+      "type": "dependency",
+      "location": "backend/package.json",
+      "snippet": "\"amqplib\": \"^0.10.3\"",
+      "note": "AMQP library for queue integration"
+    }
+  ],
+  "tags": ["architecture", "messaging", "async", "rabbitmq"],
+  "impact": "Enables horizontal scaling and system resilience. Services can process events asynchronously without blocking."
+}
+```
+
+---
+
+### Example 2: Third-Party Payment Dependency
+
+```json
+{
+  "id": "obs-third-party-payment",
+  "category": "external-dependencies",
+  "severity": "warning",
+  "title": "Critical dependency on third-party payment gateway",
+  "description": "System has a hard dependency on Stripe payment gateway with no fallback mechanism. Stripe outages directly impact payment processing capability.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/services/payment.ts:23",
+      "snippet": "const stripe = new Stripe(process.env.STRIPE_KEY);",
+      "note": "Direct Stripe integration with no abstraction layer"
+    },
+    {
+      "type": "file",
+      "location": "src/services/payment.ts",
+      "note": "Single payment provider implementation, no interface"
+    }
+  ],
+  "tags": ["external-dependency", "payments", "stripe", "resilience"],
+  "impact": "System unavailable for payments during Stripe outages. No ability to switch payment providers.",
+  "recommendation": "Implement payment gateway abstraction layer to support multiple providers (Stripe, PayPal, Square) with failover capability."
+}
+```
+
+---
+
+### Example 3: Microservices Architecture
+
+```json
+{
+  "id": "obs-microservices-pattern",
+  "category": "architecture",
+  "severity": "info",
+  "title": "Microservices architecture with API gateway",
+  "description": "System follows microservices architecture pattern with Kong API gateway routing requests to independent services (user-service, product-service, order-service).",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "kong/kong.yml",
+      "snippet": "services:\n  - name: user-service\n    url: http://user-api:3000\n  - name: product-service\n    url: http://product-api:3001",
+      "note": "Kong gateway configuration"
+    },
+    {
+      "type": "pattern",
+      "location": "repos/",
+      "note": "Separate repositories for each service: user-service/, product-service/, order-service/"
+    }
+  ],
+  "tags": ["architecture", "microservices", "api-gateway", "kong"],
+  "impact": "Enables independent deployment and scaling of services. Increases operational complexity."
+}
+```
+
+---
+
+### Example 4: Public API Without Rate Limiting
+
+```json
+{
+  "id": "obs-no-rate-limiting",
+  "category": "security",
+  "severity": "critical",
+  "title": "Public API lacks rate limiting",
+  "description": "REST API is publicly accessible without rate limiting, making it vulnerable to denial-of-service attacks and API abuse.",
+  "evidence": [
+    {
+      "type": "file",
+      "location": "src/middleware/",
+      "note": "No rate limiting middleware found"
+    },
+    {
+      "type": "config",
+      "location": "package.json",
+      "note": "No rate limiting library installed (express-rate-limit, rate-limiter-flexible)"
+    }
+  ],
+  "tags": ["security", "rate-limiting", "dos", "api"],
+  "impact": "System vulnerable to denial-of-service attacks, API abuse, and resource exhaustion.",
+  "recommendation": "Implement rate limiting using express-rate-limit or API gateway rate limiting policies."
+}
+```
+
+---
+
+### Example 5: OAuth2 Authentication
+
+```json
+{
+  "id": "obs-oauth2-integration",
+  "category": "integration",
+  "severity": "info",
+  "title": "OAuth2 authentication via Auth0",
+  "description": "System integrates with Auth0 for OAuth2 authentication, supporting social login (Google, Facebook, GitHub) and enterprise SSO.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": ".env.example",
+      "snippet": "AUTH0_DOMAIN=example.auth0.com\nAUTH0_CLIENT_ID=xxx\nAUTH0_CALLBACK_URL=https://app.example.com/callback"
+    },
+    {
+      "type": "dependency",
+      "location": "frontend/package.json",
+      "snippet": "\"@auth0/auth0-react\": \"^2.0.1\""
+    }
+  ],
+  "tags": ["authentication", "oauth2", "auth0", "sso"],
+  "impact": "Enables enterprise SSO and social login. Reduces authentication implementation complexity."
+}
+```
+
+---
+
+### Example 6: Multi-Tenant Architecture
+
+```json
+{
+  "id": "obs-multi-tenant-saas",
+  "category": "architecture",
+  "severity": "info",
+  "title": "Multi-tenant SaaS architecture with tenant isolation",
+  "description": "System implements multi-tenant architecture with database-per-tenant isolation strategy. Each customer organization has a dedicated PostgreSQL schema.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/db/tenant.ts:34-38",
+      "snippet": "const schema = `tenant_${tenantId}`;\nawait db.raw(`SET search_path TO ${schema}`);\nreturn db;",
+      "note": "Schema-based tenant isolation"
+    },
+    {
+      "type": "pattern",
+      "location": "src/middleware/tenant-context.ts",
+      "note": "Middleware extracts tenant from subdomain and sets context"
+    }
+  ],
+  "tags": ["architecture", "multi-tenant", "saas", "isolation"],
+  "impact": "Strong tenant data isolation. Schema-per-tenant approach may limit scalability with thousands of tenants."
+}
+```
+
+---
+
+### Example 7: Cloud-Native Deployment
+
+```json
+{
+  "id": "obs-cloud-native-aws",
+  "category": "deployment",
+  "severity": "info",
+  "title": "Cloud-native deployment on AWS with auto-scaling",
+  "description": "System deployed on AWS using ECS Fargate for container orchestration with auto-scaling based on CPU and memory metrics.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "infrastructure/terraform/ecs.tf",
+      "snippet": "resource \"aws_appautoscaling_target\" \"ecs_target\" {\n  max_capacity = 10\n  min_capacity = 2\n  resource_id = aws_ecs_service.main.id\n}",
+      "note": "Terraform configuration for ECS auto-scaling"
+    },
+    {
+      "type": "file",
+      "location": "infrastructure/terraform/",
+      "note": "Infrastructure as code using Terraform"
+    }
+  ],
+  "tags": ["deployment", "aws", "ecs", "auto-scaling", "cloud-native"],
+  "impact": "Enables automatic scaling based on demand. Reduces infrastructure management overhead."
+}
+```
+
+---
+
+### Example 8: Data Lake Integration
+
+```json
+{
+  "id": "obs-data-lake-snowflake",
+  "category": "data-flow",
+  "severity": "info",
+  "title": "Batch data export to Snowflake data lake",
+  "description": "System exports operational data to Snowflake data lake nightly for analytics and reporting. ETL pipeline implemented using Apache Airflow.",
+  "evidence": [
+    {
+      "type": "file",
+      "location": "airflow/dags/export-to-snowflake.py",
+      "note": "Airflow DAG for nightly data export"
+    },
+    {
+      "type": "config",
+      "location": "airflow/config/connections.yml",
+      "snippet": "snowflake_conn:\n  conn_type: snowflake\n  account: xy12345\n  database: analytics_db"
+    }
+  ],
+  "tags": ["data-flow", "etl", "snowflake", "analytics", "airflow"],
+  "impact": "Enables advanced analytics and reporting without impacting operational database performance."
+}
+```
+
+---
+
+### Example 9: Service Mesh Implementation
+
+```json
+{
+  "id": "obs-istio-service-mesh",
+  "category": "integration",
+  "severity": "info",
+  "title": "Istio service mesh for service-to-service communication",
+  "description": "Microservices communicate through Istio service mesh providing mTLS encryption, traffic management, and observability.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "k8s/istio/virtual-service.yml",
+      "snippet": "apiVersion: networking.istio.io/v1beta1\nkind: VirtualService\nmetadata:\n  name: user-service"
+    },
+    {
+      "type": "pattern",
+      "location": "k8s/",
+      "note": "Istio sidecar proxies injected into all service pods"
+    }
+  ],
+  "tags": ["integration", "service-mesh", "istio", "mtls", "microservices"],
+  "impact": "Provides mTLS encryption, circuit breaking, and distributed tracing without application code changes."
+}
+```
+
+---
+
+### Example 10: Geographic Distribution
+
+```json
+{
+  "id": "obs-multi-region-active-active",
+  "category": "scalability",
+  "severity": "info",
+  "title": "Multi-region active-active deployment for global users",
+  "description": "System deployed in active-active configuration across US-East, US-West, and EU-Central regions with Route53 latency-based routing.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "infrastructure/terraform/route53.tf",
+      "snippet": "routing_policy = \"latency\"\nset_identifier = \"us-east-1\""
+    },
+    {
+      "type": "pattern",
+      "location": "infrastructure/",
+      "note": "Three Terraform workspaces: us-east, us-west, eu-central"
+    }
+  ],
+  "tags": ["scalability", "multi-region", "global", "high-availability"],
+  "impact": "Reduces latency for global users. Provides regional failover capability. Increases infrastructure cost and complexity."
+}
+```
+
+---
+
+## C2 Container Examples
+
+### Example 11: React SPA with State Management
+
+```json
+{
+  "id": "obs-spa-state-mgmt",
+  "category": "technology",
+  "severity": "info",
+  "title": "Redux Toolkit for state management in React SPA",
+  "description": "Frontend SPA uses Redux Toolkit for global state management, following best practices with feature-based slices and RTK Query for API calls.",
+  "evidence": [
+    {
+      "type": "dependency",
+      "location": "frontend/package.json",
+      "snippet": "\"@reduxjs/toolkit\": \"^1.9.5\",\n\"react-redux\": \"^8.1.1\""
+    },
+    {
+      "type": "file",
+      "location": "frontend/src/store/",
+      "note": "Well-organized store structure with feature slices: authSlice, userSlice, productSlice"
+    },
+    {
+      "type": "code",
+      "location": "frontend/src/store/index.ts",
+      "snippet": "import { configureStore } from '@reduxjs/toolkit';\nimport authReducer from './authSlice';"
+    }
+  ],
+  "tags": ["state-management", "redux", "frontend", "react"],
+  "impact": "Provides predictable state updates, improved debugging with Redux DevTools, and type-safe API calls."
+}
+```
+
+---
+
+### Example 12: Database Connection Pool Missing
+
+```json
+{
+  "id": "obs-db-no-connection-pool",
+  "category": "performance",
+  "severity": "warning",
+  "title": "Database connections not pooled",
+  "description": "Backend API creates new database connections for each request instead of using connection pooling, leading to performance degradation under load.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/db/connection.ts:12-15",
+      "snippet": "export async function getConnection() {\n  return await mysql.createConnection(config);\n}",
+      "note": "New connection created for every query"
+    },
+    {
+      "type": "code",
+      "location": "src/routes/users.ts:23",
+      "snippet": "const conn = await getConnection();\nconst users = await conn.query('SELECT * FROM users');",
+      "note": "Pattern repeated throughout codebase"
+    }
+  ],
+  "tags": ["performance", "database", "connection-pool", "scalability"],
+  "impact": "High latency for database queries. Connection exhaustion under concurrent load. Potential database server overload.",
+  "recommendation": "Implement connection pooling using mysql2/pool with min 5, max 20 connections."
+}
+```
+
+---
+
+### Example 13: Container Health Checks
+
+```json
+{
+  "id": "obs-health-check-implemented",
+  "category": "deployment",
+  "severity": "info",
+  "title": "Comprehensive health check endpoints",
+  "description": "Container implements /health (liveness) and /ready (readiness) endpoints with dependency checks for database, cache, and message queue.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/routes/health.ts:10-25",
+      "snippet": "app.get('/health', async (req, res) => {\n  const dbOk = await checkDatabase();\n  const redisOk = await checkRedis();\n  const queueOk = await checkQueue();\n  res.status(dbOk && redisOk && queueOk ? 200 : 503).json({...});\n});"
+    },
+    {
+      "type": "config",
+      "location": "k8s/deployment.yml:45-52",
+      "snippet": "livenessProbe:\n  httpGet:\n    path: /health\n    port: 3000\nreadinessProbe:\n  httpGet:\n    path: /ready\n    port: 3000"
+    }
+  ],
+  "tags": ["deployment", "health-check", "kubernetes", "reliability"],
+  "impact": "Kubernetes can detect and restart unhealthy containers. Prevents routing traffic to containers not ready to serve requests."
+}
+```
+
+---
+
+### Example 14: WebSocket Real-Time Communication
+
+```json
+{
+  "id": "obs-websocket-notifications",
+  "category": "communication",
+  "severity": "info",
+  "title": "WebSocket server for real-time notifications",
+  "description": "Container implements WebSocket server using Socket.io for real-time push notifications to connected clients.",
+  "evidence": [
+    {
+      "type": "dependency",
+      "location": "backend/package.json",
+      "snippet": "\"socket.io\": \"^4.6.1\""
+    },
+    {
+      "type": "code",
+      "location": "src/websocket/server.ts:15-20",
+      "snippet": "const io = new Server(httpServer, {\n  cors: { origin: process.env.CORS_ORIGIN },\n  transports: ['websocket', 'polling']\n});"
+    }
+  ],
+  "tags": ["communication", "websocket", "real-time", "socket.io"],
+  "impact": "Enables instant notifications without polling. Maintains persistent connections, increasing server memory usage."
+}
+```
+
+---
+
+### Example 15: Docker Multi-Stage Build
+
+```json
+{
+  "id": "obs-docker-multi-stage",
+  "category": "deployment",
+  "severity": "info",
+  "title": "Multi-stage Docker build for optimized image size",
+  "description": "Container uses multi-stage Dockerfile separating build and runtime stages, reducing final image size from 1.2GB to 180MB.",
+  "evidence": [
+    {
+      "type": "config",
+      "location": "Dockerfile:1-15",
+      "snippet": "# Build stage\nFROM node:18-alpine AS builder\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci\nCOPY . .\nRUN npm run build\n\n# Runtime stage\nFROM node:18-alpine\nWORKDIR /app\nCOPY --from=builder /app/dist ./dist\nCOPY package*.json ./\nRUN npm ci --production"
+    }
+  ],
+  "tags": ["deployment", "docker", "optimization", "image-size"],
+  "impact": "Reduces image size by 84%, faster deployments, lower storage costs, smaller attack surface."
+}
+```
+
+---
+
+### Example 16: Redis Session Storage
+
+```json
+{
+  "id": "obs-redis-sessions",
+  "category": "data-storage",
+  "severity": "info",
+  "title": "Redis for session storage with TTL",
+  "description": "Container stores user sessions in Redis with 24-hour TTL, enabling horizontal scaling and fast session lookups.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/config/session.ts:8-14",
+      "snippet": "app.use(session({\n  store: new RedisStore({ client: redisClient }),\n  secret: process.env.SESSION_SECRET,\n  resave: false,\n  saveUninitialized: false,\n  cookie: { maxAge: 24 * 60 * 60 * 1000 }\n}));"
+    },
+    {
+      "type": "dependency",
+      "location": "package.json",
+      "snippet": "\"connect-redis\": \"^7.1.0\",\n\"redis\": \"^4.6.5\""
+    }
+  ],
+  "tags": ["data-storage", "redis", "sessions", "caching"],
+  "impact": "Enables stateless application design. Session data survives container restarts. Fast session access (~1ms)."
+}
+```
+
+---
+
+### Example 17: Environment Variable Overload
+
+```json
+{
+  "id": "obs-env-var-overload",
+  "category": "configuration",
+  "severity": "warning",
+  "title": "Excessive environment variables (42 required)",
+  "description": "Container requires 42 environment variables to start, making configuration error-prone and deployment complex.",
+  "evidence": [
+    {
+      "type": "file",
+      "location": ".env.example",
+      "note": "42 environment variables listed"
+    },
+    {
+      "type": "code",
+      "location": "src/config/index.ts:5-50",
+      "snippet": "export const config = {\n  dbHost: required('DB_HOST'),\n  dbPort: required('DB_PORT'),\n  // ... 40 more",
+      "note": "Long list of required config values"
+    }
+  ],
+  "tags": ["configuration", "environment-variables", "complexity"],
+  "impact": "High configuration complexity. Prone to misconfiguration errors. Difficult onboarding for new developers.",
+  "recommendation": "Consolidate configuration using a config server (e.g., Spring Cloud Config) or use sensible defaults with override capability."
+}
+```
+
+---
+
+### Example 18: No Distributed Tracing
+
+```json
+{
+  "id": "obs-no-distributed-tracing",
+  "category": "monitoring",
+  "severity": "warning",
+  "title": "Missing distributed tracing in microservices",
+  "description": "Container has logging but no distributed tracing instrumentation, making it difficult to debug cross-service request flows.",
+  "evidence": [
+    {
+      "type": "file",
+      "location": "package.json",
+      "note": "No OpenTelemetry, Jaeger, or Zipkin dependencies"
+    },
+    {
+      "type": "pattern",
+      "location": "src/middleware/",
+      "note": "No trace context propagation middleware"
+    }
+  ],
+  "tags": ["monitoring", "distributed-tracing", "observability", "microservices"],
+  "impact": "Difficult to trace requests across service boundaries. Hard to identify performance bottlenecks in multi-service flows.",
+  "recommendation": "Implement OpenTelemetry instrumentation with Jaeger or Tempo backend for distributed tracing."
+}
+```
+
+---
+
+### Example 19: gRPC Inter-Service Communication
+
+```json
+{
+  "id": "obs-grpc-communication",
+  "category": "communication",
+  "severity": "info",
+  "title": "gRPC for high-performance inter-service communication",
+  "description": "Container uses gRPC with Protocol Buffers for efficient inter-service communication, providing better performance than REST for internal APIs.",
+  "evidence": [
+    {
+      "type": "dependency",
+      "location": "package.json",
+      "snippet": "\"@grpc/grpc-js\": \"^1.8.14\",\n\"@grpc/proto-loader\": \"^0.7.6\""
+    },
+    {
+      "type": "file",
+      "location": "proto/user-service.proto",
+      "snippet": "service UserService {\n  rpc GetUser (GetUserRequest) returns (User);\n  rpc ListUsers (ListUsersRequest) returns (UserList);\n}",
+      "note": "Protocol Buffer service definition"
+    }
+  ],
+  "tags": ["communication", "grpc", "protobuf", "performance"],
+  "impact": "Lower latency and bandwidth usage vs REST. Type-safe service contracts. Requires gRPC-compatible clients."
+}
+```
+
+---
+
+### Example 20: JWT Authentication with Refresh Tokens
+
+```json
+{
+  "id": "obs-jwt-refresh-tokens",
+  "category": "authentication",
+  "severity": "info",
+  "title": "JWT authentication with refresh token rotation",
+  "description": "Container implements JWT access tokens (15min TTL) with refresh tokens (7 days) stored in httpOnly cookies, following OAuth2 best practices.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/auth/jwt.ts:45-52",
+      "snippet": "const accessToken = jwt.sign(payload, secret, { expiresIn: '15m' });\nconst refreshToken = jwt.sign({ userId }, refreshSecret, { expiresIn: '7d' });\nres.cookie('refreshToken', refreshToken, { httpOnly: true, secure: true });",
+      "note": "Token generation with appropriate TTLs"
+    }
+  ],
+  "tags": ["authentication", "jwt", "refresh-tokens", "security"],
+  "impact": "Balances security (short-lived access tokens) with UX (long refresh window). Refresh tokens in httpOnly cookies prevent XSS theft."
+}
+```
+
+---
+
+## C3 Component Examples
+
+### Example 21: JWT in localStorage (Security Issue)
+
+```json
+{
+  "id": "obs-auth-jwt-localstorage",
+  "category": "security",
+  "severity": "critical",
+  "title": "JWT tokens stored in localStorage",
+  "description": "Authentication component stores JWT tokens in browser localStorage, making them accessible to JavaScript and vulnerable to XSS attacks. Tokens should be stored in httpOnly cookies.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/features/auth/authSlice.ts:45",
+      "snippet": "localStorage.setItem('authToken', action.payload.token);",
+      "note": "Token persisted in localStorage"
+    },
+    {
+      "type": "code",
+      "location": "src/features/auth/authSlice.ts:52",
+      "snippet": "const token = localStorage.getItem('authToken');\nif (token) { setAuthHeader(token); }",
+      "note": "Token retrieved from localStorage on app init"
+    }
+  ],
+  "tags": ["security", "authentication", "xss", "jwt"],
+  "impact": "High security risk - Any XSS vulnerability can lead to token theft and account takeover. Tokens persist across browser sessions.",
+  "recommendation": "Migrate to httpOnly cookies for token storage. Tokens will be automatically included in requests and inaccessible to JavaScript."
+}
+```
+
+---
+
+### Example 22: Repository Pattern Implementation
+
+```json
+{
+  "id": "obs-repository-pattern",
+  "category": "design-patterns",
+  "severity": "info",
+  "title": "Repository pattern for data access layer",
+  "description": "UserService component implements the repository pattern to abstract database operations, improving testability and separation of concerns.",
+  "evidence": [
+    {
+      "type": "file",
+      "location": "src/repositories/UserRepository.ts",
+      "note": "Dedicated repository class implementing IUserRepository interface"
+    },
+    {
+      "type": "code",
+      "location": "src/services/UserService.ts:23",
+      "snippet": "constructor(private userRepo: IUserRepository) {}",
+      "note": "Dependency injection of repository interface, not concrete implementation"
+    },
+    {
+      "type": "code",
+      "location": "src/repositories/UserRepository.ts:15-20",
+      "snippet": "async findById(id: string): Promise<User | null> {\n  const row = await this.db('users').where({ id }).first();\n  return row ? this.mapToEntity(row) : null;\n}",
+      "note": "Repository handles ORM queries and entity mapping"
+    }
+  ],
+  "tags": ["design-pattern", "repository", "data-access", "separation-of-concerns"],
+  "impact": "Improved testability through dependency injection. Clean separation between business logic and data access. Easier to swap database implementations."
+}
+```
+
+---
+
+### Example 23: Missing Error Handling
+
+```json
+{
+  "id": "obs-no-error-handling",
+  "category": "error-handling",
+  "severity": "warning",
+  "title": "Missing error handling in async operations",
+  "description": "PaymentService component performs async Stripe operations without proper error handling, risking unhandled promise rejections and application crashes.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/features/payment/PaymentService.ts:78-82",
+      "snippet": "async processPayment(amount: number) {\n  const charge = await stripe.charges.create({ amount });\n  await this.recordPayment(charge.id);\n  return charge.id;\n}",
+      "note": "No try-catch block or .catch() handler"
+    },
+    {
+      "type": "code",
+      "location": "src/features/payment/PaymentService.ts:95-98",
+      "snippet": "async refundPayment(chargeId: string) {\n  const refund = await stripe.refunds.create({ charge: chargeId });\n  return refund;\n}",
+      "note": "Same pattern - no error handling"
+    }
+  ],
+  "tags": ["error-handling", "async", "reliability", "payment"],
+  "impact": "Application crashes or silent failures when Stripe API errors occur. No user feedback on payment failures. Potential data inconsistency.",
+  "recommendation": "Add try-catch blocks to all async operations. Handle specific error types (network, API errors, validation). Log errors and return user-friendly messages."
+}
+```
+
+---
+
+### Example 24: High Cyclomatic Complexity
+
+```json
+{
+  "id": "obs-high-complexity-validation",
+  "category": "complexity",
+  "severity": "warning",
+  "title": "High cyclomatic complexity in validation function",
+  "description": "FormValidator.validate() function has cyclomatic complexity of 45, making it difficult to understand, test, and maintain.",
+  "evidence": [
+    {
+      "type": "metric",
+      "location": "src/utils/FormValidator.ts:validate",
+      "snippet": "Cyclomatic complexity: 45",
+      "note": "Measured with ESLint complexity rule"
+    },
+    {
+      "type": "code",
+      "location": "src/utils/FormValidator.ts:25-180",
+      "snippet": "function validate(form: Form): ValidationResult {\n  if (form.email) {\n    if (!isEmail(form.email)) {\n      if (form.email.includes('@')) {\n        // 150+ lines of nested conditions...",
+      "note": "Deep nesting (7 levels) with many branches"
+    }
+  ],
+  "tags": ["complexity", "code-quality", "maintainability", "testing"],
+  "impact": "Difficult to understand control flow. Hard to achieve full test coverage. High risk of bugs when modifying. New developers struggle to maintain.",
+  "recommendation": "Refactor into smaller functions, each validating one field. Extract common validation logic. Consider using validation library like Joi or Yup."
+}
+```
+
+---
+
+### Example 25: Comprehensive Unit Tests
+
+```json
+{
+  "id": "obs-good-test-coverage",
+  "category": "testing",
+  "severity": "info",
+  "title": "High unit test coverage with quality tests",
+  "description": "AuthService component has 95% unit test coverage with well-structured tests covering happy paths, edge cases, and error scenarios.",
+  "evidence": [
+    {
+      "type": "metric",
+      "location": "coverage/auth/AuthService.ts.html",
+      "snippet": "Lines: 95.2% (120/126)\nBranches: 92.5% (37/40)",
+      "note": "Jest coverage report"
+    },
+    {
+      "type": "file",
+      "location": "src/features/auth/__tests__/AuthService.test.ts",
+      "note": "12 test cases covering login, logout, token refresh, error scenarios"
+    },
+    {
+      "type": "code",
+      "location": "src/features/auth/__tests__/AuthService.test.ts:45-52",
+      "snippet": "describe('login', () => {\n  it('should return tokens on valid credentials', async () => {...});\n  it('should throw on invalid credentials', async () => {...});\n  it('should lock account after 5 failed attempts', async () => {...});\n});"
+    }
+  ],
+  "tags": ["testing", "unit-tests", "coverage", "quality"],
+  "impact": "High confidence in component behavior. Early bug detection. Safe refactoring. Good documentation through tests."
+}
+```
+
+---
+
+### Example 26: N+1 Query Problem
+
+```json
+{
+  "id": "obs-n-plus-one-queries",
+  "category": "performance",
+  "severity": "warning",
+  "title": "N+1 query problem in dashboard data loading",
+  "description": "DashboardController loads user posts in a loop, executing one query per post (N+1 problem). For a user with 100 posts, this results in 101 database queries.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/controllers/DashboardController.ts:78-82",
+      "snippet": "const posts = await Post.find({ userId });\nfor (const post of posts) {\n  post.comments = await Comment.find({ postId: post.id }); // N queries\n  post.likes = await Like.count({ postId: post.id });      // N queries\n}",
+      "note": "Separate query for each post's comments and likes"
+    }
+  ],
+  "tags": ["performance", "database", "n+1", "orm"],
+  "impact": "Dashboard load time scales linearly with number of posts. 100 posts = 201 queries = ~2 seconds. Severe performance degradation with large datasets.",
+  "recommendation": "Use eager loading or JOIN queries to load related data in single query. Example: Post.find({ userId }).populate('comments likes')"
+}
+```
+
+---
+
+### Example 27: Tight Coupling to ORM
+
+```json
+{
+  "id": "obs-tight-orm-coupling",
+  "category": "coupling",
+  "severity": "warning",
+  "title": "Business logic tightly coupled to Sequelize ORM",
+  "description": "Service layer components directly use Sequelize models and queries throughout, making it difficult to test or switch ORMs.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/services/OrderService.ts:34-38",
+      "snippet": "async createOrder(data: OrderData) {\n  const order = await Order.create(data);\n  const items = await OrderItem.bulkCreate(order.id, data.items);\n  return order;\n}",
+      "note": "Direct Sequelize model usage in service"
+    },
+    {
+      "type": "pattern",
+      "location": "src/services/",
+      "note": "All 15 service files directly import and use Sequelize models"
+    }
+  ],
+  "tags": ["coupling", "orm", "architecture", "testability"],
+  "impact": "Difficult to unit test services (requires database). Hard to switch ORM. Business logic mixed with data access concerns.",
+  "recommendation": "Introduce repository layer to abstract ORM. Services depend on repository interfaces, not concrete ORM implementations."
+}
+```
+
+---
+
+### Example 28: Factory Pattern for Service Creation
+
+```json
+{
+  "id": "obs-factory-pattern-services",
+  "category": "design-patterns",
+  "severity": "info",
+  "title": "Factory pattern for creating service instances",
+  "description": "ServiceFactory component uses factory pattern to create service instances with appropriate dependencies, improving modularity and testability.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/factories/ServiceFactory.ts:12-25",
+      "snippet": "class ServiceFactory {\n  createUserService(): UserService {\n    const repo = new UserRepository(this.db);\n    const cache = new RedisCache(this.redis);\n    const notifier = new EmailNotifier(this.mailer);\n    return new UserService(repo, cache, notifier);\n  }\n}",
+      "note": "Factory encapsulates complex service construction"
+    }
+  ],
+  "tags": ["design-pattern", "factory", "dependency-injection", "modularity"],
+  "impact": "Centralized service creation logic. Easy to swap implementations. Supports testing with mock dependencies."
+}
+```
+
+---
+
+### Example 29: Missing Input Validation
+
+```json
+{
+  "id": "obs-no-input-validation",
+  "category": "security",
+  "severity": "critical",
+  "title": "No input validation in API controllers",
+  "description": "UserController accepts user input without validation, allowing malformed data to reach the database and potentially causing SQL injection or data corruption.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/controllers/UserController.ts:23-27",
+      "snippet": "async createUser(req: Request, res: Response) {\n  const user = await userService.create(req.body);\n  res.json(user);\n}",
+      "note": "req.body used directly without validation"
+    },
+    {
+      "type": "pattern",
+      "location": "src/controllers/",
+      "note": "No validation middleware (joi, class-validator, zod) found in any controller"
+    }
+  ],
+  "tags": ["security", "validation", "input-validation", "api"],
+  "impact": "Critical security vulnerability. Risk of SQL injection, NoSQL injection, data corruption. Invalid data can crash application.",
+  "recommendation": "Implement input validation using Joi, class-validator, or Zod. Validate all inputs at controller level before processing."
+}
+```
+
+---
+
+### Example 30: Code Documentation with TSDoc
+
+```json
+{
+  "id": "obs-tsdoc-documentation",
+  "category": "documentation",
+  "severity": "info",
+  "title": "Comprehensive TSDoc documentation for public APIs",
+  "description": "All public methods and classes in the API layer have comprehensive TSDoc comments including descriptions, parameter types, return values, and usage examples.",
+  "evidence": [
+    {
+      "type": "code",
+      "location": "src/api/UserAPI.ts:15-24",
+      "snippet": "/**\n * Creates a new user account.\n * @param userData - User registration data\n * @param userData.email - User email (must be unique)\n * @param userData.password - Password (min 8 characters)\n * @returns Newly created user object (password excluded)\n * @throws {ValidationError} If email already exists\n * @example\n * const user = await userAPI.createUser({ email: 'test@example.com', password: 'secret123' });\n */\nasync createUser(userData: UserRegistrationData): Promise<User>"
+    }
+  ],
+  "tags": ["documentation", "tsdoc", "api", "code-quality"],
+  "impact": "Excellent developer experience. IntelliSense shows detailed information. Easier onboarding for new developers. Reduced need for external documentation."
+}
+```
+
+---
+
+## Summary
+
+This examples document provides 30 real-world observation examples:
+
+- **C1 System Context**: 10 examples covering architecture, integration, security, scalability, deployment
+- **C2 Container**: 10 examples covering technology, performance, communication, monitoring, authentication
+- **C3 Component**: 10 examples covering design patterns, security, testing, complexity, code quality
+
+Each example demonstrates:
+- Proper structure with all required fields
+- Concrete evidence with file paths and code snippets
+- Appropriate severity levels
+- Clear impact and recommendations
+- Relevant tags for searchability
+
+Use these examples as templates when documenting your own architectural observations.

skills/c4model-observations/reference.md

@@ -0,0 +1,883 @@
+# Observation Documentation Reference
+
+**Complete guide for documenting architectural observations across C1, C2, and C3 levels.**
+
+---
+
+## Table of Contents
+
+1. [Category Definitions](#category-definitions)
+2. [Evidence Collection Guidelines](#evidence-collection-guidelines)
+3. [Severity Level Best Practices](#severity-level-best-practices)
+4. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+5. [Cross-Level Consistency](#cross-level-consistency)
+6. [Validation Requirements](#validation-requirements)
+
+---
+
+## Category Definitions
+
+### C1 System Context Categories
+
+#### architecture
+**Definition:** Overall system architecture patterns, styles, and strategic decisions.
+
+**What to document:**
+- Architectural styles (monolith, microservices, event-driven, layered)
+- System decomposition approach
+- Major architectural patterns (CQRS, event sourcing, etc.)
+- High-level structural decisions
+
+**Examples:**
+- "Event-driven architecture with message queues"
+- "Microservices architecture with API gateway"
+- "Monolithic layered architecture"
+
+---
+
+#### integration
+**Definition:** How systems integrate and communicate with each other.
+
+**What to document:**
+- Integration patterns (REST, GraphQL, gRPC, messaging)
+- API contracts and interfaces
+- Data exchange formats
+- Synchronous vs asynchronous communication
+
+**Examples:**
+- "Systems communicate via REST APIs over HTTPS"
+- "Event-driven integration using RabbitMQ"
+- "GraphQL gateway for unified API access"
+
+---
+
+#### boundaries
+**Definition:** System scope, ownership boundaries, and organizational limits.
+
+**What to document:**
+- What's inside vs outside the system
+- Team ownership boundaries
+- Deployment boundaries
+- Network boundaries (public/private/DMZ)
+
+**Examples:**
+- "System boundary includes web app and API, excludes database"
+- "Frontend team owns UI system, backend team owns API system"
+
+---
+
+#### security
+**Definition:** System-level security concerns, authentication, and authorization.
+
+**What to document:**
+- Authentication mechanisms (OAuth, JWT, SAML)
+- Authorization approaches (RBAC, ABAC)
+- Security vulnerabilities
+- Data protection strategies
+
+**Examples:**
+- "JWT-based authentication with OAuth2"
+- "No rate limiting on public API endpoints"
+- "TLS encryption for all inter-system communication"
+
+---
+
+#### scalability
+**Definition:** System's ability to scale and handle growth.
+
+**What to document:**
+- Horizontal vs vertical scaling approaches
+- Scaling limitations
+- Load balancing strategies
+- Stateless vs stateful design
+
+**Examples:**
+- "Horizontally scalable via container orchestration"
+- "Vertical scaling limited by database constraints"
+- "Stateless design enables cloud auto-scaling"
+
+---
+
+#### actors
+**Definition:** User types and external actors interacting with the system.
+
+**What to document:**
+- User personas and roles
+- External systems acting as users
+- Actor permissions and capabilities
+
+**Examples:**
+- "Three user types: Customer, Admin, Support Agent"
+- "External audit system queries via API"
+
+---
+
+#### external-dependencies
+**Definition:** Third-party systems, services, and critical external dependencies.
+
+**What to document:**
+- SaaS services and APIs
+- Third-party integrations
+- Dependency criticality
+- Fallback mechanisms
+
+**Examples:**
+- "Critical dependency on Stripe payment gateway"
+- "SendGrid for email, with fallback to AWS SES"
+- "No fallback for authentication via Auth0"
+
+---
+
+#### deployment
+**Definition:** Infrastructure, hosting, and deployment approaches.
+
+**What to document:**
+- Cloud vs on-premise
+- Deployment strategies (blue-green, canary)
+- Infrastructure as code
+- Container orchestration
+
+**Examples:**
+- "Deployed on AWS using Kubernetes"
+- "Blue-green deployment strategy with Terraform"
+- "On-premise deployment with Docker Swarm"
+
+---
+
+#### data-flow
+**Definition:** How data moves between systems and external actors.
+
+**What to document:**
+- Data flow directions
+- Data transformations
+- Data formats
+- Real-time vs batch processing
+
+**Examples:**
+- "User data flows from web app to API to database"
+- "Analytics data streamed to data warehouse via Kafka"
+
+---
+
+### C2 Container Categories
+
+#### technology
+**Definition:** Technology stack, frameworks, libraries, and languages.
+
+**What to document:**
+- Programming languages
+- Frameworks and libraries
+- Runtime environments
+- Major dependencies
+
+**Examples:**
+- "React 18 SPA with Redux Toolkit"
+- "Node.js 18 with Express.js framework"
+- "Python 3.11 with FastAPI"
+
+---
+
+#### runtime
+**Definition:** Runtime characteristics, environment, and execution context.
+
+**What to document:**
+- Runtime environment (Node.js, JVM, .NET)
+- Process model (single-threaded, multi-threaded)
+- Memory and resource requirements
+- Environment variables
+
+**Examples:**
+- "Single-threaded Node.js event loop"
+- "JVM with 4GB heap size"
+- "Requires 16 environment variables"
+
+---
+
+#### communication
+**Definition:** Inter-container communication protocols and patterns.
+
+**What to document:**
+- Communication protocols (HTTP, gRPC, WebSocket)
+- API styles (REST, GraphQL)
+- Message formats (JSON, Protobuf)
+- Communication patterns (request/response, pub/sub)
+
+**Examples:**
+- "REST API with JSON payloads"
+- "gRPC with Protobuf serialization"
+- "WebSocket for real-time updates"
+
+---
+
+#### data-storage
+**Definition:** Databases, caches, and storage mechanisms.
+
+**What to document:**
+- Database types (relational, NoSQL, graph)
+- Caching strategies
+- Storage technologies
+- Data persistence approaches
+
+**Examples:**
+- "PostgreSQL 14 for relational data"
+- "Redis for session caching"
+- "MongoDB for document storage"
+
+---
+
+#### authentication
+**Definition:** Container-level authentication and authorization.
+
+**What to document:**
+- Authentication mechanisms
+- Token management
+- Session handling
+- Authorization strategies
+
+**Examples:**
+- "JWT bearer token authentication"
+- "Session cookies with Redis storage"
+- "API key authentication for service-to-service"
+
+---
+
+#### deployment
+**Definition:** Container deployment strategies and configurations.
+
+**What to document:**
+- Containerization (Docker, etc.)
+- Orchestration (Kubernetes, Docker Swarm)
+- Deployment pipelines
+- Health checks and readiness probes
+
+**Examples:**
+- "Docker container deployed on Kubernetes"
+- "Health check endpoint at /health"
+- "Blue-green deployment via ArgoCD"
+
+---
+
+#### scalability
+**Definition:** Container-level scaling capabilities.
+
+**What to document:**
+- Horizontal pod autoscaling
+- Replica counts
+- Resource limits
+- Scaling triggers
+
+**Examples:**
+- "Auto-scales 2-10 pods based on CPU"
+- "Stateless design enables horizontal scaling"
+- "Limited by database connection pool size"
+
+---
+
+#### performance
+**Definition:** Container performance characteristics and optimizations.
+
+**What to document:**
+- Response times
+- Throughput capacity
+- Resource utilization
+- Performance optimizations
+
+**Examples:**
+- "Average response time: 50ms"
+- "Code splitting and lazy loading implemented"
+- "Database queries not optimized with indexes"
+
+---
+
+#### dependencies
+**Definition:** Container dependencies on other containers or services.
+
+**What to document:**
+- Direct dependencies
+- Dependency versions
+- Dependency criticality
+- Coupling strength
+
+**Examples:**
+- "Depends on API container and Redis cache"
+- "Critical dependency on database"
+- "Loose coupling via message queue"
+
+---
+
+#### configuration
+**Definition:** Configuration management approaches.
+
+**What to document:**
+- Configuration sources (env vars, config files, config servers)
+- Secret management
+- Feature flags
+- Configuration validation
+
+**Examples:**
+- "Configuration via environment variables"
+- "Secrets stored in Kubernetes secrets"
+- "Feature flags managed in LaunchDarkly"
+
+---
+
+#### monitoring
+**Definition:** Observability, logging, and monitoring.
+
+**What to document:**
+- Logging frameworks and formats
+- Metrics collection
+- Tracing and APM
+- Alerting
+
+**Examples:**
+- "Winston logger with JSON format"
+- "Prometheus metrics exposed at /metrics"
+- "No distributed tracing implemented"
+
+---
+
+### C3 Component Categories
+
+#### design-patterns
+**Definition:** Design patterns and architectural patterns in code.
+
+**What to document:**
+- Creational patterns (Factory, Singleton, Builder)
+- Structural patterns (Adapter, Decorator, Facade)
+- Behavioral patterns (Observer, Strategy, Command)
+- Domain patterns (Repository, Service, Entity)
+
+**Examples:**
+- "Repository pattern for data access"
+- "Factory pattern for creating services"
+- "Observer pattern for event handling"
+
+---
+
+#### code-structure
+**Definition:** Code organization, modularity, and file structure.
+
+**What to document:**
+- Directory structure
+- Module organization
+- File naming conventions
+- Code grouping strategies
+
+**Examples:**
+- "Feature-based directory structure"
+- "Layered architecture: controllers/services/repositories"
+- "Modules organized by domain"
+
+---
+
+#### dependencies
+**Definition:** Component-level imports and dependencies.
+
+**What to document:**
+- Import patterns
+- Circular dependencies
+- Dependency injection
+- Module coupling
+
+**Examples:**
+- "Dependency injection via constructor"
+- "Circular dependency between User and Order modules"
+- "Heavy reliance on utility modules"
+
+---
+
+#### error-handling
+**Definition:** Error handling strategies and patterns.
+
+**What to document:**
+- Try-catch usage
+- Error propagation
+- Error logging
+- Custom error types
+
+**Examples:**
+- "No error handling in async operations"
+- "Custom error classes for domain errors"
+- "Global error handler middleware"
+
+---
+
+#### testing
+**Definition:** Test coverage, quality, and strategies.
+
+**What to document:**
+- Unit test coverage
+- Integration tests
+- Test frameworks
+- Test quality
+
+**Examples:**
+- "85% unit test coverage with Jest"
+- "No integration tests"
+- "Tests use actual database instead of mocks"
+
+---
+
+#### performance
+**Definition:** Algorithm efficiency and code-level optimizations.
+
+**What to document:**
+- Algorithm complexity
+- Performance bottlenecks
+- Optimization techniques
+- Resource usage
+
+**Examples:**
+- "O(n²) algorithm for data processing"
+- "Memoization used for expensive calculations"
+- "No caching of computed values"
+
+---
+
+#### security
+**Definition:** Security implementation details in code.
+
+**What to document:**
+- Input validation
+- Output encoding
+- Secret handling
+- Vulnerability patterns
+
+**Examples:**
+- "SQL injection vulnerability in query builder"
+- "JWT tokens stored in localStorage"
+- "Input validation using Joi schema"
+
+---
+
+#### code-quality
+**Definition:** Code quality metrics and standards.
+
+**What to document:**
+- Code complexity
+- Code duplication
+- Naming conventions
+- Code style
+
+**Examples:**
+- "High cyclomatic complexity (>20)"
+- "Consistent naming conventions followed"
+- "Significant code duplication in controllers"
+
+---
+
+#### documentation
+**Definition:** Code documentation quality and coverage.
+
+**What to document:**
+- JSDoc/TSDoc comments
+- README files
+- API documentation
+- Inline comments
+
+**Examples:**
+- "Comprehensive JSDoc for all public APIs"
+- "No documentation for complex algorithms"
+- "README outdated, doesn't match implementation"
+
+---
+
+#### complexity
+**Definition:** Code complexity measurements.
+
+**What to document:**
+- Cyclomatic complexity
+- Cognitive complexity
+- Function length
+- Nesting depth
+
+**Examples:**
+- "Function with cyclomatic complexity of 45"
+- "Deep nesting (6 levels) in conditional logic"
+- "Functions average 150 lines (too long)"
+
+---
+
+#### coupling
+**Definition:** Degree of interdependence between components.
+
+**What to document:**
+- Tight vs loose coupling
+- Coupling to external libraries
+- Coupling to infrastructure
+- Circular dependencies
+
+**Examples:**
+- "Tight coupling to ORM throughout codebase"
+- "Components loosely coupled via interfaces"
+- "Direct database access in UI components"
+
+---
+
+#### cohesion
+**Definition:** How closely related component responsibilities are.
+
+**What to document:**
+- Single Responsibility Principle adherence
+- Component focus
+- Mixed concerns
+
+**Examples:**
+- "High cohesion: each service has single responsibility"
+- "Low cohesion: AuthService handles auth, logging, and config"
+
+---
+
+#### maintainability
+**Definition:** How easy it is to maintain and modify the code.
+
+**What to document:**
+- Code readability
+- Modification complexity
+- Technical debt
+- Refactoring needs
+
+**Examples:**
+- "High maintainability with clear separation of concerns"
+- "Technical debt: hardcoded values throughout"
+- "Difficult to modify due to tight coupling"
+
+---
+
+## Evidence Collection Guidelines
+
+### Best Practices
+
+1. **Always provide file paths**
+   - Use relative paths from repository root
+   - Include line numbers for code snippets: `src/auth.ts:45-52`
+   - For directories, use trailing slash: `src/controllers/`
+
+2. **Keep snippets concise**
+   - 1-10 lines maximum
+   - Focus on the relevant part
+   - Use `...` to indicate omitted code
+
+3. **Match evidence type to content**
+   - `file` - For file/directory existence: `package.json`, `src/config/`
+   - `code` - For actual code snippets
+   - `config` - For configuration values: `.env`, `docker-compose.yml`
+   - `pattern` - For architectural patterns without specific file
+   - `metric` - For quantitative measurements
+   - `dependency` - For package dependencies from manifests
+
+4. **Add context with notes**
+   - Explain what the evidence shows
+   - Clarify non-obvious connections
+   - Provide additional context
+
+### Evidence Examples
+
+**Good file evidence:**
+```json
+{
+  "type": "file",
+  "location": "src/repositories/UserRepository.ts",
+  "note": "Repository pattern implementation"
+}
+```
+
+**Good code evidence:**
+```json
+{
+  "type": "code",
+  "location": "src/auth/AuthService.ts:45-47",
+  "snippet": "localStorage.setItem('token', jwt);\nconst decoded = jwtDecode(jwt);\nreturn decoded;",
+  "note": "JWT stored in localStorage, vulnerable to XSS"
+}
+```
+
+**Good config evidence:**
+```json
+{
+  "type": "config",
+  "location": "docker-compose.yml:15-18",
+  "snippet": "redis:\n  image: redis:7-alpine\n  ports:\n    - '6379:6379'",
+  "note": "Redis configured for caching"
+}
+```
+
+**Good pattern evidence:**
+```json
+{
+  "type": "pattern",
+  "location": "src/services/",
+  "note": "Service layer pattern with dependency injection throughout codebase"
+}
+```
+
+---
+
+## Severity Level Best Practices
+
+### Critical Severity
+
+**Use for:**
+- **Security vulnerabilities**: XSS, SQL injection, exposed secrets, insecure authentication
+- **Data loss risks**: No backups, data deletion without confirmation
+- **System unavailability**: Single points of failure, no failover
+- **Critical bugs**: Core functionality broken, data corruption
+
+**Checklist:**
+- ✅ Does this pose immediate risk to security, data, or availability?
+- ✅ Could this result in data breach or data loss?
+- ✅ Would this cause system downtime or service outage?
+- ✅ Is immediate action required?
+
+**Example:**
+```json
+{
+  "severity": "critical",
+  "title": "SQL injection vulnerability in user query",
+  "description": "User input directly concatenated into SQL query without sanitization.",
+  "impact": "Attackers can execute arbitrary SQL commands, access/modify all data",
+  "recommendation": "Use parameterized queries immediately"
+}
+```
+
+---
+
+### Warning Severity
+
+**Use for:**
+- **Performance issues**: N+1 queries, inefficient algorithms, resource leaks
+- **Code quality**: High complexity, duplication, poor naming
+- **Missing best practices**: No error handling, no tests, deprecated dependencies
+- **Architectural concerns**: Anti-patterns, tight coupling, violations of SOLID
+
+**Checklist:**
+- ✅ Should this be fixed but isn't immediately critical?
+- ✅ Does this impact performance, maintainability, or scalability?
+- ✅ Is this a violation of best practices?
+- ✅ Could this become critical if left unaddressed?
+
+**Example:**
+```json
+{
+  "severity": "warning",
+  "title": "Database connections not pooled",
+  "description": "New database connection created for each request.",
+  "impact": "High latency and connection exhaustion under load",
+  "recommendation": "Implement connection pooling"
+}
+```
+
+---
+
+### Info Severity
+
+**Use for:**
+- **Design patterns**: Documented architectural patterns
+- **Technology stack**: Frameworks and libraries in use
+- **Good practices**: Well-implemented features
+- **Architectural decisions**: Strategic technical choices
+- **System capabilities**: Features and functionality
+
+**Checklist:**
+- ✅ Is this neutral or positive information?
+- ✅ Does this document "what is" without judgment?
+- ✅ Is this useful for understanding the system?
+- ✅ Is no action required?
+
+**Example:**
+```json
+{
+  "severity": "info",
+  "title": "Event-driven architecture with RabbitMQ",
+  "description": "System uses message queues for async processing between services.",
+  "impact": "Enables loose coupling and horizontal scaling"
+}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Opinion Instead of Fact
+
+❌ **Bad:**
+```json
+{
+  "description": "The authentication approach is poorly designed and should be refactored."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "description": "JWT tokens stored in localStorage are vulnerable to XSS attacks.",
+  "recommendation": "Migrate to httpOnly cookies"
+}
+```
+
+---
+
+### 2. Vague Observations
+
+❌ **Bad:**
+```json
+{
+  "title": "Performance issues",
+  "description": "The system is slow."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "title": "N+1 query problem in user dashboard",
+  "description": "Dashboard loads user posts in a loop, executing one query per post instead of batching.",
+  "evidence": [{"type": "code", "location": "src/dashboard.ts:78"}]
+}
+```
+
+---
+
+### 3. Missing Evidence
+
+❌ **Bad:**
+```json
+{
+  "title": "Uses event-driven architecture",
+  "description": "The system has an event-driven design."
+}
+```
+
+✅ **Good:**
+```json
+{
+  "title": "Event-driven architecture with RabbitMQ",
+  "description": "System uses RabbitMQ message broker for async event processing.",
+  "evidence": [
+    {"type": "config", "location": "docker-compose.yml", "snippet": "rabbitmq:..."},
+    {"type": "dependency", "location": "package.json", "snippet": "\"amqplib\": \"^0.10.3\""}
+  ]
+}
+```
+
+---
+
+### 4. Wrong Severity
+
+❌ **Bad:**
+```json
+{
+  "severity": "critical",
+  "title": "Using older version of React",
+  "description": "React 17 instead of React 18"
+}
+```
+
+✅ **Good:**
+```json
+{
+  "severity": "warning",
+  "title": "React version outdated",
+  "description": "Using React 17.0.2, missing React 18 performance improvements",
+  "recommendation": "Upgrade to React 18 for concurrent features"
+}
+```
+
+---
+
+### 5. Wrong Category Level
+
+❌ **Bad (C1 level):**
+```json
+{
+  "category": "code-quality",
+  "title": "High cyclomatic complexity in AuthService"
+}
+```
+
+✅ **Good (C1 level):**
+```json
+{
+  "category": "architecture",
+  "title": "Microservices architecture with API gateway"
+}
+```
+
+*Code quality is a C3 category; architecture is appropriate for C1*
+
+---
+
+## Cross-Level Consistency
+
+### Observation Granularity
+
+**C1 observations** should be high-level:
+- System-wide patterns
+- External integrations
+- System boundaries
+- Actor interactions
+
+**C2 observations** should be mid-level:
+- Container technologies
+- Inter-container communication
+- Container deployment
+- Container-level performance
+
+**C3 observations** should be detailed:
+- Code patterns
+- Component structure
+- Implementation details
+- Code quality metrics
+
+### Avoid Duplication Across Levels
+
+If the same observation applies to multiple levels, document it at the **highest appropriate level** and reference it at lower levels.
+
+**Example:**
+- C1: "System uses PostgreSQL for data persistence"
+- C2: "API container connects to PostgreSQL database"
+- C3: Don't repeat—focus on component-specific details like query patterns
+
+---
+
+## Validation Requirements
+
+### Required Field Validation
+
+1. **ID format**: Must match `^obs-[a-z0-9-]+$`
+   - ✅ `obs-event-driven-arch`
+   - ❌ `OBS-001`, `observation1`
+
+2. **Category**: Must be valid for the C4 level
+   - C1: 9 categories (architecture, integration, boundaries, ...)
+   - C2: 12 categories (technology, runtime, communication, ...)
+   - C3: 13 categories (design-patterns, code-structure, dependencies, ...)
+
+3. **Severity**: Must be `critical`, `warning`, or `info`
+
+4. **Title**: Max 100 characters, descriptive
+
+5. **Description**: Min 10 characters, detailed
+
+### Evidence Validation
+
+1. **Type**: Must be valid evidence type
+2. **Location**: Required, should be a valid path
+3. **Snippet**: Optional but recommended
+4. **Note**: Optional but helpful for context
+
+### Recommendation Validation
+
+- **Critical** observations MUST include `recommendation`
+- **Warning** observations SHOULD include `recommendation`
+- **Info** observations MAY include `recommendation`
+
+---
+
+## Additional Resources
+
+- **[examples.md](examples.md)** - 30+ complete examples
+- **[categories.md](categories.md)** - Category quick reference
+- **Validation scripts** - `${CLAUDE_PLUGIN_ROOT}/validation/scripts/validate-*.py`
+- **Type definitions** - `${CLAUDE_PLUGIN_ROOT}/validation/templates/types-observations.json`