# Skill: generate-solution-doc

Solution documentation from implementation results.

## Invoked by

📝 DocGen mode

## Required Inputs

| Input | Source | Example |
|-------|--------|---------|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
| `MODULE` | PAISY module name | `eau` |
| `PLAN_PATH` | Path to plan.md | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-plan.md` |
| `TESTPLAN_PATH` | Path to testplan.md | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-testplan.md` |
| `REVIEW_PATH` | Path to review.md (optional) | `docs/EAU/ESIDEPAISY-12081/ESIDEPAISY-12081-review.md` |

## Output

- Markdown: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`
- PDF: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf`

## Steps

### 1. Read input documents

Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`:
- Plan document (required)
- Test plan (required)
- Assessment (if exists)
- Review findings (if exists)

### 2. Analyze actual changes

```bash
# If in worktree
cd /Users/pplate/git/paisy-<TICKET_KEY>
git diff origin/current --stat
git diff origin/current --name-only

# Or use git log for committed changes
git log origin/current..HEAD --oneline
```

Read the changed files to understand what was actually implemented vs. what was planned.

### 3. Gather test results

```bash
# Check if tests were run
# Look for surefire reports or test output
find . -name "TEST-*.xml" -path "*/surefire-reports/*" | head -20
```

Or reference the testplan status if already updated.

### 4. Generate solution document

Write `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md`:

```markdown
# Lösungsdokumentation: <TICKET_KEY>

**Datum:** <today>
**Modul:** <MODULE>
**Autor:** Patrick Plate / Roo (DocGen)
**Jira:** <TICKET_KEY>
**Branch:** current/<type>/<module>/<TICKET_KEY>-<desc>

---

## 1. Problemstellung

<From assessment/plan: What was the problem? Why did it need solving?>

## 2. Lösungsansatz

<High-level approach chosen. Reference the plan document.>

## 3. Architektur-Entscheidungen

| Entscheidung | Begründung | Alternativen |
|-------------|-----------|--------------|
| <decision> | <why> | <what was considered> |

<Include Mermaid diagrams where helpful:>

```mermaid
graph TD
    A[Component] --> B[Component]
```

## 4. Implementierte Änderungen

### 4.1 <Component/File group>

| Datei | Änderung | Beschreibung |
|-------|---------|-------------|
| `<path>` | Neu/Geändert | <what changed> |

<Explain key code changes. Reference patterns used.>

### 4.2 <Next component group>
...

### 4.n Datenbank-Migrationen

| Migration | Datenbank | Beschreibung |
|-----------|----------|-------------|
| `V{timestamp}__C_...` | H2/Oracle | <what it does> |

## 5. Testabdeckung

| ID | Beschreibung | Typ | Ergebnis |
|----|-------------|-----|----------|
| T-01 | <desc> | Unit | ✅ |
| T-02 | <desc> | Integration | ✅ |

**Zusammenfassung:** <N> Tests, alle bestanden.

## 6. Offene Punkte

| # | Beschreibung | Priorität | Ticket |
|---|-------------|-----------|--------|
| 1 | <open item> | Hoch/Mittel/Niedrig | <linked ticket or "—"> |

<If no open items: "Keine offenen Punkte.">
```

### 5. Ask for PDF color scheme

Before generating the PDF, ask Patrick:

> "Welches Farbschema für das PDF? Verfügbar: adp (rot), royal_purple, ocean, forest, sunset, slate, rose"

Default to `adp` if Patrick says "standard" or doesn't have a preference.

### 6. Generate PDF

```python
generate_pdf(
    content=<markdown content>,
    title=f"Lösungsdokumentation {TICKET_KEY}",
    author="Patrick Plate",
    classification="ADP Internal",
    output_path=f"docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.pdf",
    color_scheme=<chosen scheme>
)
```

### 7. Store in BigMind

```python
memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Solution doc at docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-solution.md, PDF generated"
)
memory_append_chunk(
    session_id=SESSION_ID,
    content=f"Solution doc for {TICKET_KEY}: <summary of changes and decisions>",
    flag_reason="solution documentation"
)
```

## Language

- Document content: **German**
- Section headers: German (Problemstellung, Lösungsansatz, etc.)
- Code references, class names, patterns: English as-is
- Mermaid diagram labels: German or English depending on audience

## Template Variants

### Minimal (for small bugfixes)

Skip sections 3 (Architektur-Entscheidungen) and 6 (Offene Punkte) if not applicable. Keep sections 1, 2, 4, 5.

### Extended (for large features)

Add additional sections:
- **Konfigurationsänderungen** — environment variables, properties
- **Deployment-Hinweise** — special deployment steps needed
- **Rückwärtskompatibilität** — backward compatibility considerations
- **Performance-Auswirkungen** — performance impact analysis

## PDF Conventions

- Always use `generate_pdf` MCP tool (never write PDF bytes directly)
- Color scheme must be confirmed by Patrick before generation
- Author field: "Patrick Plate" (not "Roo")
- Classification: "ADP Internal" unless told otherwise