# Observation Guide for C4 Code Elements

This guide provides comprehensive methodology for documenting observations at the C4 Code level.

---

## Observation Categories

### 1. **implementation**
Code implementation patterns, algorithms, logic flow

**Examples:**
- "Uses async/await pattern for non-blocking database operations"
- "Implements retry logic with exponential backoff"
- "Uses memoization to cache expensive calculations"
- "Implements pagination with cursor-based navigation"
- "Uses builder pattern for complex object construction"

**Evidence types:** code, pattern

---

### 2. **error-handling**
Exception handling, error propagation, recovery mechanisms

**Examples:**
- "Generic catch block masks specific error types - consider typed error handling"
- "Custom error classes with proper error codes and stack traces"
- "Missing error handling for null/undefined cases"
- "Proper error boundary implementation with fallback UI"
- "Silently catches and ignores errors - may hide bugs"

**Evidence types:** code, pattern

---

### 3. **type-safety**
Type definitions, generics, type guards, null safety

**Examples:**
- "Uses strict null checks with proper type guards"
- "Generic function with proper type constraints"
- "Missing type annotation on public API - should be explicit"
- "Type narrowing with discriminated unions for safe handling"
- "Uses `any` type extensively - reduces type safety benefits"

**Evidence types:** code, pattern

---

### 4. **documentation**
JSDoc, docstrings, inline comments, API documentation

**Examples:**
- "Comprehensive JSDoc with @param, @returns, and @example"
- "Missing documentation for complex algorithm - add explanatory comments"
- "Inline comments explain business logic decisions"
- "API endpoint documentation includes request/response examples"
- "Outdated comments don't match current implementation"

**Evidence types:** documentation, code

---

### 5. **testing**
Test coverage, testability, mocking concerns

**Examples:**
- "90% test coverage with edge cases covered"
- "Hard to test due to static dependencies - consider dependency injection"
- "Proper use of dependency injection improves testability"
- "Missing tests for error paths and edge cases"
- "Test file exists but only covers happy path"

**Evidence types:** test, code

---

### 6. **complexity**
Cyclomatic complexity, cognitive complexity, nesting depth

**Examples:**
- "Cyclomatic complexity of 15 exceeds threshold (6) - extract methods"
- "Deep nesting (5 levels) reduces readability - use guard clauses"
- "Function has 8 parameters - consider parameter object pattern"
- "Method is 150 LOC - split into smaller focused functions"
- "Single method handles multiple responsibilities - violates SRP"

**Evidence types:** metric, code

---

### 7. **performance**
Algorithm efficiency, memory usage, async patterns

**Examples:**
- "O(n²) algorithm could be optimized to O(n log n)"
- "Memory leak: event listener not removed on cleanup"
- "Unnecessary database queries in loop - use batch query"
- "Proper use of lazy loading for large data sets"
- "Missing debounce on rapid event handler"

**Evidence types:** code, metric, pattern

---

### 8. **security**
Input validation, sanitization, authentication, authorization

**Examples:**
- "Missing input validation on user-provided data"
- "SQL query properly parameterized against injection"
- "Password stored with bcrypt hashing (cost factor 12)"
- "Sensitive data logged in debug output - security risk"
- "Authorization check missing before data access"

**Evidence types:** code, pattern

---

### 9. **concurrency**
Async/await, promises, race conditions, thread safety

**Examples:**
- "Potential race condition in concurrent state updates"
- "Proper use of Promise.all for parallel independent requests"
- "Missing await on async function call - returns Promise instead of value"
- "Deadlock potential with multiple lock acquisitions"
- "Uses mutex pattern for thread-safe resource access"

**Evidence types:** code, pattern

---

### 10. **patterns**
Design patterns, code patterns, anti-patterns

**Examples:**
- "Factory pattern used for creating validator instances"
- "God object anti-pattern - class has too many responsibilities"
- "Proper use of strategy pattern for payment processing"
- "Singleton pattern ensures single database connection pool"
- "Repository pattern cleanly separates data access concerns"

**Evidence types:** pattern, code

---

## Observation Structure

```json
{
  "id": "obs-{element-id}-{category}-{number}",
  "category": "implementation|error-handling|type-safety|documentation|testing|complexity|performance|security|concurrency|patterns",
  "severity": "info|warning|critical",
  "description": "Clear, actionable description of the observation",
  "evidence": [
    {
      "location": "src/path/to/file.ts:45-67",
      "type": "code|metric|pattern|test|documentation",
      "snippet": "Optional relevant code snippet"
    }
  ],
  "tags": ["relevant", "searchable", "tags"]
}
```

---

## Severity Guidelines

### ℹ️ info
Use for:
- Best practices being followed
- Interesting implementation details
- Documentation notes
- Positive observations

**Examples:**
- "Uses dependency injection for loose coupling"
- "Well-documented API with comprehensive JSDoc"
- "Implements singleton pattern correctly"

---

### ⚠️ warning
Use for:
- Potential issues that should be addressed
- Technical debt
- Performance concerns
- Missing tests
- Minor security considerations

**Examples:**
- "Cyclomatic complexity exceeds threshold"
- "Missing input validation on internal API"
- "No tests for edge cases"
- "Consider using more specific error types"

---

### 🔴 critical
Use for:
- Security vulnerabilities
- Breaking bugs
- Data loss potential
- Production-impacting issues
- Immediate action required

**Examples:**
- "SQL injection vulnerability - user input not sanitized"
- "Unhandled promise rejection crashes application"
- "Sensitive data exposed in logs"
- "Race condition causes data corruption"

---

## Evidence Types

| Type | Description | Example |
|------|-------------|---------|
| `code` | Code snippet or reference | `"snippet": "if (user.role === 'admin')"` |
| `metric` | Calculated metric value | Complexity score, LOC count |
| `pattern` | Design pattern identification | Factory, Singleton, Repository |
| `test` | Test file or coverage info | Test file location |
| `documentation` | Doc reference | JSDoc, README section |

---

## Complete Example

```json
{
  "observations": [
    {
      "id": "obs-auth-service-security-01",
      "category": "security",
      "severity": "critical",
      "description": "Password comparison uses timing-vulnerable equality check. Use constant-time comparison to prevent timing attacks.",
      "evidence": [
        {
          "location": "src/services/auth.ts:78",
          "type": "code",
          "snippet": "if (password === storedPassword)"
        }
      ],
      "tags": ["security", "timing-attack", "authentication"]
    },
    {
      "id": "obs-auth-service-patterns-01",
      "category": "patterns",
      "severity": "info",
      "description": "Implements repository pattern for data access, providing clean separation between business logic and persistence.",
      "evidence": [
        {
          "location": "src/services/auth.ts:15-20",
          "type": "pattern"
        }
      ],
      "tags": ["repository-pattern", "clean-architecture"]
    },
    {
      "id": "obs-auth-service-complexity-01",
      "category": "complexity",
      "severity": "warning",
      "description": "Authenticate method has cyclomatic complexity of 12, exceeding recommended threshold of 6. Consider extracting validation and token generation into separate methods.",
      "evidence": [
        {
          "location": "src/services/auth.ts:45-120",
          "type": "metric"
        }
      ],
      "tags": ["complexity", "refactoring-candidate"]
    }
  ]
}
```

---

## Writing Good Observations

### ✅ DO:
- Be specific and actionable
- Include exact file paths and line numbers
- Provide code snippets for context
- Use appropriate severity levels
- Include relevant tags for searchability
- Suggest fixes for warnings/critical issues

### ❌ DON'T:
- Be vague ("code is complex")
- Skip evidence
- Overuse critical severity
- Write observations without actionable insight
- Forget to tag important categories
- Mix multiple issues in one observation

---

## Tags Reference

Common useful tags:

**Architecture:** `clean-architecture`, `hexagonal`, `layered`, `microservices`

**Patterns:** `singleton`, `factory`, `repository`, `strategy`, `observer`, `decorator`

**Anti-patterns:** `god-object`, `spaghetti-code`, `magic-numbers`, `primitive-obsession`

**Quality:** `refactoring-candidate`, `technical-debt`, `needs-review`

**Security:** `input-validation`, `authentication`, `authorization`, `sql-injection`, `xss`

**Performance:** `n-plus-one`, `memory-leak`, `optimization-candidate`

**Testing:** `needs-tests`, `integration-test`, `unit-test`, `edge-cases`