Pre-push grep audit for cross-cutting changes (auth-status code flips, response-envelope reshapes, DELETE-success status flips, /api/health body reshapes). The per-push gate's spec list is a strict subset of e2e-full's; cross-cutting changes that pass per-push can red e2e-full because the bare *.spec.js smoke tests aren't in the per-push gate list. Without this audit, every cross-cutting change pays a release-validation round-trip (~15 min) to discover its missed specs. With it, both layers go green on the first try. Today's v3.4.14 cycle hit this twice (#537 401-vs-403 missed 7 specs;
Closes a multi-piece GitHub issue (e.g. `[Bug] Patients page: missing pagination, no bulk/individual tag add, no CSV/XLSX export & template`) by enumerating its sub-items, shipping one slice per cron tick as a file-disjoint pair (backend + frontend; or two backends; or backend + PRD), and only closing the issue after the final slice. Use when an open issue's body lists ≥3 sub-features. Encodes the discipline established across the #820 arc (14 commits across 10 ticks #181 → #197): pagination → bulk-tags → tag-chip → CSV → XLSX backend → XLSX button → template backend → template button → backend filters → frontend filters → import backend → import button → tag-remove backend → tag-remove UI. Each tick shipped 1 small slice; the issue closed naturally once 7/8 items were green.
Authors a NEW `docs/PRD_<FEATURE>.md` for a multi-day or product-call-blocked feature. Use when an open issue (`[Gap]` / `[Zylu-Gap]` / `[Travel Gap]` / `[Bug]` with multi-piece scope) needs a design call before implementation can start, and writing the PRD makes the open questions explicit so the call can actually happen. Encodes the §1-§10 template + 4-7 DD + 5-7 OQ + MANUAL_CODING_BACKLOG D-cluster cross-ref shape that 12+ bonus PRDs followed across the 2026-05-24 → 2026-05-25 cron arc (Purchase Orders, Payment Gateway Config, IE Jobs, Integrations Hub, Tag Master, AI Chat History, Customer Segments, Staff Detail, Wallet Top-up, POS New Sale, POS Polymorphic Invoice, Mini Website). Saves ~15 min of structural decisions per PRD; ships a usable design-call surface.
Authors a new `backend/services/<vendor>Client.js` stub for a cred-blocked third-party integration. Use when a vendor API (RFU Zikr Cabs, Haramain Rail, Booking.com, AdsGPT, RateHawk, Callified, etc.) is on the roadmap but the credentials haven't landed yet — ship the API surface inert so downstream consumers (routes, frontend admin pages, cron engines) can be built end-to-end. Encodes the 8-instance recipe established across adsGptClient / ratehawkClient / callifiedClient / bookingExpediaClient / bookingCom / haramainRailClient / zikrCabsClient: INTEGRATION constant + BUDGET_CAP_KEY + DEFAULT_CAP_CENTS + checkBudgetCap with CJS self-mocking seam + provider-specific search/details/book methods + bookX() throws `XXX_NOT_YET_ENABLED` + 12+ vitest cases including one regression-pin for the seam. Future stubs clone this in ~30 min vs ~90 min from scratch.
Post-push verification + batch close-out for commits with multiple `Closes
Pattern for one-shot paramiko SSH scripts that clean demo's MySQL database of E2E test pollution (E2E_*, _teardown_*, IsoTest *), polluted seed entries, or schema-migration orphans. Use when a pen-test or QA report flags "ledger contains ~N duplicate rows" / "list shows N rows of test data" / "seed-X polluted with Y prefix" — these are operator-side cleanups, NOT code fixes. Encodes the dotenv + paramiko + tenant-scope-by-default + BEFORE/AFTER counts + idempotency + JSON-summary pattern that 3 successful scripts have used (cleanup-orphan-touchpoints.py, seed-drugs-on-demo.py, cleanup-demo-pollution.py). Pairs with applying-demo-ssh-config for non-DB ops.
Orchestrates a wave of parallel closer agents to ship multiple independent gate specs / unit tests / fixes in one round. Use when the user asks to "fire up parallel agents" or when there's a batch of disjoint pickups (R-1/R-4 small-route specs, R-5 cron-engine vitests, G-x engine specs) and waiting for them sequentially would be slow. Encodes the patterns that worked in v3.4.x — disjoint-files invariant (no two agents touching the same route or workflow YAML), max 4-5 concurrent agents (5 worked; 8 had merge collisions), when to spawn a discovery agent first vs jump straight to closers, the standing-rule preamble that points agents at the existing skills, and the rebase-on-collision recovery pattern.
Process for class-fix sweeps that touch many routes' response shape (e.g. flip every DELETE handler from "200 + {message}" to "204 No Content", or migrate every error response from {message:} to {error, code}). Pin shape with user FIRST, identify all touch sites with a fixed grep, sweep routes + their specs in lockstep in one PR, verify zero hits on the OLD shape post-sweep. Anti-pattern: shipping per-route — partial-state where some routes return 200 and others 204 is worse than either consistent shape. The canonical example is commit 8853546 (#550 sweep) that closed yesterday.