docs(agents-md): tell agents to file an issue when they hit one - #169
Merged
Conversation
Nothing said to write problems down, so they stayed in session transcripts: a workaround gets applied, the PR moves on, and the next agent rediscovers the same thing from scratch. Add a "Filing Issues" section covering the trigger (bug, design gap, stale doc, flaky check, surprising behavior you worked around), which repo owns the fix (local-channels vs. agent-box, with cross-links when symptom and fix differ), and what the issue should contain — observation, smallest repro, where the fix belongs, options with a recommendation. Search first, add to an existing issue over near-duplicates. Prompted by defangdevs/local-channels#10, which came out of exactly this: the box's own PR spawned duplicate hook-* triage sessions and the finding would otherwise have lived only in a transcript. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PsqGhkpjsb4kKAdVz25xKN
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
AGENTS.md said nothing about filing issues, so problems agents hit mid-task stayed in session transcripts: a workaround gets applied, the PR moves on, and the next agent — starting with none of that context — rediscovers the same thing from scratch.
Prompted by defangdevs/local-channels#10, which came out of exactly this failure mode. While driving #168, the box's own PR spawned two duplicate
hook-*triage sessions (CI-outcome events bypassignoreSendersby design, so the standing watch fired on a PR a session already owned). Easy to shrug off withagent-box-session rmand never write down.Changes
A new "Filing Issues" section in
AGENTS.md, before the commit/PR guidelines:local-channelsfor local-webhook behavior,agent-boxfor the module and the box), with cross-links when symptom and fix live apart.User-visible / security effects
None — documentation for agents working in this repo. No module, no AWS, no IAM, no networking impact.
Checks run
Markdown-only change touching no Nix source, so no flake check is affected;
modules/agent-box.nixis untouched andmodule-generated-up-to-dateis unaffected. CI runs the full suite regardless.🤖 Generated with Claude Code
https://claude.ai/code/session_01PsqGhkpjsb4kKAdVz25xKN