#22503: docs: proposed fix for reasoning array error (#18480)

Related to #18480 This PR documents the proposed fix for the OpenAI reasoning array validation error: ``` 400 Item '[]' of type 'reasoning' was provided without its required following item ``` ## Problem Analysis OpenAI's API requires each `reasoning` item to be followed by a content item. When reasoning items are the last item or appear consecutively, the API returns this validation error. ## Proposed Solution - Filter out empty reasoning items before sending to API - Ensure reasoning items are always paired with content items - Add validation in message preparation layer ## Files Added - `FIX-18480-proposed.md` - Detailed fix proposal ## Note This fix requires deeper investigation into the pi-ai library internals. The proposed solution provides a starting point for discussion. --- Looking for feedback from maintainers on the approach! <!-- greptile_comment --> <h3>Greptile Summary</h3> Added `FIX-18480-proposed.md` documenting a proposed fix for the OpenAI reasoning array validation error (`400 Item '[]' of type 'reasoning' was provided without its required following item`). However, this issue has already been resolved in the codebase: - Implementation: `downgradeOpenAIReasoningBlocks` in `src/agents/pi-embedded-helpers/openai.ts:69` - Documentation: `docs/reference/transcript-hygiene.md:98` - Tests: `src/agents/pi-embedded-helpers.downgradeopenai-reasoning.e2e.test.ts` - CHANGELOG entry: line 1671 The existing implementation drops orphaned reasoning blocks (those without following content) and is more sophisticated than the proposed approach. This documentation file may cause confusion since it presents a "proposed" fix for an already-solved problem. <h3>Confidence Score: 4/5</h3> - Safe to merge but may cause confusion about fix status - Only adds documentation (no code changes), so no risk of bugs. However, documents a "proposed" fix for an already-resolved issue, which could confuse contributors unaware the fix is already in production. - FIX-18480-proposed.md should clarify the fix is already implemented, or be removed _{Last reviewed commit: c737277} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->