interface:
  display_name: Compound docs
  short_description: Capture solved problems for team reuse.

# Critical Pattern Template

Use this template when adding a pattern to `docs/solutions/patterns/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

---
module: [Module name or "System" 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: [model|controller|view|service_object|background_job|database|frontend_component|api_endpoint|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]
framework_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 "System-wide"]
- Framework/Language Version: [e.g., Laravel 11.0, Python 3.12, Node 20.0]
- Affected Component: [e.g., "User model", "Payment service", "Auth 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):
```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, version incompatibility, etc.)?

[Be detailed enough that future developers understand the "why", not just the "what"]

## Prevention

[How to avoid this problem in future 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.

# Documentation Capture Process (Detailed)

<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:** `/ia-compound` 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 module or component 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:**

- Framework/language 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 [yaml-schema.md](./yaml-schema.md) and classify the problem against the enum values. 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, high, medium, low], got "invalid"
- 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 [yaml-schema.md](./yaml-schema.md).

</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 [yaml-schema.md](../references/yaml-schema.md).

**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 [resolution-template.md](../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 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, add a note suggesting it might be worth adding to Required Reading. But **NEVER auto-promote**. User decides via decision menu.

**Template for critical pattern addition:**

When user selects "Add to Required Reading", use the template from [critical-pattern-template.md](../assets/critical-pattern-template.md) to structure the pattern entry. Number it sequentially based on existing patterns in `docs/solutions/patterns/critical-patterns.md`.
</step>

</critical_sequence>

---

## Decision Menu Response Handling

After successful documentation, present the decision menu and handle responses:

**Option 1: Continue workflow** - Return to calling skill/workflow. Documentation is complete.

**Option 2: Add to Required Reading** - Extract pattern, format as WRONG vs CORRECT with code examples, add to `docs/solutions/patterns/critical-patterns.md`, add cross-reference back to this doc.

**Option 3: Link related issues** - Prompt for doc to link, search docs/solutions/, add cross-reference to both docs.

**Option 4: Add to existing skill** - Prompt for skill name, determine which reference file to update, add link and brief description.

**Option 5: Create new skill** - Extract into new learning skill.

**Option 6: View documentation** - Display the created doc, then present decision menu again.

**Option 7: Other** - Ask what they'd like to do.

# 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 `->with('emails')` on the Brief Eloquent 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: database_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 (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., react-frontend)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other
```

# Quality Guidelines & Error Handling

## 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)

**Ground behavioral claims in source, not session memory:**

- Before asserting how code behaves (enum values, status semantics, limits, defaults), Read the defining line at the current tree and cite `file:line`. A knowledge doc that captures wrong semantics from memory is worse than no doc -- it becomes an authoritative lie future sessions trust.
- Attribute unverifiable claims to their basis ("per this session's conclusion...") instead of stating them as established fact.
- Cite **PR numbers, not bare commit SHAs** -- squash and rebase merges rewrite SHAs, so a bare SHA won't resolve on another checkout. Phrase not-yet-merged fixes as pending.

**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

---

## 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

---

## 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 modules documentation:**
- Warn but don't block
- Proceed with documentation
- Suggest: "Add [Module] to modules documentation if not there"

# YAML Frontmatter Schema

**Schema specification for YAML frontmatter in solution documents.**

## Required Fields

- **module** (string): Module name (e.g., "EmailProcessing") or "System" 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 [model, controller, view, service_object, background_job, database, frontend_component, api_endpoint, 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

- **framework_version** (string): Framework or language 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. framework_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: model
symptoms:
  - "N+1 query when loading email threads"
  - "Brief generation taking >5 seconds"
root_cause: missing_include
framework_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/`

#!/usr/bin/env python3
"""Validate solution-document frontmatter using Python 3 and PyYAML."""

import re
import sys
from pathlib import Path

try:
    import yaml
except ImportError:
    sys.exit("FAIL: PyYAML is required; install with python3 -m pip install PyYAML")


class FrontmatterLoader(yaml.SafeLoader):
    pass


FrontmatterLoader.yaml_implicit_resolvers = {
    key: [(tag, pattern) for tag, pattern in values if tag != "tag:yaml.org,2002:timestamp"]
    for key, values in yaml.SafeLoader.yaml_implicit_resolvers.items()
}


def unique_mapping(loader, node):
    keys = set()
    for key_node, value_node in node.value:
        if key_node.tag == "tag:yaml.org,2002:merge":
            continue
        key = loader.construct_object(key_node)
        if not isinstance(key, str) or key in keys:
            raise ValueError("Frontmatter keys must be unique strings")
        keys.add(key)
    loader.flatten_mapping(node)
    return loader.construct_mapping(node)


FrontmatterLoader.add_constructor("tag:yaml.org,2002:map", unique_mapping)

ENUMS = {
    "problem_type": "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": "model controller view service_object background_job database frontend_component api_endpoint authentication payments development_workflow testing_framework documentation tooling",
    "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 missing_workflow_step inadequate_documentation missing_tooling incomplete_setup",
    "resolution_type": "code_fix migration config_change test_fix dependency_update environment_setup workflow_improvement documentation_update tooling_addition seed_data_update",
    "severity": "critical high medium low",
}


def main():
    try:
        if len(sys.argv) != 2:
            raise ValueError("Usage: validate-frontmatter.sh <file.md>")
        lines = Path(sys.argv[1]).read_text(encoding="utf-8").splitlines()
        if not lines or lines[0] != "---":
            raise ValueError("No YAML frontmatter found (expected opening ---)")
        try:
            end = lines.index("---", 1)
        except ValueError:
            raise ValueError("Missing closing --- delimiter") from None
        data = yaml.load("\n".join(lines[1:end]), Loader=FrontmatterLoader)
        if not isinstance(data, dict):
            raise ValueError("Frontmatter must be a YAML mapping")
    except (OSError, UnicodeError, ValueError, yaml.YAMLError) as error:
        print(f"FAIL: {error}")
        return 1

    errors = []
    warnings = []
    for field in ("module", "date", *ENUMS):
        value = data.get(field)
        if not isinstance(value, str) or not value.strip():
            errors.append(f"{field}: MISSING or not a non-empty string (required)")
        elif field in ENUMS and value not in ENUMS[field].split():
            errors.append(f"{field}: '{value}' not in allowed values [{ENUMS[field]}]")
    if isinstance(data.get("date"), str) and not re.fullmatch(r"[0-9]{4}-[0-9]{2}-[0-9]{2}", data["date"]):
        errors.append("date: does not match YYYY-MM-DD format")
    symptoms = data.get("symptoms")
    if not isinstance(symptoms, list) or not 1 <= len(symptoms) <= 5:
        errors.append("symptoms: required array with 1-5 items (empty array is invalid)")
    elif any(not isinstance(item, str) or not item.strip() for item in symptoms):
        errors.append("symptoms: each item must be a non-empty string")
    if "framework_version" in data and (not isinstance(data["framework_version"], str) or not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", data["framework_version"])):
        warnings.append("framework_version: does not match X.Y.Z format")
    print(f"Validating: {sys.argv[1]}")
    if warnings:
        print("WARNINGS:\n" + "\n".join(f"  - {warning}" for warning in warnings))
    if errors:
        print("ERRORS:\n" + "\n".join(f"  - {error}" for error in errors))
        return 1
    print("PASS: All fields valid")
    return 0


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env bash
set -euo pipefail
exec python3 "$(dirname "${BASH_SOURCE[0]}")/validate-frontmatter.py" "$@"