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
+```
--- a/skills/codify-solution/assets/critical-pattern-template.md
+++ b/skills/codify-solution/assets/critical-pattern-template.md
@@ -0,0 +1,69 @@
+---
+pattern_name: {{PATTERN_NAME}}
+category: {{CATEGORY}}
+frequency: {{high|medium|low}}
+severity_when_missed: {{critical|high|medium|low}}
+created: {{DATE}}
+instances:
+  - {{SOLUTION_DOC_1}}
+---
+
+# Critical Pattern: {{PATTERN_NAME}}
+
+## Summary
+
+{{One sentence description of the pattern}}
+
+## The Pattern
+
+{{Describe the anti-pattern or mistake that keeps recurring}}
+
+## Why It Happens
+
+1. {{Common reason 1}}
+2. {{Common reason 2}}
+
+## How to Recognize
+
+**Warning Signs:**
+- {{Sign 1}}
+- {{Sign 2}}
+
+**Typical Error Messages:**
+```
+{{Common error message}}
+```
+
+## The Fix
+
+**Standard Solution:**
+
+```{{LANGUAGE}}
+{{Code showing the correct approach}}
+```
+
+**Checklist:**
+- [ ] {{Step 1}}
+- [ ] {{Step 2}}
+
+## Prevention
+
+### Code Review Checklist
+
+When reviewing code in this area, check:
+- [ ] {{Item to verify}}
+- [ ] {{Item to verify}}
+
+### Automated Checks
+
+{{Suggest linting rules, tests, or CI checks that could catch this}}
+
+## Instance History
+
+| Date | Solution Doc | Component |
+|------|--------------|-----------|
+| {{DATE}} | [{{title}}]({{path}}) | {{component}} |
+
+## Related Patterns
+
+- {{Link to related pattern}}
--- a/skills/codify-solution/assets/resolution-template.md
+++ b/skills/codify-solution/assets/resolution-template.md
@@ -0,0 +1,89 @@
+---
+date: {{DATE}}  # Format: YYYY-MM-DD (e.g., 2025-01-27)
+problem_type: {{PROBLEM_TYPE}}
+component: {{COMPONENT}}
+symptoms:
+  - "{{SYMPTOM_1}}"
+  # - "{{SYMPTOM_2}}"  # Add if applicable
+  # - "{{SYMPTOM_3}}"  # Add if applicable
+  # - "{{SYMPTOM_4}}"  # Add if applicable
+  # - "{{SYMPTOM_5}}"  # Add if applicable (max 5 per schema)
+root_cause: {{ROOT_CAUSE}}
+resolution_type: {{RESOLUTION_TYPE}}
+severity: {{SEVERITY}}
+# Optional fields (remove if not applicable)
+project: {{PROJECT|unknown}}
+language: {{LANGUAGE|unknown}}
+framework: {{FRAMEWORK|none}}
+tags:
+  - {{TAG_1|untagged}}
+  # - {{TAG_2}}  # Add relevant tags for searchability
+  # - {{TAG_3}}  # Maximum 8 tags per schema
+related_issues: []
+---
+
+# {{TITLE}}
+
+## Problem
+
+{{Brief description of the problem - what was happening, what was expected}}
+
+### Symptoms
+
+{{List the observable symptoms - error messages, visual issues, unexpected behavior}}
+
+```
+{{Exact error message or log output if applicable}}
+```
+
+### Context
+
+- **Component:** {{COMPONENT}}
+- **Affected files:** {{List key files involved}}
+- **When it occurred:** {{Under what conditions - deployment, specific input, load, etc.}}
+
+## Investigation
+
+### What didn't work
+
+1. {{First thing tried and why it didn't solve it}}
+2. {{Second thing tried and why it didn't solve it}}
+
+### Root Cause
+
+{{Technical explanation of the actual cause - be specific}}
+
+## Solution
+
+### The Fix
+
+{{Describe what was changed and why}}
+
+```{{LANGUAGE}}
+// Before
+{{Code that had the problem}}
+
+// After
+{{Code with the fix}}
+```
+
+### Files Changed
+
+| File | Change |
+|------|--------|
+| {{file_path}} | {{Brief description of change}} |
+
+## Prevention
+
+### How to avoid this in the future
+
+1. {{Preventive measure 1}}
+2. {{Preventive measure 2}}
+
+### Warning signs to watch for
+
+- {{Early indicator that this problem might be occurring}}
+
+## Related
+
+- {{Link to related solution docs or external resources}}
--- a/skills/codify-solution/references/yaml-schema.md
+++ b/skills/codify-solution/references/yaml-schema.md
@@ -0,0 +1,163 @@
+# YAML Schema Reference for Solution Documentation
+
+This document describes the YAML frontmatter schema used in solution documentation files created by the `codify-solution` skill.
+
+## Required Fields
+
+### `date`
+- **Type:** String (ISO date format)
+- **Pattern:** `YYYY-MM-DD`
+- **Example:** `2025-01-27`
+- **Purpose:** When the problem was solved
+
+### `problem_type`
+- **Type:** Enum
+- **Values:**
+  - `build_error` - Compilation, bundling, or build process failures
+  - `test_failure` - Unit, integration, or E2E test failures
+  - `runtime_error` - Errors occurring during execution
+  - `performance_issue` - Slow queries, memory leaks, latency
+  - `database_issue` - Migration, query, or data integrity problems
+  - `security_issue` - Vulnerabilities, auth problems, data exposure
+  - `ui_bug` - Visual glitches, interaction problems
+  - `integration_issue` - API, service communication, third-party
+  - `logic_error` - Incorrect behavior, wrong calculations
+  - `dependency_issue` - Package conflicts, version mismatches
+  - `configuration_error` - Environment, settings, config files
+  - `workflow_issue` - CI/CD, deployment, process problems
+- **Purpose:** Determines storage directory and enables filtering
+
+### `component`
+- **Type:** String (free-form)
+- **Example:** `auth-service`, `payment-gateway`, `user-dashboard`
+- **Purpose:** Identifies the affected module/service
+- **Note:** Not an enum - varies by project
+
+### `symptoms`
+- **Type:** Array of strings (1-5 items)
+- **Example:**
+  ```yaml
+  symptoms:
+    - "Error: Cannot read property 'id' of undefined"
+    - "Login button unresponsive after 3 clicks"
+  ```
+- **Purpose:** Observable error messages or behaviors for searchability
+
+### `root_cause`
+- **Type:** Enum
+- **Values:**
+  - `missing_dependency` - Required package/module not installed
+  - `wrong_api_usage` - Incorrect use of library/framework API
+  - `configuration_error` - Wrong settings or environment variables
+  - `logic_error` - Bug in business logic or algorithms
+  - `race_condition` - Timing-dependent bug
+  - `memory_issue` - Leaks, excessive allocation
+  - `type_mismatch` - Wrong type passed or returned
+  - `missing_validation` - Input not properly validated
+  - `permission_error` - Access denied, wrong credentials
+  - `environment_issue` - Dev/prod differences, missing tools
+  - `version_incompatibility` - Breaking changes between versions
+  - `data_corruption` - Invalid or inconsistent data state
+  - `missing_error_handling` - Unhandled exceptions/rejections
+  - `incorrect_assumption` - Wrong mental model of system
+- **Purpose:** Enables pattern detection across similar issues
+
+### `resolution_type`
+- **Type:** Enum
+- **Values:**
+  - `code_fix` - Changed source code
+  - `config_change` - Updated configuration files
+  - `dependency_update` - Updated/added/removed packages
+  - `migration` - Database or data migration
+  - `test_fix` - Fixed test code (not production code)
+  - `environment_setup` - Changed environment/infrastructure
+  - `documentation` - Solution was documenting existing behavior
+  - `workaround` - Temporary fix, not ideal solution
+- **Purpose:** Categorizes the type of change made
+
+### `severity`
+- **Type:** Enum
+- **Values:** `critical`, `high`, `medium`, `low`
+- **Purpose:** Original impact severity for prioritization analysis
+
+## Optional Fields
+
+### `project`
+- **Type:** String
+- **Example:** `midaz`
+- **Purpose:** Project identifier (auto-detected from git)
+
+### `language`
+- **Type:** String
+- **Example:** `go`, `typescript`, `python`
+- **Purpose:** Primary language involved for filtering
+
+### `framework`
+- **Type:** String
+- **Example:** `gin`, `nextjs`, `fastapi`
+- **Purpose:** Framework-specific issues for filtering
+
+### `tags`
+- **Type:** Array of strings (max 8)
+- **Example:** `[authentication, jwt, middleware, rate-limiting]`
+- **Purpose:** Free-form keywords for discovery
+
+### `related_issues`
+- **Type:** Array of strings
+- **Example:**
+  ```yaml
+  related_issues:
+    - "docs/solutions/security-issues/jwt-expiry-20250115.md"
+    - "https://github.com/org/repo/issues/123"
+  ```
+- **Purpose:** Cross-reference related solutions or external issues
+
+## Category to Directory Mapping
+
+| `problem_type` | Directory |
+|----------------|-----------|
+| `build_error` | `docs/solutions/build-errors/` |
+| `test_failure` | `docs/solutions/test-failures/` |
+| `runtime_error` | `docs/solutions/runtime-errors/` |
+| `performance_issue` | `docs/solutions/performance-issues/` |
+| `database_issue` | `docs/solutions/database-issues/` |
+| `security_issue` | `docs/solutions/security-issues/` |
+| `ui_bug` | `docs/solutions/ui-bugs/` |
+| `integration_issue` | `docs/solutions/integration-issues/` |
+| `logic_error` | `docs/solutions/logic-errors/` |
+| `dependency_issue` | `docs/solutions/dependency-issues/` |
+| `configuration_error` | `docs/solutions/configuration-errors/` |
+| `workflow_issue` | `docs/solutions/workflow-issues/` |
+
+## Validation Rules
+
+1. **All required fields must be present**
+2. **Enum values must match exactly** (case-sensitive)
+3. **Date must be valid ISO format**
+4. **Symptoms array must have 1-5 items**
+5. **Tags array limited to 8 items**
+
+## Example Complete Frontmatter
+
+```yaml
+---
+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
+related_issues:
+  - "docs/solutions/security-issues/jwt-refresh-logic-20250110.md"
+---
+```
--- a/skills/codify-solution/schema.yaml
+++ b/skills/codify-solution/schema.yaml
@@ -0,0 +1,137 @@
+# Schema for Solution Documentation
+# Version: 1.0
+# Validator: Manual validation per codify-solution skill Step 5
+# Format: Custom Ring schema (not JSON Schema)
+# Used by: codify-solution skill for AI agent validation
+#
+# This schema defines the required and optional fields for solution documentation.
+# AI agents use this schema to validate YAML frontmatter before creating docs.
+
+required_fields:
+  date:
+    type: string
+    pattern: '^\d{4}-\d{2}-\d{2}$'
+    description: "Date problem was solved (YYYY-MM-DD)"
+    example: "2025-01-27"
+
+  problem_type:
+    type: enum
+    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
+    description: "Primary category - determines storage directory"
+
+  component:
+    type: string
+    description: "Affected component/module (project-specific, not enum)"
+    example: "auth-service"
+
+  symptoms:
+    type: array
+    items: string
+    min_items: 1
+    max_items: 5
+    description: "Observable symptoms (error messages, visual issues)"
+    example:
+      - "Error: Cannot read property 'id' of undefined"
+      - "Login button unresponsive after 3 clicks"
+
+  root_cause:
+    type: enum
+    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
+    description: "Fundamental cause of the problem"
+
+  resolution_type:
+    type: enum
+    values:
+      - code_fix
+      - config_change
+      - dependency_update
+      - migration
+      - test_fix
+      - environment_setup
+      - documentation
+      - workaround
+    description: "Type of fix applied"
+
+  severity:
+    type: enum
+    values:
+      - critical
+      - high
+      - medium
+      - low
+    description: "Impact severity of the original problem"
+
+optional_fields:
+  project:
+    type: string
+    description: "Project name (auto-detected from git remote)"
+    example: "midaz"
+
+  language:
+    type: string
+    description: "Primary language involved"
+    example: "go"
+
+  framework:
+    type: string
+    description: "Framework if applicable"
+    example: "gin"
+
+  tags:
+    type: array
+    items: string
+    max_items: 8
+    description: "Searchable keywords for discovery"
+    example:
+      - "authentication"
+      - "jwt"
+      - "middleware"
+
+  related_issues:
+    type: array
+    items: string
+    description: "Links to related solution docs or external issues"
+    example:
+      - "docs/solutions/security-issues/jwt-expiry-handling-20250115.md"
+      - "https://github.com/org/repo/issues/123"
+
+# Category to directory mapping
+category_directories:
+  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"