Issue workflow should offter to help users with bugs, additional changes, and questions at the end of the workflow

[acreeger]

The orchestraor should use iloom agents as necessary i.e. when making non-trivial changes (i.e more than 1 file) it should use an implementer subagent. To deep dive on tricky bug, use analyzer, to implement new addition feature, analyze and plan, then implementer.

The orchestraor should also use recap MCP commands to update any decisions/risks/insights/assumptions that get made during the ad-hoc conversation after the workflow has completed

[acreeger]

Enhancement Request Analysis

Questions for Reporter

Question	Answer
Should this help workflow trigger automatically after il finish completes, or should it be opt-in (e.g., a flag like --help-after or manual trigger via il help)?	Automatic after finish - Always offer help after il finish completes
When a user declines further help, should iloom remember this preference for the session/loom, or always ask each time?	Always ask each time - No memory, prompt after every workflow completion
If the orchestrator creates a recap entry during the help session, should it update the original issue comment or create a new recap comment?	N/A - This is about the recap MCP tool (recap.add_entry), not about posting comments on the issue. The recap MCP server captures insights/decisions in its internal storage.
Should the help workflow be available during il start as well (e.g., after initial planning but before implementation begins)?	Out of scope for this issue
What should happen if the user requests help with something outside the current issue scope (e.g., "help me set up a new database")? Should the orchestrator suggest creating a new issue/loom?	Ask user to decide - Present options and let user choose each time

Problem Summary
After completing an issue workflow, users may discover bugs, want to make additional changes, or have questions about the implementation, but currently have no structured way to continue working with AI assistance in the same context.

User Impact
Developers using iloom lose the benefits of the multi-agent workflow after il finish completes, forcing them to either manually use Claude without the specialized agents, or start a new workflow which loses the existing context and session knowledge.

Enhancement Goal
Enable users to seamlessly continue working with AI assistance after the primary workflow completes by offering structured help options that intelligently delegate to appropriate iloom agents (analyzer, planner, implementer) and maintain session context through recap MCP commands.

Next Steps

• ✅ Reporter provided answers to clarifying questions
• Technical analysis to identify integration points with existing workflow orchestrator
• Implementation planning for agent delegation logic and recap integration
• Execution

---

📋 Complete Context & Details (click to expand)

Current Workflow Context

Based on README.md and CLAUDE.md, the current il finish workflow:

1. Validates tests/lint
2. Commits changes
3. Handles conflicts
4. Merges or creates PR
5. Generates session summary using recap
6. Ends the session

The enhancement requests extending this flow to offer continued assistance.

Desired Behavior (from issue description)

Agent Delegation Strategy:

• Simple changes (1 file): Orchestrator handles directly
• Multi-file changes: Use implementer subagent
• Tricky bugs: Use analyzer agent for deep dive
• New feature additions: Use analyzer for planning, then implementer for execution

Recap Integration:

• Orchestrator should use recap MCP commands to capture:
  • Decisions made during ad-hoc conversation
  • Risks identified
  • Insights discovered
  • Assumptions documented

Additional Context

Existing iloom Agent System:

• iloom-issue-enhancer: Expands requirements
• iloom-issue-complexity-evaluator: Determines workflow approach (simple vs complex)
• Implementer: Executes plans
• These agents already write to issue comments for context persistence

Related Commands:

• il spin: Launches Claude inside current loom with auto-detected context
• Recap command: Already used in il finish for session summaries (recently added per commit d04ddc7)

Integration Points to Consider:

• Workflow orchestrator (handles multi-agent coordination)
• recap MCP server (for capturing session insights)
• Agent templates and prompts (may need help-specific variants)
• Permission modes (acceptEdits, etc.)
• Comment management (where to post updates)

User Experience Flow (Implied):

1. User runs il finish or completes workflow
2. System asks: "Would you like help with bugs, changes, or questions?"
3. User selects option (or describes issue)
4. Orchestrator evaluates complexity
5. Delegates to appropriate agent(s)
6. Agent works with user
7. Updates recap with insights/decisions
8. Returns to help prompt (or exits if user declines)

[acreeger]

Complexity Assessment

Classification: COMPLEX → SIMPLE

Revised Understanding: This issue is about modifying the issue-prompt.txt orchestrator template, NOT implementing new CLI code. The prompt already has a "Wrapping Up Instructions" section, and this enhancement adds post-workflow help offerings to the orchestrator's behavior.

Metrics:

• Estimated files affected: 1-2 (issue-prompt.txt, possibly related agent templates)
• Estimated lines of code: 50-100 (prompt template additions)
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: N/A (prompt template, not code)
• Overall risk level: Low

Reasoning: The existing orchestrator prompt template (issue-prompt.txt) already handles the full workflow including "Wrapping Up Instructions". This enhancement adds instructions for the orchestrator to:

1. Offer help with bugs, additional changes, or questions after workflow completion
2. Delegate to appropriate iloom agents based on task complexity
3. Use recap MCP commands to capture decisions/risks/insights during ad-hoc conversations

This is a prompt engineering task, not a code implementation task. The infrastructure (agents, recap MCP, orchestrator) already exists.

[acreeger]

Combined Analysis & Plan - Issue #355

Executive Summary

This issue enhances the orchestrator prompt (issue-prompt.txt) to automatically offer users help with bugs, additional changes, or questions after the main workflow completes. The enhancement adds a new "Post-Workflow Help" section after the existing "Wrapping Up Instructions" that intelligently delegates tasks to appropriate iloom agents based on complexity.

HIGH/CRITICAL Risks (if any)

None identified - this is a prompt template modification with no code changes.

Implementation Overview

High-Level Execution Phases

1. Add Post-Workflow Help Section: Insert new instructions after "Wrapping Up Instructions" (line 543) that offer help and handle delegation
2. Define Agent Delegation Logic: Specify when to use orchestrator directly vs. subagents (analyzer, implementer)
3. Add Recap Integration: Instructions to use recap.add_entry during ad-hoc conversations

Quick Stats

• 1 file to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Users lose AI assistance context after workflow completion, forcing manual Claude usage or new workflow starts
• Architectural context: The orchestrator prompt already handles full workflow with "Wrapping Up Instructions" at the end
• Edge cases: Out-of-scope requests (user decides), user declining help (always re-ask next time)

Codebase Research

• Entry point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-355__end-workflow-help/templates/prompts/issue-prompt.txt:521-543 - "Wrapping Up Instructions" section
• Agent delegation pattern: Lines 142-158 show @agent-* syntax for launching subagents
• Available agents: @agent-iloom-issue-analyzer (deep dive), @agent-iloom-issue-planner (planning), @agent-iloom-issue-implementer (execution), @agent-iloom-issue-analyze-and-plan (combined)
• Recap usage pattern: Lines 23-45 define recap MCP tool usage; Lines 350, 423, 463, 512 show contextual logging in workflow phases

Key Decisions from Issue Comments

Decision	Answer
Trigger	Automatic after finish (always offer help)
Preference memory	Always ask each time (no memory)
Recap integration	Uses MCP tool (recap.add_entry), not issue comments
Out of scope requests	Ask user to decide
Context preservation	Prefer subagents to preserve orchestrator context window

---

Implementation Plan

Automated Test Cases to Create

N/A - This is a prompt template modification, not code. No automated tests required.

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-355__end-workflow-help/templates/prompts/issue-prompt.txt:543 (append after line 543)

Change: Add new "Post-Workflow Help" section after "Wrapping Up Instructions"

Click to expand complete structure (~90 lines)

---

## Post-Workflow Help

After providing the wrap-up instructions above, ALWAYS offer to help the user with additional work:

**IMPORTANT: Context Preservation Strategy**

To preserve your own context window for ongoing conversation with the user, **prefer using subagents over handling tasks directly** whenever possible. Subagents run in their own context and return summarized results, keeping the orchestrator's context available for continued user interaction.

- Use subagents liberally - they're designed to handle focused tasks efficiently
- Only handle tasks directly when they're truly trivial (quick answers, single-line changes)
- When in doubt, delegate to a subagent

**STEP 5 - Offer Post-Workflow Assistance:**

1. Use AskUserQuestion tool to offer help:
   - Question: "Before you wrap up, would you like help with anything else? I can assist with bugs, additional changes, explanations, or questions."
   - Options:
     - "No thanks, I'm ready to wrap up" (default)
     - "Yes, I found a bug or issue"
     - "Yes, I want to make additional changes"
     - "Yes, I have questions about the implementation"
   - multiSelect: false

2. If user selects "No thanks, I'm ready to wrap up":
   - End the session gracefully
   - Do NOT offer help again

3. If user selects any help option, proceed to **Help Request Handling** below

**Help Request Handling:**

When the user requests help, gather details and determine the appropriate subagent:

1. Ask the user to describe what they need (if not already clear from their selection)

2. Evaluate the request and delegate appropriately:

   **For trivial tasks (quick answer, single-line change):**
   - Handle directly only if truly minimal effort
   - If any code reading or multi-step work is needed, use a subagent instead

   **For bug investigation or analysis:**
   - Launch @agent-iloom-issue-analyzer with instructions:
     - "Investigate the following issue: [user's description]. Identify root cause and document findings."
   - Upon completion, present findings to user
   - Ask if they want to proceed with a fix (delegate to implementer)
   - Use `recap.add_entry` to log key insights (type: "insight") and risks (type: "risk")

   **For code changes (any modification, even single-file):**
   - Launch @agent-iloom-issue-implementer with clear instructions:
     - "Implement the following change request: [user's description]. This is an ad-hoc change, not tied to a formal issue."
   - Upon completion, extract results and present to user
   - Use `recap.add_entry` to log significant insights or decisions

   **For new feature additions or complex changes:**
   - Launch @agent-iloom-issue-analyze-and-plan with instructions:
     - "Analyze and plan the following feature request: [user's description]. Create an implementation plan."
   - Upon completion, present plan to user
   - Ask if they want to proceed with implementation
   - If yes, launch @agent-iloom-issue-implementer with the plan
   - Use `recap.add_entry` to log decisions and assumptions

   **For questions or explanations:**
   - For quick factual questions: answer directly
   - For deeper exploration (how does X work, why was Y designed this way): 
     - Launch @agent-iloom-issue-analyzer with exploration instructions
     - This preserves your context while getting thorough answers

   **For out-of-scope requests (unrelated to current issue/codebase):**
   - Use AskUserQuestion tool:
     - Question: "This request appears to be outside the scope of the current issue. How would you like to proceed?"
     - Options:
       - "Help me with it anyway"
       - "Create a new issue for this"
       - "Skip this and wrap up"
     - multiSelect: false
   - Follow user's choice

3. After handling each request, return to Step 5 to offer additional help
   - Always ask again after completing each help request
   - Only exit when user explicitly chooses "No thanks, I'm ready to wrap up"

**Recap Integration for Ad-Hoc Conversations:**

During post-workflow help sessions, use the recap MCP commands to capture important information:

- **Decisions**: When making choices about how to handle requests or implement changes
  - Example: `recap.add_entry({ type: "decision", content: "Added error handling for null input based on user's bug report" })`

- **Risks**: When identifying potential issues or concerns
  - Example: `recap.add_entry({ type: "risk", content: "The quick fix doesn't handle concurrent access - may need revisiting" })`

- **Insights**: When discovering important technical information
  - Example: `recap.add_entry({ type: "insight", content: "The auth module caches tokens for 1 hour - affects testing approach" })`

- **Assumptions**: When making bets about requirements or approach
  - Example: `recap.add_entry({ type: "assumption", content: "Assuming backwards compatibility not needed for this internal API" })`

Do NOT log:
- Status updates about the help session itself
- What the user asked for (they know)
- That you completed a task

Detailed Execution Order

Phase 1: Add Post-Workflow Help Section

1. Read /Users/adam/Documents/Projects/iloom-cli/feat-issue-355__end-workflow-help/templates/prompts/issue-prompt.txt -> Verify current structure ends at line 543
2. Append new "Post-Workflow Help" section after line 543 -> Verify section properly follows "Wrapping Up Instructions"
3. Ensure proper markdown formatting (headers, code blocks, bullet points) -> Verify renders correctly

Phase 2: Validate Changes

1. Run pnpm build -> Verify TypeScript compilation succeeds
2. Verify the template file is copied to dist/prompts/ -> Check file exists in dist

Dependencies and Configuration

None - this is a prompt template modification only.

[acreeger]

Implementation Complete - Issue #355

Summary

Added a new "Post-Workflow Help" section to issue-prompt.txt that automatically offers users help with bugs, additional changes, or questions after workflow completion. The section emphasizes using subagents to preserve orchestrator context window and includes recap MCP integration for capturing decisions/risks/insights during ad-hoc conversations.

Changes Made

• templates/prompts/issue-prompt.txt: Added ~100 lines of new "Post-Workflow Help" section after the existing "Wrapping Up Instructions" section

Validation Results

• Build: Passed (pnpm build completed successfully)
• Template copied to dist/prompts/issue-prompt.txt: Verified (647 lines, includes new section)

---

Detailed Changes by File (click to expand)

Files Modified

templates/prompts/issue-prompt.txt

Changes: Appended new "Post-Workflow Help" section after line 543 (end of "Wrapping Up Instructions")

New section includes:

• Context Preservation Strategy (prefer subagents to preserve context window)
• STEP 5 - Offer Post-Workflow Assistance (AskUserQuestion with 4 options)
• Help Request Handling with delegation logic for:
  • Trivial tasks (handle directly)
  • Bug investigation (use analyzer agent)
  • Code changes (use implementer agent)
  • New features (use analyze-and-plan, then implementer)
  • Questions/explanations (quick answers directly, deep exploration via analyzer)
  • Out-of-scope requests (present options to user)
• Loop back to offer additional help after each request
• Recap Integration for Ad-Hoc Conversations with examples for decisions, risks, insights, assumptions

Files Created

None

Test Coverage Added

N/A - This is a prompt template modification, not code.

Dependencies Added

None

---

Tasks

• Read issue and implementation plan from comment 3662765434
• Read current file structure of issue-prompt.txt (543 lines, ends at "Wrapping Up Instructions")
• Append Post-Workflow Help section after line 543
• Run pnpm build to verify template is copied to dist/
• Verify template exists in dist/prompts/

[acreeger]

iloom Session Summary

Key Themes:

• Issue complexity was initially misunderstood as CLI code changes, but was actually a prompt template modification task
• User workflow requires review/test time before needing help, not immediate prompting
• Condensed verbose guidance from ~95 lines to ~25 lines using hybrid approach (Gemini suggestions + table format)

---

Session Details (click to expand)

Key Insights

• The post-workflow help feature is entirely handled by orchestrator prompt templates (issue-prompt.txt, regular-prompt.txt, pr-prompt.txt), not TypeScript code
• Natural user flow is: implementation → review → test → then questions/help, not immediate assistance offering
• Context preservation is critical - orchestrator should delegate to subagents liberally to maintain conversation capacity
• Wrapping Up Instructions should only display when user explicitly says they're done, not automatically after implementation

Decisions Made

• Complexity reclassification: Changed from COMPLEX to SIMPLE after understanding this was prompt engineering, not code implementation
• Flow restructuring: Moved Wrapping Up Instructions after Post-Workflow Help section, triggered only when user indicates readiness
• Condensing strategy: Combined Gemini's verbose quoted message with table-based agent routing for scannable reference
• Scope expansion: Applied same pattern to all three workflow prompts (issue, regular, PR) for consistency
• Agent delegation strategy: Added explicit "Ready to wrap up" option in routing table to make workflow exit clear

Challenges Resolved

• Initial misunderstanding: Evaluator assumed code changes needed; corrected after user clarified this was prompt-only work
• Verbosity issue: Original implementation was ~95 lines; used Gemini collaboration to compress to ~25 lines while retaining all essential guidance
• User agency: First version prompted immediately with AskUserQuestion; revised to wait passively for user to initiate help requests
• Missing exit path: "Ready to wrap up" wasn't explicitly mentioned; added to both message and routing table

Lessons Learned

• Always verify implementation scope before making assumptions about code vs. configuration changes
• When shortening content, consider comparing multiple approaches (AI-generated vs. manual restructuring) before choosing
• User experience flows often differ from engineer assumptions - validate the natural workflow sequence
• Explicit routing tables are more scannable than nested bullet lists for decision-making guidance

---

Generated with 🤖❤️ by iloom.ai