pi_mcps/zoo_backup/work/rules/skills/skill-generate-solution-doc.md

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

# 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

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

# 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

4.2

...

4.n Datenbank-Migrationen

Migration	Datenbank	Beschreibung
V{timestamp}__C_...	H2/Oracle

5. Testabdeckung

ID	Beschreibung	Typ	Ergebnis
T-01		Unit	✅
T-02		Integration	✅

Zusammenfassung: Tests, alle bestanden.

6. Offene Punkte

#	Beschreibung	Priorität	Ticket
1		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

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