What happened
PR #2761 deleted env/retro.env as part of ADR 0055. The review agent flagged stale references in docs/superpowers/plans/2026-05-04-retro-agent.md. The retro agent then created issue #2939 proposing to fix those stale references. The triage agent confirmed it as a good first issue. The code agent attempted and failed. An external contributor (sreedhards) volunteered, did the work, and opened PR #2946 — which maintainer ralphbean closed without merging, stating that updating historical plan docs is unnecessary. The entire cascade wasted agent tokens and human contributor time on work that should never have been proposed.
What could go better
All three agents (review, retro, triage) lacked repo-specific context that plan documents under docs/superpowers/plans/ are historical artifacts — point-in-time implementation plans that are not maintained after implementation is complete. ralphbean explicitly requested repo-specific guidance so agents stop treating stale references in plan docs as actionable issues. Adding a section to AGENTS.md about plan document conventions would give all agents (review, retro, triage, code) the context they need to skip this class of finding. This is the highest-leverage fix because AGENTS.md is read by every agent role.
Proposed change
Add a section to AGENTS.md (in fullsend-ai/fullsend) under a heading like 'Plan documents' that states: (1) files under docs/superpowers/plans/ are historical implementation plans, frozen at the time of implementation; (2) stale references, outdated file paths, or deprecated patterns in plan docs are expected and should NOT be flagged as issues, proposed as fixes, or used as implementation guidance; (3) plan docs should not be modified after their associated work is complete; (4) agents should not create issues or review findings about staleness in plan docs. This guidance is repo-specific as ralphbean requested — it reflects how this particular repo treats plan documents, not a universal convention.
Validation criteria
Within the next 5 PRs that touch files previously referenced in plan docs, neither the review agent nor the retro agent flags stale plan doc references as issues. Grep AGENTS.md for 'plan' or 'historical' confirms the guidance is present. No new issues are created by the retro agent proposing plan doc updates. Related: #2678 (review agent deprioritize plan doc findings), #2939 (the triggering issue).
Generated by retro agent from #2946
What happened
PR #2761 deleted env/retro.env as part of ADR 0055. The review agent flagged stale references in docs/superpowers/plans/2026-05-04-retro-agent.md. The retro agent then created issue #2939 proposing to fix those stale references. The triage agent confirmed it as a good first issue. The code agent attempted and failed. An external contributor (sreedhards) volunteered, did the work, and opened PR #2946 — which maintainer ralphbean closed without merging, stating that updating historical plan docs is unnecessary. The entire cascade wasted agent tokens and human contributor time on work that should never have been proposed.
What could go better
All three agents (review, retro, triage) lacked repo-specific context that plan documents under docs/superpowers/plans/ are historical artifacts — point-in-time implementation plans that are not maintained after implementation is complete. ralphbean explicitly requested repo-specific guidance so agents stop treating stale references in plan docs as actionable issues. Adding a section to AGENTS.md about plan document conventions would give all agents (review, retro, triage, code) the context they need to skip this class of finding. This is the highest-leverage fix because AGENTS.md is read by every agent role.
Proposed change
Add a section to AGENTS.md (in fullsend-ai/fullsend) under a heading like 'Plan documents' that states: (1) files under docs/superpowers/plans/ are historical implementation plans, frozen at the time of implementation; (2) stale references, outdated file paths, or deprecated patterns in plan docs are expected and should NOT be flagged as issues, proposed as fixes, or used as implementation guidance; (3) plan docs should not be modified after their associated work is complete; (4) agents should not create issues or review findings about staleness in plan docs. This guidance is repo-specific as ralphbean requested — it reflects how this particular repo treats plan documents, not a universal convention.
Validation criteria
Within the next 5 PRs that touch files previously referenced in plan docs, neither the review agent nor the retro agent flags stale plan doc references as issues. Grep AGENTS.md for 'plan' or 'historical' confirms the guidance is present. No new issues are created by the retro agent proposing plan doc updates. Related: #2678 (review agent deprioritize plan doc findings), #2939 (the triggering issue).
Generated by retro agent from #2946