Skip to main content

RTM Reconciliation Playbook

Source: First pilot landed 2026-05-24 covering BF-001 Tenant + Property Onboarding. Spec at ../../superpowers/specs/2026-05-24-rtm-reconciliation-pilot-design.md; plan at ../../superpowers/plans/2026-05-24-rtm-reconciliation-pilot.md.

This playbook is the template for the next 12 business-flow reconciliations (BF-002 through BF-013). It captures what worked, what to change, and the mandatory operating rules that survived the pilot intact.

When to author a new RTM reconciliation​

  • A business flow has shipped to production but no RTM exists for it.
  • A user audit (like the 2026-04-28 Property #1 readiness audit) raises questions the existing artifacts can't answer — typically "is this story actually built?" or "what test covers this gap?".
  • Quarterly drift sweep. Recommended cadence: per quarter, one BF per sprint.
  • A regulatory deadline (e.g. DPDPA, e-invoice schema bump) makes the story-vs-code delta material to compliance posture.

Sequence (10 steps mapping to pilot Tasks 1-11)​

The pilot proved this sequence works end-to-end. Reuse:

  1. Pick the business flow. Should map to 1+ flow-test specs in hmp-infrastructure/testing/flow-tests/src/flows/ AND span 2+ EPICs (single-EPIC flows don't justify the BF doc overhead).
  2. Source exploration (pilot Task 1) — read the EPIC docs, the catalog row, every existing review file, the implementation code paths, every test file (Jest + flow + Playwright + real-backend smokes), and every use-case YAML that mentions the flow's nouns. Output: scratch notes file under _scratch/source-map.md. ~½ day.
    • DO NOT skip this even if the format feels internalized — see the "Reconsidered" callout under What to change below.
  3. Per-EPIC RTM scaffolding (pilot Tasks 2-3) — mechanical: one section per story, code paths + test files + pass rate. NO SME notes / drift / refinements yet (those land in Step 6). ~½ day per EPIC.
    • When a code path you expected to find isn't there, tag it [CITED-BUT-NOT-FOUND] (see What worked below) so Step 6 reconciles it.
  4. Top-level dashboard update (pilot Task 4) — add the newly-covered EPIC row(s) to RTM-DASHBOARD.md. ~30 min.
  5. Business-flow doc (pilot Task 5) — narrate the user journey step-by-step under ../business-flows/BF-NNN-<slug>.md. Step shape: story → code → test → pre/post conditions → notes. This is the deliverable that surfaces cross-EPIC drift no single story owns. ~½ day.
  6. SME deep-dive (pilot Task 6) — for each story, re-read story body → re-read code → re-read tests → apply the drift criteria (reproduced below) → draft [SME-PROPOSED] refinements. Assign each drift finding a D-NNN id per EPIC (e.g. EP-002 D-001). Severity = P0/P1/P2 per the criteria table. ~1 day.
    • Immediately after the SME pass, re-tally the SUMMARY table at the top of each per-EPIC RTM by greping for the actual counts. The pilot shipped Task 6 with stale summary counts and had to land a follow-up commit c6db866 to fix the drift; see What worked below.
  7. Use-case sidecars (pilot Task 7) — for each in-scope _data/use-cases/uc-*.yaml needing change, ship uc-<name>-SME-PROPOSED.yaml under use-case-proposals/. For each P0 gap with no UC, propose a NEW one. Annotate each sidecar with the drift ID it closes. ~½ day.
  8. Catalog sidecar (pilot Task 8) — corrected story status using the 5-state vocabulary (Built / Built-Untested / Partial / Stub / Not Started). Land as 01-epic-catalog-<EP-NNN>-SME-PROPOSED.md OR append a new EPIC section to the existing sidecar. Includes proposed-new-story table for D-findings that need a US row. ~½ day.
  9. Enhance per-story reviews (pilot Task 9) — in-place add three sections (Tests / Drift / SME refinements) to each existing review file. Create missing review files where the SME pass discovered gaps. ~½ day.
  10. Index + close (pilot Tasks 10-11) — author/update the folder README, fill the TBD cells in RTM-DASHBOARD with actual counts, delete the _scratch/ notes, wire the new docs into the Docusaurus sidebar, run npm run build until green. ~½ day.

Total: ~4 days per business flow. 12 remaining flows = ~10 weeks at single-author cadence, ~3 weeks at fan-out (4 SMEs in parallel per the "What to change" section below).

What worked in the pilot​

  • Cross-EPIC business-flow doc revealed gaps no single EPIC owned. BF-001 surfaced D-001 through D-005 (signup with no story, email-verification with no story, GST configuration code-without-story, booking-engine-branding code-without-story, onboarding-wizard with no backend state API). None would have been caught reading EP-001 or EP-002 in isolation. Keep this as the load-bearing deliverable.
  • 5-state status vocabulary distinguished Built from Built-Untested. Multiple stories (e.g. US-002-010) were silently in the latter bucket and the live catalog couldn't surface it. The pilot's catalog sidecar reclassified US-002-010 → Built-Untested and US-002-011 → Stub (re-uses generic room-status, no dedicated block entity), which the previous 3-state vocabulary masked as Built.
  • Sidecar pattern for proposed changes (use-case-proposals/ folder + 01-epic-catalog-SME-PROPOSED.md) preserved the live artifacts and avoided the "trust me, SME has decided" tone. Operator can diff + merge selectively, per row. This was the right call — the alternative (in-place edits with diff for review) would have lost the traceability of what changed and why and made revert harder.
  • Drift D-NNN ID numbering per EPIC kept findings traceable across artifacts. EP-001 has D-001 through D-011; EP-002 has D-001 through D-014; BF-001 has D-001 through D-005. Cross-references between the business flow and the per-EPIC RTM use these IDs as anchors.
  • [CITED-BUT-NOT-FOUND] marker for uncertain code paths worked well. 16 occurrences across EP-001-rtm.md (8) + EP-002-rtm.md (8). The Step 3 scaffolder cited paths from memory / from review-file claims; the Step 6 SME pass either found the real path or confirmed the path doesn't exist, promoting the marker to a D-NNN drift finding. Keep this marker — it surfaces path uncertainty cheaply at scaffold time instead of forcing exhaustive grep upfront.
  • Source-map scratch file (_scratch/source-map.md) was VALUABLE, not optional. The pilot landed it at 710 lines: per-story code paths, per-test inventories, pass-rate snapshots, use-case YAMLs, and pre-loaded drift candidates surfaced during reading. Task 6 (SME deep-dive) used the pre-loaded drift candidates HEAVILY — the scaffolder noticed several drift conditions while reading code that would have been missed if Task 6 started cold. Reconsidered guidance below: do not skip this even on flows 2-13.

What to change for the next 12 flows​

  • Parallelize via subagents. Pilot was single-author to validate the format. For BF-002 onward, fan-out per EPIC is safe — each per-EPIC RTM is independent. Recommended: 1 sub-agent per EPIC for Steps 3 + 6 (scaffolding
    • SME pass). The business-flow doc (Step 5) must stay single-author to keep voice consistent.
  • Reconsidered: DO NOT skip the scratch notes file. Earlier draft of this playbook said "skip if format internalized". After living through Task 6, the pre-loaded drift candidates in _scratch/source-map.md were used heavily and would have been missed if the SME pass started cold. The scratch file is the pre-SME drift radar; deleting it just means doing the reading twice. Keep the scratch file. Delete it only at Step 10.
  • Inline-grep the SUMMARY table after Step 6. The pilot shipped Task 6 with the SUMMARY block at the top of each per-EPIC RTM still carrying stale counts (TBD placeholders + outdated drift counts from before the SME pass found more findings). Operator caught it on review; follow-up commit c6db866 fixed it. Make this an explicit Step 6 sub-step: after the SME pass, run grep -c "\[SME-PROPOSED\]" EP-NNN-rtm.md, grep -c "^### D-" EP-NNN-rtm.md, and grep -c "\*\*Verified status\*\*: <Status>" EP-NNN-rtm.md for each of the 5 status values, and update the SUMMARY block before committing.
  • Add a [SME-PROPOSED] count threshold per EPIC. Pilot spec target was ≥10 across both EPICs (1 BF, 2 EPICs); pilot delivered 50 (20 in EP-001 + 30 in EP-002). Realistic floor for future flows: ≥5 per EPIC if the EPIC is mature (catalog Partial/Built mix), ≥10 per EPIC if the EPIC is Not Started-heavy or has known compliance debt.
  • Lift D-NNN ids to a global namespace if cross-EPIC drift becomes common. BF-001 already had D-003 (GST) and D-004 (branding) spanning property-service code + dashboard UI + (D-004 specifically) a missing EP-011 ownership. A global BF-NNN-D-XXX scheme might scale better than per-EPIC EP-NNN D-XXX once we have 13 BFs in flight.
  • Build automation in Phase 4. A script that grep-walks every story across all 22 EPICs and auto-populates the mechanical RTM layer (Step 3) would cut that step from ~½ day to ~5 minutes. After that, only the SME layer (Step 6) needs human work. Recommended input sources: per-repo CLAUDE.md Gotchas tables (the codebase ground-truth), 01-epic-catalog.md (the requirements ground-truth), and flow-tests/*.spec.ts test names.
  • Use the sidecar pattern aggressively. The pilot used sidecars for catalog corrections AND use-case proposals AND new-story proposals. Both worked. Do not edit the live _data/use-cases/uc-*.yaml or 01-epic-catalog.md in-place even when the proposed change is obviously correct — the operator's accept/reject review step is what keeps the catalog honest. Honour it.

Drift criteria reference​

(reproduced from the pilot spec §5 — these are the criteria that turn an observation into a recorded D-NNN finding)

Drift typeSeverityExample
Code does X, story says YP1Code accepts 6 doc types; story says 3
Tests assert behavior story doesn't describeP0Test asserts Aadhaar 12-digit validation; story has no acceptance criterion for ID format
Catalog says "Built", tests fail / code is stubP0US-001-012 SSO-OIDC marked "Partial", actual code is a TODO comment
Story has no testable acceptance criteriaP1"MFA Setup" — pass criteria undefined
Orphaned code (no story references)P2bookingEngineTheme field has no US
Orphaned test (no story references)P2tenant-boundary-fuzz.flow.spec.ts exercises behaviors not in any catalog story
Cross-service handoff no test exercisesP1"TENANT_CREATED event propagation from auth to property" — only published, never asserted-arrived

Pilot results applying these criteria: 25 drift findings total (11 EP-001 + 14 EP-002), of which 7 P0s. The most common drift type was "orphaned code" (P2) at scaffolding time, which the SME pass frequently escalated to P1/P0 once the regulatory or compliance surface was considered (e.g. GST configuration with no story owner is P0 in Indian hospitality, not P2, because mis-configured GST = e-invoice rejection = revenue loss).

SME hat — operating rules​

(reproduced from the pilot spec §6 — these rules are NON-NEGOTIABLE)

  • I propose; you decide. No requirements doc, use-case YAML, or flow definition changes unilaterally. Every proposal lands as [SME-PROPOSED] alongside the original, in a sidecar where possible.
  • For each story, the loop is:
    • Read the story body in ../epics/EP-NNN-*.md
    • Read the implementation review in ../reviews/EP-NNN/US-NNN-NNN-review.md
    • Read the code (paths cited in the RTM section)
    • Read every test that exercises it
    • Apply drift criteria above
    • For each finding: assign D-NNN, severity, action recommendation
    • For each vague / missing / ambiguous criterion: draft [SME-PROPOSED] refinement with reasoning note
  • For each use case (_data/use-cases/uc-*.yaml):
    • Check whether the UC references a story; if not, propose linking
    • Check whether the given/when/then matches what the tests exercise
    • Propose new UCs where business-critical flows have no UC YAML
  • For each business flow:
    • Validate the flow definition matches the actual user journey in production
    • Propose adjustments where the flow definition skips steps or includes unrealistic ones
    • Surface missing flows (e.g. "Day-2 onboarding follow-up" — first-time-login experience, surfaced in BF-001's Day-2 onboarding callout)
  • Indian-hospitality regulatory context is always in scope. Apply domain knowledge: GST (CGST/SGST/IGST split, HSN/SAC codes, inclusive vs exclusive), e-invoice (IRN, NIC schema versions), CERT-In 6-hour breach window, DPDPA consent + 90-day PII deletion, C-Form / FRRO for foreign guests, Aadhaar 12-digit + masking, PCI DSS network isolation, TRAI DND for marketing SMS. If the spec says "user provides ID" and the code accepts Aadhaar without masking, that is a P0 finding regardless of how the story is worded.

Ranked by Property #1 launch-blocker priority + flow-test pass-rate gap as of the 2026-05-16 demo-readiness snapshot. The first 5 are the launch-critical sequence; 6-13 are post-launch hardening.

OrderFlowSpans EPICsWhy this position
1BF-001 (DONE)EP-001 (partial), EP-002Pilot. Smallest scope, validates format. Shipped 2026-05-24.
2BF-003 Check-in (Indian + International + C-Form)EP-005A, EP-004, EP-006Property #1 launch-blocker (flow-6 was 6/13 PASS at 2026-05-16). C-Form + Aadhaar handling are India-specific compliance surfaces — high SME value.
3BF-005 Check-out + e-invoiceEP-005A, EP-005B, EP-012CProperty #1 launch-blocker (flow-8 was 0/15 PASS — worst on the platform). E-invoice IRN generation + folio close are revenue-critical.
4BF-004 POS Order → FolioEP-007, EP-005BProperty #1 launch-blocker (flow-7 was 0/10 PASS). POS-1 tenant-plan gating + KOT → folio charge propagation are common production failures.
5BF-006 Night AuditEP-005CFrequent prod failure path; the EOD batch that posts room charges and advances business date. Blocks the whole hotel's next day if it fails.
6BF-002 Guest Booking (search → confirmation)EP-003, EP-011, EP-004Public-facing; revenue-critical. Booking engine + reservation + guest profile path.
7BF-007 OTA Channel SyncEP-009, EP-003High-complexity, frequent incidents. ARI push + rate parity + booking pull from MakeMyTrip / Booking.com / Agoda.
8BF-008 Payment Capture + RefundEP-015, EP-005B (or new payment-service EPIC)Compliance-critical (PCI). Razorpay terminal + payment-link + 2026-05-19 reconciliation pipeline.
9BF-009 Housekeeping LifecycleEP-006Lower complexity but operationally daily. Task assignment + room-status propagation.
10BF-010 Banquet EventEP-008Lower volume but high per-event value. Venue blocking + KOT + folio integration.
11BF-011 Spa BookingEP-016Similar to banquet in scale. Therapist scheduling + service catalog.
12BF-012 Reporting & Compliance ExportEP-012B, EP-012CRegulatory deadlines (GST return filing, e-invoice batch).
13BF-013 DSAR / GDPR / DPDPA ErasureEP-004, EP-014, EP-015DPDPA mandate; lower frequency but high consequence-of-failure.

Sub-EPIC scope rule: when a flow spans a sub-EPIC (EP-005A, EP-012C, etc.), reconcile just that sub-EPIC in the pilot — do not balloon scope to the whole parent EPIC. The pilot proved tight scope = high signal.

Pilot stats (BF-001, 2026-05-24)​

These are the numbers the pilot shipped. Use them as a calibration baseline when planning the next reconciliation.

MetricPilot resultSpec targetReuse as baseline?
[SME-PROPOSED] refinements50 (20 EP-001 + 30 EP-002)≥10Floor: ≥5 per EPIC mature, ≥10 per EPIC Not Started-heavy
Drift findings25 (11 EP-001 + 14 EP-002)not specifiedFloor: ≥3 per EPIC if catalog ≥80% Built
P0 findings7not specifiedShould track
Use-case sidecars7 (2 enhancing existing + 5 NEW proposals)not specifiedFloor: 1 per drift finding tagged "story has no acceptance criteria"
Catalog status corrections6 (3 demoted EP-001, 1 promoted EP-001, 2 demoted EP-002)not specifiedTrack
Proposed new stories5 (US-001-017, US-001-018, US-002-015, US-002-016, US-002-017)not specifiedTrack
[CITED-BUT-NOT-FOUND] markers16 (8 per RTM file)not specifiedExpected; track for trend
Days elapsed~1 day actual (pilot ran compressed)4 day estimateFuture runs at 4 days at fan-out

See also​