Skip to content

fix(docs): rdd-shadow-evaluation.md references retired GENTLE_AI_RDD_SHADOW switch #2998

Description

@Dreamcoder08

Pre-flight Checklist

  • I have searched existing issues and this is not a duplicate
  • I understand that PRs will be rejected if the linked issue does not have status:approved

📝 Bug Description

docs/architecture/rdd-shadow-evaluation.md still documents the GENTLE_AI_RDD_SHADOW=1 opt-in switch as current, operator-facing guidance, but the switch and its shadow observer were removed from the codebase in RDD root simplification Wave 7 S2a (commit 17e40eb0, "retire the Wave 1 shadow observer surface").

On current upstream main (69ac5a45), GENTLE_AI_RDD_SHADOW appears in the code only in comments stating it was retired, for example internal/reviewtransaction/candidate_relation.go:8: "the Wave 1 shadow observer that also called it (shadow_observer.go, GENTLE_AI_RDD_SHADOW) retired in Wave 7 S2a". There is no environment-variable reader left, and shadow_observer.go no longer exists. The doc remains as an actionable "Quick path" that tells readers to set the switch and watch stderr for a gentle-ai.rdd-shadow/v1 line that can never be emitted.

🔄 Steps to Reproduce

  1. Check out current upstream main (69ac5a45).
  2. Read docs/architecture/rdd-shadow-evaluation.md, "Quick path" section (lines 7-8): "To opt in for local investigation, set GENTLE_AI_RDD_SHADOW=1 before running a gate".
  3. Grep the codebase for GENTLE_AI_RDD_SHADOW: only comments remain, all saying the switch was retired in Wave 7 S2a.
  4. Run any gate with GENTLE_AI_RDD_SHADOW=1 set: no gentle-ai.rdd-shadow/v1 line is ever written, because shadow_observer.go and shadowObservationEnvVar were deleted in Wave 7 S2a (commit 17e40eb0).

✅ Expected Behavior

docs/architecture/rdd-shadow-evaluation.md is updated or removed so it no longer instructs users to set a switch that does not exist. If shadow evaluation is retired, the doc should say so (or be deleted), matching the Wave 7 outcome.

❌ Actual Behavior

The doc presents a removed switch as current guidance. A reader following it sets an environment variable that has no effect and waits for stderr output that cannot appear.

🖥️ Environment

  • Gentle AI Version: main @ 69ac5a45 (documentation-only defect; no installed release involved)
  • Operating System: Linux (Arch/Manjaro)
  • AI Agent / Client: Other
  • Affected Area: Documentation

💡 Logs / Error Output

N/A - documentation-only report; no runtime logs.

Additional Context

  • Evidence of removal: commit 17e40eb0 ("feat(reviewtransaction): retire the Wave 1 shadow observer surface", Wave 7 WU4+WU5+WU6) removes ObserveShadowRelation (shadow_observer.go), shadowObservationEnvVar, and all 5 consumers. It is an ancestor of upstream main.
  • The Wave 7 change (openspec/changes/rdd-root-simplification-wave7) records the observer as fully retired and does not plan any update to docs/architecture/rdd-shadow-evaluation.md, so this doc is stale rather than intentionally historical.
  • This is a post-removal documentation accuracy defect (the removal has landed on main); it is not reporting an in-flight or planned redesign mismatch.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workinggood first issueGood for newcomerspriority:lowLow prioritystatus:approvedApproved for implementation — PRs can now be openedtype:bugBug fixup-for-grabsScoped, approved and ready for a community contributor to pick up

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions