What happened
On PR #6101, the code agent generated documentation that included org-mode-specific content (how stage workflows are installed in org-mode, when to switch to org-mode). The review agent engaged with the org-mode details in its critical finding, treating the org-mode/repo-mode distinction as a technical accuracy issue rather than flagging org-mode content as inappropriate. Human reviewer ralphbean corrected this: "org mode is deprecated and will be removed soon. Don't bother mentioning it more here." The deprecation is documented in ADR 0044 and in the org-mode guide deprecation banner, but AGENTS.md and docs/contributing/ contain no mention of the deprecation. The triage agent doc (docs/agents/triage.md) references org mode at line 73 without noting it is deprecated.
What could go better
If AGENTS.md or a contributing guide noted that org-mode is deprecated per ADR 0044, the code agent would have avoided generating org-mode-specific documentation, and the review agent would have flagged org-mode content as stale rather than treating it as a technical-accuracy concern. This is a narrow, high-confidence fix: the deprecation is an established decision (ADR accepted 2026-06-16) with a tracking issue (#2302) for full removal, but agents cannot discover it from any file they routinely read. Confidence: high that this gap exists; moderate that it contributed to the wasted work on this PR (the PR was ultimately closed for a broader audience-mismatch reason, not solely because of org-mode content).
Proposed change
Add a note to AGENTS.md or docs/contributing/workflow-contracts.md stating that per-org installation mode is deprecated per ADR 0044 and will be removed. The note should instruct agents to: (1) not generate new org-mode-specific documentation or code, (2) when reviewing PRs that touch org-mode content, flag it as deprecated rather than treating org/repo mode distinctions as active architectural decisions. Also update docs/agents/triage.md line 73 to note the deprecation inline. A one-line addition to AGENTS.md in the relevant section would suffice, e.g.: "Per-org installation mode is deprecated (ADR 0044); do not add org-mode-specific content to docs or code."
Validation criteria
On the next 3 agent-authored PRs that touch Jira integration, scaffold, or installation documentation, the code agent should not generate org-mode-specific content. If a PR does mention org-mode, the review agent should flag it as referencing deprecated functionality rather than engaging with org-mode details as active architecture.
Generated by retro agent from #6101
What happened
On PR #6101, the code agent generated documentation that included org-mode-specific content (how stage workflows are installed in org-mode, when to switch to org-mode). The review agent engaged with the org-mode details in its critical finding, treating the org-mode/repo-mode distinction as a technical accuracy issue rather than flagging org-mode content as inappropriate. Human reviewer
ralphbeancorrected this: "org mode is deprecated and will be removed soon. Don't bother mentioning it more here." The deprecation is documented in ADR 0044 and in the org-mode guide deprecation banner, but AGENTS.md anddocs/contributing/contain no mention of the deprecation. The triage agent doc (docs/agents/triage.md) references org mode at line 73 without noting it is deprecated.What could go better
If AGENTS.md or a contributing guide noted that org-mode is deprecated per ADR 0044, the code agent would have avoided generating org-mode-specific documentation, and the review agent would have flagged org-mode content as stale rather than treating it as a technical-accuracy concern. This is a narrow, high-confidence fix: the deprecation is an established decision (ADR accepted 2026-06-16) with a tracking issue (#2302) for full removal, but agents cannot discover it from any file they routinely read. Confidence: high that this gap exists; moderate that it contributed to the wasted work on this PR (the PR was ultimately closed for a broader audience-mismatch reason, not solely because of org-mode content).
Proposed change
Add a note to
AGENTS.mdordocs/contributing/workflow-contracts.mdstating that per-org installation mode is deprecated per ADR 0044 and will be removed. The note should instruct agents to: (1) not generate new org-mode-specific documentation or code, (2) when reviewing PRs that touch org-mode content, flag it as deprecated rather than treating org/repo mode distinctions as active architectural decisions. Also updatedocs/agents/triage.mdline 73 to note the deprecation inline. A one-line addition to AGENTS.md in the relevant section would suffice, e.g.: "Per-org installation mode is deprecated (ADR 0044); do not add org-mode-specific content to docs or code."Validation criteria
On the next 3 agent-authored PRs that touch Jira integration, scaffold, or installation documentation, the code agent should not generate org-mode-specific content. If a PR does mention org-mode, the review agent should flag it as referencing deprecated functionality rather than engaging with org-mode details as active architecture.
Generated by retro agent from #6101