Initial commit

skills/mem-search/operations/formatting.md

@@ -0,0 +1,403 @@
+# Response Formatting Guidelines
+
+How to present search results to users for maximum clarity and usefulness.
+
+## General Principles
+
+1. **Progressive disclosure** - Show index results first, full details on demand
+2. **Visual hierarchy** - Use emojis, bold, and structure for scannability
+3. **Context-aware** - Tailor presentation to user's question
+4. **Actionable** - Include IDs for follow-up queries
+5. **Token-efficient** - Balance detail with token budget
+
+---
+
+## Format: Index Results
+
+**When to use:** First response to searches, overviews, multiple results
+
+**Structure:**
+```markdown
+Found {count} results for "{query}":
+
+{emoji} **#{id}** {title}
+   > {subtitle}
+   > {date} • {project}
+```
+
+**Example:**
+```markdown
+Found 5 results for "authentication":
+
+🟣 **#1234** Implemented JWT authentication
+   > Added token-based auth with refresh tokens
+   > Nov 9, 2024 • api-server
+
+🔴 **#1235** Fixed token expiration edge case
+   > Handled race condition in refresh flow
+   > Nov 9, 2024 • api-server
+```
+
+**Type Emojis:**
+- 🔴 bugfix
+- 🟣 feature
+- 🔄 refactor
+- 🔵 discovery
+- 🧠 decision
+- ✅ change
+- 🎯 session
+- 💬 prompt
+
+**What to include:**
+- ✅ ID (for follow-up)
+- ✅ Type emoji
+- ✅ Title
+- ✅ Subtitle (if available)
+- ✅ Date (human-readable)
+- ✅ Project name
+- ❌ Don't include full narrative/facts/files in index format
+
+---
+
+## Format: Full Results
+
+**When to use:** User requests details, specific items selected from index
+
+**Structure:**
+```markdown
+## {emoji} {type} #{id}: {title}
+
+**Summary:** {subtitle}
+
+**What happened:**
+{narrative}
+
+**Key Facts:**
+- {fact1}
+- {fact2}
+
+**Files modified:**
+- {file1}
+- {file2}
+
+**Concepts:** {concepts}
+
+**Date:** {human_readable_date}
+**Project:** {project}
+```
+
+**Example:**
+```markdown
+## 🟣 Feature #1234: Implemented JWT authentication
+
+**Summary:** Added token-based auth with refresh tokens
+
+**What happened:**
+Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm and proper key rotation infrastructure.
+
+**Key Facts:**
+- Access tokens use 15-minute expiration
+- Refresh tokens stored in httpOnly cookies
+- RS256 algorithm with key rotation support
+- Token refresh endpoint handles race conditions gracefully
+
+**Files modified:**
+- src/auth/jwt.ts (created)
+- src/auth/refresh.ts (created)
+- src/middleware/auth.ts (modified)
+
+**Concepts:** how-it-works, pattern
+
+**Date:** November 9, 2024 at 2:55 PM
+**Project:** api-server
+```
+
+**What to include:**
+- ✅ Full title with emoji and ID
+- ✅ Summary/subtitle
+- ✅ Complete narrative
+- ✅ All key facts
+- ✅ All files (with status: created/modified/deleted)
+- ✅ Concepts/tags
+- ✅ Precise timestamp
+- ✅ Project name
+
+---
+
+## Format: Timeline Results
+
+**When to use:** Temporal investigations, "what was happening" questions
+
+**Structure:**
+```markdown
+## Timeline: {anchor_description}
+
+### Before ({count} records)
+
+**{time}** - {emoji} {type} #{id}: {title}
+**{time}** - {emoji} {type} #{id}: {title}
+
+### ⭐ Anchor Point ({time})
+{emoji} **{type} #{id}**: {title}
+
+### After ({count} records)
+
+**{time}** - {emoji} {type} #{id}: {title}
+**{time}** - {emoji} {type} #{id}: {title}
+```
+
+**Example:**
+```markdown
+## Timeline: Deployment
+
+### Before (10 records)
+
+**2:30 PM** - 🟣 #1230: Prepared deployment scripts
+**2:45 PM** - 🔄 #1232: Updated configuration files
+**2:50 PM** - 💬 User asked: "Are we ready to deploy?"
+
+### ⭐ Anchor Point (2:55 PM)
+🎯 **Session #545**: Deployed to production
+
+### After (10 records)
+
+**3:00 PM** - 🔴 #1235: Fixed post-deployment routing issue
+**3:10 PM** - 🔵 #1236: Discovered caching behavior in production
+**3:15 PM** - 🧠 #1237: Decided to add health check endpoint
+```
+
+**What to include:**
+- ✅ Chronological ordering (oldest to newest)
+- ✅ Human-readable times (not epochs)
+- ✅ Clear anchor point marker (⭐)
+- ✅ Mix of all record types (observations, sessions, prompts)
+- ✅ Concise titles (not full narratives)
+- ✅ Type emojis for quick scanning
+
+---
+
+## Format: Session Summaries
+
+**When to use:** Recent context, "what did we do" questions
+
+**Structure:**
+```markdown
+## Recent Work on {project}
+
+### 🎯 Session #{id} - {date}
+
+**Request:** {user_request}
+
+**Completed:**
+- {completion1}
+- {completion2}
+
+**Key Learning:** {learning}
+
+**Observations:**
+- {emoji} **#{obs_id}** {obs_title}
+  - Files: {file_list}
+```
+
+**Example:**
+```markdown
+## Recent Work on api-server
+
+### 🎯 Session #545 - November 9, 2024
+
+**Request:** Add JWT authentication with refresh tokens
+
+**Completed:**
+- Implemented token-based auth with refresh logic
+- Added JWT signing and verification
+- Created refresh token rotation
+
+**Key Learning:** JWT expiration requires careful handling of refresh race conditions
+
+**Observations:**
+- 🟣 **#1234** Implemented JWT authentication
+  - Files: jwt.ts, refresh.ts, middleware/auth.ts
+- 🔴 **#1235** Fixed token expiration edge case
+  - Files: refresh.ts
+```
+
+**What to include:**
+- ✅ Session ID and date
+- ✅ Original user request
+- ✅ What was completed (bulleted list)
+- ✅ Key learnings/insights
+- ✅ Linked observations with file lists
+- ✅ Clear hierarchy (session → observations)
+
+---
+
+## Format: User Prompts
+
+**When to use:** "What did I ask" questions, prompt searches
+
+**Structure:**
+```markdown
+Found {count} user prompts:
+
+💬 **Prompt #{id}** (Session #{session_id})
+   > "{preview_text}"
+   > {date} • {project}
+```
+
+**Example:**
+```markdown
+Found 5 user prompts about "authentication":
+
+💬 **Prompt #1250** (Session #545)
+   > "How do I implement JWT authentication with refresh tokens? I need to handle token expiration..."
+   > Nov 9, 2024 • api-server
+
+💬 **Prompt #1251** (Session #546)
+   > "The auth tokens are expiring too quickly. Can you help debug the refresh flow?"
+   > Nov 8, 2024 • api-server
+```
+
+**What to include:**
+- ✅ Prompt ID
+- ✅ Session ID (for context linking)
+- ✅ Preview text (200 chars for index, full text for full format)
+- ✅ Date and project
+- ✅ Quote formatting for prompt text
+
+---
+
+## Error Responses
+
+**No results found:**
+```markdown
+No results found for "{query}". Try:
+- Different search terms
+- Broader keywords
+- Checking spelling
+- Using partial paths (for file searches)
+```
+
+**Service unavailable:**
+```markdown
+The search service isn't available. Check if the worker is running:
+
+```bash
+pm2 list
+```
+
+If the worker is stopped, restart it:
+
+```bash
+npm run worker:restart
+```
+```
+
+**Invalid parameters:**
+```markdown
+Invalid search parameters:
+- {parameter}: {error_message}
+
+See the [API help](help.md) for valid parameter options.
+```
+
+---
+
+## Context-Aware Presentation
+
+Tailor formatting to user's question:
+
+**"What bugs did we fix?"**
+→ Use index format, emphasize date/type, group by recency
+
+**"How did we implement X?"**
+→ Use full format for best match, include complete narrative and files
+
+**"What was happening when..."**
+→ Use timeline format, emphasize chronology and causality
+
+**"Catch me up on recent work"**
+→ Use session summary format, focus on high-level accomplishments
+
+---
+
+## Token Budget Guidelines
+
+**Minimal presentation (~100-200 tokens):**
+- Index format with 3-5 results
+- Compact list structure
+- Essential metadata only
+
+**Standard presentation (~500-1,000 tokens):**
+- Index format with 10-15 results
+- Include subtitles and context
+- Clear formatting and emojis
+
+**Detailed presentation (~1,500-3,000 tokens):**
+- Full format for 2-3 items
+- Complete narratives and facts
+- Timeline with 20-30 records
+
+**Comprehensive presentation (~5,000+ tokens):**
+- Multiple full results
+- Deep timelines (40+ records)
+- Session summaries with observations
+
+Always start minimal, expand only when needed.
+
+---
+
+## Markdown Best Practices
+
+1. **Use headers (##, ###)** for hierarchy
+2. **Bold important elements** (IDs, titles, dates)
+3. **Quote user text** (prompts, questions)
+4. **Bullet lists** for facts and files
+5. **Code blocks** for commands and examples
+6. **Emojis** for type indicators
+7. **Horizontal rules (---)** for section breaks
+8. **Blockquotes (>)** for subtitles and previews
+
+---
+
+## Examples by Use Case
+
+### Use Case 1: Quick Overview
+User: "What did we do last session?"
+
+```markdown
+## Recent Work
+
+### 🎯 Session #545 - November 9, 2024
+Implemented JWT authentication system
+
+**Key accomplishment:** Added token-based auth with refresh tokens
+**Key learning:** JWT expiration requires careful handling of refresh race conditions
+```
+
+### Use Case 2: Specific Investigation
+User: "How did we implement JWT authentication?"
+
+```markdown
+## 🟣 Feature #1234: Implemented JWT authentication
+
+**What happened:**
+Implemented a complete JWT authentication system with access and refresh tokens. Access tokens expire after 15 minutes, refresh tokens after 7 days. Added token signing with RS256 algorithm.
+
+**Files:**
+- src/auth/jwt.ts (created)
+- src/auth/refresh.ts (created)
+- src/middleware/auth.ts (modified)
+
+**Key insight:** Refresh race conditions require atomic token exchange logic.
+```
+
+### Use Case 3: Timeline Investigation
+User: "What was happening around the deployment?"
+
+```markdown
+## Timeline: Deployment
+
+[... chronological timeline with before/after context ...]
+```
+
+Choose presentation style based on user's question and information needs.