john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(plugin): reorganize compounding-engineering v2.0.0

Browse Source 
Major restructure of the compounding-engineering plugin:

## Agents (24 total, now categorized)
- review/ (10): architecture-strategist, code-simplicity-reviewer,
  data-integrity-guardian, dhh-rails-reviewer, kieran-rails-reviewer,
  kieran-python-reviewer, kieran-typescript-reviewer,
  pattern-recognition-specialist, performance-oracle, security-sentinel
- research/ (4): best-practices-researcher, framework-docs-researcher,
  git-history-analyzer, repo-research-analyst
- design/ (3): design-implementation-reviewer, design-iterator,
  figma-design-sync
- workflow/ (6): bug-reproduction-validator, every-style-editor,
  feedback-codifier, lint, pr-comment-resolver, spec-flow-analyzer
- docs/ (1): ankane-readme-writer

## Commands (15 total)
- Moved workflow commands to commands/workflows/ subdirectory
- Added: changelog, create-agent-skill, heal-skill, plan_review,
  prime, reproduce-bug, resolve_parallel, resolve_pr_parallel

## Skills (11 total)
- Added: andrew-kane-gem-writer, codify-docs, create-agent-skills,
  dhh-ruby-style, dspy-ruby, every-style-editor, file-todos,
  frontend-design, git-worktree, skill-creator
- Kept: gemini-imagegen

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
2025-11-24 11:42:18 -08:00
parent 8cd694c518
commit 8cc99ab483
99 changed files with 16491 additions and 647 deletions
Download Patch File Download Diff File Expand all files Collapse all files

510
plugins/compounding-engineering/skills/codify-docs/SKILL.md Normal file
View File

@@ -0,0 +1,510 @@
---
name: codify-docs
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
allowed-tools:
- Read # Parse conversation context
- Write # Create resolution docs
- Bash # Create directories
- Grep # Search existing docs
preconditions:
- Problem has been solved (not in-progress)
- Solution has been verified working
---
# codify-docs Skill
**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
## Overview
This skill captures problem solutions immediately after confirmation, creating structured documentation that serves as a searchable knowledge base for future sessions.
**Organization:** Single-file architecture - each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.
---
<critical_sequence name="documentation-capture" enforce_order="strict">
## 7-Step Process
<step number="1" required="true">
### Step 1: Detect Confirmation
**Auto-invoke after phrases:**
- "that worked"
- "it's fixed"
- "working now"
- "problem solved"
- "that did it"
**OR manual:** `/doc-fix` command
**Non-trivial problems only:**
- Multiple investigation attempts needed
- Tricky debugging that took time
- Non-obvious solution
- Future sessions would benefit
**Skip documentation for:**
- Simple typos
- Obvious syntax errors
- Trivial fixes immediately corrected
</step>
<step number="2" required="true" depends_on="1">
### Step 2: Gather Context
Extract from conversation history:
**Required information:**
- **Module name**: Which CORA module had the problem
- **Symptom**: Observable error/behavior (exact error messages)
- **Investigation attempts**: What didn't work and why
- **Root cause**: Technical explanation of actual problem
- **Solution**: What fixed it (code/config changes)
- **Prevention**: How to avoid in future
**Environment details:**
- Rails version
- Stage (0-6 or post-implementation)
- OS version
- File/line references
**BLOCKING REQUIREMENT:** If critical context is missing (module name, exact error, stage, or resolution steps), ask user and WAIT for response before proceeding to Step 3:
```
I need a few details to document this properly:
1. Which module had this issue? [ModuleName]
2. What was the exact error message or symptom?
3. What stage were you in? (0-6 or post-implementation)
[Continue after user provides details]
```
</step>
<step number="3" required="false" depends_on="2">
### Step 3: Check Existing Docs
Search docs/solutions/ for similar issues:
```bash
# Search by error message keywords
grep -r "exact error phrase" docs/solutions/
# Search by symptom category
ls docs/solutions/[category]/
```
**IF similar issue found:**
THEN present decision options:
```
Found similar issue: docs/solutions/[path]
What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc (only if same root cause)
3. Other
Choose (1-3): _
```
WAIT for user response, then execute chosen action.
**ELSE** (no similar issue found):
Proceed directly to Step 4 (no user interaction needed).
</step>
<step number="4" required="true" depends_on="2">
### Step 4: Generate Filename
Format: `[sanitized-symptom]-[module]-[YYYYMMDD].md`
**Sanitization rules:**
- Lowercase
- Replace spaces with hyphens
- Remove special characters except hyphens
- Truncate to reasonable length (< 80 chars)
**Examples:**
- `missing-include-BriefSystem-20251110.md`
- `parameter-not-saving-state-EmailProcessing-20251110.md`
- `webview-crash-on-resize-Assistant-20251110.md`
</step>
<step number="5" required="true" depends_on="4" blocking="true">
### Step 5: Validate YAML Schema
**CRITICAL:** All docs require validated YAML frontmatter with enum validation.
<validation_gate name="yaml-schema" blocking="true">
**Validate against schema:**
Load `schema.yaml` and classify the problem against the enum values defined in `references/yaml-schema.md`. Ensure all required fields are present and match allowed values exactly.
**BLOCK if validation fails:**
```
❌ YAML validation failed
Errors:
- problem_type: must be one of schema enums, got "compilation_error"
- severity: must be one of [critical, moderate, minor], got "high"
- symptoms: must be array with 1-5 items, got string
Please provide corrected values.
```
**GATE ENFORCEMENT:** Do NOT proceed to Step 6 (Create Documentation) until YAML frontmatter passes all validation rules defined in `schema.yaml`.
</validation_gate>
</step>
<step number="6" required="true" depends_on="5">
### Step 6: Create Documentation
**Determine category from problem_type:** Use the category mapping defined in `references/yaml-schema.md` (lines 49-61).
**Create documentation file:**
```bash
PROBLEM_TYPE="[from validated YAML]"
CATEGORY="[mapped from problem_type]"
FILENAME="[generated-filename].md"
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"
# Create directory if needed
mkdir -p "docs/solutions/${CATEGORY}"
# Write documentation using template from assets/resolution-template.md
# (Content populated with Step 2 context and validated YAML frontmatter)
```
**Result:**
- Single file in category directory
- Enum validation ensures consistent categorization
**Create documentation:** Populate the structure from `assets/resolution-template.md` with context gathered in Step 2 and validated YAML frontmatter from Step 5.
</step>
<step number="7" required="false" depends_on="6">
### Step 7: Cross-Reference & Critical Pattern Detection
If similar issues found in Step 3:
**Update existing doc:**
```bash
# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]
```
**Update new doc:**
Already includes cross-reference from Step 6.
**Update patterns if applicable:**
If this represents a common pattern (3+ similar issues):
```bash
# Add to docs/solutions/patterns/common-solutions.md
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'
## [Pattern Name]
**Common symptom:** [Description]
**Root cause:** [Technical explanation]
**Solution pattern:** [General approach]
**Examples:**
- [Link to doc 1]
- [Link to doc 2]
- [Link to doc 3]
EOF
```
**Critical Pattern Detection (Optional Proactive Suggestion):**
If this issue has automatic indicators suggesting it might be critical:
- Severity: `critical` in YAML
- Affects multiple modules OR foundational stage (Stage 2 or 3)
- Non-obvious solution
Then in the decision menu (Step 8), add a note:
```
💡 This might be worth adding to Required Reading (Option 2)
```
But **NEVER auto-promote**. User decides via decision menu (Option 2).
**Template for critical pattern addition:**
When user selects Option 2 (Add to Required Reading), use the template from `assets/critical-pattern-template.md` to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/cora-critical-patterns.md`.
</step>
</critical_sequence>
---
<decision_gate name="post-documentation" wait_for_user="true">
## Decision Menu After Capture
After successful documentation, present options and WAIT for user response:
```
✓ Solution documented
File created:
- docs/solutions/[category]/[filename].md
What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other
```
**Handle responses:**
**Option 1: Continue workflow**
- Return to calling skill/workflow
- Documentation is complete
**Option 2: Add to Required Reading** ⭐ PRIMARY PATH FOR CRITICAL PATTERNS
User selects this when:
- System made this mistake multiple times across different modules
- Solution is non-obvious but must be followed every time
- Foundational requirement (Rails, Rails API, threading, etc.)
Action:
1. Extract pattern from the documentation
2. Format as ❌ WRONG vs ✅ CORRECT with code examples
3. Add to `docs/solutions/patterns/cora-critical-patterns.md`
4. Add cross-reference back to this doc
5. Confirm: "✓ Added to Required Reading. All subagents will see this pattern before code generation."
**Option 3: Link related issues**
- Prompt: "Which doc to link? (provide filename or describe)"
- Search docs/solutions/ for the doc
- Add cross-reference to both docs
- Confirm: "✓ Cross-reference added"
**Option 4: Add to existing skill**
User selects this when the documented solution relates to an existing learning skill:
Action:
1. Prompt: "Which skill? (hotwire-native, etc.)"
2. Determine which reference file to update (resources.md, patterns.md, or examples.md)
3. Add link and brief description to appropriate section
4. Confirm: "✓ Added to [skill-name] skill in [file]"
Example: For Hotwire Native Tailwind variants solution:
- Add to `hotwire-native/references/resources.md` under "CORA-Specific Resources"
- Add to `hotwire-native/references/examples.md` with link to solution doc
**Option 5: Create new skill**
User selects this when the solution represents the start of a new learning domain:
Action:
1. Prompt: "What should the new skill be called? (e.g., stripe-billing, email-processing)"
2. Run `python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]`
3. Create initial reference files with this solution as first example
4. Confirm: "✓ Created new [skill-name] skill with this solution as first example"
**Option 6: View documentation**
- Display the created documentation
- Present decision menu again
**Option 7: Other**
- Ask what they'd like to do
</decision_gate>
---
<integration_protocol>
## Integration Points
**Invoked by:**
- /codify command (primary interface)
- Manual invocation in conversation after solution confirmed
- Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc.
**Invokes:**
- None (terminal skill - does not delegate to other skills)
**Handoff expectations:**
All context needed for documentation should be present in conversation history before invocation.
</integration_protocol>
---
<success_criteria>
## Success Criteria
Documentation is successful when ALL of the following are true:
- ✅ YAML frontmatter validated (all required fields, correct formats)
- ✅ File created in docs/solutions/[category]/[filename].md
- ✅ Enum values match schema.yaml exactly
- ✅ Code examples included in solution section
- ✅ Cross-references added if related issues found
- ✅ User presented with decision menu and action confirmed
</success_criteria>
---
## Error Handling
**Missing context:**
- Ask user for missing details
- Don't proceed until critical info provided
**YAML validation failure:**
- Show specific errors
- Present retry with corrected values
- BLOCK until valid
**Similar issue ambiguity:**
- Present multiple matches
- Let user choose: new doc, update existing, or link as duplicate
**Module not in CORA-MODULES.md:**
- Warn but don't block
- Proceed with documentation
- Suggest: "Add [Module] to CORA-MODULES.md if not there"
---
## Execution Guidelines
**MUST do:**
- Validate YAML frontmatter (BLOCK if invalid per Step 5 validation gate)
- Extract exact error messages from conversation
- Include code examples in solution section
- Create directories before writing files (`mkdir -p`)
- Ask user and WAIT if critical context missing
**MUST NOT do:**
- Skip YAML validation (validation gate is blocking)
- Use vague descriptions (not searchable)
- Omit code examples or cross-references
---
## Quality Guidelines
**Good documentation has:**
- ✅ Exact error messages (copy-paste from output)
- ✅ Specific file:line references
- ✅ Observable symptoms (what you saw, not interpretations)
- ✅ Failed attempts documented (helps avoid wrong paths)
- ✅ Technical explanation (not just "what" but "why")
- ✅ Code examples (before/after if applicable)
- ✅ Prevention guidance (how to catch early)
- ✅ Cross-references (related issues)
**Avoid:**
- ❌ Vague descriptions ("something was wrong")
- ❌ Missing technical details ("fixed the code")
- ❌ No context (which version? which file?)
- ❌ Just code dumps (explain why it works)
- ❌ No prevention guidance
- ❌ No cross-references
---
## Example Scenario
**User:** "That worked! The N+1 query is fixed."
**Skill activates:**
1. **Detect confirmation:** "That worked!" triggers auto-invoke
2. **Gather context:**
- Module: Brief System
- Symptom: Brief generation taking >5 seconds, N+1 query when loading email threads
- Failed attempts: Added pagination (didn't help), checked background job performance
- Solution: Added eager loading with `includes(:emails)` on Brief model
- Root cause: Missing eager loading causing separate database query per email thread
3. **Check existing:** No similar issue found
4. **Generate filename:** `n-plus-one-brief-generation-BriefSystem-20251110.md`
5. **Validate YAML:**
```yaml
module: Brief System
date: 2025-11-10
problem_type: performance_issue
component: rails_model
symptoms:
- "N+1 query when loading email threads"
- "Brief generation taking >5 seconds"
root_cause: missing_include
severity: high
tags: [n-plus-one, eager-loading, performance]
```
✅ Valid
6. **Create documentation:**
- `docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md`
7. **Cross-reference:** None needed (no similar issues)
**Output:**
```
✓ Solution documented
File created:
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (cora-critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other
```
---
## Future Enhancements
**Not in Phase 7 scope, but potential:**
- Search by date range
- Filter by severity
- Tag-based search interface
- Metrics (most common issues, resolution time)
- Export to shareable format (community knowledge sharing)
- Import community solutions

34
plugins/compounding-engineering/skills/codify-docs/assets/critical-pattern-template.md Normal file
View File

@@ -0,0 +1,34 @@
# Critical Pattern Template
Use this template when adding a pattern to `docs/solutions/patterns/cora-critical-patterns.md`:
---
## N. [Pattern Name] (ALWAYS REQUIRED)
### ❌ WRONG ([Will cause X error])
```[language]
[code showing wrong approach]
```
### ✅ CORRECT
```[language]
[code showing correct approach]
```
**Why:** [Technical explanation of why this is required]
**Placement/Context:** [When this applies]
**Documented in:** `docs/solutions/[category]/[filename].md`
---
**Instructions:**
1. Replace N with the next pattern number
2. Replace [Pattern Name] with descriptive title
3. Fill in WRONG example with code that causes the problem
4. Fill in CORRECT example with the solution
5. Explain the technical reason in "Why"
6. Clarify when this pattern applies in "Placement/Context"
7. Link to the full troubleshooting doc where this was originally solved

93
plugins/compounding-engineering/skills/codify-docs/assets/resolution-template.md Normal file
View File

@@ -0,0 +1,93 @@
---
module: [Module name or "CORA" for system-wide]
date: [YYYY-MM-DD]
problem_type: [build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error]
component: [rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments]
symptoms:
- [Observable symptom 1 - specific error message or behavior]
- [Observable symptom 2 - what user actually saw/experienced]
root_cause: [missing_association|missing_include|missing_index|wrong_api|scope_issue|thread_violation|async_timing|memory_leak|config_error|logic_error|test_isolation|missing_validation|missing_permission]
rails_version: [7.1.2 - optional]
resolution_type: [code_fix|migration|config_change|test_fix|dependency_update|environment_setup]
severity: [critical|high|medium|low]
tags: [keyword1, keyword2, keyword3]
---
# Troubleshooting: [Clear Problem Title]
## Problem
[1-2 sentence clear description of the issue and what the user experienced]
## Environment
- Module: [Name or "CORA system"]
- Rails Version: [e.g., 7.1.2]
- Affected Component: [e.g., "Email Processing model", "Brief System service", "Authentication controller"]
- Date: [YYYY-MM-DD when this was solved]
## Symptoms
- [Observable symptom 1 - what the user saw/experienced]
- [Observable symptom 2 - error messages, visual issues, unexpected behavior]
- [Continue as needed - be specific]
## What Didn't Work
**Attempted Solution 1:** [Description of what was tried]
- **Why it failed:** [Technical reason this didn't solve the problem]
**Attempted Solution 2:** [Description of second attempt]
- **Why it failed:** [Technical reason]
[Continue for all significant attempts that DIDN'T work]
[If nothing else was attempted first, write:]
**Direct solution:** The problem was identified and fixed on the first attempt.
## Solution
[The actual fix that worked - provide specific details]
**Code changes** (if applicable):
```ruby
# Before (broken):
[Show the problematic code]
# After (fixed):
[Show the corrected code with explanation]
```
**Database migration** (if applicable):
```ruby
# Migration change:
[Show what was changed in the migration]
```
**Commands run** (if applicable):
```bash
# Steps taken to fix:
[Commands or actions]
```
## Why This Works
[Technical explanation of:]
1. What was the ROOT CAUSE of the problem?
2. Why does the solution address this root cause?
3. What was the underlying issue (API misuse, configuration error, Rails version issue, etc.)?
[Be detailed enough that future developers understand the "why", not just the "what"]
## Prevention
[How to avoid this problem in future CORA development:]
- [Specific coding practice, check, or pattern to follow]
- [What to watch out for]
- [How to catch this early]
## Related Issues
[If any similar problems exist in docs/solutions/, link to them:]
- See also: [another-related-issue.md](../category/another-related-issue.md)
- Similar to: [related-problem.md](../category/related-problem.md)
[If no related issues, write:]
No related issues documented yet.

65
plugins/compounding-engineering/skills/codify-docs/references/yaml-schema.md Normal file
View File

@@ -0,0 +1,65 @@
# YAML Frontmatter Schema
**See `.claude/skills/codify-docs/schema.yaml` for the complete schema specification.**
## Required Fields
- **module** (string): Module name (e.g., "EmailProcessing") or "CORA" for system-wide issues
- **date** (string): ISO 8601 date (YYYY-MM-DD)
- **problem_type** (enum): One of [build_error, test_failure, runtime_error, performance_issue, database_issue, security_issue, ui_bug, integration_issue, logic_error, developer_experience, workflow_issue, best_practice, documentation_gap]
- **component** (enum): One of [rails_model, rails_controller, rails_view, service_object, background_job, database, frontend_stimulus, hotwire_turbo, email_processing, brief_system, assistant, authentication, payments, development_workflow, testing_framework, documentation, tooling]
- **symptoms** (array): 1-5 specific observable symptoms
- **root_cause** (enum): One of [missing_association, missing_include, missing_index, wrong_api, scope_issue, thread_violation, async_timing, memory_leak, config_error, logic_error, test_isolation, missing_validation, missing_permission, missing_workflow_step, inadequate_documentation, missing_tooling, incomplete_setup]
- **resolution_type** (enum): One of [code_fix, migration, config_change, test_fix, dependency_update, environment_setup, workflow_improvement, documentation_update, tooling_addition, seed_data_update]
- **severity** (enum): One of [critical, high, medium, low]
## Optional Fields
- **rails_version** (string): Rails version in X.Y.Z format
- **tags** (array): Searchable keywords (lowercase, hyphen-separated)
## Validation Rules
1. All required fields must be present
2. Enum fields must match allowed values exactly (case-sensitive)
3. symptoms must be YAML array with 1-5 items
4. date must match YYYY-MM-DD format
5. rails_version (if provided) must match X.Y.Z format
6. tags should be lowercase, hyphen-separated
## Example
```yaml
---
module: Email Processing
date: 2025-11-12
problem_type: performance_issue
component: rails_model
symptoms:
- "N+1 query when loading email threads"
- "Brief generation taking >5 seconds"
root_cause: missing_include
rails_version: 7.1.2
resolution_type: code_fix
severity: high
tags: [n-plus-one, eager-loading, performance]
---
```
## Category Mapping
Based on `problem_type`, documentation is filed in:
- **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/`
- **developer_experience** → `docs/solutions/developer-experience/`
- **workflow_issue** → `docs/solutions/workflow-issues/`
- **best_practice** → `docs/solutions/best-practices/`
- **documentation_gap** → `docs/solutions/documentation-gaps/`

176
plugins/compounding-engineering/skills/codify-docs/schema.yaml Normal file
View File

@@ -0,0 +1,176 @@
# CORA Documentation Schema
# This schema MUST be validated before writing any documentation file
required_fields:
module:
type: string
description: "Module/area of CORA (e.g., 'Email Processing', 'Brief System', 'Authentication')"
examples:
- "Email Processing"
- "Brief System"
- "Assistant"
- "Authentication"
date:
type: string
pattern: '^\d{4}-\d{2}-\d{2}$'
description: "Date when this problem was solved (YYYY-MM-DD)"
problem_type:
type: enum
values:
- build_error # Rails, bundle, compilation errors
- test_failure # Test failures, flaky tests
- runtime_error # Exceptions, crashes during execution
- performance_issue # Slow queries, memory issues, N+1 queries
- database_issue # Migration, query, schema problems
- security_issue # Authentication, authorization, XSS, SQL injection
- ui_bug # Frontend, Stimulus, Turbo issues
- integration_issue # External service, API integration problems
- logic_error # Business logic bugs
- developer_experience # DX issues: workflow, tooling, seed data, dev setup
- workflow_issue # Development process, missing steps, unclear practices
- best_practice # Documenting patterns and practices to follow
- documentation_gap # Missing or inadequate documentation
description: "Primary category of the problem"
component:
type: enum
values:
- rails_model # ActiveRecord models
- rails_controller # ActionController
- rails_view # ERB templates, ViewComponent
- service_object # Custom service classes
- background_job # Sidekiq, Active Job
- database # PostgreSQL, migrations, schema
- frontend_stimulus # Stimulus JS controllers
- hotwire_turbo # Turbo Streams, Turbo Drive
- email_processing # Email handling, mailers
- brief_system # Brief generation, summarization
- assistant # AI assistant, prompts
- authentication # Devise, user auth
- payments # Stripe, billing
- development_workflow # Dev process, seed data, tooling
- testing_framework # Test setup, fixtures, VCR
- documentation # README, guides, inline docs
- tooling # Scripts, generators, CLI tools
description: "CORA component involved"
symptoms:
type: array[string]
min_items: 1
max_items: 5
description: "Observable symptoms (error messages, visual issues, crashes)"
examples:
- "N+1 query detected in brief generation"
- "Brief emails not appearing in summary"
- "Turbo Stream response returns 404"
root_cause:
type: enum
values:
- missing_association # Incorrect Rails associations
- missing_include # Missing eager loading (N+1)
- missing_index # Database performance issue
- wrong_api # Using deprecated/incorrect Rails API
- scope_issue # Incorrect query scope or filtering
- thread_violation # Real-time unsafe operation
- async_timing # Async/background job timing
- memory_leak # Memory leak or excessive allocation
- config_error # Configuration or environment issue
- logic_error # Algorithm/business logic bug
- test_isolation # Test isolation or fixture issue
- missing_validation # Missing model validation
- missing_permission # Authorization check missing
- missing_workflow_step # Skipped or undocumented workflow step
- inadequate_documentation # Missing or unclear documentation
- missing_tooling # Lacking helper scripts or automation
- incomplete_setup # Missing seed data, fixtures, or config
description: "Fundamental cause of the problem"
resolution_type:
type: enum
values:
- code_fix # Fixed by changing source code
- migration # Fixed by database migration
- config_change # Fixed by changing configuration
- test_fix # Fixed by correcting tests
- dependency_update # Fixed by updating gem/dependency
- environment_setup # Fixed by environment configuration
- workflow_improvement # Improved development workflow or process
- documentation_update # Added or updated documentation
- tooling_addition # Added helper script or automation
- seed_data_update # Updated db/seeds.rb or fixtures
description: "Type of fix applied"
severity:
type: enum
values:
- critical # Blocks production or development (build fails, data loss)
- high # Impairs core functionality (feature broken, security issue)
- medium # Affects specific feature (UI broken, performance impact)
- low # Minor issue or edge case
description: "Impact severity"
optional_fields:
rails_version:
type: string
pattern: '^\d+\.\d+\.\d+$'
description: "Rails version where this was encountered (e.g., '7.1.0')"
related_components:
type: array[string]
description: "Other components that interact with this issue"
tags:
type: array[string]
max_items: 8
description: "Searchable keywords (lowercase, hyphen-separated)"
examples:
- "n-plus-one"
- "eager-loading"
- "test-isolation"
- "turbo-stream"
validation_rules:
- "module must be a valid CORA module name"
- "date must be in YYYY-MM-DD format"
- "problem_type must match one of the enum values"
- "component must match one of the enum values"
- "symptoms must be specific and observable (not vague)"
- "root_cause must be the ACTUAL cause, not a symptom"
- "resolution_type must match one of the enum values"
- "severity must match one of the enum values"
- "tags should be lowercase, hyphen-separated"
# Example valid front matter:
# ---
# module: Email Processing
# date: 2025-11-12
# problem_type: performance_issue
# component: rails_model
# symptoms:
# - N+1 query when loading email threads
# - Brief generation taking >5 seconds
# root_cause: missing_include
# rails_version: 7.1.2
# resolution_type: code_fix
# severity: high
# tags: [n-plus-one, eager-loading, performance]
# ---
#
# Example DX issue front matter:
# ---
# module: Development Workflow
# date: 2025-11-13
# problem_type: developer_experience
# component: development_workflow
# symptoms:
# - No example data for new feature in development
# - Rails db:seed doesn't demonstrate new capabilities
# root_cause: incomplete_setup
# rails_version: 7.1.2
# resolution_type: seed_data_update
# severity: low
# tags: [seed-data, dx, workflow]
# ---