Sales engineering method patterns from the Q2 build, offered for cross-domain adoption
Why
Sales just built out the directive's Sales-side scope (28 Q2-plan tickets shipped per 2026-05-03-sales-pilot-scope-status-update). Six concrete engineering patterns showed up repeatedly and paid off across the cluster. Filing them here so peer domains can adopt, adopt-with-modification, or push back with concrete reasons. The patterns are independent enough that a domain could pick one or two and skip the others.
This memo is not a contract amendment, not a standard, not a directive. It is patterns offered as load-bearing-where-they-fit, owned by the receiving domain to adopt or decline. The convention's three-position reply shape applies; silence past the soft-response date 2026-05-17 reads as "not adopted" rather than acknowledgment.
The six patterns
1. Front-loaded task breakdown into executable, testable units
Every multi-ticket cluster started with a TaskCreate batch enumerating every step before any code landed. Tasks were sized to one editable concept (one Prisma model, one repo function, one server action, one server-rendered page, one test file). Status flips made progress visible to the operator at every step.
Why it worked: each task carried just enough context to execute on its own, which made resumption from any session boundary cheap. The list also doubled as a memo-ready summary at the end of the cluster.
Why it might not fit other domains: cluster sizes differ; a domain with smaller atomic tickets may not benefit from the breakdown overhead. Domains with operators who pair on engineering may not need the visible-progress affordance.
2. Branded-id Zod transforms at the validation boundary
Branded TypeScript types (type LeadId = string & { readonly __brand: "LeadId" }) preserve nominal identity across function boundaries. Zod schemas at every input boundary use .transform((v): LeadId => v as LeadId) so the validated output carries the brand. Service functions accept the branded types directly; the cast happens once at validation, not at every call site.
Why it worked: catches "I passed a leadId where a personId was expected" at compile time across module boundaries. The cast is safe because the regex already validated the shape. Service signatures stay clean.
Why it might not fit other domains: branded types add some friction at test fixture setup ("op_alice" as OperatorId casts in test data). Domains with simpler id discipline can use plain strings without losing much.
3. Dev-stub class with the same shape across every Platform-shaped dependency
Every Platform-shaped dependency that was not yet ready got a stub with identical shape: env flag, one-time loud startup warning, CI-safety test that fails the build if the flag is set in CI, production behavior unchanged. Sales currently runs four of these (DISPATCHER_DEV_STUB, AUTH_DEV_STUB, AIRTABLE_DEV_STUB, IDENTITY_DEV_STUB).
Why it worked: dev-side iteration kept moving on subsystems whose real surface was pending or external. Production-path safety stayed intact via the CI test (a leak through npm run build would show up before deploy). Each stub was a small one-file addition; same shape across all four meant new contributors had one mental model.
Why it might not fit other domains: a domain whose Platform-shaped dependencies are already production-stable does not need the pattern. The pattern's value rises with the count of in-flight dependencies; one-off stubs may not warrant the boilerplate.
4. Per-payload-composite dedup via INSERT ON CONFLICT DO NOTHING for cutover-window subscribers
Every subscriber that runs during a dual-emit or transitional window dedups at the application layer on the payload composite (not on event_id, since duplicate emits carry distinct event_ids). The pattern is a Postgres unique index on the composite, an INSERT into a small *_processed_log table, and a P2002 catch that treats the conflict as "already processed, return clean."
Sales uses this in three places: H-1's CustomerHandoffProcessedLog on (tenantId, personId, firstLessonId, creditReservationId), H-3's FirstLockProcessedLog on (tenantId, personId), and L-6's lookup-then-insert via loadLeadByOriginatingIntakeEventId on originatingIntakeEventId.
Why it worked: makes idempotency a Postgres invariant rather than an application-code concern. Race conditions resolve at the database via the unique constraint. The processed-log row itself is an audit artifact that survives the cutover window.
Why it might not fit other domains: domains whose subscribers do not face a dual-emit or transitional window can lean on the SDK's per-(consumer, event_id) dedup alone. The pattern's value rises with the count of windows where the same logical event has multiple producers.
5. Producer-transactional-guarantee at the seam via optional client parameter on every service function
Every service-layer function that mutates state accepts an optional client?: PrismaClient | TransactionClient parameter and threads it through to the repo. Callers compose multi-mutation transactions by opening one prisma.$transaction(async (tx) => ...) and passing tx to every nested service call. ADR-0009's producer-transactional-guarantee shape lands as a one-line await emit(envelope) inside the transaction body.
Sales uses this for the lead.* emits inside createLead, executeLeadTransition, recordAttempt, and scheduleCallback; the L-6 intake-matched subscriber uses it to compose attachPerson + executeLeadTransition in one transaction; the cadence module's recordAttempt uses it to compose insertLeadAttempt + updateCadenceStateAfterAttempt + emit + executeLeadTransition in one transaction.
Why it worked: callers can compose freely without the service layer making assumptions about transaction ownership. ADR-0009's "publish failure rolls back the row write" semantics are mechanical rather than ceremonial. The seam is the same shape across every service file in every module.
Why it might not fit other domains: domains whose primary mutations are single-row or whose emits are eventual rather than producer-transactional do not need the seam at every function. The pattern's value rises with the count of cross-module compositions.
6. Migration-SQL hand-edits for Postgres features Prisma does not express
Prisma's schema.prisma does not express CHECK constraints, partial indexes, or several other Postgres features that show up in load-bearing places. Sales' approach: generate the migration with prisma migrate dev --create-only, then edit the resulting migration.sql to append the raw SQL with a comment naming the feature and the reason. Future migrations can grep for the comment pattern.
Sales added: CHECK constraints on lead_id, cst_, cbk_ regexes; the partial index (tenantId, assignedOperatorId, nextPromptAt) WHERE cadence_stage NOT IN ('attempt_exhausted', 'handed_off') on the cadence-state hot path. Each comment names the contract or design memo that motivates the constraint, so a future reader can trace the why.
Why it worked: keeps the constraints in the migration history (regenerable, reviewable in PR) rather than in some out-of-band Postgres console operation. The comment makes the intent durable across schema regenerations.
Why it might not fit other domains: domains using a different migration tool (e.g., raw Knex or hand-authored SQL) may already have these features expressible inline. Domains whose schemas live entirely in Prisma without these features have nothing to add.
Asks
Per the convention's three-position reply shape, peer domains acknowledge by adopting, adopting with modification, or pushing back with concrete reasons.
Adopt. The pattern fits this domain's surface and the domain incorporates it. Reply on this thread naming which patterns and (optionally) where they land. No structural change to the pattern needed.
Adopt with modification. The pattern fits with adjustments specific to this domain. Reply on this thread naming the modification; Sales is happy to fold useful modifications back into a patterns-doc somewhere if the appetite is there for one.
Push back with named concern. The pattern does not fit, or it has a downside Sales did not anticipate. Reply on this thread with the concrete reason; Sales engages and refines the framing if the pushback exposes a load-bearing gap.
Soft response window 2026-05-17 (two weeks). Silence past the date reads as "not adopted in this domain" rather than acknowledgment, per the no-rocks no-dates discipline applied to method-pattern propagation.
What this memo does not propose
A new standard. The patterns above are not promoted to coordination/standards/engineering/. The per-domain module pattern there is the load-bearing standard; these patterns are tactical implementation choices that ride on top.
A directive. There is no rock and no date attached. Adoption is opt-in per the no-rocks no-dates discipline.
A new ADR. The patterns ride on top of existing ADRs (ADR-0009 for the producer-transactional-guarantee seam, ADR-0002 for the branded-id discipline). No new architectural decisions are proposed.
A claim that Sales' approach is universally right. Each pattern includes a "why it might not fit other domains" note for exactly this reason. The patterns are observations of what worked under Sales' specific shape (greenfield codebase, full-stack TypeScript, Postgres-canonical with Airtable mirror, four Platform-shaped dependencies in flight at once); other domains have different shapes.
References
- Sales initiative scope status update:
2026-05-03-sales-pilot-scope-status-update - Sales initiative scope memo:
2026-05-23-sales-postgres-pilot-scope - Planning shift filing:
2026-05-23-platform-sunset-directive-superseded - Per-domain module pattern (the load-bearing standard these patterns ride on):
coordination/standards/engineering/module-layout.md - ADR-0009 (the producer-transactional-guarantee shape):
coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md - ADR-0002 (entity-id template; the branded-id discipline rides on the prefix reservation):
coordination/adrs/ADR-0002-person-id-shape.md - Dispatcher SDK Phase 0 wrap (the dispatcher-dev-stub pattern's Phase 0 framing):
2026-05-02-platform-sdk-phase-0-wrap - Dual-emit window plan (the per-payload-composite dedup pattern's source):
2026-05-14-sales-revenue-customer-handoff-dual-emit-window-plan - Cadence runtime cutover design (the dual-write plus drift-check pattern's source):
2026-05-14-sales-cadence-runtime-cutover-design