Initial commit

2025-11-30 08:37:11 +08:00
commit 20b36ca9b1
56 changed files with 14530 additions and 0 deletions
--- a/skills/codify-solution/SKILL.md
+++ b/skills/codify-solution/SKILL.md
@@ -0,0 +1,510 @@
+---
+name: codify-solution
+description: |
+  Capture solved problems as structured documentation - auto-triggers when user
+  confirms fix worked. Creates searchable knowledge base in docs/solutions/.
+  The compounding effect: each documented solution makes future debugging faster.
+
+trigger: |
+  - User confirms fix worked ("that worked", "it's fixed", "solved it")
+  - /ring-default:codify command invoked manually
+  - Non-trivial debugging completed (multiple investigation attempts)
+  - After systematic-debugging Phase 4 succeeds
+
+skip_when: |
+  - Simple typo or obvious syntax error (< 2 min to fix)
+  - Solution already documented in docs/solutions/
+  - Trivial fix that won't recur
+  - User declines documentation
+
+sequence:
+  after: [systematic-debugging, root-cause-tracing]
+
+related:
+  similar: [writing-plans]  # writing-plans is for implementation planning, codify-solution is for solved problems
+  complementary: [systematic-debugging, writing-plans, test-driven-development]
+
+compliance_rules:
+  - id: "docs_directory_exists"
+    description: "Solution docs directory must exist or be creatable"
+    check_type: "command_output"
+    command: "test -d docs/solutions/ || mkdir -p docs/solutions/"
+    severity: "blocking"
+    failure_message: "Cannot access docs/solutions/. Check permissions."
+
+  - id: "required_context_gathered"
+    description: "All required context fields must be populated before doc creation"
+    check_type: "manual_verification"
+    required_fields:
+      - component
+      - symptoms
+      - root_cause
+      - solution
+    severity: "blocking"
+    failure_message: "Missing required context. Ask user for: component, symptoms, root_cause, solution."
+
+  - id: "schema_validation"
+    description: "YAML frontmatter must pass schema validation"
+    check_type: "schema_validation"
+    schema_path: "schema.yaml"
+    severity: "blocking"
+    failure_message: "Schema validation failed. Check problem_type, root_cause, resolution_type enum values."
+
+prerequisites:
+  - name: "docs_directory_writable"
+    check: "test -w docs/ || mkdir -p docs/solutions/"
+    failure_message: "Cannot write to docs/. Check permissions."
+    severity: "blocking"
+
+composition:
+  works_well_with:
+    - skill: "systematic-debugging"
+      when: "debugging session completed successfully"
+      transition: "Automatically suggest codify after Phase 4 verification"
+
+    - skill: "writing-plans"
+      when: "planning new feature implementation"
+      transition: "Search docs/solutions/ for prior related issues during planning"
+
+    - skill: "test-driven-development"
+      when: "writing tests for bug fixes"
+      transition: "After test passes, document the solution for future reference"
+
+  conflicts_with: []
+
+  typical_workflow: |
+    1. Debugging session completes (systematic-debugging Phase 4)
+    2. User confirms fix worked
+    3. Auto-suggest codify-solution via hook
+    4. Gather context from conversation
+    5. Validate schema and create documentation
+    6. Cross-reference with related solutions
+---
+
+# Codify Solution Skill
+
+**Purpose:** Build searchable institutional knowledge by capturing solved problems immediately after confirmation.
+
+**The Compounding Effect:**
+```
+First time solving issue → Research (30 min)
+Document the solution   → docs/solutions/{category}/ (5 min)
+Next similar issue      → Quick lookup (2 min)
+Knowledge compounds     → Team gets smarter over time
+```
+
+---
+
+## 7-Step Process
+
+### Step 1: Detect Confirmation
+
+**Auto-invoke after phrases:**
+- "that worked"
+- "it's fixed", "fixed it"
+- "working now"
+- "problem solved", "solved it"
+- "that did it"
+- "all good now"
+- "issue resolved"
+
+**Criteria for documentation (ALL must apply):**
+- Non-trivial problem (took multiple attempts to solve)
+- Solution is not immediately obvious
+- Future sessions would benefit from having this documented
+- User hasn't declined
+
+**If triggered automatically:**
+> "It looks like you've solved a problem! Would you like to document this solution for future reference?
+>
+> Run: `/ring-default:codify`
+> Or say: 'yes, document this'"
+
+---
+
+### Step 2: Gather Context
+
+Extract from conversation history:
+
+| Field | Description | Source |
+|-------|-------------|--------|
+| **Title** | Document title for H1 heading | Derived: "[Primary Symptom] in [Component]" |
+| **Component** | Which module/file had the problem | File paths mentioned |
+| **Symptoms** | Observable error/behavior | Error messages, logs |
+| **Investigation** | What was tried and failed | Conversation history |
+| **Root Cause** | Technical explanation | Analysis performed |
+| **Solution** | What fixed it | Code changes made |
+| **Prevention** | How to avoid in future | Lessons learned |
+
+**BLOCKING GATE:**
+If ANY critical context is missing, ask the user and WAIT for response:
+
+```
+Missing context for documentation:
+- [ ] Component: Which module/service was affected?
+- [ ] Symptoms: What was the exact error message?
+- [ ] Root Cause: What was the underlying cause?
+
+Please provide the missing information before I create the documentation.
+```
+
+---
+
+### Step 3: Check Existing Docs
+
+**First, ensure docs/solutions/ exists:**
+```bash
+# Initialize directory structure if needed
+mkdir -p docs/solutions/
+```
+
+Search `docs/solutions/` for similar issues:
+
+```bash
+# Search for similar symptoms
+grep -r "exact error phrase" docs/solutions/ 2>/dev/null || true
+
+# Search by component
+grep -r "component: similar-component" docs/solutions/ 2>/dev/null || true
+```
+
+**If similar found, present options:**
+
+| Option | When to Use |
+|--------|-------------|
+| **1. Create new doc with cross-reference** | Different root cause but related symptoms (recommended) |
+| **2. Update existing doc** | Same root cause, additional context to add |
+| **3. Skip documentation** | Exact duplicate, no new information |
+
+---
+
+### Step 4: Generate Filename
+
+**Format:** `[sanitized-symptom]-[component]-[YYYYMMDD].md`
+
+**Sanitization rules:**
+1. Convert to lowercase
+2. Replace spaces with hyphens
+3. Remove special characters (keep alphanumeric and hyphens)
+4. Truncate to < 80 characters total
+5. **Ensure unique** - check for existing files:
+
+```bash
+# Get category directory from problem_type
+CATEGORY_DIR=$(get_category_directory "$PROBLEM_TYPE")
+
+# Check for filename collision
+BASE_NAME="sanitized-symptom-component-YYYYMMDD"
+FILENAME="${BASE_NAME}.md"
+COUNTER=2
+
+while [ -f "docs/solutions/${CATEGORY_DIR}/${FILENAME}" ]; do
+    FILENAME="${BASE_NAME}-${COUNTER}.md"
+    COUNTER=$((COUNTER + 1))
+done
+```
+
+**Examples:**
+```
+cannot-read-property-id-auth-service-20250127.md
+jwt-malformed-error-middleware-20250127.md
+n-plus-one-query-user-api-20250127.md
+# If duplicate exists:
+jwt-malformed-error-middleware-20250127-2.md
+```
+
+---
+
+### Step 5: Validate YAML Schema
+
+**CRITICAL GATE:** Load `schema.yaml` and validate all required fields.
+
+**Required fields checklist:**
+- [ ] `date` - Format: YYYY-MM-DD
+- [ ] `problem_type` - Must be valid enum value
+- [ ] `component` - Non-empty string
+- [ ] `symptoms` - Array with 1-5 items
+- [ ] `root_cause` - Must be valid enum value
+- [ ] `resolution_type` - Must be valid enum value
+- [ ] `severity` - Must be: critical, high, medium, or low
+
+**BLOCK if validation fails:**
+```
+Schema validation failed:
+- problem_type: "database" is not valid. Use one of: build_error, test_failure,
+  runtime_error, performance_issue, database_issue, ...
+- symptoms: Must have at least 1 item
+
+Please correct these fields before proceeding.
+```
+
+**Valid `problem_type` values:**
+- build_error, test_failure, runtime_error, performance_issue
+- database_issue, security_issue, ui_bug, integration_issue
+- logic_error, dependency_issue, configuration_error, workflow_issue
+
+**Valid `root_cause` values:**
+- missing_dependency, wrong_api_usage, configuration_error, logic_error
+- race_condition, memory_issue, type_mismatch, missing_validation
+- permission_error, environment_issue, version_incompatibility
+- data_corruption, missing_error_handling, incorrect_assumption
+
+**Valid `resolution_type` values:**
+- code_fix, config_change, dependency_update, migration
+- test_fix, environment_setup, documentation, workaround
+
+---
+
+### Step 6: Create Documentation
+
+1. **Ensure directory exists:**
+   ```bash
+   mkdir -p docs/solutions/{category}/
+   ```
+
+2. **Load template:** Read `assets/resolution-template.md`
+
+3. **Fill placeholders:**
+   - Replace all `{{FIELD}}` placeholders with gathered context
+   - Ensure code blocks have correct language tags
+   - Format tables properly
+
+   **Placeholder Syntax:**
+   - `{{FIELD}}` - Required field, must be replaced with actual value
+   - `{{FIELD|default}}` - Optional field, use default value if not available
+   - Remove unused optional field lines entirely (e.g., empty symptom slots)
+
+4. **Write file:**
+   ```bash
+   # Path: docs/solutions/{category}/{filename}.md
+   ```
+
+5. **Verify creation:**
+   ```bash
+   ls -la docs/solutions/{category}/{filename}.md
+   ```
+
+**Category to directory mapping (MANDATORY):**
+
+```bash
+# Category mapping function - use this EXACTLY
+get_category_directory() {
+    local problem_type="$1"
+    case "$problem_type" in
+        build_error) echo "build-errors" ;;
+        test_failure) echo "test-failures" ;;
+        runtime_error) echo "runtime-errors" ;;
+        performance_issue) echo "performance-issues" ;;
+        database_issue) echo "database-issues" ;;
+        security_issue) echo "security-issues" ;;
+        ui_bug) echo "ui-bugs" ;;
+        integration_issue) echo "integration-issues" ;;
+        logic_error) echo "logic-errors" ;;
+        dependency_issue) echo "dependency-issues" ;;
+        configuration_error) echo "configuration-errors" ;;
+        workflow_issue) echo "workflow-issues" ;;
+        *) echo "INVALID_CATEGORY"; return 1 ;;
+    esac
+}
+```
+
+| problem_type | Directory |
+|--------------|-----------|
+| build_error | build-errors |
+| test_failure | test-failures |
+| runtime_error | runtime-errors |
+| performance_issue | performance-issues |
+| database_issue | database-issues |
+| security_issue | security-issues |
+| ui_bug | ui-bugs |
+| integration_issue | integration-issues |
+| logic_error | logic-errors |
+| dependency_issue | dependency-issues |
+| configuration_error | configuration-errors |
+| workflow_issue | workflow-issues |
+
+**CRITICAL:** If `problem_type` is not in this list, **BLOCK** and ask user to select valid category.
+
+6. **Confirm creation:**
+   ```
+   ✅ Solution documented: docs/solutions/{category}/{filename}.md
+
+   File created with {N} required fields and {M} optional fields populated.
+   ```
+
+---
+
+### Step 7: Post-Documentation Options
+
+Present decision menu after successful creation:
+
+```
+Solution documented: docs/solutions/{category}/{filename}.md
+
+What would you like to do next?
+1. Continue with current workflow
+2. Promote to Critical Pattern (if recurring issue)
+3. Link to related issues
+4. View the documentation
+5. Search for similar issues
+```
+
+**Option 2: Promote to Critical Pattern**
+If this issue has occurred multiple times or is particularly important:
+1. Ensure directory exists: `mkdir -p docs/solutions/patterns/`
+2. Load `assets/critical-pattern-template.md`
+3. Create in `docs/solutions/patterns/`
+4. Link all related instance docs
+
+**Option 3: Link to related issues**
+- Search for related docs
+- Add to `related_issues` field in YAML frontmatter
+- Update the related doc to cross-reference this one
+
+---
+
+## Integration Points
+
+### With systematic-debugging
+
+After Phase 4 (Verification) succeeds, suggest:
+> "The fix has been verified. Would you like to document this solution for future reference?
+> Run: `/ring-default:codify`"
+
+### With writing-plans
+
+During planning phase, search existing solutions:
+```bash
+# Before designing a feature, check for known issues
+grep -r "component: {related-component}" docs/solutions/
+```
+
+### With pre-dev workflow
+
+In Gate 1 (PRD Creation), reference existing solutions:
+- Search `docs/solutions/` for related prior art
+- Include relevant learnings in requirements
+
+---
+
+## Solution Doc Search Patterns
+
+**Search by error message:**
+```bash
+grep -r "exact error text" docs/solutions/
+```
+
+**Search by component:**
+```bash
+grep -r "component: auth" docs/solutions/
+```
+
+**Search by root cause:**
+```bash
+grep -r "root_cause: race_condition" docs/solutions/
+```
+
+**Search by tag:**
+```bash
+grep -r "- authentication" docs/solutions/
+```
+
+**List all by category:**
+```bash
+ls docs/solutions/performance-issues/
+```
+
+---
+
+## Rationalization Defenses
+
+| Excuse | Counter |
+|--------|---------|
+| "This was too simple to document" | If it took > 5 min to solve, document it |
+| "I'll remember this" | You won't. Your future self will thank you. |
+| "Nobody else will hit this" | They will. And they'll spend 30 min re-investigating. |
+| "The code is self-documenting" | The investigation process isn't in the code |
+| "I'll do it later" | No you won't. Do it now while context is fresh. |
+
+---
+
+## Success Metrics
+
+A well-documented solution should:
+- [ ] Be findable via grep search on symptoms
+- [ ] Have clear root cause explanation
+- [ ] Include before/after code examples
+- [ ] List prevention strategies
+- [ ] Take < 5 minutes to write (use template)
+
+---
+
+## Example Output
+
+**File:** `docs/solutions/runtime-errors/jwt-malformed-auth-middleware-20250127.md`
+
+```markdown
+---
+date: 2025-01-27
+problem_type: runtime_error
+component: auth-middleware
+symptoms:
+  - "Error: JWT malformed"
+  - "401 Unauthorized on valid tokens"
+root_cause: wrong_api_usage
+resolution_type: code_fix
+severity: high
+project: midaz
+language: go
+framework: gin
+tags:
+  - authentication
+  - jwt
+  - middleware
+---
+
+# JWT Malformed Error in Auth Middleware
+
+## Problem
+
+Valid JWTs were being rejected with "JWT malformed" error after
+upgrading the jwt-go library.
+
+### Symptoms
+
+- "Error: JWT malformed" on all authenticated requests
+- 401 Unauthorized responses for valid tokens
+- Started after dependency update
+
+## Investigation
+
+### What didn't work
+
+1. Regenerating tokens - same error
+2. Checking token format - tokens were valid
+
+### Root Cause
+
+The new jwt-go version changed the default parser behavior.
+The `ParseWithClaims` function now requires explicit algorithm
+specification.
+
+## Solution
+
+Added explicit algorithm in parser options:
+
+```go
+// Before
+token, err := jwt.ParseWithClaims(tokenString, claims, keyFunc)
+
+// After
+token, err := jwt.ParseWithClaims(tokenString, claims, keyFunc,
+    jwt.WithValidMethods([]string{"HS256"}))
+```
+
+## Prevention
+
+1. Read changelogs before upgrading auth-related dependencies
+2. Add integration tests for token parsing
+3. Pin major versions of security-critical packages
+```