Initial commit

2025-11-29 18:17:07 +08:00
commit c0cd55ad8d
55 changed files with 15836 additions and 0 deletions
--- a/skills/c4model-c4/observation-guide-c4.md
+++ b/skills/c4model-c4/observation-guide-c4.md
@@ -0,0 +1,317 @@
+# 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`