gh-cubical6-melly/skills/c4model-c4/observation-guide-c4.md

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

{
  "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

{
  "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