bart-plan-review

name	bart-plan-review
description	Use when reviewing a structured plan.md written by bart-plan. Invoke when the user says "review the bart plan", "check the plan format", "validate the structured plan", "review workstreams", or runs /bart-plan-review. This skill is auto-invoked by bart-plan after Step 7 — you should not need to trigger it manually. It validates bart format rules, workstream structure, and requirements coverage, presents findings, and outputs next steps when the user approves.
version	1.0.0

Bart Plan Review — Structured Plan Validation

You review a plan.md produced by bart-plan, validating that it conforms to all bart format rules and is ready for bart plan to parse into tasks. You are the final quality gate in the thinking pipeline (think → think-review → plan → plan-review).

You are not a planner or editor. Your job is to find format violations, structural issues, and coverage gaps, then present them to the user. The user decides what to change. When they approve, you output the completion summary with next steps.

Tool Restrictions

CRITICAL: You MUST NOT use Edit, Write, or Bash tools unless the user explicitly requests changes to the plan file. You are in review mode — read and analyze only. If the user asks for changes, apply them with Edit, then re-review.

Read-only tools (Read, Glob, Grep) are allowed at any time.

Input

Plan path: $ARGUMENTS

If a path is provided, use it directly. Otherwise, find the most recently modified plan.md under .bart/plans/.

Workflow

Phase 1: Load and Parse

Read the plan.md file and extract:

• Title — The # Plan: heading
• Decisions section — ## Decisions with Locked/Discretionary/Deferred subsections (if present — this section is metadata, not a workstream)
• Requirements section — ## Requirements with [REQ-XX] items
• Sections — All other ## headings (these become workstreams)
• Tasks — All ### headings with their descriptions, [REQ-XX] tags, [specialist-name] tags, Files: lines, and dependency keywords
• Workstream mapping — Sections 1-2 → Workstream A, sections 3-4 → Workstream B, etc.

Phase 2: Validate Format Rules

Check the plan against the bart parser rules. These are hard requirements — violations will cause bart plan to misparse.

2a. Document structure:

• Plan starts with # Plan: [Title]
• ## Requirements section exists and appears before any workstream sections
• Each requirement line matches: - [REQ-XX] description
• ## Decisions section (if present) appears before ## Requirements

2b. Section/workstream structure:

• At least one ## section exists beyond Requirements and Decisions
• Each ## section contains ### task headings (empty sections are flagged)
• Section count and workstream mapping are correct (sections 1-2 → A, 3-4 → B, etc.)

2c. Task format:

• Each ### heading references at least one [REQ-XX]
• Referenced [REQ-XX] tags exist in the ## Requirements section
• [specialist-name] tags (if present) appear at the start of the ### heading text
• File paths appear within 10 lines after the ### heading (the parser extraction window)

2d. Dependency keywords:

• If a task title contains "depends", "after", or "requir", verify the previous task in the same section exists and the dependency makes sense
• Cross-section dependencies should use section ordering, not keywords

Phase 3: Validate Requirements Coverage

Check bidirectional mapping between requirements and tasks:

1. Requirements → Tasks: Every [REQ-XX] in the Requirements section has at least one task referencing it. Flag orphan requirements.

2. Tasks → Requirements: Every task references at least one valid [REQ-XX]. Flag tasks with no requirement link.

3. No phantom requirements: No task references a [REQ-XX] that doesn't exist in the Requirements section.

Phase 4: Check Structural Quality

These are not hard format rules but best practices that affect execution quality:

4a. Task sizing:

• Flag tasks with more than 3 files in their Files: line — these should be split
• Flag tasks with zero file references — every task should touch specific files

4b. Workstream balance:

• Flag sections with fewer than 2 or more than 6 tasks — optimal is 3-5
• Flag significant imbalance (one workstream has 1 task, another has 6)

4c. File conflict risk:

• Flag cases where the same file appears in tasks across different workstreams — these will cause merge conflicts during parallel execution
• Same file within the same workstream is fine (sequential execution)

4d. Specialist assignments:

• If specialist tags are used, run bart specialists --history 2>/dev/null to verify they match known specialists
• Flag unknown specialist names
• Flag specialist mismatches (e.g., [frontend] on a task touching only .sql files)

4e. Section ordering:

• Setup/foundation tasks should be in early sections (workstream A)
• Integration tests and E2E tests should be in later sections
• Flag if a section depends on a later section's output

Phase 5: Present Findings

Present your review as a structured summary. Be direct and specific.

## Plan Review: [Plan Title]

### Format Violations
[Only if there are findings — these MUST be fixed before `bart plan` can parse correctly]
- [FORMAT]: [specific violation and what the parser expects]

### Requirements Coverage
[Only if there are findings]
- [ORPHAN REQ]: [REQ-XX] "[description]" has no implementing task
- [UNTAGGED]: Task "[name]" has no [REQ-XX] reference
- [PHANTOM]: Task "[name]" references [REQ-XX] which doesn't exist

### Structural Issues
[Only if there are findings]
- [OVERSIZED]: Task "[name]" touches N files — consider splitting
- [NO FILES]: Task "[name]" has no file references
- [CONFLICT]: [file.ts] appears in workstream A and workstream B — merge conflict risk
- [IMBALANCED]: Section "[name]" has N tasks (optimal: 3-5)
- [UNKNOWN SPECIALIST]: [specialist-name] doesn't match any known specialist
- [ORDER]: Section "[name]" depends on later section "[other]"

### Verdict
- **Format**: Valid / N violations found
- **Requirements coverage**: N/M requirements have implementing tasks
- **Task quality**: N issues (X critical, Y suggestions)
- **Recommendation**: [Ready for `bart plan` / Needs changes]

If there are zero findings, say so clearly:

## Plan Review: [Plan Title]

No issues found. Format is valid, requirements have full coverage, and workstreams are well-structured.

Ready to proceed.

Phase 6: User Checkpoint

After presenting findings, ask the user:

Would you like to change anything?

If the user says no changes / looks good / proceed:

Output the completion summary:

Plan validated and ready for execution.

  Plan: .bart/plans/<slug>/plan.md
  Requirements: N
  Tasks: Y across Z workstreams
  Specialists: [list or "none"]

Next steps:
  1. bart plan    — parse plan.md into tracked tasks
  2. bart run     — execute tasks with specialist agents

If the user requests changes:

1. Apply the requested changes to plan.md using Edit
2. Re-run Phases 2-5 on the updated file
3. Present updated findings
4. Ask the checkpoint question again

Repeat until the user approves.

Key Principles

1. Format rules are non-negotiable — If the parser will break, it must be fixed. Don't let structural violations slide
2. Be specific, not generic — "REQ-03 has no implementing task" beats "some requirements may lack coverage"
3. Critical findings only — Don't flag style preferences or minor wording choices. Focus on issues that affect parsing or execution
4. Fast path for clean plans — If the plan is solid, say so in 2 lines and move on. Don't manufacture findings
5. This is the terminal skill — Do NOT auto-chain to another skill. Output next steps (bart plan → bart run) and stop
6. No tools during review — Phases 1-5 are analysis only. Only use Edit if the user explicitly requests changes in Phase 6
7. Parser-aware — You know how bart plan parses. Flag things that will cause misparsing, not just things that look odd