pm-reconcile

When to use

When a product was built outside Pureinn, legacy docs disagree with the code and each other, and the team needs one trustworthy source of truth. Typically run at Rebuild playbook entry or when onboarding an existing product into the framework.

Agent mode is not supported. Business-logic conflicts require human decisions (which value is correct - the code or the doc?). Invoking with --agent will warn once and proceed interactively.

---

What it produces

1. Reconciliation Plan (reconcile/reconciliation_plan.md) - which areas to reconcile, in what order, into which Pureinn artifacts
2. Reconciliation Report (reconcile/reconciliation_report.md) - living audit log per area: what matched, what diverged (DIV-{DOMAIN}-NN entries), human decisions recorded
3. Rebuilt Live Registers - entities.md, business_rules.md, decision_models.md, feature_list.md - structurally aligned to code, carrying business logic from docs, every divergence visible
4. Stub Feature Cards - for specified-not-yet-implemented capabilities discovered in the source
5. Open Questions & Decisions Register (domain/open_questions.md, Register 5) - every DIV-/BLK- finding is logged here too, not only in the report, so it survives after the legacy source is archived

---

How to invoke - eight modes

/pm-reconcile                       # Plan / route: no plan → build plan; plan exists → status + next area
/pm-reconcile plan                  # Force rebuild the reconciliation plan
/pm-reconcile domain                # Execute: entities + state machines → entities.md (Register 1)
/pm-reconcile rules                 # Execute: business rules + decision models → business_rules.md + decision_models.md (Registers 2-3)
/pm-reconcile features              # Execute: feature inventory → feature_list.md + stub cards (Register 4)
/pm-reconcile open-questions        # Execute: routes to /pm-open-questions migrate - consolidate scattered OQ-/DIV-/BLK-/TBD items → open_questions.md (Register 5)
/pm-reconcile [other-area]          # Execute: any extra area the plan defined (events, integrations, etc.)
/pm-reconcile verify [area]         # Verify + incorporate: re-read source, prove coverage, fill gaps, rule on disposal readiness

Default area execution order: domain → rules → features (dependency-driven: entities are the vocabulary, rules reference entities, features reference rules and entities).

---

Source of truth model (asymmetric reconciliation)

Two hard rules:

1. Never change the codebase. This skill rebuilds documents only.
2. Docs-ahead-of-code (specified but not yet implemented) → stub Feature Card at 1_Backlog status. Do NOT include in Live Registers 1-3. Backlog items must be carded to survive source archival.

---

The source is whatever you point to

The skill never assumes the source is a "BRD" or any specific filename. At PLAN time, it asks where the source of business intent lives and deep-ingests whatever the user points to: FSD, Confluence/Notion space, wiki, spreadsheet, spec folder, any format.

---

Multi-session support

Reconciliation spans multiple sessions. Progress is held in state.json. Use /pm-reconcile-status to see a dashboard of completed/pending areas and open divergences before sitting down to a new session.

---

Rebuild vs. strategic layer

Reconcile captures structure (entities, rules, features), not the strategic layer (vision, North Star, business model, per-phase success criteria). If you want strategy-driven roadmap phases, backfill the strategic layer after reconcile completes before running /pm-product-roadmap. If a delivery-driven roadmap is acceptable, run roadmap directly and let it mark strategic fields TBD.

This is a fork the team should decide consciously. The skill surfaces it at handoff.

---

Dependencies

Required:

• A codebase accessible to Claude Code
• A source of business intent (legacy docs, any format) pointed to by the user
• Pureinn workspace initialized (/pureinn or /pureinn rebuild)

Produces for:

• pm-entity-registry - entities.md (Rebuild mode, Register 1)
• pm-business-rules-library - business_rules.md + decision_models.md (Rebuild mode, Registers 2-3)
• pm-reverse-extract - uses reconciliation_report.md as authoritative input
• pm-audit - runs after reconcile as the verification pass
• pm-domain-model - builds cross-domain ERD on top of reconciled entities

Related skills: pm-reconcile-status, pm-reverse-extract, pm-entity-registry, pm-business-rules-library, pm-domain-model, pm-audit, pm-open-questions