gh-lerianstudio-ring-default/skills/codify-solution/SKILL.md

name, description, trigger, skip_when, sequence, related, compliance_rules, prerequisites, composition

name	description	trigger	skip_when	sequence	related	compliance_rules	prerequisites	composition
codify-solution	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.	- 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	- 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	after systematic-debugging root-cause-tracing	similar complementary writing-plans systematic-debugging writing-plans test-driven-development	id description check_type command severity failure_message docs_directory_exists Solution docs directory must exist or be creatable command_output test -d docs/solutions/ || mkdir -p docs/solutions/ blocking Cannot access docs/solutions/. Check permissions. id description check_type required_fields severity failure_message required_context_gathered All required context fields must be populated before doc creation manual_verification component symptoms root_cause solution blocking Missing required context. Ask user for: component, symptoms, root_cause, solution. id description check_type schema_path severity failure_message schema_validation YAML frontmatter must pass schema validation schema_validation schema.yaml blocking Schema validation failed. Check problem_type, root_cause, resolution_type enum values.	name check failure_message severity docs_directory_writable test -w docs/ || mkdir -p docs/solutions/ Cannot write to docs/. Check permissions. blocking	works_well_with conflicts_with typical_workflow skill when transition systematic-debugging debugging session completed successfully Automatically suggest codify after Phase 4 verification skill when transition writing-plans planning new feature implementation Search docs/solutions/ for prior related issues during planning skill when transition test-driven-development writing tests for bug fixes After test passes, document the solution for future reference 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:

# Initialize directory structure if needed
mkdir -p docs/solutions/

Search docs/solutions/ for similar issues:

# 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:

# 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:

   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:

   # Path: docs/solutions/{category}/{filename}.md
   

5. Verify creation:

   ls -la docs/solutions/{category}/{filename}.md
   

Category to directory mapping (MANDATORY):

# 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:

# 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:

grep -r "exact error text" docs/solutions/

Search by component:

grep -r "component: auth" docs/solutions/

Search by root cause:

grep -r "root_cause: race_condition" docs/solutions/

Search by tag:

grep -r "- authentication" docs/solutions/

List all by category:

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

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