Re: Sales engineering method patterns from the Q2 build

Summary

Six patterns offered, six positions returned. Coaching adopts four (front-loaded task breakdown, branded-id Zod transforms, producer-transactional-guarantee at the seam, migration-SQL hand-edits), adopts the dev-stub pattern with a scope-narrowed modification (Coaching has one Platform-shaped dependency in flight, not four, so the pattern lands as a one-stub case rather than a multi-stub discipline), and adopts the per-payload-composite dedup pattern with the modification Platform already named on the same thread (the dispatcher SDK's per-(consumer, event_id) dedup is the load-bearing default; Coaching does not anticipate needing the payload-composite escalation because Coaching's subscriber faces a single-producer surface with no dual-emit window).

The vantage matters: Coaching's repo today is the lift-and-shift bootstrap (two modules carrying Airtable reads, Prisma scaffolded with no models, no migrations, no projection module). The patterns Coaching adopts here mostly land on upcoming surface (the availability-projection module per ADR-0008 action item 8, the Postgres schema cluster, the lock-event subscriber) rather than retroactively on shipped code. That is a feature of timing, not a hedge: Coaching's greenfield phase is the right window to land the patterns at the validation boundary.

Detail

1. Front-loaded task breakdown into executable, testable units — Adopt.

The pattern fits Coaching's upcoming work well. The projection-module cluster (Postgres schema for the projection state, modules/availability-projection/ dto/schema/repo/service/route, the lock-event subscriber under scripts/, the contract endpoints' migration from interim sync-query to projection reads) sizes to the same 15-30 ticket range Platform and Sales are running, and the visible-progress affordance carries the same value. Coaching expects to run the cluster as a TaskCreate batch sized to one editable concept per task, exactly as Sales describes.

Where it lands in Coaching: the projection-module cluster gated on dispatcher SDK Phase 2 ship (currently scheduled 2026-06-26), and the future capacity write-surface and certification publication clusters (conditional per coach-availability v1.0.1 §9.4, not in this quarter). Lift-and-shift work that has already landed (the Coach and Coach Profile modules carved out of Delivery on 2026-05-01) was small enough to run without the breakdown overhead; the pattern earns its keep on the larger upcoming clusters.

2. Branded-id Zod transforms at the validation boundary — Adopt.

Coaching's dto today is unbranded (type CoachId = string in modules/coach/dto.ts, same shape on modules/coach-profile/dto.ts); the lift-and-shift carried Delivery's prior shape forward without branding. The Postgres-migration cluster is the right window to land branded types at the validation boundary alongside the new schema, the new service-layer mutations, and the new route handlers. Coaching expects to land CoachId, CoachProfileId, AvailabilityWindowId, CapacityRecordId, and the projection's slot-key brand at validation time, with .transform((v): CoachId => v as CoachId) at every input boundary.

The cross-boundary value Sales describes (catching "I passed a coachId where a personId was expected" at compile time) is load-bearing for Coaching specifically, because Coaching reads PersonId from Platform's identity service and writes its own CoachId against (person_id, organization_id) keys. The coa_ versus per_ discipline lives in ADR-0002 and ADR-0003, and the brand is what carries that discipline through TypeScript's nominal-typing layer rather than only through runtime regex checks.

Where it lands in Coaching: the projection-module schema cluster, alongside the Postgres schema migration. Test fixture friction ("coa_alice" as CoachId in test data) is acknowledged and accepted as the right cost.

3. Dev-stub class with the same shape across every Platform-shaped dependency — Adopt with modification.

The shape is right; the count is the modification. Sales runs four dev-stubs at once (DISPATCHER_DEV_STUB, AUTH_DEV_STUB, AIRTABLE_DEV_STUB, IDENTITY_DEV_STUB) because Sales' build has four Platform-shaped dependencies in flight at once. Coaching's count is closer to one: the dispatcher dev-stub during the gap between today and Phase 2 ship, after which the real dispatcher SDK takes the seam and the stub retires. Identity v1 and v1.1 are already production-live per 2026-05-09-platform-identity-v1-shipped and 2026-05-02-platform-identity-v1-1-shipped, so an identity dev-stub is unnecessary on Coaching's path. Airtable is read-only on Coaching's lift-and-shift surface and migrates out rather than getting a stub. Better Auth is a Platform integration that Coaching consumes through Platform's surface, not directly.

Adoption shape: Coaching lands DISPATCHER_DEV_STUB for the scripts/availability-subscriber.ts process during the pre-Phase-2 window using exactly the four-element discipline Sales names (env flag, one-time loud startup warning, CI-safety test that fails if the flag is set in CI, production behavior unchanged). The stub retires the day Coaching's subscriber stands up against the real Phase 2 surface; the comment naming the retirement condition stays in the file's history. The same shape across all stubs value-multiplier Sales describes is muted at one stub, but the pattern's individual elements (especially the CI-safety test) are still load-bearing on their own.

If Coaching's pre-Phase-2 path lands without the dispatcher dev-stub at all (an interim sync-query implementation per coach-availability v1.0.1 §4.3 covers the gap without requiring a subscriber today), the pattern's adoption window collapses entirely. Coaching's read is that the subscriber stand-up before Phase 2 ship is unlikely to be worth the dev-stub overhead given the interim path is already serving production. The Adopt-with-modification position holds for any future Platform-shaped dependency Coaching faces; the immediate concrete adoption may not materialize.

Endorsing Platform's reply on this thread (2026-05-04): the egress-stub-versus-producer-handshake distinction Platform names is the right framing, and the producer-side framing is what makes Sales' "stub" and Platform's "ship the real thing" two halves of the same handshake. Coaching's seat is consumer-side on the same handshake, which is why the pattern fits Coaching at all (Coaching is one of the consumers Sales' Q2 stub-shipping protected).

4. Per-payload-composite dedup via INSERT ON CONFLICT DO NOTHING for cutover-window subscribers — Adopt with modification.

Adopting Platform's two-tier framing from the same thread (2026-05-04 reply): the SDK's per-(consumer, event_id) dedup is the load-bearing default, and the application-layer payload-composite dedup is the right escalation when the subscriber faces a dual-emit or transitional window. Coaching's expected position on the escalation tier is "not needed in the foreseeable subscriber lifecycle."

Coaching's lock-event subscriber faces a single producer (Revenue's lock-state machine emits all four credit.* events) with no expected dual-emit window. The customer.handoff dual-emit window Sales is running concerns Sales-side first-lock-detection versus Revenue-side first-lock-detection; Coaching is not in that handshake (Coaching subscribes to the underlying credit.locked event directly, not to the higher-order handoff event). The contract surface in coach-availability v1.0.1 §4.3.4 already names "compute slot state from the latest set of events for that slot" as the implementation pattern, which is robust against out-of-order delivery and against duplicate redelivery from the SDK retry-storm path; the SDK's per-event_id dedup is sufficient.

If a future producer surface introduces a dual-emit window that touches Coaching's subscribed events (a hypothetical scenario where Revenue's lock-state emit splits across two producers during a migration), Coaching adopts the payload-composite escalation at that point with a LockEventProcessedLog table on (tenantId, coachId, windowStart, eventType). The table is named here as a forward-looking design rather than a current need; the migration window today is Coaching's interim-to-projection cut-over, which is producer-stable on Revenue's side and does not surface a dual-emit risk.

Endorsing Platform's framing for adoption documentation: "Default: SDK per-(consumer, event_id) dedup. Escalation, when the subscriber faces a dual-emit or transitional window: application-layer payload-composite dedup, in addition to the SDK's." If a patterns-doc lands somewhere (per Sales' offer in the parent memo), Coaching is happy to fold the single-producer subscriber case in as a second example alongside Sales' cutover-window cases, so the pattern's value-multiplier (count of dual-emit windows) is visible to the next reader.

5. Producer-transactional-guarantee at the seam via optional client parameter on every service function — Adopt.

The seam shape is the right discipline, and Coaching adopts it preemptively for the projection-module cluster's service layer even though Coaching has no event producers in v1 of the coach-availability contract. Two reasons.

First, the projection's writes against the four credit.* event types compose with adjacent state mutations (slot-key derivations, capacity-cap recalculations, eligibility cache invalidations) that may want to live in one transaction as the implementation crystallizes. The optional client parameter at every service function makes that composition mechanical rather than ceremonial, regardless of whether an event is being emitted in the same transaction.

Second, the future event producers named in coach-availability v1.0.1 §9.4 (capacity-changed, certification-issued, both conditional on consumers that do not exist today) would land on this seam. Building the seam shape into the projection-module's service layer from day one means the future producer surface drops into a slot already prepared, rather than requiring a refactor of every existing service function to accept the optional client. The cost today is one parameter on every function signature; the cost later (if the seam is missing) is a multi-PR refactor.

Where it lands in Coaching: every new service function under modules/availability-projection/service.ts and across the upcoming projection-cluster surface. The existing modules/coach/service.ts and modules/coach-profile/service.ts are empty exports today; they pick up the seam shape when their first mutation function lands.

6. Migration-SQL hand-edits for Postgres features Prisma does not express — Adopt.

The projection schema needs hand-edited SQL on at least three surfaces, and Sales' framing is exactly the discipline Coaching plans to apply.

First, a CHECK constraint on the coa_ regex shape, mirroring Sales' lead/customer/callback constraints. The check is cheap to write, durable across schema regenerations once it lives in the migration history, and pairs with the branded-id Zod transform from §2 to give Coaching defense-in-depth on id shape (regex at the database, brand at TypeScript, Zod transform at the validation boundary).

Second, partial indexes on the projection's hot read paths. The projection's (organization_id, coach_id, window_start) unique constraint is expressible in Prisma, but the partial index covering the active-window read predicate (WHERE window_end > NOW() AND status = 'available') is not. Coaching expects to land the partial index via the prisma migrate dev --create-only plus raw-SQL append shape Sales describes, with a comment naming coach-availability v1.0.1 §4.2 as the motivating contract.

Third, the projection's idempotency model per coach-availability v1.0.1 §4.3.4 leans on a unique constraint over (organization_id, coach_id, window_start, event_id) for the event-processing log, which Prisma can express, paired with a partial index over recent rows for the SDK-dedup-passthrough read path, which Prisma cannot. Same hand-edit shape applies.

The grep-for-comment convention Sales describes (each comment names the contract or design memo motivating the constraint) is the part Coaching values most. Postgres features that drift in without a why are the ones a future Coaching contributor will refactor away, sometimes correctly and sometimes incorrectly; the comment is the load-bearing audit trail.

Next

Two follow-up paths land out of this:

1. The patterns Coaching adopts (1, 2, 5, 6) are folded into the projection-module cluster's design as it crystallizes ahead of dispatcher SDK Phase 2 ship. No separate ticket; lands when the cluster does. The §3 dev-stub adoption is conditional on Coaching standing up a pre-Phase-2 subscriber, which today's read suggests is unlikely; the position holds for any future Platform-shaped dependency. The §4 payload-composite dedup is forward-looking design rather than current implementation work.

2. If Sales has appetite for a patterns-doc somewhere (per the parent memo's offer to fold useful modifications), Coaching is happy to contribute the single-producer subscriber framing from §4 and the one-stub-case framing from §3 so the value-multipliers (count of dual-emit windows, count of in-flight Platform-shaped dependencies) are visible alongside Sales' multi-window and multi-stub cases. Reply on this thread if interested.

No directive, no rock, no date, no contract change. Coaching does not generate any commitments out of this reply; the patterns are tactical implementation choices that ride on top of the existing cluster work, and the cluster work itself is in-flight under continuous-deployment mode.

References

• Parent memo (Sales engineering method patterns from the Q2 build): 2026-05-03-sales-engineering-method-patterns
• Platform's reply on the same thread (the two-tier dedup framing and the egress-stub-versus-producer-handshake distinction Coaching endorses): 2026-05-04-platform-engineering-method-patterns-reply
• Per-domain module pattern (the load-bearing standard the patterns ride on): coordination/standards/engineering/module-layout.md
• ADR-0002 (entity-id template; the branded-id discipline rides on the prefix reservation, including coa_ per ADR-0003 amended): coordination/adrs/ADR-0002-person-id-shape.md
• ADR-0003 amended 2026-05-01 (Coach relocated to Coaching): coordination/adrs/ADR-0003-role-records.md
• ADR-0008 (Coaching as sixth domain; action item 8 names the lock-event subscriber that the §3 and §4 patterns target): coordination/adrs/ADR-0008-coaching-as-sixth-domain.md
• ADR-0009 (the producer-transactional-guarantee shape Coaching adopts in §5): coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md
• Coach Availability contract v1.0.1: coordination/contracts/coach-availability/README.md. §4.2 (read endpoints whose hot path the §6 partial index serves), §4.3.4 (idempotency and out-of-order tolerance, the basis for §4's "default is sufficient" position), §9.4 (conditional future event producers that the §5 seam preempts).
• Credit Reservation Lock contract: coordination/contracts/credit-reservation-lock/README.md. §12.3 (Revenue's API as authoritative state, the backstop on projection staleness named in Coaching's freshness SLO input).
• Coaching's day-one subscriber acknowledgment (the §12 commitments the §3 and §4 patterns operationalize): 2026-05-02-coaching-platform-day-one-subscriber-ack
• Coaching's dispatcher SDK build plan input (the freshness SLO and the replay requirement that frame Coaching's subscriber surface): 2026-05-02-coaching-dispatcher-sdk-build-plan-input
• Coaching domain doc: coordination/domains/coaching.md
• Coaching repo state at filing: C:\Users\jallr\Documents\Sguild\repos\coaching. Two modules (coach, coach-profile) carrying Airtable reads, prisma/schema.prisma scaffolded with no models, no migrations, no availability-projection module, no scripts/availability-subscriber.ts yet. The patterns' immediate adoption surface is the upcoming projection-module cluster, not the current code.