# Shipkit Review Planning

> Internal reviewer — assesses planning artifact alignment. Checks definitions agree, specs cover roadmap, no gaps. A per-unit reviewer invoked by a caller (the engine in steered mode or a direction/planning caller), not for direct use.

- Skill: `stefan-stepzero/shipkit-review-planning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stefan-stepzero/shipkit-review-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stefan-stepzero/shipkit-review-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: stefan-stepzero (https://skillmd.com/u/stefan-stepzero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stefan-stepzero/shipkit-review-planning

---


# shipkit-review-planning - Planning Assessment

**Purpose**: Read all planning artifacts and cross-reference them for alignment. Write a structured assessment for the planning orchestrator.

## Input

**Required artifacts** (the planning phase must produce all of these):
- `.shipkit/stack.json`
- `.shipkit/codebase-index.json`
- `.shipkit/spec-roadmap.json`
- `.shipkit/specs/*.json` — at least one spec per roadmap item
- `.shipkit/plans/*.json` — at least one plan per spec
- `.shipkit/test-cases/` — test specifications
- `.shipkit/user-tasks.json` — manual user tasks

**Direction context** (produced by prior loop, read for cross-reference):
- `.shipkit/why.json`
- `.shipkit/product-definition.json`, `.shipkit/engineering-definition.json`
- `.shipkit/architecture.json`
- `.shipkit/goals/strategic.json`, `.shipkit/goals/product.json`, `.shipkit/goals/engineering.json`

## Alignment Checks

1. **Completeness**: Are ALL required planning artifacts present? Missing artifacts are gaps.
2. **Product ↔ Engineering**: Every product feature has a corresponding mechanism?
3. **Definition ↔ Specs**: Every defined feature has a spec?
4. **Specs ↔ Roadmap**: Roadmap includes all specs with sensible priority?
5. **Plans ↔ Specs**: Every spec has a plan? Plans reference the correct spec?
6. **Stage alignment**: Specs and plans scoped for current stage?
7. **Goal coverage**: Specs, if implemented, satisfy product and engineering goals?
8. **Architecture consistency**: Do plans align with architecture.json decisions?
9. **Prerequisites by phase**: Group blocking user tasks by their `blocksPhase` value. Report separately:
   - Current-phase blockers (tasks where `blocksPhase` matches `why.json` current stage AND `blocking: true`)
   - Future-phase blockers (tasks where `blocksPhase` is a later stage)
   - General tasks (tasks where `blocksPhase` is `null`)

   **Only current-phase blockers count as blocking prerequisites.** Future-phase tasks are informational — do NOT count them in the blocker total. If a task has no `blocksPhase` field (legacy format), infer from context or treat as current-phase.

### Completion Tracking

Create tasks for each alignment check:
- `TaskCreate`: "Check 1: Completeness (all artifacts present)"
- `TaskCreate`: "Check 2: Product ↔ Engineering alignment"
- `TaskCreate`: "Check 3: Definition ↔ Specs"
- `TaskCreate`: "Check 4: Specs ↔ Roadmap"
- `TaskCreate`: "Check 5: Plans ↔ Specs"
- `TaskCreate`: "Check 6: Stage alignment"
- `TaskCreate`: "Check 7: Goal coverage"
- `TaskCreate`: "Check 8: Architecture consistency"
- `TaskCreate`: "Check 9: Prerequisites by phase"
- `TaskCreate`: "Write planning-assessment.json"

`TaskUpdate` each task to `in_progress` when starting it, `completed` when done.

Each check task requires evidence — do NOT mark complete without citing specific artifacts. Do NOT write the assessment until all 9 checks are completed.

## Output

Write `.shipkit/reviews/planning-assessment.json` with structured findings.

`status: "pass"` when all checks pass. `status: "gaps_found"` with specific `gaps[]` entries when issues exist. Each gap must include `artifact`, `issue`, `relatedArtifact`, `evidence`, and `fix` fields.

**For prerequisite reporting**, the assessment must include a `prerequisites` summary object:
```json
{
  "prerequisites": {
    "currentPhase": "phase-0",
    "blocking": [{ "id": "...", "title": "...", "blocksPhase": "phase-0" }],
    "futurePhase": [{ "id": "...", "title": "...", "blocksPhase": "phase-1" }],
    "general": [{ "id": "...", "title": "...", "blocksPhase": null }]
  }
}
```
The `blocking` array drives the blocker count. `futurePhase` and `general` are informational only.

<!-- SECTION:after-completion -->
## After Completion

Assessment written to `.shipkit/reviews/planning-assessment.json`.

**Next:** The caller (the orchestration engine in steered mode, or a direction/planning
caller) reads this assessment:
- If **gaps found**: re-dispatches the affected upstream skills for revision, then re-runs this reviewer.
- If **pass**: proceeds to the next step.

This skill is a per-unit reviewer, normally invoked by a caller (the engine in steered mode
or a direction/planning caller), not directly by the user.
<!-- /SECTION:after-completion -->