Include the recap into the summary generation process

[acreeger]

We should inject the recap json into the summary and change the prompt to use it as a guide. If there are conflicts with the conversation transcript, the dialog/recap entry with the latest timestamp should be used.

Additional note: the recap seems to have a better signal to noise ratio - the guidance that has been used around the use of add_entry in prompt/agents templates might be missing from the summary prompt.

[acreeger]

Enhancement Analysis Complete

Enhancement Analysis

Questions for Reporter

Question	Answer
When you mention "inject the recap json into the summary," should the recap data be passed as structured JSON to the prompt template, or should it be formatted as human-readable text (similar to how compact summaries are currently formatted)?
Should the recap data completely replace the compact summaries from the session transcript, or should both be provided to Claude (with recap taking precedence per your note about timestamps)?
What specific recap fields should be included in the summary prompt? All fields (goal, complexity, entries with type/content, artifacts), or a subset?
The note mentions "guidance that has been used around the use of add_entry in prompt/agents templates might be missing" - should this guidance be copied directly from agent templates into the session-summary prompt, or should new guidance be written specifically for summary generation?

Problem Summary
Session summary generation currently uses only compact summaries from the session transcript, ignoring the recap data (decisions, insights, risks, assumptions) that has better signal-to-noise ratio. This results in lower quality summaries that miss important context captured during the session.

User Impact
Developers and future AI agents reading session summaries miss critical context about decisions, insights, and risks that were captured in the recap but not included in the final summary.

Enhancement Goal
Improve session summary quality by incorporating recap data into the summary generation process. The recap data should guide the summary, and when there are conflicts with the conversation transcript, the most recent timestamp (whether from recap or dialog) should be used.

Next Steps

• Reporter to provide answers to the questions above
• Technical analysis to identify integration points in SessionSummaryService and prompt template
• Implementation planning and execution

---

📋 Complete Context & Details (click to expand)

Current Behavior
The SessionSummaryService.generateSummary() method:

1. Reads metadata to get session ID
2. Loads compact summaries from session transcript using readSessionContext()
3. Passes compact summaries to the session-summary prompt template
4. Invokes Claude headless to generate summary

The recap data stored in ~/.config/iloom-ai/recaps/ (containing goal, complexity, entries, artifacts) is never accessed during this process.

Recap Data Structure
Based on recap-types.ts, the recap contains:

• goal: Original problem statement
• complexity: Task complexity assessment (trivial/simple/complex) with reason
• entries: Array of typed entries (decision, insight, risk, assumption, other) with timestamps
• artifacts: Array of created items (comments, issues, PRs) with URLs and descriptions

Agent Template Guidance
All agent templates (enhancer, analyzer, planner, implementer, reviewer) include a "Loom Recap" section with guidance on:

• When to use recap.add_entry (specific to each agent's role)
• What types to log (decision, insight, risk, assumption)
• What NOT to log (workflow status, completion notices, quality assessments)

This guidance is completely absent from the session-summary-prompt.txt.

Integration Points

1. Data Retrieval: SessionSummaryService would need to read recap data from the recap file (similar to how it reads compact summaries)
2. Prompt Template: session-summary-prompt.txt would need sections to receive and explain recap data usage
3. Conflict Resolution: Logic to handle timestamp comparison between recap entries and dialog events
4. Guidance Transfer: Agent-style recap guidance should be adapted for summary generation context

Technical Considerations

• Recap file path follows pattern: ~/.config/iloom-ai/recaps/{sessionId}.json
• Session ID is already available in SessionSummaryService.generateSummary()
• Recap data structure is well-typed via RecapFile interface
• Current template uses simple variable substitution; recap data would be more complex (arrays, nested objects)

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 3
• Estimated lines of code: 150
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good - all files <400 LOC
• Overall risk level: Low

Reasoning: This feature integrates recap data into session summary generation by reading recap files and injecting them into the summary prompt template. The required changes are isolated to SessionSummaryService.ts (add recap file reading), session-summary-prompt.txt (add recap variables and guidance), and tests. The recap file reading pattern is already demonstrated in RecapCommand, requiring only minor adaptation. No architectural layers need coordination, no breaking changes, and all modified files are well-structured.

[acreeger]

Analysis Phase - Complete

• Review issue context and previous comments
• Research codebase: SessionSummaryService implementation
• Research codebase: Recap data handling patterns
• Research codebase: Prompt template structure
• Document findings in structured format

Executive Summary

Session summary generation currently uses only compact summaries from transcript, ignoring recap data (decisions, insights, risks, assumptions, artifacts) that has better signal-to-noise ratio. The implementation requires reading recap files from ~/.config/iloom-ai/recaps/ and injecting them into the session-summary-prompt.txt template alongside existing compact summaries.

Questions and Key Decisions

Question	Answer
Should recap data be formatted as structured JSON or human-readable text for the prompt?	Use standard recap output as-is (user confirmed)
Should recap replace or supplement compact summaries?	Supplement, not replace (user confirmed)
What recap fields to include?	All fields: goal, complexity, entries, artifacts (user confirmed)
Should recap guidance be copied from agent templates?	Yes, copy guidance to summary prompt (user confirmed)

Impact Summary

• 2 files to modify:
  • src/lib/SessionSummaryService.ts (add recap file reading, ~20-30 lines)
  • templates/prompts/session-summary-prompt.txt (add recap section and guidance, ~40-50 lines)
• 1 test file to update: src/lib/SessionSummaryService.test.ts
• No breaking changes, no cross-cutting concerns

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

Session summaries miss critical context captured during sessions (decisions, insights, risks, assumptions, artifacts) because only compact transcript summaries are used. The recap data has better signal-to-noise ratio as agents are instructed to log only substantive information.

Architectural Context

• SessionSummaryService orchestrates summary generation via Claude headless
• Recap files are stored separately from transcript, keyed by worktree path
• Prompt template uses variable substitution for dynamic content

Edge Cases Identified

• Recap file may not exist (new or legacy looms) - graceful degradation needed
• Recap may be empty (no entries/artifacts) - template should handle conditionally
• Conflict resolution between recap timestamps and dialog - per issue: use latest timestamp

Codebase Research Findings

Affected Area: SessionSummaryService

Entry Point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts:86-101 - Where compact summaries are read and passed to template

Dependencies:

• Uses: PromptTemplateManager.getPrompt(), readSessionContext(), launchClaude()
• Used By: FinishCommand, SummaryCommand

Current Data Flow:

1. Line 88: readSessionContext(worktreePath, sessionId) reads compact summaries
2. Lines 96-101: Template variables passed: ISSUE_NUMBER, BRANCH_NAME, LOOM_TYPE, COMPACT_SUMMARIES
3. Lines 108-112: Claude headless invoked with prompt

Where to Insert Recap Reading:

• After line 88 (compact summaries reading)
• Before line 96 (template loading)

Recap File Reading Pattern

Existing Pattern: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/commands/recap.ts:26-65

slugifyPath(worktreePath) algorithm:
1. Trim trailing slashes
2. Replace path separators (/ or \) with ___ (triple underscore)
3. Replace non-alphanumeric (except _ and -) with -
4. Append .json

Recap Directory: ~/.config/iloom-ai/recaps/

RecapFile Interface (/Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/mcp/recap-types.ts:44-49):

interface RecapFile {
  goal?: string | null
  complexity?: RecapComplexity | null
  entries?: RecapEntry[]
  artifacts?: RecapArtifact[]
}

Prompt Template Structure

File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt

Current Template Variables:

• ISSUE_NUMBER, BRANCH_NAME, LOOM_TYPE
• COMPACT_SUMMARIES (uses {{#IF}} conditional block, lines 9-23)

Template Pattern for Conditional Sections (lines 9-23):

{{#IF COMPACT_SUMMARIES}}
[content with COMPACT_SUMMARIES variable]
{{/IF COMPACT_SUMMARIES}}

New Template Variables Needed:

• RECAP_DATA - formatted recap content (goal, complexity, entries, artifacts)

Recap Guidance in Agent Templates

Source: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/issue-prompt.txt:23-47

Guidance explains recap entry types and what NOT to log. This guidance should be adapted for the summary prompt to help Claude understand how to weight and use recap data.

Key sections to adapt:

• Lines 25-32: Explains entry types (decisions, insights, risks, assumptions)
• Lines 40-46: What NOT to log (process noise)

Affected Files

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts:86-101 - Add recap file reading logic after compact summary reading
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt - Add RECAP_DATA conditional section and guidance
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.test.ts - Add tests for recap reading scenarios

Similar Patterns Found

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/commands/recap.ts:46-65 - Complete pattern for reading recap file with graceful degradation
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt:9-23 - Conditional template block pattern

Integration Points

• slugifyPath algorithm must match exactly (already duplicated in 3 places: MetadataManager, recap.ts, mcp.ts)
• Recap reading should follow same graceful degradation pattern as compact summaries (null on error)

[acreeger]

Implementation Plan for Issue #363

Summary

Integrate recap data (goal, complexity, entries, artifacts) into session summary generation by reading the recap file in SessionSummaryService and injecting it into session-summary-prompt.txt. The recap will supplement (not replace) compact summaries, providing Claude with better signal-to-noise context for generating higher quality summaries.

Questions and Key Decisions

Question	Answer	Rationale
Should recap be JSON or human-readable in prompt?	Human-readable (standard recap output)	User confirmed; markdown formatting deferred to #384
Replace or supplement compact summaries?	Supplement	User confirmed; both sources provide complementary value
Which recap fields to include?	All: goal, complexity, entries, artifacts	User confirmed
Copy recap guidance from agent templates?	Yes	User confirmed; helps Claude understand entry types

High-Level Execution Phases

1. Add recap file reading: Read recap JSON file in SessionSummaryService.generateSummary() after compact summaries reading
2. Format recap data: Convert recap JSON to human-readable string using pattern from RecapCommand
3. Update prompt template: Add RECAP_DATA conditional section with guidance adapted from agent templates
4. Add tests: Test recap reading with scenarios for missing files, empty data, and full content

Quick Stats

• 0 files for deletion
• 2 files to modify:
  • src/lib/SessionSummaryService.ts (~30 lines)
  • templates/prompts/session-summary-prompt.txt (~45 lines)
• 1 test file to update: src/lib/SessionSummaryService.test.ts
• Dependencies: None (uses existing fs-extra)
• Estimated complexity: Simple

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Create

Test File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.test.ts (MODIFY)

Purpose: Verify recap reading and template injection behavior

Click to expand complete test structure (35 lines)

describe('recap integration', () => {
  it('should include recap data in prompt when recap file exists', async () => {
    // Mock fs-extra to return recap file content
    // Verify template receives RECAP_DATA variable with formatted content
  })

  it('should work without recap file (graceful degradation)', async () => {
    // Mock fs-extra to throw ENOENT
    // Verify template receives empty RECAP_DATA, no errors thrown
  })

  it('should handle empty recap file', async () => {
    // Mock recap with null goal, null complexity, empty entries/artifacts
    // Verify template receives minimal RECAP_DATA or empty string
  })

  it('should format recap entries correctly', async () => {
    // Mock recap with entries: decision, insight, risk, assumption
    // Verify formatted output includes [type] prefix per entry
  })

  it('should format recap artifacts correctly', async () => {
    // Mock recap with artifacts
    // Verify formatted output includes [type] prefix and URL per artifact
  })

  it('should include goal and complexity when present', async () => {
    // Mock recap with goal and complexity
    // Verify formatted output includes both
  })
})

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts

Add imports at top (after line 19):

import path from 'path'
import os from 'os'
import fs from 'fs-extra'
import type { RecapFile, RecapEntry, RecapArtifact, RecapComplexity } from '../mcp/recap-types.js'

Add helper functions before the class (around line 40):

const RECAPS_DIR = path.join(os.homedir(), '.config', 'iloom-ai', 'recaps')

// slugifyPath: copy from RecapCommand (same algorithm as MetadataManager)
function slugifyPath(loomPath: string): string {
  let slug = loomPath.replace(/[/\\]+$/, '')
  slug = slug.replace(/[/\\]/g, '___')
  slug = slug.replace(/[^a-zA-Z0-9_-]/g, '-')
  return `${slug}.json`
}

// Format recap to human-readable string (same output format as RecapCommand)
function formatRecapData(recap: RecapFile): string {
  // Build lines array, join with newlines
  // Include goal, complexity, entries, artifacts following RecapCommand pattern
}

Add readRecapFile method to class (after generateSummary method, around line 210):

private async readRecapFile(worktreePath: string): Promise<string | null> {
  // Build file path using slugifyPath
  // Read and parse JSON with graceful degradation (return null on error)
  // Return formatted string using formatRecapData
}

Modify generateSummary method (lines 168-183):

• After line 175 (compact summaries debug log), add recap file reading
• Line 178: Add RECAP_DATA to template variables

Modify generateAndPostSummary method (lines 86-101):

• After line 93 (compact summaries debug log), add recap file reading
• Line 96-101: Add RECAP_DATA to template variables

2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt

Add RECAP_DATA section after COMPACT_SUMMARIES section (after line 23):

Click to expand template additions (40 lines)

{{#IF RECAP_DATA}}

## Session Recap - Key Context

**CRITICAL: The recap below contains high-signal context captured during this session.** Unlike the conversation transcript which includes all dialog, the recap contains only substantive information that was deliberately logged:

- **Decisions**: Choices that affect the codebase with rationale
- **Insights**: Discoveries that future developers need to know
- **Risks**: Things that could go wrong
- **Assumptions**: Bets being made about the implementation

When there are conflicts between the recap and conversation transcript, give weight to the most recent timestamp.

------- BEGIN SESSION RECAP ------

RECAP_DATA

------- END SESSION RECAP ------
{{/IF RECAP_DATA}}

Modify "Your Task" section (line 27) to reference recap:

• Update the reflection instruction to include recap data alongside compact summaries

Add to validation checklist (around line 81):

{{#IF RECAP_DATA}}* Did you use the decisions, insights, risks, and assumptions from the "Session Recap" section?{{/IF RECAP_DATA}}

Detailed Execution Order

Phase 1: Add Recap Reading Infrastructure

1. Add imports to SessionSummaryService.ts:19 -> Verify: TypeScript compiles
2. Add RECAPS_DIR constant and slugifyPath function -> Verify: Matches RecapCommand implementation
3. Add formatRecapData helper function -> Verify: Produces same format as RecapCommand lines 73-89

Phase 2: Integrate Recap Reading into Service

1. Add readRecapFile private method -> Verify: Returns string | null with graceful degradation
2. Modify generateSummary to call readRecapFile after line 175 -> Verify: Debug log shows recap data
3. Add RECAP_DATA to template variables at line 178 -> Verify: Template receives variable
4. Repeat for generateAndPostSummary method (lines 88-101) -> Verify: Both methods include recap

Phase 3: Update Prompt Template

1. Add RECAP_DATA conditional section after line 23 -> Verify: Template parses correctly
2. Add recap guidance explaining entry types -> Verify: Matches agent template guidance style
3. Update "Your Task" section to reference recap -> Verify: Instructions are clear
4. Add validation checklist item -> Verify: Reminder for Claude to use recap

Phase 4: Add Tests

1. Add fs-extra mock to test file -> Verify: Mock controls file reading
2. Add test for recap file present scenario -> Verify: RECAP_DATA included in template call
3. Add test for recap file missing scenario -> Verify: Graceful degradation, no errors
4. Add test for empty recap scenario -> Verify: Handles null/empty fields
5. Add test for recap formatting -> Verify: Output matches expected format

Dependencies and Configuration

None - uses existing fs-extra dependency already in project.

[acreeger]

Implementation Complete - Issue #363

Summary

Integrated recap data (goal, complexity, entries, artifacts) into session summary generation. The recap is now read from ~/.config/iloom-ai/recaps/ and injected into the session-summary prompt template, supplementing the existing compact summaries with high-signal context.

Changes Made

• SessionSummaryService.ts: Added recap file reading with graceful degradation and formatting logic
• session-summary-prompt.txt: Added RECAP_DATA conditional section with guidance on entry types
• PromptTemplateManager.ts: Added RECAP_DATA to TemplateVariables interface
• SessionSummaryService.test.ts: Added 8 new tests for recap integration scenarios

Validation Results

• Tests: 3029 passed (0 failed)
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

src/lib/SessionSummaryService.ts

Changes: Added recap file reading infrastructure and integration

• Added imports: path, os, fs-extra, RecapFile type
• Added RECAPS_DIR constant and slugifyPath() helper (matching RecapCommand algorithm)
• Added formatRecapData() to convert recap JSON to human-readable string
• Added readRecapFile() async function with graceful degradation
• Modified generateAndPostSummary() and generateSummary() to read and pass RECAP_DATA

src/lib/PromptTemplateManager.ts

Changes: Added RECAP_DATA to template variables interface

• Added RECAP_DATA?: string to TemplateVariables interface

templates/prompts/session-summary-prompt.txt

Changes: Added RECAP_DATA conditional section with guidance

• Added {{#IF RECAP_DATA}} section after COMPACT_SUMMARIES
• Added explanation of recap entry types (decisions, insights, risks, assumptions)
• Updated "Your Task" section to reference recap data
• Added recap validation item to checklist

src/lib/SessionSummaryService.test.ts

Changes: Added comprehensive recap integration tests

• Added fs-extra mock
• Updated existing test assertions to include RECAP_DATA
• Added 8 new tests covering: recap present, entry formatting, artifact formatting, goal/complexity, graceful degradation, empty file, read errors, invalid JSON

Test Coverage Added

• SessionSummaryService.test.ts: 8 new tests in "recap integration" describe block

Dependencies Added

None - uses existing fs-extra dependency.

[acreeger]

Analysis Phase - Post-Rebase Integration

• Review new formatRecapMarkdown in src/utils/recap-formatter.ts
• Analyze current formatRecapData in SessionSummaryService.ts
• Identify type compatibility issues between RecapFile and RecapOutput
• Document required changes for integration

Executive Summary

After rebasing on #384 (commit 98f58c2), the codebase now has a shared formatRecapMarkdown utility in src/utils/recap-formatter.ts. The current SessionSummaryService.ts has its own formatRecapData function (lines 47-73) that should be replaced with this shared utility. However, there is a type incompatibility between RecapFile (used by SessionSummaryService) and RecapOutput (required by formatRecapMarkdown).

Questions and Key Decisions

Question	Answer
Should we adapt SessionSummaryService to use RecapOutput or modify formatRecapMarkdown to accept RecapFile?	Adapt SessionSummaryService - it already reads the file and can construct RecapOutput inline (see RecapCommand.ts:62-66 for pattern)

HIGH/CRITICAL Risks

• Type Incompatibility: formatRecapMarkdown requires RecapOutput (with required filePath field), but SessionSummaryService.readRecapFile works with RecapFile (all optional fields). Direct replacement would cause TypeScript compilation errors.

Impact Summary

• 1 file to modify: src/lib/SessionSummaryService.ts
  • Remove local formatRecapData function (lines 47-73, 27 lines)
  • Modify readRecapFile to construct RecapOutput with filePath and return formatted markdown string
  • Add import for formatRecapMarkdown
• No breaking changes, no test modifications expected

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

The rebase on #384 introduced a shared formatRecapMarkdown utility in src/utils/recap-formatter.ts. This creates code duplication with the existing formatRecapData function in SessionSummaryService.ts. The shared utility should be used instead.

Architectural Context

• RecapCommand (line 74) already uses formatRecapMarkdown after rebasing
• SessionSummaryService still has its own implementation that predates the rebase
• Both produce markdown, but the shared utility produces richer markdown (headers, bold, links for artifacts)

Edge Cases Identified

• Empty recap: Both implementations handle gracefully, but output differs (shared utility includes headers like "## Entries (0)")
• Missing filePath: SessionSummaryService reads file but discards the path; formatRecapMarkdown requires it in output

Codebase Research Findings

Type Definitions: RecapFile vs RecapOutput

RecapFile (/Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/mcp/recap-types.ts:44-49):

interface RecapFile {
  goal?: string | null           // optional
  complexity?: RecapComplexity | null  // optional
  entries?: RecapEntry[]         // optional
  artifacts?: RecapArtifact[]    // optional
}

RecapOutput (/Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/mcp/recap-types.ts:52-58):

interface RecapOutput {
  filePath: string              // REQUIRED - key difference
  goal: string | null           // required (nullable)
  complexity: RecapComplexity | null  // required (nullable)
  entries: RecapEntry[]         // required (empty array if none)
  artifacts: RecapArtifact[]    // required (empty array if none)
}

Key Difference: RecapOutput has required fields with explicit null/empty defaults and includes filePath. RecapFile has all optional fields (used for JSON deserialization).

Current Implementation: SessionSummaryService.formatRecapData (lines 47-73)

Output Format (plain text, not markdown):

Goal: (not set)
Complexity: complex - reason

Entries: 2
  [decision] content here
  [insight] content here

Artifacts: 1
  [comment] description - https://url

New Shared Implementation: formatRecapMarkdown (recap-formatter.ts:61-70)

Output Format (rich markdown):

# Loom Recap

**File:** `/path/to/recap.json`

## Goal
(not set)

## Complexity
**complex** - reason

## Entries (2)
- **[decision]** content here
- **[insight]** content here

## Artifacts (1)
- **[comment](https://url)** description

Conversion Pattern: RecapFile to RecapOutput

Already implemented in RecapCommand (/Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/commands/recap.ts:62-66):

const goal = recap.goal ?? null
const complexity = recap.complexity ?? null
const entries = recap.entries ?? []
const artifacts = recap.artifacts ?? []
const result: RecapOutput = { filePath, goal, complexity, entries, artifacts }

This pattern should be reused in SessionSummaryService.readRecapFile.

Affected Files

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts:14 - Add import for formatRecapMarkdown
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts:47-73 - Remove local formatRecapData function
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts:79-102 - Modify readRecapFile to construct RecapOutput and call formatRecapMarkdown

Similar Patterns Found

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/commands/recap.ts:62-74 - Same RecapFile to RecapOutput conversion with formatRecapMarkdown call

Output Format Difference

The shared formatRecapMarkdown produces richer markdown output than the current formatRecapData. This is an improvement, not a breaking change - the session summary prompt will receive better-formatted context.

Integration Points

• SessionSummaryService.readRecapFile() is called from:
  • generateAndPostSummary() at line 179
  • generateSummary() at line 270
• Return value is passed to template as RECAP_DATA variable
• No other callers exist

[acreeger]

Implementation Plan for Issue #363 - Post-Rebase Integration

Summary

Integrate the shared formatRecapMarkdown utility (from PR #384) into SessionSummaryService by removing the duplicate formatRecapData function and adapting the recap reading logic to construct RecapOutput (which has required fields) from the deserialized RecapFile (which has optional fields). This follows the same conversion pattern already used in RecapCommand.ts.

Questions and Key Decisions

Question	Answer	Rationale
Adapt SessionSummaryService or modify formatRecapMarkdown?	Adapt SessionSummaryService	Follow existing pattern in RecapCommand.ts lines 61-66; keeps shared utility clean

High-Level Execution Phases

1. Add import: Import formatRecapMarkdown from src/utils/recap-formatter.ts
2. Remove duplicate function: Delete local formatRecapData function (27 lines)
3. Modify readRecapFile: Construct RecapOutput with filePath field and call shared formatter
4. Update tests: Adjust test assertions to match new markdown output format

Quick Stats

• 0 files for deletion
• 1 file to modify: src/lib/SessionSummaryService.ts
• 1 test file to modify: src/lib/SessionSummaryService.test.ts
• Dependencies: None
• Estimated complexity: Simple

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Modify

Test File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.test.ts (MODIFY)

Purpose: Update assertions to match new markdown format from formatRecapMarkdown

The current tests expect plain text format:

Goal: Fix the authentication bug
Complexity: simple - Straightforward fix
[decision] Use OAuth2...
[insight] The token...
[comment] Progress update

The new formatRecapMarkdown produces markdown format:

# Loom Recap

**File:** `/path/to/recap.json`

## Goal
Fix the authentication bug

## Complexity
**simple** - Straightforward fix

## Entries (2)
- **[decision]** Use OAuth2...
- **[insight]** The token...

## Artifacts (1)
- **[comment](https://...) Progress update

Click to expand test changes (20 lines)

// Line 561: Change from '[decision]' to '**[decision]**'
RECAP_DATA: expect.stringContaining('**[decision]** Use OAuth2 instead of basic auth'),

// Line 564: Change from '[insight]' to '**[insight]**'
RECAP_DATA: expect.stringContaining('**[insight]** The token was expiring too early'),

// Line 575: Change from '[comment] Progress update' to artifact format with link
RECAP_DATA: expect.stringContaining('**[comment](https://github.com/org/repo/issues/123#issuecomment-1)** Progress update'),

// Line 586: Change from 'Goal: Fix...' to markdown header
RECAP_DATA: expect.stringContaining('## Goal'),
RECAP_DATA: expect.stringContaining('Fix the authentication bug'),

// Line 589: Change from 'simple - Straightforward fix' to bold format
RECAP_DATA: expect.stringContaining('**simple** - Straightforward fix'),

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.ts

Change 1: Add import (line 14)

// After line 23 (import type { RecapFile }), add:
import { formatRecapMarkdown } from '../utils/recap-formatter.js'
import type { RecapOutput } from '../mcp/recap-types.js'

Change 2: Remove formatRecapData function (lines 43-73)
Delete the entire formatRecapData function (27 lines including JSDoc comment).

Change 3: Modify readRecapFile function (lines 79-102)
Replace the current implementation to:

1. Construct RecapOutput with filePath field (not just RecapFile)
2. Call formatRecapMarkdown instead of formatRecapData

Click to expand readRecapFile changes (25 lines)

async function readRecapFile(worktreePath: string): Promise<string | null> {
  try {
    const filePath = path.join(RECAPS_DIR, slugifyPath(worktreePath))
    if (await fs.pathExists(filePath)) {
      const content = await fs.readFile(filePath, 'utf8')
      const recap = JSON.parse(content) as RecapFile

      // Check if recap has any meaningful content
      const hasGoal = recap.goal !== null && recap.goal !== undefined
      const hasComplexity = recap.complexity !== null && recap.complexity !== undefined
      const hasEntries = Array.isArray(recap.entries) && recap.entries.length > 0
      const hasArtifacts = Array.isArray(recap.artifacts) && recap.artifacts.length > 0
      const hasContent = hasGoal || hasComplexity || hasEntries || hasArtifacts

      if (hasContent) {
        // Convert RecapFile (optional fields) to RecapOutput (required fields)
        // Same pattern as RecapCommand.ts:61-66
        const recapOutput: RecapOutput = {
          filePath,
          goal: recap.goal ?? null,
          complexity: recap.complexity ?? null,
          entries: recap.entries ?? [],
          artifacts: recap.artifacts ?? [],
        }
        return formatRecapMarkdown(recapOutput)
      }
    }
    return null
  } catch {
    return null
  }
}

2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/src/lib/SessionSummaryService.test.ts

Change: Update recap integration test assertions (lines 549-591)

Update assertions to match markdown format produced by formatRecapMarkdown:

• Line 550: expect.stringContaining('Fix the authentication bug') - still works (content unchanged)
• Line 561: Change to expect.stringContaining('**[decision]** Use OAuth2 instead of basic auth')
• Line 564: Change to expect.stringContaining('**[insight]** The token was expiring too early')
• Line 575: Change to expect.stringContaining('**[comment](https://github.com/org/repo/issues/123#issuecomment-1)** Progress update')
• Lines 586-589: Change to check for markdown format:
  • expect.stringContaining('## Goal')
  • expect.stringContaining('**simple** - Straightforward fix')

Detailed Execution Order

Phase 1: Update SessionSummaryService.ts

1. Add import for formatRecapMarkdown at line 24 -> Verify: TypeScript compiles
2. Add import for RecapOutput type at line 24 -> Verify: TypeScript compiles
3. Delete formatRecapData function (lines 43-73, 31 lines total) -> Verify: No references remain
4. Modify readRecapFile to construct RecapOutput and call formatRecapMarkdown -> Verify: TypeScript compiles

Phase 2: Update Tests

1. Update test at line 561 for decision format -> Verify: Test passes
2. Update test at line 564 for insight format -> Verify: Test passes
3. Update test at line 575 for artifact format -> Verify: Test passes
4. Update tests at lines 586-589 for goal/complexity format -> Verify: Test passes

Phase 3: Verify

1. Run pnpm test -> Verify: All tests pass
2. Run pnpm build -> Verify: Build succeeds

Dependencies and Configuration

None - uses existing imports and shared utility already in codebase.

[acreeger]

Implementation Complete - Issue #363 (Post-Rebase Integration)

Summary

Integrated the shared formatRecapMarkdown utility from PR #384 into SessionSummaryService by removing the duplicate formatRecapData function and adapting the recap reading logic to construct RecapOutput objects required by the shared formatter.

Changes Made

• SessionSummaryService.ts: Added import for formatRecapMarkdown and RecapOutput type, removed local formatRecapData function (27 lines), modified readRecapFile to construct RecapOutput and call shared formatter
• SessionSummaryService.test.ts: Updated 4 test assertions to match new markdown format (**[type]** entries, **[type](url)** artifacts, ## Goal headers, **level** complexity)

Validation Results

• Tests: 3041 passed (0 failed)
• Typecheck: Passed
• Lint: Passed
• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

src/lib/SessionSummaryService.ts

Changes: Integrated shared recap-formatter utility

• Added import for formatRecapMarkdown from ../utils/recap-formatter.js
• Added import for RecapOutput type from ../mcp/recap-types.js
• Deleted local formatRecapData function (lines 43-73, 27 lines)
• Modified readRecapFile to construct RecapOutput with filePath field and call formatRecapMarkdown

src/lib/SessionSummaryService.test.ts

Changes: Updated test assertions for new markdown format

• Line 561: Changed [decision] to **[decision]**
• Line 564: Changed [insight] to **[insight]**
• Line 575: Changed [comment] Progress update to **[comment](url)** Progress update
• Lines 585-593: Updated goal/complexity checks to use markdown format (## Goal, **simple**)

Test Coverage

No new tests needed - existing tests updated to match new output format.

Dependencies Added

None - uses existing shared utility from PR #384.

[acreeger]

Analysis: add_entry Guidance Comparison

Executive Summary

The agent templates contain specific anti-slop guidance for add_entry usage that is completely absent from session-summary-prompt.txt. This gap likely causes the summary generation to include process noise in "Lessons Learned" sections.

Key Findings

Agent Template Guidance (issue-prompt.txt lines 23-47, identical in pr-prompt.txt and regular-prompt.txt)

1. Framing - The "Why It Matters" Statement:

"The recap is NOT a work log. It's a knowledge capture system for the USER."
"They don't care about your internal process."

2. Positive Examples (What TO Log) - Concrete with Technical Flavor:

• Decisions: "Using X pattern because Y"
• Insights: "The auth module depends on Z"
• Risks: "This assumes X, will break if Y"
• Assumptions: "Assuming backwards compat not needed"

3. Explicit NEVER Log List:

• What phases you skipped
• Complexity classifications
• Status updates ("implementation complete", "tests pass")
• Anything about your own workflow process

4. Self-Check Rule (The Anti-Slop Filter):

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

Session Summary Prompt Guidance (session-summary-prompt.txt lines 45-53)

The current guidance for summary generation only provides generic section headers:

1. **Key Insights**: What important learnings emerged during implementation?
2. **Decisions Made**: What significant technical decisions were made and why?
3. **Challenges Encountered**: What obstacles were faced and how were they resolved?
4. **Mistakes and Corrections**: What mistakes were made and what was learned from them?

Missing:

• The "NOT a work log" framing
• Concrete examples of good vs bad content
• The explicit NEVER list
• The self-check anti-slop filter
• Any mention that entries should be user-focused, not process-focused

Gap Analysis

Guidance Element	Agent Templates	Session Summary Prompt
"NOT a work log" framing	Present	Missing
Concrete positive examples	Present (4 examples)	Missing
NEVER log list	Present (4 items)	Missing
Self-check filter (keyword list)	Present	Missing
User-focused perspective	Present	Missing

---

Complete Technical Reference (click to expand)

File Locations

• Agent templates with guidance:

  • /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/issue-prompt.txt:23-47
  • /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/pr-prompt.txt:23-47
  • /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/regular-prompt.txt:23-47

• Session summary prompt:

  • /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt:45-53

Exact Text Comparisons

Agent Template Loom Recap Section (lines 23-47)

## 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"

Use these Recap MCP tools:
- `recap.set_complexity` - Call when complexity is confirmed at ROUTING DECISION POINT (trivial/simple/complex)
- `recap.get_recap` - Call before adding entries to check what's already captured
- `recap.add_entry` - Call with type (decision/insight/risk/assumption) and concise content
- `recap.add_artifact` - After creating/updating comments, issues, or PRs, log them with type, primaryUrl, and description.

**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.

Session Summary Prompt "Your Task" Section (lines 45-53)

## Your Task

Reflect on THIS conversation ... and generate a concise summary focused on:

1. **Key Insights**: What important learnings emerged during implementation?
2. **Decisions Made**: What significant technical decisions were made and why?
3. **Challenges Encountered**: What obstacles were faced and how were they resolved?
4. **Mistakes and Corrections**: What mistakes were made and what was learned from them?

Variant Differences

The agent templates have slight variations:

• issue-prompt.txt: Uses recap.set_complexity at ROUTING DECISION POINT
• pr-prompt.txt: Uses recap.set_goal for PR context, no set_complexity
• regular-prompt.txt: Uses recap.set_goal for user problem statement, set_complexity at ROUTING DECISION POINT

All three share identical NEVER log and self-check guidance.

Agent-Specific Recap Guidance (Analyzer)

The analyzer agent (iloom-issue-analyzer.md:13-24) has a more specialized version:

**Log these:**
- **insight**: Technical discoveries - "Auth module depends on session middleware being initialized first"
- **risk**: Things that could go wrong - "Removing this function breaks the CLI's --verbose flag"

**Never log** workflow status, complexity classifications, or what phases you skipped.

This is more concise but carries the same "technical content, not process" distinction.

Session Summary Output Structure

The session summary output format (lines 67-92) includes a "Lessons Learned" section:

### Lessons Learned
- [What could be done better next time]

This is the section most susceptible to process noise because:

1. No guidance on what makes a good lesson vs process noise
2. No examples provided
3. Naturally invites reflection on the workflow itself

[acreeger]

Implementation Plan for Issue #363 - Anti-Slop Guidance

Summary

Add anti-slop guidance to session-summary-prompt.txt that prevents process noise (workflow steps, git commands, build commands) and focuses on technical insights. The guidance will be adapted from agent templates (issue-prompt.txt lines 23-47) and include: "NOT a work log" framing, concrete examples of good vs bad content, explicit NEVER list, and self-check filter. The "Lessons Learned" section will be reframed to avoid inviting process reflection.

Questions and Key Decisions

Question	Answer	Rationale
Rename "Lessons Learned" or add clarifying guidance?	Rename to "Technical Takeaways" AND add clarifying examples	The current name naturally invites process reflection; both changes reinforce the user-focused framing
Where to place anti-slop guidance?	After line 52 (after the 4 focus areas), before "## Output Format"	Keeps it close to where content decisions are made, before output structure is defined
Adapt agent template guidance verbatim or rewrite for summary context?	Adapt for summary context - change from "recap entries" to "summary content"	The agent guidance is about add_entry calls; summary guidance is about what to write in the summary itself

High-Level Execution Phases

1. Add anti-slop guidance section: Insert new section after line 52 with "NOT a work log" framing, concrete examples, and NEVER list
2. Rename "Lessons Learned": Change to "Technical Takeaways" (line 89) with example content
3. Add self-check validation: Add keyword filter to validation checklist at end
4. Update example content: Modify example bullet points in output format to show good vs bad patterns

Quick Stats

• 0 files for deletion
• 1 file to modify: templates/prompts/session-summary-prompt.txt
• 0 new files to create
• Dependencies: None
• Estimated complexity: Simple

---

Complete Implementation Guide (click to expand for step-by-step details)

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-363__recap-summary/templates/prompts/session-summary-prompt.txt

Change 1: Add anti-slop guidance section (after line 52, before "## Output Format")

Insert new section with anti-slop framing adapted from agent templates:

Click to expand new section content (35 lines)

## Content Quality Guidelines

**CRITICAL: This summary is NOT a work log. It's knowledge capture for future developers and AI agents.**

The reader doesn't care about your internal process. They care about:

1. **Technical discoveries** - "The auth module depends on session middleware being initialized first"
2. **Design rationale** - "Chose retry pattern over circuit breaker because failure rate is low"
3. **Gotchas and edge cases** - "Empty arrays must be handled specially in the validator"
4. **Codebase knowledge** - "The legacy endpoint can't be removed until v3 migration completes"

**NEVER include in your summary:**
- Workflow phases you executed or skipped (enhancement, analysis, planning, implementation)
- Complexity classifications (TRIVIAL, SIMPLE, COMPLEX)
- Status updates ("tests pass", "build succeeded", "implementation complete")
- Git operations (commits made, branches created, rebases performed)
- Process reflection ("could have planned better", "spent time on X")
- Tool usage ("used grep to find", "ran the linter")

**Self-check before including content:** If it mentions "phase", "workflow", "SIMPLE/COMPLEX", "commit", "tests pass", "build", "lint", or describes what YOU did rather than what was LEARNED - it's process noise. Don't include it.

**Good vs Bad Examples:**

| BAD (process noise) | GOOD (technical insight) |
|---------------------|--------------------------|
| "Ran tests and they passed after fixing" | "The validator silently accepts null, causing downstream errors" |
| "Used the SIMPLE workflow since only 2 files changed" | "Config changes require server restart, no hot-reload support" |
| "Committed changes in 3 separate commits" | "Database constraints prevent orphaned records, no cleanup needed" |
| "Could have skipped the analysis phase" | "The caching layer assumes immutable data; TTL won't help for this use case" |

Change 2: Rename "Lessons Learned" section (line 89-90)

Current:

### Lessons Learned
- [What could be done better next time]

New:

### Technical Takeaways
- [Codebase knowledge or gotchas that would help someone working on similar tasks]

Change 3: Add self-check to validation checklist (after line 102)

Add new validation item:

* Did you avoid process noise? (No mentions of: workflow phases, complexity classifications, git commands, test/build results, or descriptions of what you DID vs what was LEARNED)

Change 4: Update "Challenges Resolved" section guidance (line 86-87)

Current:

### Challenges Resolved
- [Challenge and resolution]

New:

### Challenges Resolved
- [Technical challenge and the insight gained, NOT "ran X command" or "tried Y approach"]

Detailed Execution Order

Phase 1: Add Anti-Slop Guidance Section

1. Insert new section after line 52 (after "4. Mistakes and Corrections...") -> Verify: Section appears before "## Output Format"
2. Content includes: "NOT a work log" framing, 4 good content examples, 6-item NEVER list, self-check keywords, good/bad comparison table

Phase 2: Update Output Format Example

1. Line 89-90: Change "Lessons Learned" to "Technical Takeaways" -> Verify: Example shows new section name
2. Line 90: Update placeholder from "[What could be done better next time]" to "[Codebase knowledge or gotchas that would help someone working on similar tasks]"
3. Lines 86-87: Update "Challenges Resolved" placeholder to clarify technical focus

Phase 3: Add Validation Item

1. After line 102: Add process noise self-check validation item -> Verify: Appears in validation checklist
2. Ensure it uses conditional formatting matching other items

Dependencies and Configuration

None - this is a prompt template modification only.

[acreeger]

Implementation Complete - Issue #363 (Anti-Slop Guidance)

Summary

Added anti-slop guidance to session-summary-prompt.txt to prevent process noise (workflow steps, git commands, build commands) and focus on technical insights. Kept "Lessons Learned" section name per user request, but added specific guidance distinguishing good vs bad content.

Changes Made

• session-summary-prompt.txt: Added new "Content Quality Guidelines" section with "NOT a work log" framing, concrete examples, NEVER list, self-check filter, good/bad comparison table, specific guidance for Lessons Learned section, and validation checklist item

Validation Results

• Build: Passed

---

Detailed Changes by File (click to expand)

Files Modified

templates/prompts/session-summary-prompt.txt

Changes: Added comprehensive anti-slop guidance

1. New "Content Quality Guidelines" section (after line 52, before "Output Format"):

   • "NOT a work log" framing with user-focused perspective
   • 4 examples of good technical content (discoveries, rationale, gotchas, codebase knowledge)
   • 6-item NEVER list (workflow phases, complexity classifications, status updates, git operations, process reflection, tool usage)
   • Self-check filter with specific keywords to avoid
   • Good vs Bad comparison table with 4 examples

2. Updated "Challenges Resolved" placeholder (line 116-117):

   • Changed from generic "[Challenge and resolution]"
   • To: "[Technical challenge and the insight gained, NOT 'ran X command' or 'tried Y approach']"

3. Added specific guidance for "Lessons Learned" section (lines 119-122):

   • Kept section name (valuable for reinforcement learning per user request)
   • Added clear guidance: "[Technical patterns discovered, codebase gotchas, design principles, reusable approaches]"
   • Added GOOD example: "The ORM's lazy loading causes N+1 queries when iterating collections"
   • Added BAD example: "Should have run tests earlier" / "The build command is pnpm build"

4. Added validation checklist item (line 135):

   • "Did you avoid process noise? (No mentions of: workflow phases, complexity classifications, git commands, test/build results, or descriptions of what you DID vs what was LEARNED)"

Dependencies Added

None