fix(party-mode): add return protocol to prevent lost-in-the-middle failures

[arcaven]

Summary

Adds a Return Protocol section to Party Mode's graceful exit step to prevent lost-in-the-middle context failures when Party Mode is invoked from a parent workflow.

Fixes #1319

Problem

After Party Mode completes within a parent workflow (e.g., step-02-discovery in agent creation), the LLM fails to re-present the parent workflow's completion menu. The user has to explicitly ask for it.

Root cause: Party Mode often runs into the 50-100K token range, pushing the parent workflow's instructions into mid-context where they are no longer proactively recalled.

Solution

Add explicit instructions to step-03-graceful-exit.md that force the LLM to:

1. Identify the parent workflow step that invoked Party Mode
2. Re-read that file to restore context
3. Resume from the invocation point
4. Present any required menus/options

This is platform-independent prompt engineering — it works for both sharded workflows (steps/step-XX-name.md) and standard workflows (instructions.md).

Changes

• Added ## RETURN PROTOCOL: section to src/core/workflows/party-mode/steps/step-03-graceful-exit.md
• Wording matches the exact specification in Add Return Protocol to Party Mode to prevent lost-in-the-middle workflow failures #1319

Testing

Re-run a workflow that invokes Party Mode (e.g., Doc agent creation through step-02-discovery) and confirm menu presentation after Party Mode completes.

---

Adversarial Analysis: Limitations of This Approach

While offering this code, I perceived (you be the judge) some potential improvements:

The Circular Dependency Problem

The Return Protocol asks an LLM to:

1. Remember it was invoked from a parent workflow
2. Identify which file that was
3. Re-read that file

But the root cause of #1319 is that the LLM has already forgotten that mid-context information due to lost-in-the-middle effect. We're asking it to recall the very thing it forgot.

Why It May Still Help

• The Return Protocol is placed at the end of the file, benefiting from recency bias
• At lower token counts (<30K), mid-context recall is more reliable
• The explicit instruction to "re-read" may trigger the LLM to search for the invocation point

When It Will Likely Fail

• At 50-100K tokens (as cited in issue)
• When many conversation turns have occurred during Party Mode
• When the parent workflow invocation is deeply buried in context

---

Proposed Enhancement: Workflow State Tracking

A more robust solution might be to use explicit state instead of relying on LLM recall:

Option A: Frontmatter Variable

When a parent workflow invokes Party Mode, it could set:

---
parentWorkflow: "step-02-discovery.md"
returnAction: "redisplay A/P/C menu"
---

Then the Return Protocol becomes a lookup instead of a recall:

## RETURN PROTOCOL:

If frontmatter contains `parentWorkflow`:
1. Read fully and follow: {parentWorkflow}
2. Execute: {returnAction}

Option B: Workflow Stack

For nested sub-workflow invocations:

---
workflowStack:
  - file: "step-02-discovery.md"
    returnAction: "redisplay A/P/C menu"
---

Pop the stack on return. This mirrors how programming languages handle function calls.
Or if you have another idea, I am option to direction.

---

Request for Maintainers

Three paths forward:

1. Merge this as v1 — The Return Protocol matches Add Return Protocol to Party Mode to prevent lost-in-the-middle workflow failures #1319's specification exactly. It's a reasonable first-step mitigation that may help in many cases. We can iterate based on real-world feedback.

2. Implement state tracking now — If you agree the enhancement is valuable, I can implement Option A (frontmatter variable, or examine another other option) in this PR before merging. This may require changes to:

   • step-02-discovery.md (set parentWorkflow when invoking Party Mode)
   • step-03-graceful-exit.md (read parentWorkflow instead of asking LLM to recall)

3. Implement coderabbitai-variation - See below and/or state tracking now.

Let me know which direction you prefer, merge and ignore, merge and pursue second step, or adopt one of these perceived improvements now.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a Return Protocol section to Party Mode's graceful exit step that instructs the LLM to identify parent workflows, re-read their instructions, resume execution at the correct point, and explicitly return control instead of continuing conversationally.

Changes

Cohort / File(s)	Summary
Party Mode Exit Protocol src/core/workflows/party-mode/steps/step-03-graceful-exit.md	Added a Return Protocol section (11 lines) to address lost-in-the-middle behavior by explicitly instructing resumption of parent workflow control flow, including re-reading parent instructions and presenting required menus.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly describes the main change: adding a return protocol to Party Mode to fix lost-in-the-middle failures when returning from parent workflows.
Linked Issues check	✅ Passed	Changes fully implement the requirements from issue #1319: adds Return Protocol section to step-03-graceful-exit.md with explicit instructions to identify parent workflow, re-read parent file, resume execution, and present required menus.
Out of Scope Changes check	✅ Passed	Changes are strictly in-scope: only the specified Party Mode exit step file is modified to add the Return Protocol section as required by issue #1319.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description clearly relates to the changeset. It explains the problem (lost-in-the-middle context failures), the solution (Return Protocol section), and references the specific file modified with detailed context about why the change is necessary.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/core/workflows/party-mode/steps/step-03-graceful-exit.md (1)

111-117: ⚠️ Potential issue | 🟠 Major

Possible contradiction between “Exit Workflow” and Return Protocol.

Lines 111-117 instruct final workflow termination, but the new RETURN PROTOCOL requires resuming the parent workflow and presenting menus. Please reconcile the ordering/wording so the model doesn’t terminate before returning control.

Also applies to: 145-155

[arcaven]

Re: CodeRabbit's Ordering Concern

CodeRabbit flagged a valid structural issue:

Lines 111-117 instruct final workflow termination ([PARTY MODE WORKFLOW COMPLETE]), but the new RETURN PROTOCOL requires resuming the parent workflow. Please reconcile the ordering/wording so the model doesn't terminate before returning control.

The concern is legitimate. The LLM reads sequentially through the numbered steps (1-6). By the time it reaches step 6 ("Exit Workflow") and sees [PARTY MODE WORKFLOW COMPLETE], it may consider the workflow done — before ever reaching the RETURN PROTOCOL section below.

However, the current implementation matches your exact specification from #1319. I don't want to deviate from your design without your input.

---

Suggested Variation (if you want it)

Integrate the Return Protocol into step 6 with conditional logic:

### 6. Return to Parent or Exit

**If Party Mode was invoked from within a parent workflow:**

1. Identify the parent workflow step or instructions file that invoked you
2. Re-read that file now to restore context
3. Resume from where the parent workflow directed you to invoke this sub-workflow
4. Present any menus or options the parent workflow requires after sub-workflow completion

Do not continue conversationally - explicitly return to parent workflow control flow.

**If Party Mode was invoked standalone (no parent workflow):**

"[PARTY MODE WORKFLOW COMPLETE]

Thank you for using BMAD Party Mode for collaborative multi-agent discussions!"

Then remove the separate ## RETURN PROTOCOL: section (now redundant).

---

Your Call

1. Merge as-is — Your spec, your call. The Return Protocol section placement may work fine in practice.
2. Impliment state tracking variation - with or without 3.
3. I can apply the coderabbitai variation — Just say the word and I'll push the integrated version with or without 2.

Let me know your preference.

[arcaven]

(Reposting with improved contrast)

Visual: Expected Flow vs. Potential Short-Circuit

Current Structure (CodeRabbit's Concern)

flowchart TD
    subgraph "Numbered Execution Steps"
        S1["Step 1: Acknowledge"] --> S2["Step 2: Farewells"]
        S2 --> S3["Step 3: Highlights"]
        S3 --> S4["Step 4: Conclusion"]
        S4 --> S5["Step 5: Frontmatter"]
        S5 --> S6["Step 6: Exit Workflow<br/>⚠️ PARTY MODE WORKFLOW COMPLETE"]
    end
    
    subgraph "Reference Sections (below steps)"
        RP["RETURN PROTOCOL:<br/>If parent workflow exists...<br/>re-read and resume"]
    end
    
    S6 -->|"LLM may stop here"| DONE["🛑 Done"]
    S6 -.->|"Should continue to"| RP
    RP -->|"Return to parent"| PARENT["Parent Workflow Menu"]
    
    style S6 fill:#8b0000,color:#ffffff
    style DONE fill:#660000,color:#ffffff
    style RP fill:#006400,color:#ffffff
    style PARENT fill:#004d00,color:#ffffff

Loading

Risk: LLM sees "WORKFLOW COMPLETE" at step 6 and considers itself done before reaching the RETURN PROTOCOL section.

---

Proposed Integrated Structure

flowchart TD
    subgraph "Numbered Execution Steps"
        S1["Step 1: Acknowledge"] --> S2["Step 2: Farewells"]
        S2 --> S3["Step 3: Highlights"]
        S3 --> S4["Step 4: Conclusion"]
        S4 --> S5["Step 5: Frontmatter"]
        S5 --> S6{"Step 6: Return or Exit"}
    end
    
    S6 -->|"Has parent workflow?"| RETURN["Re-read parent file<br/>Resume at invocation point<br/>Present parent's menu"]
    S6 -->|"Standalone"| EXIT["PARTY MODE COMPLETE"]
    
    RETURN --> PARENT["Parent Workflow Menu"]
    EXIT --> DONE["🛑 Done"]
    
    style S6 fill:#006400,color:#ffffff
    style RETURN fill:#004d00,color:#ffffff
    style PARENT fill:#003300,color:#ffffff
    style EXIT fill:#333333,color:#ffffff
    style DONE fill:#333333,color:#ffffff

Loading

Benefit: The decision point is inside the execution flow, not in a separate reference section the LLM might skip.