claude-engineering-plugin/plugins/compound-engineering/skills/compound-docs/assets/resolution-template.md

module, date, problem_type, component, symptoms, root_cause, rails_version, resolution_type, severity, tags

module	date	problem_type	component	symptoms	root_cause	rails_version	resolution_type	severity	tags
Module name or "CORA" for system-wide	YYYY-MM-DD	build_error|test_failure|runtime_error|performance_issue|database_issue|security_issue|ui_bug|integration_issue|logic_error	rails_model|rails_controller|rails_view|service_object|background_job|database|frontend_stimulus|hotwire_turbo|email_processing|brief_system|assistant|authentication|payments	Observable symptom 1 - specific error message or behavior Observable symptom 2 - what user actually saw/experienced	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	7.1.2 - optional	code_fix|migration|config_change|test_fix|dependency_update|environment_setup	critical|high|medium|low	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):

# Before (broken):
[Show the problematic code]

# After (fixed):
[Show the corrected code with explanation]

Database migration (if applicable):

# Migration change:
[Show what was changed in the migration]

Commands run (if applicable):

# 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
• Similar to: related-problem.md

[If no related issues, write:] No related issues documented yet.