# Agent Guidelines

Rules for AI coding agents (Claude Code, OpenAI Codex, Gemini, Cursor, etc.) working on this codebase. Read this before making any changes.

---

## 1. Stay In Scope

Only modify what you were asked to modify.

- Do not refactor, restyle, add docblocks, improve naming, or "clean up" code that is not part of your task
- Do not add error handling, validation, or fallbacks for scenarios that are not part of your task
- Do not add type annotations, comments, or documentation to code you did not change
- If you find an unrelated issue while working, report it to the user — do not fix it silently

**One task = one set of changes.** If your diff touches files unrelated to the task, you went too far.

---

## 2. Distinguish Root Causes

Before reporting or fixing a "bug", determine whether it is:

- **An actual bug**: Incorrect logic, wrong behavior, security issue, missing edge case — independent of any other change
- **A propagation change**: The code broke because an upstream dependency changed (renamed interface, new enum, changed method signature, new data model). The fix is mechanical (rename/update references). This is NOT a bug in the consuming file.
- **A style preference**: Different but equally valid way of writing the same logic (e.g. ternary vs if/else, early return vs nested). This is NOT a bug.

**Rule**: Only report actual bugs. Propagation changes must be fixed together with the upstream change that caused them. Style preferences are not actionable unless the user explicitly asks for a style review.

---

## 3. Avoid Churn Loops

A churn loop is when agents repeatedly modify the same files without making meaningful progress:

1. Agent A reviews code, finds an "issue", fixes it
2. Agent B reviews again, sees the file was recently changed, scrutinizes it harder
3. Agent B finds a new "issue" (often introduced by A's fix, or a style preference)
4. The file accumulates commits but no real improvement

**How to prevent this:**
- Do not treat "recently changed" as a signal for "likely buggy"
- Do not re-review files that were not part of your task
- If a file has good test coverage and tests pass, assume it is correct
- If you are about to make the 3rd+ change to a file for non-feature reasons, STOP and ask the user
- Before changing code, verify your proposed fix is actually correct — run or reason through the tests. A wrong "fix" starts the next churn cycle.

---

## 4. Verify Before Changing

Before modifying any code:

1. **Read the file** you want to change — do not rely on assumptions or memory
2. **Read the tests** for that file — understand what behavior is already verified
3. **Understand the context** — why the code was written this way, what constraints apply
4. **Run the tests** after your change, or at minimum reason through whether existing tests will still pass

Do not propose changes based on pattern matching alone (e.g. "this looks like it could be null" without verifying whether it can actually be null in practice). Static pattern analysis misses runtime correctness.

---

## 5. Review Scope

When asked to "review", "find bugs", or "audit" code:

- Review only the files, diff, or scope specified by the user
- Do NOT scan the entire codebase looking for issues unless explicitly asked
- Prioritize: **security > correctness > performance > style** (in that order)
- Do not report style issues unless the user specifically asks for a style review
- Do not report theoretical issues that require unlikely conditions — focus on real, demonstrable problems
- When reporting issues, include evidence (the specific code path, input that triggers it, or failing test)

---

## 6. Multi-File Changes

When a refactor changes an interface, enum, service name, or data structure:

- Update ALL consumers in the same change — do not leave broken references for a follow-up "fix"
- Run tests to verify the full propagation is correct before committing
- If you miss a consumer and tests fail, fix it as part of the same work — not as a separate "bugfix"

---

## 7. Do Not Over-Engineer

- Do not add abstractions, helpers, or utilities for one-time operations
- Do not add configuration options or feature flags for behavior that should just be changed
- Do not add backwards-compatibility shims for internal code
- Three similar lines of code is better than a premature abstraction
- The right amount of complexity is what the task requires — no more

---

## 8. Separate Analysis from Implementation

When reviewing code or searching for bugs:

- **Report findings to the user** — do not immediately fix everything you find
- Classify each finding: **critical** (security, data loss, crash), **important** (incorrect behavior), **minor** (edge case, style)
- Let the user decide which findings are worth fixing and in what order
- A finding without evidence (code path, trigger condition, or failing test) is not actionable — do not report it

This prevents the pattern where an agent finds 12 "issues", fixes all 12 in one pass, introduces 2 new problems, and the next agent finds those plus 3 more style preferences — creating an infinite loop.

**The agent's job during analysis is to produce a prioritized list. The user decides what gets fixed.**

---

## 9. Cross-File Analysis Rules

Tracing data flow across files (caller → service → query) is valuable for finding real bugs. However:

- **Analysis** across file boundaries: always allowed and encouraged
- **Changes** across file boundaries: only within the scope of your task
- If your analysis reveals a bug in a file outside your task scope, report it — do not fix it
- Do not follow a cross-file analysis rabbit hole into unrelated subsystems

Example: If asked to review `QueueController.php`, you may trace how `QueueManager::removeFromQueue()` behaves to verify correctness. But do not then also "fix" something you noticed in `QueueManager` unless that was part of your task.

---

## 10. When In Doubt, Ask

If you are uncertain whether:
- Something is a bug or a style preference
- A change is in scope for your task
- Your fix might break something else
- A file should be modified or left alone

**Ask the user.** The cost of asking is low. The cost of unnecessary churn, broken code, or wasted review cycles is high.
