diff --git a/.rules b/.rules index 5965f5a185a9df47f5fce48bed4d677fa2937d0a..8ed1157775e8f4e0446edafbf960170753cf50c1 100644 --- a/.rules +++ b/.rules @@ -136,3 +136,35 @@ Other entities can then register a callback to handle these events by doing `cx. ## Build guidelines - Use `./script/clippy` instead of `cargo clippy` + +# Crash Investigation + +## Sentry Integration +- Crash investigation prompts: `.factory/prompts/crash/investigate.md` +- Crash fix prompts: `.factory/prompts/crash/fix.md` +- Fetch crash reports: `script/sentry-fetch ` +- Generate investigation prompt from crash: `script/crash-to-prompt ` + +# Rules Hygiene + +These `.rules` files are read by every agent session. Keep them high-signal. + +## After any agentic session +If you discover a non-obvious pattern that would help future sessions, include a **"Suggested .rules additions"** heading in your PR description with the proposed text. Do **not** edit `.rules` inline during normal feature/fix work. Reviewers decide what gets merged. + +## High bar for new rules +Editing or clarifying existing rules is always welcome. New rules must meet **all three** criteria: +1. **Non-obvious** — someone familiar with the codebase would still get it wrong without the rule. +2. **Repeatedly encountered** — it came up more than once (multiple hits in one session counts). +3. **Specific enough to act on** — a concrete instruction, not a vague principle. + +Rules that apply to a single crate belong in that crate's own `.rules` file, not the repo root. + +## What NOT to put in `.rules` +Avoid architectural descriptions of a crate (module layout, data flow, key types). These go stale fast and the agent can gather them by reading the code. Rules should be **traps to avoid**, not **maps to follow**. + +## No drive-by additions +Rules emerge from validated patterns, not one-off observations. The workflow is: +1. Agent notes a pattern during a session. +2. Team validates the pattern in code review. +3. A dedicated commit adds the rule with context on *why* it exists.