pi_mcps/zoo_backup/work/rules/skills/skill-plan-review.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. 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

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:

# 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

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