diff --git a/AGENTS.md b/AGENTS.md index 5cb03b85..477cead9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,7 +57,7 @@ When CodeGraph MCP tools are available and `.codegraph/` exists, prefer them for | Dependencies or import graph changed | Run `yarn knip` as an advisory manifest/import audit | | Translation key/value changed | Use the `translate` skill (spawns parallel `translator` subagents); for manual script operations see `docs/agent-playbooks/translations.md` | | Public-facing English content or AI context changed (`README.md`, `index.html`, `AGENTS.md`, docs pages, or `scripts/generate-llms-files.mjs`) | Run `yarn llms:generate`; inspect and commit any resulting changes to `public/llms*.txt` so LLM indexes stay current | -| Bug report in a specific file/line | Start with git history scan from `docs/agent-playbooks/bug-investigation.md` before editing | +| Bug report | Reproduce the reported behavior or establish the defect from conclusive source/runtime evidence before editing; for a specific file/line, also start with the git history scan in `docs/agent-playbooks/bug-investigation.md` | | `CHANGELOG.md`, `scripts/release-body.js`, or package version changed | Run `yarn changelog` if release notes need regeneration | | Long-running task spans multiple sessions, handoffs, or spawned agents | Use `docs/agent-playbooks/long-running-agent-workflow.md`, keep a machine-readable feature list plus a progress log, and run `./scripts/agent-init.sh` before starting a fresh feature slice | | New reviewable feature/fix started while on `master` | Create a short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branch from `master` before editing; use a separate worktree only for parallel tasks | @@ -135,6 +135,9 @@ src/ ### Bug Investigation Rules +- A bug fix requires either a reproduction of the reported behavior or conclusive source/runtime evidence that identifies both the defect and the correct fix with equivalent certainty. +- If the bug cannot be reproduced and the evidence is not conclusive, do not guess or make speculative changes. Report what was checked, say that the bug was not reproduced, and ask for the missing reproduction details when useful. +- When proceeding from conclusive evidence without a reproduction, explain why the evidence is sufficient and add a targeted regression test when practical. - For bug reports tied to a specific file/line, check relevant git history before any fix. - Minimum sequence: `git log --oneline` or `git blame` first, then scoped `git show` for relevant commits. - Full workflow: `docs/agent-playbooks/bug-investigation.md`. diff --git a/public/llms-full.txt b/public/llms-full.txt index 2e4b55b9..8f912a85 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -152,7 +152,7 @@ When CodeGraph MCP tools are available and `.codegraph/` exists, prefer them for | Dependencies or import graph changed | Run `yarn knip` as an advisory manifest/import audit | | Translation key/value changed | Use the `translate` skill (spawns parallel `translator` subagents); for manual script operations see `docs/agent-playbooks/translations.md` | | Public-facing English content or AI context changed (`README.md`, `index.html`, `AGENTS.md`, docs pages, or `scripts/generate-llms-files.mjs`) | Run `yarn llms:generate`; inspect and commit any resulting changes to `public/llms*.txt` so LLM indexes stay current | -| Bug report in a specific file/line | Start with git history scan from `docs/agent-playbooks/bug-investigation.md` before editing | +| Bug report | Reproduce the reported behavior or establish the defect from conclusive source/runtime evidence before editing; for a specific file/line, also start with the git history scan in `docs/agent-playbooks/bug-investigation.md` | | `CHANGELOG.md`, `scripts/release-body.js`, or package version changed | Run `yarn changelog` if release notes need regeneration | | Long-running task spans multiple sessions, handoffs, or spawned agents | Use `docs/agent-playbooks/long-running-agent-workflow.md`, keep a machine-readable feature list plus a progress log, and run `./scripts/agent-init.sh` before starting a fresh feature slice | | New reviewable feature/fix started while on `master` | Create a short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branch from `master` before editing; use a separate worktree only for parallel tasks | @@ -230,6 +230,9 @@ src/ ### Bug Investigation Rules +- A bug fix requires either a reproduction of the reported behavior or conclusive source/runtime evidence that identifies both the defect and the correct fix with equivalent certainty. +- If the bug cannot be reproduced and the evidence is not conclusive, do not guess or make speculative changes. Report what was checked, say that the bug was not reproduced, and ask for the missing reproduction details when useful. +- When proceeding from conclusive evidence without a reproduction, explain why the evidence is sufficient and add a targeted regression test when practical. - For bug reports tied to a specific file/line, check relevant git history before any fix. - Minimum sequence: `git log --oneline` or `git blame` first, then scoped `git show` for relevant commits. - Full workflow: `docs/agent-playbooks/bug-investigation.md`.