Original Source Post-Mortems
Relevant source files
The following files were used as context for generating this wiki page:
Original Source Post-Mortems represent the foundational layer of the amir-bug-patterns repository. These documents contain raw evidence from specific software projects—such as Noa Leads, EmailFlow, and various side projects—capturing technical failures, race conditions, and architectural oversights encountered in production environments. The purpose of these post-mortems is to transform individual errors into repeatable detection patterns, ensuring that similar "classes" of bugs are caught mechanically in new projects.
The post-mortem methodology relies on documentation structured by frequency, severity, and technology stack. By analyzing these original sources, common denominators were identified, leading to the creation of CORE-PATTERNS, CRITICAL-PATTERNS, and TESTING-PATTERNS. This structured approach allows developers to apply lessons learned from past projects to new implementations, specifically through tools like CLAUDE.md triggers and automated code review rules.
Sources: README.md:9-25, MIGRATION-NOTES.md:5-10
The Post-Mortem Documentation Lifecycle
The project utilizes a specific loop to ensure knowledge from source projects is integrated and maintained. When a bug is caught or a recurring mistake is identified, it follows a structured path from documentation to automation.
Documentation and Classification Flow
The diagram illustrates how a new discovery in a source project moves through classification tiers before becoming an automated rule.
Sources: README.md:121-145
Key Source Projects and Derived Patterns
Specific projects served as the primary data sources for this repository. Each contributed unique insights into failure modes associated with their respective technology stacks.
| Source Project | Primary Tech Stack | Notable Pattern Contributions |
|---|---|---|
| Noa Leads | FastAPI, Next.js, Supabase, SQLAlchemy | State-machine integrity, Cron loops, React sync issues |
| EmailFlow | Pub/Sub, SQLAlchemy, Async ORM | AsyncSession lifecycle, Audit log intent, Tiebreaker pagination |
| Shipment-bot | Celery, Telegram ID, SQL | Race conditions, BIGINT ID overflow, singleton engine failures |
| Markdown-Docs | MCP, HTML/JS, CSP | Browser policy blocks, spec vs. client drift, testing failures |
Sources: README.md:186-200, INTEGRATION.md:95-125, MIGRATION-NOTES.md:15-30
Analysis of Common Failure Modes
1. The Terminal State Problem (Cron Jobs)
A recurring theme in the Noa Leads post-mortem is the "infinite loop" in scheduled tasks. This occurs when a filter query selects rows for processing but the subsequent action fails to move the row out of the filter's scope.
As shown, failing to provide a terminal state leads to redundant compute usage and API quota exhaustion.
Sources: BY-STACK/cron-jobs.md:16-45, MIGRATION-NOTES.md:27-35
2. Async Race Conditions and TOCTOU
Across all source projects (specifically EmailFlow and Shipment-bot), race conditions during asynchronous operations were identified as the most frequent bug class. The "Reserve-then-fill" pattern emerged as the mandatory fix, requiring a local database write before an irreversible external action.
Recommended Implementation Logic:
-- Atomic Check-and-Set (CAS) to prevent double-processing
UPDATE messages
SET status = 'processing'
WHERE id = :id AND status = 'pending'
RETURNING id;
Developers must check the rowcount in the application worker; if zero, another process has already claimed the task.
Sources: BY-STACK/cron-jobs.md:106-115, MIGRATION-NOTES.md:46-56, RECURRING-PATTERNS.md:58-75
3. State-Machine and Linked-Field Atomicity
In CRM-style projects like Noa Leads, updating a status without updating secondary linked fields (e.g., last_outbound_at) leads to silent data corruption. The post-mortem for Noa Leads revealed multiple instances where apply_chip functions forgot side-effects required for downstream logic.
Atomicity Checklist:
- Update
statusfield. - Update
last_activity_type. - Close associated tasks in
AUTO_CLOSE_TASK_TYPES. - Log intent in Activity Log with
metadata.applied=True/False.
Sources: BY-STACK/state-machine.md:15-40, RECURRING-PATTERNS.md:175-190
Testing Pattern Post-Mortems
The TESTING-PATTERNS.md analysis provides a unique perspective where the test suite itself is the source of the failure.
- Spec vs. Client: Tests often pass against a specification (e.g., "The API should return 200"), while the real-world consumer (e.g., a browser or specific SDK) expects a different behavior (e.g., a 401 challenge for OAuth).
- Environment Mismatch: Traditional test clients (like
httpx) do not enforce Browser Policies such as Content Security Policy (CSP) or CORS. A test may pass while a browser blocks the action due to aform-action 'none'directive.
Sources: TESTING-PATTERNS.md:9-40, BY-STACK/browser-policy.md:20-35
Conclusion
Original Source Post-Mortems serve as the empirical foundation for the amir-bug-patterns repository. By analyzing specific failures in projects like Noa Leads and EmailFlow, the system categorizes bugs into actionable patterns. These post-mortems prove that technical errors—ranging from SQL NULL handling in CAS updates to React state synchronization—are often universal across stacks, necessitating a central repository for prevention and mechanical enforcement.
Sources: README.md:9-15, MIGRATION-NOTES.md:120-135