Initial commit

skills/c4model-c3/observation-guide.md

@@ -0,0 +1,126 @@
+# Observation Guide for C3 Components
+
+This guide provides comprehensive methodology for documenting observations at the C3 level.
+
+---
+
+## Observation Categories for C3
+
+### Observation Categories
+
+When documenting components, capture these observation categories:
+
+#### 1. **code-structure**
+Code organization patterns and file structure
+
+**Examples:**
+- "Feature-based structure with users/, orders/, products/ directories"
+- "Layered architecture with controllers/, services/, repositories/ separation"
+- "Domain-driven design with domain/, application/, infrastructure/ layers"
+- "Monolithic structure - all code in single src/ directory"
+
+#### 2. **design-patterns**
+Design patterns identified in code
+
+**Examples:**
+- "Singleton pattern for DatabaseConnection ensures single instance"
+- "Repository pattern abstracts data access across all entities"
+- "Factory pattern used for creating different user types"
+- "Dependency injection via NestJS @Injectable decorators"
+- "Observer pattern for event-driven order processing"
+
+#### 3. **dependencies**
+Component dependencies and coupling
+
+**Examples:**
+- "UserService depends on UserRepository, EmailService, and ValidationUtil"
+- "High coupling between OrderService and PaymentService (7 method calls)"
+- "Circular dependency detected: UserService ↔ OrderService"
+- "Controllers depend only on Services (proper layering)"
+
+#### 4. **complexity**
+Code complexity metrics
+
+**Examples:**
+- "OrderService has cyclomatic complexity of 24 (high risk)"
+- "UserController is 450 LOC (consider splitting)"
+- "PaymentService has 12 public methods (large interface)"
+- "Average complexity across services: 8 (acceptable)"
+
+#### 5. **coupling**
+Coupling and cohesion analysis
+
+**Examples:**
+- "Tight coupling: UserService directly instantiates EmailService (no DI)"
+- "Loose coupling: All dependencies injected via constructor"
+- "High afferent coupling: UserModel imported by 15 components"
+- "Low cohesion: UtilityService has unrelated helper methods"
+
+#### 6. **cohesion**
+Component cohesion and single responsibility
+
+**Examples:**
+- "UserService has high cohesion - all methods relate to user management"
+- "UtilityService has low cohesion - contains unrelated helpers"
+- "OrderController violates SRP - handles both orders and payments"
+- "Each repository focused on single entity (good cohesion)"
+
+#### 7. **testing**
+Test coverage and testability
+
+**Examples:**
+- "UserService has 95% test coverage with 24 unit tests"
+- "PaymentGateway untestable - uses hardcoded external URLs"
+- "All services use dependency injection for easy mocking"
+- "Controllers have integration tests covering main flows"
+
+#### 8. **documentation**
+Code documentation quality
+
+**Examples:**
+- "All public methods have JSDoc comments"
+- "UserService missing documentation for complex methods"
+- "README.md in authentication/ explains module architecture"
+- "Inline comments explain business logic in PaymentService"
+
+### Observation Structure for C3
+
+```json
+{
+  "id": "obs-repo-pattern-all-entities",
+  "title": "Repository pattern used for all entity data access",
+  "category": "design-patterns",
+  "severity": "info",
+  "pattern": "repository",
+  "description": "All entities (User, Order, Product, Payment) have dedicated repository classes that abstract database operations using the Repository pattern. Repositories provide methods like findById, findAll, save, delete.",
+  "evidence": [
+    {
+      "type": "pattern",
+      "location": "src/users/UserRepository.ts",
+      "snippet": "export class UserRepository { async findById(id: string): Promise<User> { ... } }"
+    },
+    {
+      "type": "pattern",
+      "location": "src/orders/OrderRepository.ts",
+      "snippet": "export class OrderRepository { async findById(id: string): Promise<Order> { ... } }"
+    }
+  ],
+  "impact": {
+    "maintainability": "high",
+    "testability": "high",
+    "scalability": "medium"
+  },
+  "tags": ["repository-pattern", "data-access", "abstraction"]
+}
+```
+
+### Observation Severity Levels
+
+- **info** - Informational observation (neutral)
+- **warning** - Potential issue requiring attention
+- **critical** - Critical issue requiring immediate action
+
+**Examples:**
+- ℹ️ **info**: "Repository pattern used for data access abstraction"
+- ⚠️ **warning**: "Circular dependency between UserService and OrderService"
+- 🔴 **critical**: "No input validation in UserController endpoints"