Bugbot Rules: Code Logic
Relevant source files
The following files were used as context for generating this wiki page:
Bugbot rules are a collection of stack-agnostic detection signatures designed to identify recurring logical errors, race conditions, and integration anti-patterns across software projects. These rules are derived from production post-mortems and are intended to be applied mechanically during code reviews or through automated tools like cubic, qodo, or CodeRabbit.
The logic encapsulated in these rules focuses on preventing fundamental mistakes that lead to data corruption, silent failures, or security vulnerabilities, such as unhandled return values, improper state transitions, and concurrency issues.
Sources: README.md:10-25, INTEGRATION.md:125-130
Core Logic Patterns
The project categorizes code logic bugs into several dimensions, including frequency, severity, and technology stack. Universal patterns are those that apply across all projects regardless of the specific technology used.
Race Conditions and Atomicity
Concurrency errors often stem from "read-then-write" sequences that lack proper synchronization. Rules dictate the use of UNIQUE constraints, advisory locks, or Compare-And-Swap (CAS) mechanisms to ensure atomicity.
The diagram shows the "reserve-then-fill" pattern where a local database entry with a unique constraint must be created before an irreversible external action to prevent duplicate execution.
Sources: claude-md-snippets/universal.md:1, INTEGRATION.md:144-148
External Input Validation
A critical logical requirement is the use of isinstance guards and finiteness checks before performing operations like .get(), .append(), or iteration on data received from external APIs, webhooks, or LLM outputs.
| Input Type | Validation Requirement | Risk if Omitted |
|---|---|---|
| Dict / Objects | isinstance(data, dict) | Crash on .get() if list returned |
| Numbers | isfinite() + Range check | NaN/Infinity propagation |
| Strings | re.fullmatch() with raw strings | Partial match bypass |
| SDK Clients | try/except on startup | Server boot failure |
Sources: claude-md-snippets/universal.md:3, BY-STACK/external-sdk.md:85-100
SDK and Integration Logic
Logic errors frequently occur at the boundaries of external SDKs, particularly concerning lazy evaluation and exception handling.
The Lazy Object Trap
Some SDKs (e.g., PyGithub) return "lazy" objects that do not trigger network requests upon instantiation. Logical failures occur when code assumes a successful object creation implies successful authentication or data availability.
The sequence diagram illustrates how lazy initialization bypasses immediate error handling, leading to failures deep within the application logic rather than at the point of integration.
Sources: bugbot-rules/sdk-lazy-object-not-validated.md:1-20, BY-STACK/external-sdk.md:144-160
Side Effects in Logging
A subtle logic bug involves "riding" side effects on log lines. If a log statement contains an expression that performs necessary work (like fetching a lazy field to validate a token), removing the log or wrapping it in a conditional guard (e.g., if logger.isEnabledFor(DEBUG)) will silently break the application logic.
Sources: bugbot-rules/side-effect-riding-on-log-line.md:1-15
Scheduled Task and State Logic
Logic governing periodic jobs and state machines focuses on ensuring convergence and preventing infinite loops.
Cron Job Convergence
For a scheduled task to function correctly, it must satisfy two logical conditions:
- Rows must leave the filter set after successful processing.
- The filter must not capture rows that can never be processed (terminal states).
Failure to update a status to a terminal state (e.g., failed or done) results in the cron job processing the same data repeatedly.
Sources: BY-STACK/cron-jobs.md:14-25, BY-STACK/cron-jobs.md:30-45
Linked-Field Atomicity
In state-heavy applications, updates to a status field must be linked atomically to related metadata fields (e.g., last_activity_at, audit_logs). Updating one without the other leads to "logic drift" where the system state becomes inconsistent.
Sources: claude-md-snippets/universal.md:5, INTEGRATION.md:158-160
Summary of Integration
The Bugbot Rules system ensures that these logical checks are not just theoretical but integrated into the development workflow. By placing "triggers" in a project's CLAUDE.md file, developers are prompted to review specific logic patterns before modifying sensitive areas of the code, such as authentication handlers or scheduled tasks.
Sources: INTEGRATION.md:5-20