gh-lerianstudio-ring-default/commands/codify.md

name, description, argument-hint

name	description	argument-hint
codify	Document a solved problem to build searchable knowledge base	[optional-description]

Capture the current problem solution as structured documentation in docs/solutions/{category}/. Use this after confirming a fix worked to build institutional knowledge that helps future debugging.

Usage

/ring-default:codify [optional description of the problem]

Arguments

Argument	Required	Description
description	No	Brief description of the problem (helps pre-fill template)

Examples

Document After Debugging

/ring-default:codify

Captures the solution from the current conversation context.

Document With Description

/ring-default:codify JWT parsing error in auth middleware

Pre-fills the title and helps with context gathering.

Document Specific Fix

/ring-default:codify race condition in user session cleanup

Documents a race condition fix with the given context.

What It Does

1. Gathers Context - Extracts problem details from conversation history
2. Checks for Duplicates - Searches docs/solutions/ for similar issues
3. Validates Schema - Ensures all required fields are present
4. Creates Documentation - Writes structured markdown to docs/solutions/{category}/
5. Offers Next Steps - Link issues, add patterns, continue workflow

When to Use

• After debugging session where fix was non-trivial (> 5 min)
• When solution would help future developers or AI agents
• After investigating error that took multiple attempts to solve
• When you want to prevent re-investigating the same issue

When NOT to Use

• Simple typo or syntax error (took < 2 min)
• Issue already documented in docs/solutions/
• One-off issue that won't recur
• Trivial fix obvious from error message

Output Location

Solutions are stored in category-specific directories:

docs/solutions/
├── build-errors/
├── test-failures/
├── runtime-errors/
├── performance-issues/
├── database-issues/
├── security-issues/
├── ui-bugs/
├── integration-issues/
├── logic-errors/
├── dependency-issues/
├── configuration-errors/
└── workflow-issues/

Required Fields

The command will gather and validate:

Field	Description
date	When the problem was solved
problem_type	Category (determines directory)
component	Affected module/service
symptoms	Observable errors/behaviors (1-5)
root_cause	Fundamental cause
resolution_type	Type of fix applied
severity	Impact level

Process Flow

/codify invoked
    ↓
Gather context from conversation
    ↓
Check for existing similar docs
    ↓
Validate YAML schema
    ↓
Create documentation file
    ↓
Present next steps menu

Related Commands/Skills

Command/Skill	Relationship
ring-default:systematic-debugging	Run /codify AFTER debugging completes
ring-default:codify-solution	The underlying skill (invoked automatically)
/ring-default:write-plan	Plans can search documented solutions (invokes write-plan agent)
/ring-pm-team:pre-dev-feature	Pre-dev can reference prior solutions

The Compounding Effect

Session 1: Debug issue (30 min) → Document (5 min)
Session 2: Search docs (2 min) → Apply known fix (5 min)
Session 3: Quick lookup (1 min) → Instant fix

Time saved grows with each reuse.

Troubleshooting

"Missing required context"

The command needs more information. You'll be prompted for:

• Component name
• Error symptoms
• Root cause
• What was changed to fix it

"Similar issue already documented"

A related solution exists. You'll be asked to:

1. Create new doc with cross-reference (different root cause)
2. Update existing doc (same root cause, new info)
3. Skip documentation (exact duplicate)

"Schema validation failed"

A required field has an invalid value. Check:

• problem_type uses valid enum value
• root_cause uses valid enum value
• symptoms has 1-5 items
• severity is critical/high/medium/low

Tips

1. Run immediately after fix - Context is freshest right after solving
2. Include exact error messages - Makes future searches work
3. Add prevention tips - Most valuable part of documentation
4. Cross-reference related docs - Build knowledge graph
5. Use tags - Improves discoverability