Reconcile Roadmap

Reconcile Roadmap (pre-execution, cross-plan)

Brush across all the finished task plans of a roadmap at once and stress-test that they cohere as a system — that the seams the roadmap's depends-on edges promised are actually honored by the missions on both sides — before /start-roadmap executes anything. This skill produces pushbacks, not suggestions; it never gold-plates plans that already fit together.

Silence is the expected outcome. A set of plans whose seams line up, whose coverage is complete, and whose terms agree gets a one-line "No discrepancies — the plans cohere." Do not manufacture concerns to look thorough.

ALWAYS check .ab-method/structure/index.yaml FIRST for where roadmaps, tasks, and the domain model live — paths are user-configurable, never hardcode them.

Look for it under the project root (the current working directory) first — a project's own copy is how it customises its paths, so it always wins. Only if the project has none (AB Method installed as a plugin rather than with npx ab-method), read the bundled default: ../../../.ab-method/structure/index.yaml relative to this SKILL.md. Either way, every path the index names is relative to the project root, never to the folder the bundled file lives in.

Where this sits (and what it is NOT)

Three critics guard a roadmap at three different moments. Keep them distinct:

critique-plan          → ONE plan vs the domain model          (pre-plan / per-task)
reconcile-roadmap      → ALL plans vs EACH OTHER               (pre-execution, whole roadmap)  ← this skill
review-implementation  → one task's diff vs quality critics    (post-implementation)

critique-plan at roadmap time only saw the coarse DAG (one-line task scopes), and each task's own critique-plan only saw that one task's missions. Neither ever reads the whole set of finished progress-tracker.md files together, so discrepancies that only exist between plans slip through to execution. That is exactly the gap this skill closes: it is the pre-execution counterpart of an integration test, run at the plan level.

It is read-only and advisory — it surfaces discrepancies and points at the fix; it never edits a plan, reshapes a task, or blocks a run. It is standalone: invoke it manually (/reconcile-roadmap <name>), typically once planning is done and before /start-roadmap.

Process

1. Identify the roadmap

• If the user passed a roadmap name or a path to its roadmap.md, use it.
• Otherwise list folders under docs/roadmaps/ and ask which to reconcile.

2. Load the material

Read (skip missing files silently — don't flag them or offer to create them):

• roadmap.md — the Objective (the destination), the task list, every depends-on edge (the DAG), and — when present — ## Open decisions, ## Not yet specified (fog), and ## Out of scope.
• Every planned task's tracker — for each task marked plan: ✅, read docs/tasks/<slug>/progress-tracker.md. Confirm the file actually exists with missions; don't trust the flag alone (same discipline as /start-roadmap).
• Every planned task's unresolved-questions.md, where one exists — the black boxes those plans intend to ship. Usually absent; when present, it's exactly the kind of assumption that only misbehaves across plans.
• The domain model that exists — UBIQUITOUS_LANGUAGE.md, CONTEXT.md (or CONTEXT-MAP.md
  • per-context src/<context>/CONTEXT.md), docs/adr/, docs/architecture/*. Used to judge terminology and seam ownership, not re-critiqued per plan.

3. Handle partial planning

Reconcile only the planned subset. A roadmap may be partially planned — that's fine.

• Any task still plan: ⬜ (or whose progress-tracker.md is missing) is reported as "couldn't check."
• Any seam that touches an unplanned task is flagged unverifiable, not assumed fine — you can't confirm a handoff whose other end doesn't exist yet.

(This mirrors /start-roadmap's tolerance for running a planned prefix.)

4. Spin up ONE read-only reconciler subagent

Spawn a single subagent — reconciler — with the roadmap, all the planned trackers, and the domain-model files from Step 2, and the rule that it is read-only: it returns discrepancies as text and edits nothing. Isolating it keeps the cross-plan analysis out of the main context. (For a very large roadmap you may fan out one reconciler per seam, but the default is one reconciler holding the whole set — the discrepancies live in the relationships between plans, so a single reader sees them best.)

Its brief — fire ONLY on a genuine cross-plan discrepancy, one of:

1. Broken seam / contract mismatch — Task B depends-on A, and B's missions consume a type / endpoint / table / interface that A's missions never produce, or produce under a different name or shape. The edge promised a handoff the plans don't honor.
2. Coverage gap — a piece of the roadmap Objective, or a seam implied by an edge, that no task's missions actually implement. Work that falls between tasks.
3. Overlap / duplication — two tasks plan the same artifact (same file, table, function, endpoint) — a double-build or a merge collision waiting to happen at execution.
4. Ordering / edge defect — a mission in an upstream task actually needs an artifact only produced downstream (an edge is reversed, or a needed edge is missing). This is grounded in the actual missions, which the roadmap-time critique-plan never saw.
5. Cross-task terminology drift — the same concept named differently across two tasks' missions (e.g. cancelOrder in one, voidOrder in another), which will fragment the codebase. critique-plan sees one task at a time and structurally cannot catch this.
6. Conflicting assumptions — two tasks assume incompatible things about a shared entity or contract (soft- vs hard-delete of the same record, sync vs async on the same boundary, differing auth or ownership model).
7. The map contradicts the plans — the roadmap's own sections have gone stale against the finished trackers. Never fire on fog merely existing (an uncharted area is honest). Fire when: a ## Not yet specified patch is already covered by a planned task's missions (it graduated and nobody cleared it); an ## Out of scope item is implemented by a task's missions (the scope boundary was crossed without redrawing the destination); an ## Open decisions entry blocks a task that is nonetheless plan: ✅ (planned around an unsettled decision — say which missions would change if it resolves the other way); or a ## Decisions line points at an ADR/term that doesn't exist.
8. Black boxes that leak across tasks — a parked question (⚠️ UQ-n) is a deliberate placeholder within its own task, so never fire on one existing. Fire when it stops being local: a downstream task's missions build real logic on the answer an upstream task left open; two tasks park the same question with different placeholders (the codebase gets two conflicting defaults); or a task's If the answer differs blast radius names work that a different task owns, so answering it later reopens a plan nobody flagged. Do not propose the answer — say which plans collide and that resolving UQ-n before execution is cheaper than after.