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

### 5.5 Expert Panel Review (mandatory)

Before generating the verdict, run the `expert-panel-review` skill to get a multi-perspective analysis:

1. Load the `expert-panel-review` skill
2. Execute with:
   - `ARTIFACT_TYPE`: `plan`
   - `ARTIFACT_PATH`: the plan document path (`docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan.md`)
3. Incorporate the panel's findings into the review:
   - Panel blockers (❌) → add to "Muss überarbeitet werden" section
   - Panel warnings (⚠️) → add to "Hinweise" section
   - Panel confidence level → include in Verdict section
4. If panel confidence < 70%: verdict MUST be 🔄 REVISE regardless of checklist results

The expert panel provides Domain Expert (🏛️), Architecture Expert (🔧), and Risk/Compliance Expert (🛡️) perspectives. This catches domain-level errors that the mechanical checklist alone cannot detect.

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

## Befunde

### ❌ 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. Empfehlung: GO erteilen.
— oder —
**🔄 REVISE** — <N> Punkte müssen überarbeitet werden. Zurück an Planner für v<N+1>.
**Panel-Confidence:** <X>% (<Domain: Y%, Architecture: Z%, Risk: W%>)
```

### 7. Store in BigMind

```python
memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Plan review completed — {verdict}. {findings_count} findings ({blockers} blocking)."
)
```

## Expected Output

- Plan review document at `docs/<MODULE>/<TICKET_KEY>/<TICKET_KEY>-plan-review.md`
- Clear verdict: APPROVED or REVISE
- 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 |

## Verdict Criteria

| Verdict | Criteria |
|---------|---------|
| ✅ APPROVED | All 20 checklist items pass (✅ or N/A). No blocking findings. |
| 🔄 REVISE | Any checklist item fails (❌). One or more blocking findings. |

## 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 → REVISE with specific findings
3. Planner revises → assessment v2, plan v2, testplan v2
4. Plan Reviewer reviews → 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