# Skill: plan-review

Plan and testplan quality review before implementation.

## Description

Reviews assessment documents, implementation plans, and test plans for completeness, correctness, and feasibility. Produces a structured review with APPROVED/REVISE verdict. Includes a **mandatory 3-expert panel review** for high-confidence validation before final verdict. This creates a quality gate between planning and implementation — ensuring plans are solid before code is written.

## Invoked by

📋✅ Plan Reviewer mode

## Required Inputs

| Input | Source | Example |
|-------|--------|---------|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |
| `MODULE` | PAISY module name | `eau`, `eubp`, `svmeldungen` |

## Output

Markdown file: `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`

## Steps

### 1. Read the planning documents

Read all available docs in `docs/<MODULE>/<TICKET_KEY>/`:
- Assessment (`*-assessment.md`) — required
- Implementation plan (`*-plan.md`) — required
- Test plan (`*-testplan.md`) — required

If any required document is missing, flag as REVISE immediately.

### 2. Read the Jira ticket

```python
retrieve_ticket_details(TICKET_KEY)
# Extract: summary, description, acceptance criteria (customfield_10510)
```

Cross-reference: do the plan documents address ALL requirements from the ticket?

### 3. Read affected source code

For each file/class mentioned in the plan:
- Verify the file exists at the stated path
- Verify the class/method names are correct
- Verify the patterns described match the actual code
- Check if the plan missed any related files that should also be changed

### 4. Run the plan review checklist

#### Assessment Review

| # | Check | What to verify |
|---|-------|---------------|
| 1 | Problem statement complete | Is the problem clearly described? Does it match the Jira ticket? |
| 2 | Affected components identified | Are all affected files/classes listed? Any missing? |
| 3 | Current state accurate | Does the Ist-Zustand description match the actual code? |
| 4 | Risk assessment realistic | Are risks properly categorized? Any missing risks? |
| 5 | Solution options evaluated | Were alternatives considered? Is the recommendation justified? |

#### Implementation Plan Review

| # | Check | What to verify |
|---|-------|---------------|
| 6 | All requirements covered | Every Jira requirement maps to at least one implementation step |
| 7 | Correct PAISY patterns | Plan references correct patterns (AbstractMeldung, Datenbaustein, ServiceCenter, EMFactory, JAXB) |
| 8 | File paths correct | All referenced file paths exist and are accurate |
| 9 | Implementation order logical | Steps are ordered correctly — dependencies before dependents |
| 10 | No gaps in steps | No missing steps between plan items (e.g., missing Flyway migration, missing test) |
| 11 | Flyway migrations planned | If DB changes needed: both H2 and Oracle variants mentioned? |
| 12 | Error handling planned | Plan addresses error cases, not just happy path |
| 13 | No scope creep | Plan doesn't include changes beyond what the ticket requires |

#### Test Plan Review

| # | Check | What to verify |
|---|-------|---------------|
| 14 | Coverage complete | Every implementation step has at least one test case |
| 15 | Test types appropriate | Unit tests for logic, integration for DB/ServiceCenter, SSH for batch |
| 16 | Edge cases covered | Null handling, empty dates, F; responses, boundary values |
| 17 | Test class naming correct | Follows `<OriginalClass>Test.java` convention |
| 18 | Test method naming correct | Follows `test<What>_<Scenario>_<Expected>()` pattern |
| 19 | Test data defined | Required test fixtures and data are specified |
| 20 | SSH tests identified | If batch/ServiceCenter changes: SSH test cases included? |

### 5. Verify cross-references

- Every class mentioned in the plan exists in the codebase
- Every test case in the testplan maps to a plan step
- Every plan step maps to a Jira requirement
- Assessment risks are addressed by plan mitigations

### 6. Expert Panel Review (MANDATORY)

**Before issuing the final verdict, invoke the `expert-panel-review` skill.**

This is mandatory for every plan review — no exceptions. The expert panel provides independent validation from 3 specialist perspectives:

| Expert | Lens | Why it matters |
|--------|------|---------------|
| 🏛️ Domain Expert | GKV/SV regulation correctness | Catches domain misunderstandings that pass checklist items |
| 🔧 Architecture Expert | PAISY patterns & technical design | Catches structural issues the checklist can't detect |
| 🛡️ Risk & Compliance Expert | Edge cases, backward compat | Catches what-could-go-wrong scenarios |

**Invoke with:**
```
ARTIFACT_TYPE = "plan"
ARTIFACT_PATH = docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md
```

The panel produces:
- 3 independent verdicts with confidence scores
- Consolidated findings (blocking / non-blocking / informational)
- Overall panel verdict (UNANIMOUS APPROVE / CONDITIONAL APPROVE / REVISE REQUIRED)

**Panel verdict integration:**

| Panel Verdict | Impact on Plan Review |
|--------------|----------------------|
| UNANIMOUS APPROVE | Supports APPROVED verdict (if checklist also passes) |
| CONDITIONAL APPROVE | Supports APPROVED with documented concerns |
| REVISE REQUIRED | Forces 🔄 REVISE regardless of checklist results |

### 7. Generate plan review document

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

```markdown
# Plan Review: <TICKET_KEY> — <Summary>

**Datum:** <today>
**Modul:** <MODULE>
**Reviewer:** Roo (Plan Reviewer)
**Dokumente:** assessment.md v<N>, plan.md v<N>, testplan.md v<N>
**Verdict:** ✅ APPROVED / 🔄 REVISE

---

## Zusammenfassung

<1-2 sentence summary of the review outcome>

## Geprüfte Dokumente

| Dokument | Version | Bewertung |
|----------|---------|-----------|
| Assessment | v<N> | ✅ / ⚠️ / ❌ |
| Plan | v<N> | ✅ / ⚠️ / ❌ |
| Testplan | v<N> | ✅ / ⚠️ / ❌ |

## Checkliste

### Assessment

| # | Prüfpunkt | Ergebnis | Anmerkung |
|---|-----------|----------|-----------|
| 1 | Problemstellung vollständig | ✅/❌ | |
| 2 | Betroffene Komponenten identifiziert | ✅/❌ | |
| 3 | Ist-Zustand korrekt | ✅/❌ | |
| 4 | Risikobewertung realistisch | ✅/❌ | |
| 5 | Lösungsoptionen bewertet | ✅/❌ | |

### Implementierungsplan

| # | Prüfpunkt | Ergebnis | Anmerkung |
|---|-----------|----------|-----------|
| 6 | Alle Anforderungen abgedeckt | ✅/❌ | |
| 7 | Korrekte PAISY-Patterns | ✅/❌ | |
| 8 | Dateipfade korrekt | ✅/❌ | |
| 9 | Implementierungsreihenfolge logisch | ✅/❌ | |
| 10 | Keine Lücken in Schritten | ✅/❌ | |
| 11 | Flyway-Migrationen geplant | ✅/N/A | |
| 12 | Fehlerbehandlung geplant | ✅/❌ | |
| 13 | Kein Scope Creep | ✅/❌ | |

### Testplan

| # | Prüfpunkt | Ergebnis | Anmerkung |
|---|-----------|----------|-----------|
| 14 | Abdeckung vollständig | ✅/❌ | |
| 15 | Testtypen angemessen | ✅/❌ | |
| 16 | Randfälle abgedeckt | ✅/❌ | |
| 17 | Testklassen-Benennung korrekt | ✅/❌ | |
| 18 | Testmethoden-Benennung korrekt | ✅/❌ | |
| 19 | Testdaten definiert | ✅/❌ | |
| 20 | SSH-Tests identifiziert | ✅/N/A | |

## 👥 Expert Panel Review

### Panel-Zusammensetzung

| Expert | Verdict | Konfidenz | Kernbefund |
|--------|---------|-----------|------------|
| 🏛️ Domänen-Experte | ✅/⚠️/❌ | <N>% | <one-line> |
| 🔧 Architektur-Experte | ✅/⚠️/❌ | <N>% | <one-line> |
| 🛡️ Risiko-Experte | ✅/⚠️/❌ | <N>% | <one-line> |

### Panel-Gesamturteil

**<UNANIMOUS APPROVE / CONDITIONAL APPROVE / REVISE REQUIRED>**
**Konfidenz-Durchschnitt:** <N>%

### Konsolidierte Panel-Befunde

#### Muss adressiert werden (blocking)
1. [Expert emoji] <finding>

#### Sollte adressiert werden (non-blocking)
1. [Expert emoji] <finding>

#### Zur Kenntnis (informational)
1. [Expert emoji] <observation>

### Dissenting Opinions
<If any expert disagrees — document explicitly>

## Befunde (Checklist)

### ❌ Muss überarbeitet werden (blocking)

1. **<document>** — <description of issue>
   - Empfehlung: <what needs to change>

### ⚠️ Hinweise (non-blocking)

1. **<document>** — <description of suggestion>
   - Empfehlung: <improvement suggestion>

## Traceability Matrix

| Jira-Anforderung | Plan-Schritt | Testfall | Status |
|-----------------|-------------|----------|--------|
| <requirement 1> | Step <N> | T-<NN> | ✅ Abgedeckt |
| <requirement 2> | Step <N> | T-<NN> | ❌ Fehlt |

## Verdict

**✅ APPROVED** — Plan ist vollständig, korrekt und umsetzungsbereit. Expert Panel: UNANIMOUS/CONDITIONAL APPROVE. Empfehlung: GO erteilen.
— oder —
**🔄 REVISE** — <N> Punkte müssen überarbeitet werden. Expert Panel: <verdict>. Zurück an Planner für v<N+1>.
```

### 8. Store in BigMind

```python
memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Plan review completed — {verdict}. Checklist: {findings_count} findings ({blockers} blocking). Panel: {panel_verdict} (Domain {d_conf}%, Arch {a_conf}%, Risk {r_conf}%)."
)
```

## Expected Output

- Plan review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`
- Clear verdict: APPROVED or REVISE
- Expert panel section with 3 independent verdicts
- Traceability matrix linking requirements → plan steps → test cases
- BigMind fact stored

## Error Handling

| Error | Resolution |
|-------|------------|
| Assessment missing | Flag as REVISE — assessment is required before plan review |
| Plan missing | Flag as REVISE — cannot review without a plan |
| Testplan missing | Flag as REVISE — testplan is required |
| Referenced file not found | Flag specific file path as incorrect in findings |
| Worktree not found | Use main repo to verify file paths |
| Expert panel low confidence (<70%) | Flag for human review — note in verdict section |

## Verdict Criteria

| Verdict | Criteria |
|---------|---------|
| ✅ APPROVED | All 20 checklist items pass (✅ or N/A) AND expert panel is UNANIMOUS or CONDITIONAL APPROVE. No blocking findings from either source. |
| 🔄 REVISE | Any checklist item fails (❌) OR expert panel says REVISE REQUIRED OR any blocking finding from any source. |

## Review Loop

The Plan Reviewer creates a feedback loop with the Planner:

1. Planner produces assessment v1, plan v1, testplan v1
2. Plan Reviewer reviews (checklist + expert panel) → REVISE with specific findings
3. Planner revises → assessment v2, plan v2, testplan v2
4. Plan Reviewer reviews (checklist + expert panel) → APPROVED
5. Patrick gives GO
6. Pipeline proceeds to Phase 3 (JiraOps)

This loop continues until APPROVED. Maximum 3 iterations recommended — if still not approved after v3, escalate to Patrick for manual review.

## Language

- Document content: **German**
- Code references (class names, methods, patterns): English as-is
- Checklist items: German
- Expert panel section: German