Initial commit

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"
+---
+```