This document stores reusable prompt patterns discovered through postmortems and experiments.
Agents should consult this file before generating outputs.
When creating a product specification use this structure:
Problem User Opportunity Success Metric Constraints MVP Scope
When designing backend architecture always include:
system components data flow API structure database schema scaling considerations
When generating implementation code:
follow coding-standards.md avoid unnecessary abstraction write readable functions add comments explaining logic
When reviewing code check:
logic correctness performance security maintainability
Append system learnings here.
Format:
date issue root cause system improvement
issue: Three systemic failures — unbounded pagination, missing telemetry, and synchronous batch cron root cause: Architecture plans lacked explicit constraints on data fetching, fan-out patterns for cron jobs, and upfront telemetry requirements system improvement:
- All data sync loops must declare page limit and date bound before any other logic
- All cron jobs that process N users must use a fan-out trigger pattern — master cron dispatches, never processes
- Telemetry events must be defined in the plan and implemented during feature build, not added post-QA
- Error handling for third-party APIs must classify errors before acting on them — transient vs permanent
- Database schema existence must be verified in deploy-check before any build validation begins
- Data pipelines must implement dead-letter tracking or failure limits per item to prevent poison-pill infinite loops
- Automated fallback/error notifications to users must include strict frequency caps to prevent spam during outages
issue: Serverless API terminations, Thundering Herd cron patterns, and fragile conversational UX. root cause: Execution failed to account for Vercel's immediate suspension of unawaited background tasks, cron loops defaulted to sequential DB queries instead of concurrent bulk handling, and the conversational webhook failed to handle media payloads or 'zero' amounts. system improvement:
- Serverless API routes must explicitly
awaitexternal async calls (like WhatsApp dispatches) before completing the HTTP response. - Cron jobs must implement Batch fetching (
INstatements) and concurrent mapping (Promise.allSettled) to avoid N+1 query structures. - Webhooks dealing with unstructured messages must explicitly implement logic blocks for unexpected media types (images/audio) and boundary text values (zero/negatives).
- Peer Review Agent must proactively generate an "Adversarial Edge Case List" detailing non-standard inputs for all user-facing systems.
issue: Brittle AI parsing, unbounded list queries, optimistic UI without backend persistence, and data loss on AI timeouts. root cause: Naive trust in AI response formatting, MVP shortcutting on database limits and state persistence, and absent fallback design for synchronous external calls. system improvement:
- Always strip/sanitize markdown codeblocks from AI responses before running
JSON.parse(). - Enforce
.limit()clauses on every database list query. - Never ship an optimistic UI change without an implemented and tested backend persistence (
PUT/PATCH/DELETE) endpoint. - Provide a "Fallback State" (save raw input with default labels) to guarantee zero data loss if downstream AI processing fails or times out.
- Ensure Telemetry SDKs are implemented alongside feature development, not added after QA testing.
issue: Architecture under-specification propagated 5 systemic issues downstream — rate limiting, sessionId ordering, Gemini timeout, clipboard fallback, and error-path telemetry all caught at review or later. root cause: backend-architect-agent lacked a mandatory checklist for serverless + paid-API constraints. peer-review-agent Prompt Autopsy produced directional suggestions instead of exact file/section/text changes. execute-plan command only required success-path telemetry implicitly. system improvement:
- All architecture specs with unauthenticated paid-API endpoints must include a rate limiting strategy before outputting (blocking requirement).
- All architecture specs using a sessionId across analytics + API + DB must specify: generate sessionId before all downstream operations.
- All architecture specs with external AI calls on Vercel must specify: AbortController ≤ 9s, return JSON 504 on timeout.
- All clipboard copy interactions must implement: navigator.clipboard primary → document.execCommand fallback → visible inline error if both fail.
- execute-plan must wire PostHog events on ALL API route branches (success, timeout, parse failure, rate limit) — not just success paths.
- Peer Review Prompt Autopsy must produce exact file + section + text additions, not directional suggestions.
issue: 7 systemic issues — unprotected worker, double event emission, URL ID fidelity, simulation idempotency, PostHog worker resilience, recurring README gap, recurring error-path telemetry gap. root cause: Architecture under-specification continued from prior cycles (auth, URL lookup, simulation idempotency). Two recurring failures (README, error-path telemetry) persisted despite prior cycle fixes because upstream instructions lacked sufficient specificity. system improvement:
- All API routes that write to experiment tables must specify auth mechanism by name in the architecture spec. "Internal" is not an auth mechanism.
- Each PostHog event has exactly one canonical emission point — server OR client, never both. North Star events fired server-side must not be re-fired client-side.
- URL entity ID parameters must be used as the primary DB lookup key. Architecture spec must define exact query (table + WHERE clause) for every entity ID URL.
- Simulation tools that fire write-once PostHog events must be idempotent across page refreshes — require both localStorage keying and DB ON CONFLICT DO NOTHING.
- PostHog calls in workers must use Promise.allSettled with per-call .catch(). Telemetry failure must never cause worker HTTP 500.
- README.md and .env.local.example are execute-plan deliverables, not deploy-check fixes. Env vars added in fix cycles must update .env.local.example in the same commit.
- Error-path telemetry (per-user failure event, cron_run_completed, experiment lifecycle events) is a blocking execute-plan requirement — not a production-only enhancement.
issue: 4 systemic issues — PostHog in hot path corrupting experiment data, A/B salt and cohort label exposure, frontend defensive programming gaps, North Star metric unmeasurable due to missing UI flow. root cause: Backend lacked telemetry isolation rules for serverless latency-sensitive routes. Security defaults allowed NEXTPUBLIC for shared config without checking sensitivity. Frontend prioritized completion over defensive programming. Product spec defined aspirational metrics without grounding them in the implementation scope. system improvement:
- PostHog captureServerEvent in user-facing API routes must be fire-and-forget (no await, .catch(() => {})). Admin/cron routes may await. This prevents external telemetry latency from corrupting experiment measurements via false client-side timeouts.
- A/B experiment salts must be server-only env vars (never NEXTPUBLIC). Control group API responses must return a neutral label ("default"), never the real cohort string. The true cohort is captured server-side in PostHog only.
- All JSON.parse calls on localStorage/sessionStorage must be wrapped in try/catch. All fetch calls triggered by user input (search, filter) must use AbortController to prevent race conditions.
- Every success metric in a product spec must have a "Metric → Flow Mapping" table confirming the required user action, UI component, and API endpoint exist within the committed MVP scope. Unmeasurable metrics must be descoped or the MVP expanded before /create-plan exits.
issue: 7 systemic issues — dashboard rehydration path absent, partial write as success, fan-out worker HTTP contract undefined, advisory fetch missing auth header, PostHog env var mismatch, file size violations at deploy-check, pdf-parse wrong API property. root cause: 6/7 issues trace to execute-plan output gaps. Architecture under-specification (rehydration path, write atomicity, fan-out HTTP contract), incomplete cross-verification at implementation time (auth header caller mismatch, env var names), no file-size budget during generation, and training-knowledge-only library usage. system improvement:
- Every dashboard/results/report page linked from email or external URL must specify the authenticated read path for first-load rehydration — the post-mutation result path is insufficient.
- Every parent + child write sequence must declare an explicit atomicity strategy. Partial success (parent processed, children missing) is never a terminal state.
- Fan-out worker HTTP contracts must specify: worker returns non-2xx on failure; master uses HTTP status only — never JSON body inspection — for success/failure accounting.
- After adding auth to any route, all callers must be updated in the same change. A route auth fix without caller update is an incomplete fix. Code review must cross-verify all fetch() calls to authenticated routes for missing Authorization headers.
- .env.local.example must be generated by grepping actual process.env.* calls in src/ — never from memory. Key name mismatches between example file and source code are deploy blockers.
- File size limits (route < 200 lines, page < 250 lines) must be applied during code generation. Files projected to exceed 250 lines must be split at extraction points before writing.
- After integrating any third-party npm package for the first time, verify the installed version's exported API against the generated call pattern before marking the integration complete.
issue: 2 new systemic gaps surfaced — mid-phase schema extension (3 ALTER TABLE columns added post-deploy for multi-account labels), and server-side-only validation (silent sanitization masks invalid enum inputs from client). root cause: Phase 1 postmortem rules were written to knowledge files but not converted to hard checklist items in the relevant agent prompts. Result: 2 Phase 1 lessons recurred in Phase 2. Rule-writing without prompt-wiring is incomplete. system improvement:
- Any feature adding user-facing input fields must enumerate all required DB columns in the architecture schema before execute-plan. Nullable column additions are schema migrations; they must appear in schema.sql before the first deploy of the feature.
- Enum input fields require bidirectional validation: client-side picker/select (not free text) + server 4xx on invalid value + schema CHECK constraint. Silent server-side sanitization to null is never acceptable — it gives users false confidence their input was saved.
- Meta-rule: every postmortem lesson appended to a knowledge file must have a corresponding hard constraint added to the relevant agent prompt file in the same session. A lesson with no agent prompt change has not been acted on.
issue: Deploy-check initially blocked on empty optional Sentry env vars despite PM intent; financial correctness and scope-semantics bugs caught late in code review. root cause: Default deploy-check treats Sentry as blocking without checking project-state or deploy artifacts for documented PM exceptions. Planning did not encode financial aggregate invariants or scope-aware copy defaults. system improvement:
- Before failing the deploy gate on monitoring keys (e.g.
NEXT_PUBLIC_SENTRY_DSN,SENTRY_ORG,SENTRY_PROJECT), readproject-state.mdDecisions Log and the deploy-check artifact for a documented PM exception. If the exception lists optional keys, do not block on those empty values. - For finance dashboards, architecture must require full-scope SQL aggregates for headline numbers and advisory inputs; plans must tie user-facing money/time phrases to scope shape (single month vs multi-month).
- Frontend: URL-canonical scope must rehydrate modal/editor local state on change; scope-driven fetches need AbortController to prevent stale UI.
issue: Late-cycle semantic correctness fixes required three review passes (ownership checks on optional IDs, aggregate drill-through fidelity, non-2xx completion handling) and metric naming drift risked telemetry ambiguity. root cause: Execute-plan and review prompts lacked an explicit pre-review acceptance sweep for semantic correctness, and metric-plan outputs were not forced to reconcile canonical event IDs against implementation names. system improvement:
- Add an "Acceptance Sweep" prompt at the end of execute-plan:
- "For each new endpoint/component, verify ownership enforcement, aggregate-to-detail fidelity, and non-2xx unhappy-path behavior with at least one targeted test."
- Add a review prompt check:
- "If a UI drill-through starts from an aggregate row, verify downstream filters preserve the full aggregate scope; first-item fallback is a high-severity defect."
- Add a metric-plan completion prompt:
- "Output a Canonical Event Dictionary: metric -> canonical event name -> single emission source -> primary properties; reject intent labels that do not match implemented event IDs."