docs: remove stale retro.env references from retro agent plan

[sreedhards]

Summary

• Updates stale references in the retro agent implementation plan after ADR 0055 removed per-harness env files
• Replaces the file structure table entry, Task 3 instructions, and Task 8 harness YAML example with env.runner / env.sandbox / forge.github.env configuration
• Removes deprecated runner_env and host_files env delivery from the plan doc example

Fixes #2939

Test plan

• grep -rn 'retro.env' docs/ returns zero matches
• Task 8 harness example aligns with current internal/scaffold/fullsend-repo/harness/retro.yaml pattern

Made with Cursor

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Docs: remove retro.env references from retro agent plan

📝 Documentation 🕐 10-20 Minutes

AI Description

• Update the retro agent plan to reflect ADR 0055 unified env delivery.
• Replace retro.env/runner_env examples with env.runner/env.sandbox/forge.github.env.
• Remove deprecated host_files entries and stale sandbox path examples.

Diagram

graph TD
  A["Retro agent plan"] --> B["ADR 0055"] --> C["harness/retro.yaml"] --> D["env.runner"] --> E["env.sandbox"] --> F["forge.github.env"]

Loading

High-Level Assessment

The PR’s approach is the right one: update the plan to match ADR 0055 by removing the retired per-harness env file and deprecated runner_env/host_files examples, and documenting env.runner/env.sandbox/forge.github.env instead.

Files changed (1) +29 / -32

Documentation (1) +29 / -32

2026-05-04-retro-agent.mdAlign retro agent plan env guidance with ADR 0055 +29/-32

Align retro agent plan env guidance with ADR 0055

• Removes stale references to 'env/retro.env' and deprecated 'runner_env' delivery. Updates Task 3 guidance and the Task 8 harness YAML example to use 'env.runner' / 'env.sandbox' and 'forge.github.env', and refreshes example paths accordingly.

docs/superpowers/plans/2026-05-04-retro-agent.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 Remove stale references to deleted env/retro.env in retro agent plan doc

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Task file action mismatch 🐞 Bug ≡ Correctness

Description

Task 3 lists internal/scaffold/fullsend-repo/harness/retro.yaml as a file to modify, but Task 8
later instructs creating that same file, which conflicts with the plan’s sequential task flow. This
can cause confusion for agents/humans following the checklist and looking for a file that doesn’t
exist yet at Task 3 time.

Code

docs/superpowers/plans/2026-05-04-retro-agent.md[R182-183]

**Files:**
-- Create: `internal/scaffold/fullsend-repo/env/retro.env`
+- Modify: `internal/scaffold/fullsend-repo/harness/retro.yaml` (see Task 8)

Relevance

⭐⭐⭐ High

Team has accepted fixing implementation-plan file/task inconsistencies (e.g., wrong file referenced
in Tasks corrected in PR #225).

PR-#225

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Task 3 instructs modifying the harness file, but Task 8 later instructs creating it, demonstrating
an internal inconsistency in the plan’s file actions.

docs/superpowers/plans/2026-05-04-retro-agent.md[180-192]
docs/superpowers/plans/2026-05-04-retro-agent.md[637-641]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Task 3 says to **modify** `internal/scaffold/fullsend-repo/harness/retro.yaml`, but Task 8 is where the plan actually **creates/writes** that file. This is internally inconsistent and can break the intended task-by-task execution order.

## Issue Context
The plan doc is meant to be executed sequentially using checkboxes. Referring to a file as “Modify” before it exists is confusing, even if it parenthetically points to Task 8.

## Fix Focus Areas
- docs/superpowers/plans/2026-05-04-retro-agent.md[180-192]
- docs/superpowers/plans/2026-05-04-retro-agent.md[637-646]

## Suggested fix
In **Task 3**, change the **Files** section to something like:
- (Option A) Remove the file entry entirely (since Task 3 is now guidance-only), or
- (Option B) Replace with: `- Configure in: internal/scaffold/fullsend-repo/harness/retro.yaml (created in Task 8)`

So Task 3 no longer implies an earlier modification of a not-yet-created file.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Task file action mismatch 🐞 Bug ≡ Correctness

Task 3 lists internal/scaffold/fullsend-repo/harness/retro.yaml as a file to modify, but Task 8
later instructs creating that same file, which conflicts with the plan’s sequential task flow. This
can cause confusion for agents/humans following the checklist and looking for a file that doesn’t
exist yet at Task 3 time.

Agent Prompt

## Issue description
Task 3 says to **modify** `internal/scaffold/fullsend-repo/harness/retro.yaml`, but Task 8 is where the plan actually **creates/writes** that file. This is internally inconsistent and can break the intended task-by-task execution order.

## Issue Context
The plan doc is meant to be executed sequentially using checkboxes. Referring to a file as “Modify” before it exists is confusing, even if it parenthetically points to Task 8.

## Fix Focus Areas
- docs/superpowers/plans/2026-05-04-retro-agent.md[180-192]
- docs/superpowers/plans/2026-05-04-retro-agent.md[637-646]

## Suggested fix
In **Task 3**, change the **Files** section to something like:
- (Option A) Remove the file entry entirely (since Task 3 is now guidance-only), or
- (Option B) Replace with: `- Configure in: internal/scaffold/fullsend-repo/harness/retro.yaml (created in Task 8)`

So Task 3 no longer implies an earlier modification of a not-yet-created file.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[ralphbean]

Apologies to waste your time and tokens. Thank you for the PR, but - please see latest comments on #2939

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 5:02 PM UTC · Completed 5:09 PM UTC
Commit: f0253d8 · View workflow run →

[fullsend-ai-retro]

PR #2946 was a docs-only PR opened by external contributor sreedhards to fix issue #2939 (stale retro.env references in a historical plan doc). The PR was closed without merging by maintainer ralphbean, who determined that updating historical plan documents is unnecessary work. The root cause is an agent cascade: the review agent on PR #2761 flagged stale references in the plan doc → the retro agent created issue #2939 proposing the fix → the triage agent confirmed it as a good first issue → the code agent attempted and failed → an external contributor picked it up and wasted their time. ralphbean explicitly asked for repo-specific guidance (e.g., AGENTS.md) so agents learn that plan docs under docs/superpowers/plans/ are historical artifacts that should not be updated. Issue #2678 (review agent should deprioritize findings on planning/design documents) is related but covers only the review agent dimension, not the retro or triage agents. Two proposals: (1) add repo-specific guidance in AGENTS.md about historical plan docs, and (2) add retro agent guidance to avoid proposing issues for stale references in historical documents.

Proposals filed

• Add AGENTS.md guidance that plan docs are historical artifacts not requiring updates (in fullsend-ai/fullsend)
• Retro agent should not propose issues for cosmetic staleness in historical documents (in fullsend-ai/fullsend)