pi_mcps/zoo_backup/work/skills/plan-review/SKILL.md

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

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:

# 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

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