# Resolution Template

Use this template when creating solution documentation in `.claude/solutions/`.

## Filename Convention

```
{sanitized-symptom}-{module}-{YYYYMMDD}.md
```

- Lowercase, hyphen-separated
- Special characters removed
- Truncated under 80 characters
- Example: `association-not-loaded-accounts-20251201.md`

## Full Template

````markdown
---
module: "{Module or context name}"
date: "{YYYY-MM-DD}"
problem_type: {enum from schema}
component: {enum from schema}
symptoms:
  - "{Observable symptom 1}"
  - "{Observable symptom 2}"
root_cause: {enum from schema}
severity: {critical|high|medium|low}
tags: [{tag1}, {tag2}, {tag3}]
---

# {Descriptive Title}

## Symptoms

What was observed. Include:
- Error messages (exact text)
- Unexpected behavior description
- Where it manifested (which LiveView, which context, which test)

## Investigation

What was tried and what happened:

1. **Hypothesis 1**: {what you thought} — {result}
2. **Hypothesis 2**: {what you thought} — {result}
3. **Root cause found**: {the actual cause}

## Root Cause

Detailed explanation of WHY this happened. Connect to the
underlying Elixir/Phoenix concept.

```elixir
# The problematic code
problematic_code()
```

## Solution

The fix that resolved it.

```elixir
# The working code
fixed_code()
```

### Files Changed

- `lib/my_app/accounts.ex:42` — Added preload
- `test/my_app/accounts_test.exs:15` — Added test for preload

## Prevention

How to prevent this from recurring:

- [ ] Add to Iron Laws? (if foundational pattern)
- [ ] Add to agent checks? (if detectable by reviewer)
- [ ] Add to test patterns? (if testable)
- Specific guidance: "{actionable advice}"

## Related

- `.claude/solutions/{related-file}.md` — Similar issue in different context
- Iron Law #{n}: {description} (if applicable)
````

## Category Directories

Create the file in the appropriate subdirectory:

| problem_type | Directory |
|-------------|-----------|
| `build_error` | `build-issues/` |
| `test_failure` | `testing-issues/` |
| `runtime_error` | `phoenix-issues/` |
| `performance_issue` | `performance-issues/` |
| `database_issue` | `ecto-issues/` |
| `security_issue` | `security-issues/` |
| `liveview_bug` | `liveview-issues/` |
| `oban_issue` | `oban-issues/` |
| `otp_issue` | `otp-issues/` |
| `integration_issue` | `phoenix-issues/` |
| `logic_error` | `phoenix-issues/` |
| `deployment_issue` | `deployment-issues/` |
| `iron_law_violation` | mapped by Iron Law domain |

## Quality Checklist

Before saving, verify:

- [ ] YAML frontmatter validates against schema
- [ ] All enum values are exact matches
- [ ] Symptoms are specific (include error text)
- [ ] Root cause explains WHY, not just WHAT
- [ ] Solution includes code examples
- [ ] Prevention has actionable next steps
- [ ] File is in correct category directory

# Compound Documentation Schema

YAML frontmatter schema for solution documentation files.

## Required Fields

### module

- **Type**: string
- **Description**: Elixir module or context area
- **Examples**: `"Accounts"`, `"LiveView.UserList"`, `"Workers.EmailSender"`

### date

- **Type**: string
- **Pattern**: `YYYY-MM-DD`

### problem_type

- **Type**: string
- **Description**: Category of the problem. Use a concise label.
- **Suggested values**: `build_error`, `test_failure`, `runtime_error`,
  `performance_issue`, `database_issue`, `security_issue`,
  `liveview_bug`, `oban_issue`, `otp_issue`, `integration_issue`,
  `logic_error`, `deployment_issue`, `iron_law_violation`
- Free-form — use the closest match or create a new label if needed.

### component

- **Type**: string
- **Description**: Which component area was affected.
- **Suggested values**: `ecto_schema`, `ecto_query`, `ecto_migration`,
  `phoenix_context`, `phoenix_controller`, `phoenix_router`,
  `liveview_mount`, `liveview_events`, `liveview_components`,
  `liveview_streams`, `oban_worker`, `oban_config`, `genserver`,
  `supervisor`, `pubsub`, `authentication`, `authorization`,
  `testing`, `deployment`, `configuration`
- Free-form — use the closest match or create a new label if needed.

### symptoms

- **Type**: array of strings (1-5 items)
- **Description**: Observable symptoms — error messages, visual issues,
  unexpected behavior. Must be specific and observable.
- **Examples**:
  - `"** (Ecto.Association.NotLoaded) association :posts not loaded"`
  - `"LiveView process terminated with :timeout"`

### root_cause

- **Type**: string
- **Description**: The actual underlying reason WHY this happened.
  Be specific and descriptive. Use the cause, not the symptom.
- **Examples**: `"missing preload on :posts association"`,
  `"blocking database query in disconnected LiveView mount"`,
  `"atom keys in Oban job args instead of string keys"`

### severity

- **Type**: enum
- **Values**: `critical`, `high`, `medium`, `low`

### tags

- **Type**: array of strings (up to 8)
- **Description**: Searchable keywords, lowercase, hyphen-separated
- **Examples**: `["preload", "association", "n-plus-one"]`

## Optional Fields

### elixir_version / phoenix_version

- **Type**: string, pattern `X.Y.Z`

### iron_law_number

- **Type**: integer (1-26)
- **Description**: Which Iron Law was violated (if applicable)

### related_solutions

- **Type**: array of strings (file paths to related solutions)

## Validation Rules

1. `module` must be a valid Elixir module or context name
2. `date` must be in `YYYY-MM-DD` format
3. `symptoms` must be specific and observable (not vague)
4. `root_cause` must explain WHY, not just WHAT
5. `severity` must be one of the four enum values
6. `tags` should be lowercase, hyphen-separated