Initial commit

commands/codify.md

@@ -0,0 +1,160 @@
+---
+name: codify
+description: Document a solved problem to build searchable knowledge base
+argument-hint: "[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