Update prompts to use Loom Recap MCP

[acreeger]

Summary

Update the issue, PR, and regular/branch prompts to instruct Claude to use the Loom Recap MCP for capturing decisions, insights, risks, and assumptions throughout the workflow.

Motivation

The Recap MCP (#346) provides the tools, but Claude needs to know when to use them. The prompts should instruct Claude to:

1. Set the goal at session start
2. Log significant moments as they happen (decisions, insights, risks, assumptions)

This is the "proactive" capture mechanism - Claude reports things as they happen, not just at phase boundaries.

Files to Update

• templates/prompts/issue-prompt.txt
• templates/prompts/pr-prompt.txt
• templates/prompts/regular-prompt.txt

Changes Required

1. Add Recap MCP Introduction

Add near the top of each prompt (after the forbidden phrases section):

## Loom Recap

Throughout this session, use the Recap MCP to capture context that helps the user stay oriented:

- `recap.set_goal` - Call once at session start with the problem being solved
- `recap.add_entry` - Call when something significant happens:
  - **decision**: A choice was made (e.g., "Using X approach because Y")
  - **insight**: Something important was learned (e.g., "This module depends on Z")
  - **risk**: A potential problem identified (e.g., "This could break if...")
  - **assumption**: An assumption being made (e.g., "Assuming user wants X not Y")
  - **other**: Anything else worth capturing

Keep entries concise - one clear sentence. The user sees these in the Loom Context Panel.

2. Add Goal Setting to Workflow Start

For issue-prompt.txt - after fetching issue in STEP 0:

Call recap.set_goal with the issue title and a brief summary of the problem.

For pr-prompt.txt - after reading PR:

Call recap.set_goal with the PR title and purpose.

For regular-prompt.txt - after gathering problem statement:

Call recap.set_goal with the user's problem statement.

3. Guidance on When to Log

Don't over-specify exact moments - Claude should use judgment. But provide examples:

• When choosing between approaches → decision
• When discovering a constraint or dependency → insight
• When identifying something that could go wrong → risk
• When making an assumption about requirements → assumption

Acceptance Criteria

• All three prompts updated with Recap MCP instructions
• Goal is set at workflow start
• Instructions are clear but not verbose
• Claude has enough guidance to use judgment on what to log

Related

• Loom Recap MCP Server #346 - Loom Recap MCP Server (provides the tools)
• iloom-vscode#43 - POC Loom Context Panel (displays the data)

[acreeger]

Update: set_goal only for branch mode

Since the issue/PR title is already displayed in the Context Panel header, set_goal is only needed for branch mode (regular-prompt.txt).

Remove from issue-prompt.txt and pr-prompt.txt:

• Don't call recap.set_goal - the title is already visible

Keep for regular-prompt.txt:

• Call recap.set_goal after gathering the user's problem statement
• This is the only mode where there's no title to display

The MCP introduction section should note that set_goal is optional and only used when there's no issue/PR context.

[acreeger]

Complexity Assessment

Classification: TRIVIAL

Metrics:

• Estimated files affected: 3
• Estimated lines of code: 80 (new content to add)
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - well-organized prompt templates with clear sections
• Overall risk level: Low

Reasoning: This is a straightforward documentation update adding Recap MCP instructions to three template files. Based on the issue comment, set_goal was already scoped to only regular-prompt.txt, making this purely additive text updates with no logic changes, no cross-module coordination, and minimal LOC per file.

[acreeger]

Implementation Complete - Issue #347

Summary

Added Loom Recap MCP instructions to all three prompt templates. The issue/PR prompts note that set_goal is optional (since title is already visible), while regular-prompt.txt includes an explicit set_goal call after gathering the problem statement.

Changes Made

• templates/prompts/issue-prompt.txt: Added Recap MCP section after forbidden phrases (set_goal noted as optional)
• templates/prompts/pr-prompt.txt: Added Recap MCP section after forbidden phrases (set_goal noted as optional)
• templates/prompts/regular-prompt.txt: Added Recap MCP section with set_goal as required, plus workflow step to call set_goal

Validation Results

• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

templates/prompts/issue-prompt.txt

Changes: Added Loom Recap section after forbidden phrases (lines 23-42)

• Explains recap.set_goal as optional for issue/PR context
• Documents recap.add_entry with all entry types
• Includes guidance on when to log entries

templates/prompts/pr-prompt.txt

Changes: Added Loom Recap section after forbidden phrases (lines 23-42)

• Same structure as issue-prompt.txt
• set_goal noted as optional

templates/prompts/regular-prompt.txt

Changes: Added Loom Recap section and workflow step

• Recap section (lines 23-42): set_goal described as required for branch mode
• Workflow STEP 0 (line 181): Added step 5 to call recap.set_goal after gathering problem statement
• Renumbered subsequent steps (6, 7)

Dependencies Added

None

[acreeger]

Feedback: Recap entries are too process-focused

The current phase-specific guidance table (lines 46-55) is producing "AI slop" - entries that log internal process rather than useful context.

Examples of bad entries being generated:

• "Skipping enhancement - issue Make il dev-server respect sourceEnvOnStart and consolidate dev server launching #339 already has ~350+ words with clear structure"
• "Classified SIMPLE: 4 files (~120-150 LOC changes), additive consolidation task"
• "Implementation complete: 3 source files + 2 test files modified. All 3001 tests pass"

The problem: The table explicitly tells Claude to log phases skipped and complexity classifications.

Replace the phase-specific guidance table with this:

**What to log (and what NOT to log):**

Only log entries that would be valuable if you had to hand this work off to someone else, or pick it up yourself after a week away.

✅ **DO log:**
- User direction that changed approach (decision): "User chose X over Y because..."
- Architectural choices with trade-offs (decision): "Using singleton pattern to share state across modules"
- Non-obvious discoveries (insight): "shell.ts:48-63 shows the pattern for env loading"
- Identified risks (risk): "This approach may break if concurrent requests occur"
- Assumptions that affect implementation (assumption): "Assuming backwards compatibility not required"

❌ **DON'T log:**
- Internal complexity assessments ("Classified SIMPLE...")
- Phases skipped ("Skipping enhancement...")
- Status updates ("Implementation complete, tests pass")
- Process steps or workflow progress

Also remove/update the inline examples at lines 237 and 342 that show process-focused entries.

[acreeger]

Sharper framing needed - recap is NOT a work log

The previous guidance still resulted in process logs disguised as "insights":

"Issue #339 already has complexity evaluation (SIMPLE) and partial analysis in comments. Enhancement not needed - issue body is thorough (~350 words with clear structure)."

The core problem: Claude thinks the recap is a work log. We need to reframe entirely.

Add this explicit framing to the prompt:

## Loom Recap

**IMPORTANT: The recap is NOT a work log. It's a knowledge capture system for the USER.**

The recap panel is visible to the user in VS Code. They don't care about your internal process. They care about:

1. **Decisions** - Choices that affect the codebase: "Using X pattern because Y"
2. **Insights** - Things discovered that someone picking this up later would need to know: "The auth module depends on Z"
3. **Risks** - Things that could go wrong: "This assumes X, will break if Y"
4. **Assumptions** - Bets you're making: "Assuming backwards compat not needed"

**NEVER log:**
- What phases you skipped
- Complexity classifications  
- Status updates ("implementation complete", "tests pass")
- Anything about your own workflow process

**Self-check before adding:** If your entry mentions "enhancement", "complexity evaluation", "SIMPLE/COMPLEX", "word count", "skipping", or "phase" - it's process noise. Don't add it.

This needs to be front and center in the recap section, not buried in a table.

[acreeger]

iloom Session Summary

Key Themes:

• Recap is a knowledge capture system for users to stay oriented, NOT a process log - this framing must be consistent across prompts and agents
• Examples heavily influence agent behavior - poor examples (low-level decisions, ambiguous risks) lead to noisy outputs
• Changes must cascade to all agents (analyzer, planner, analyze-and-plan), not just prompts, to maintain consistency
• Tool restrictions (allowedTools) require explicit configuration per workflow type for predictable behavior

---

Session Details (click to expand)

Key Insights

• Framing is critical: "NOT a work log" (negative framing) proved more effective than positive descriptions at preventing process-focused entries
• Wording precision matters: "capture key findings to reduce cognitive load" was misread as "findings about how to reduce load" - clearer: "helps users stay oriented without reading all your output"
• Examples shape behavior: Decision example "Creating shared helper instead of duplicating" was too granular and would create noise - substantial examples like "Using WebSocket instead of polling" set better expectations
• Type confusion in examples: Risk example "This assumes the API returns consistent field names" is actually an assumption, not a risk - risks are consequences (e.g., "Removing validation allows malformed input to reach database")
• Cascade principle: Adding recap to prompts isn't enough - analysis and planning agents also generate insights/decisions/risks/assumptions and need the same guidance

Decisions Made

• set_goal availability by workflow: Removed from issue workflow (title provides context), kept for PR workflow (unclear why user opened PR) and regular workflow (no context at all) - implemented via allowedTools configuration in ignite.ts
• Explicit tool filtering: Added allowedTools for regular workflow (was unrestricted) to match issue/PR consistency and predictability
• Agent-level recap integration: Added Loom Recap sections to three agents (analyzer, planner, analyze-and-plan) with role-specific guidance:
  • Analyzer logs: insight, risk
  • Planner logs: decision, assumption
  • Analyze-and-plan logs: all four types with phase separation
• Substantial vs granular threshold: Decisions should be architectural/design choices users care about, not implementation minutiae

Challenges Resolved

• Process noise in recap entries: Original guidance inadvertently encouraged logging "phases skipped" and "complexity classifications" - resolved with explicit "NEVER log" list and self-check filter
• Ambiguous language: Multiple rounds of refinement needed to eliminate misinterpretation:
  • "for handoff" → "to reduce cognitive load" → "helps users stay oriented"
  • "check what's already captured" → "check existing entries to avoid duplicates"
• Tool availability inconsistency: Agent could still call set_goal in issue mode despite prompt saying not to - required code change to allowedTools, not just prompt update
• Example quality: Had to replace multiple examples that would lead to wrong behavior (assumption as risk, low-level decision as substantial choice)

Lessons Learned

• Test examples for misinterpretation: Read examples from agent's perspective - could they be interpreted wrong or lead to unwanted behavior?
• Prompts + agents + code must align: Removing something from prompt text isn't enough if tool is still in allowedTools - need changes at all three levels
• Watch for cascading requirements: When adding cross-cutting functionality (recap MCP), audit all agents that could contribute to that functionality
• Negative framing for restrictions: "NOT a work log" + explicit "NEVER log" list is clearer than describing what it IS
• Screenshots reveal reality: User's screenshot showed "Using SIMPLE workflow" decision being logged - process noise we explicitly tried to prevent, indicating the complexity evaluator agent may also need updating

---

Generated with 🤖❤️ by iloom.ai