161 lines
4.4 KiB
Markdown
161 lines
4.4 KiB
Markdown
---
|
|
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
|