252 lines
6.7 KiB
Markdown
252 lines
6.7 KiB
Markdown
# Common Workflows
|
|
|
|
Step-by-step guides for typical user requests using the search API.
|
|
|
|
## Workflow 1: Understanding Past Work
|
|
|
|
**User asks:** "What did we do last session?" or "Catch me up on recent work"
|
|
|
|
**Steps:**
|
|
|
|
1. **Get recent context** (fastest path):
|
|
```bash
|
|
curl -s "http://localhost:37777/api/context/recent?limit=3"
|
|
```
|
|
|
|
2. **Present as narrative:**
|
|
```markdown
|
|
## Recent Work
|
|
|
|
### Session #545 - Nov 9, 2024
|
|
Implemented JWT authentication system
|
|
|
|
**Completed:**
|
|
- Added token-based auth with refresh tokens
|
|
- Created JWT signing and verification logic
|
|
|
|
**Key Learning:** JWT expiration requires careful handling of refresh race conditions
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- Single request gets both sessions and observations
|
|
- Optimized for "catch me up" questions
|
|
- ~1,500-2,500 tokens for 3 sessions
|
|
|
|
---
|
|
|
|
## Workflow 2: Finding Specific Bug Fixes
|
|
|
|
**User asks:** "What bugs did we fix?" or "Show me recent bug fixes"
|
|
|
|
**Steps:**
|
|
|
|
1. **Search by type** (index format first):
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limit=5"
|
|
```
|
|
|
|
2. **Review index results**, identify relevant items
|
|
|
|
3. **Get full details** for specific bugs:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=full&limit=1&offset=2"
|
|
```
|
|
|
|
4. **Present findings:**
|
|
```markdown
|
|
Found 5 bug fixes:
|
|
|
|
🔴 **#1235** Fixed token expiration edge case
|
|
> Handled race condition in refresh flow
|
|
> Nov 9, 2024 • api-server
|
|
|
|
[Click for full details on #1235]
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- Progressive disclosure: index first, full details selectively
|
|
- Type-specific search is more efficient than generic search
|
|
- ~250-500 tokens for index, ~750-1000 per full detail
|
|
|
|
---
|
|
|
|
## Workflow 3: Understanding File History
|
|
|
|
**User asks:** "What changes to auth/login.ts?" or "Show me work on this file"
|
|
|
|
**Steps:**
|
|
|
|
1. **Search by file** (index format):
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=index&limit=10"
|
|
```
|
|
|
|
2. **Review chronological changes**
|
|
|
|
3. **Get full details** for specific changes:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/by-file?filePath=auth/login.ts&format=full&limit=1&offset=3"
|
|
```
|
|
|
|
4. **Present as file timeline:**
|
|
```markdown
|
|
## History of auth/login.ts
|
|
|
|
🟣 **#1230** Added JWT authentication (Nov 9)
|
|
🔴 **#1235** Fixed token expiration bug (Nov 9)
|
|
🔄 **#1240** Refactored auth flow (Nov 8)
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- File-specific search finds all related work
|
|
- Index format shows chronological overview
|
|
- Selective full details for deep dives
|
|
|
|
---
|
|
|
|
## Workflow 4: Timeline Investigation
|
|
|
|
**User asks:** "What was happening when we deployed?" or "Show me context around that bug fix"
|
|
|
|
**Steps:**
|
|
|
|
1. **Find the event** using search:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/observations?query=deployment&format=index&limit=5"
|
|
```
|
|
|
|
2. **Note observation ID** (e.g., #1234)
|
|
|
|
3. **Get timeline context**:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/timeline/context?anchor=1234&depth_before=10&depth_after=10"
|
|
```
|
|
|
|
4. **Present as chronological narrative:**
|
|
```markdown
|
|
## Timeline: Deployment
|
|
|
|
### Before (10 records)
|
|
**2:45 PM** - 🟣 Prepared deployment scripts
|
|
**2:50 PM** - 💬 User asked: "Are we ready to deploy?"
|
|
|
|
### ⭐ Anchor Point (2:55 PM)
|
|
🎯 **Observation #1234**: Deployed to production
|
|
|
|
### After (10 records)
|
|
**3:00 PM** - 🔴 Fixed post-deployment routing issue
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- Timeline shows temporal context (what happened before/after)
|
|
- Captures causality between events
|
|
- All record types (observations, sessions, prompts) interleaved
|
|
|
|
---
|
|
|
|
## Workflow 5: Quick Timeline (One Request)
|
|
|
|
**User asks:** "Timeline of authentication work"
|
|
|
|
**Steps:**
|
|
|
|
1. **Use timeline-by-query** (auto mode):
|
|
```bash
|
|
curl -s "http://localhost:37777/api/timeline/by-query?query=authentication&mode=auto&depth_before=10&depth_after=10"
|
|
```
|
|
|
|
2. **Present timeline directly:**
|
|
```markdown
|
|
## Timeline: Authentication
|
|
|
|
**Best Match:** 🟣 Observation #1234 - Implemented JWT authentication
|
|
|
|
### Context (21 records)
|
|
[... timeline around best match ...]
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- Single request combines search + timeline
|
|
- Fastest path when query is specific
|
|
- Auto mode uses top result as anchor
|
|
|
|
**Alternative:** Use interactive mode for broad queries:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/timeline/by-query?query=auth&mode=interactive&limit=5"
|
|
```
|
|
Then choose anchor manually.
|
|
|
|
---
|
|
|
|
## Workflow 6: Search Composition
|
|
|
|
**User asks:** "What features did we add to the authentication system recently?"
|
|
|
|
**Steps:**
|
|
|
|
1. **Combine filters** for precision:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateRange[start]=2024-11-01&format=index&limit=10"
|
|
```
|
|
|
|
2. **Review filtered results**
|
|
|
|
3. **Get full details** for relevant features:
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&format=full&limit=1&offset=2"
|
|
```
|
|
|
|
4. **Present findings:**
|
|
```markdown
|
|
Found 10 authentication features added in November:
|
|
|
|
🟣 **#1234** Implemented JWT authentication (Nov 9)
|
|
🟣 **#1236** Added refresh token rotation (Nov 9)
|
|
🟣 **#1238** Implemented OAuth2 flow (Nov 7)
|
|
```
|
|
|
|
**Why this workflow:**
|
|
- Multiple filters narrow results before requesting full details
|
|
- Type + query + dateRange = precise targeting
|
|
- Progressive disclosure: index first, full details selectively
|
|
|
|
---
|
|
|
|
## Workflow Selection Guide
|
|
|
|
| User Request | Workflow | Operation | Token Cost |
|
|
|--------------|----------|-----------|------------|
|
|
| "What did we do last session?" | #1 | recent-context | 1,500-2,500 |
|
|
| "What bugs did we fix?" | #2 | by-type | 500-3,000 |
|
|
| "What changes to file.ts?" | #3 | by-file | 500-3,000 |
|
|
| "What was happening then?" | #4 | search → timeline | 3,500-6,000 |
|
|
| "Timeline of X work" | #5 | timeline-by-query | 3,000-4,000 |
|
|
| "Recent features added?" | #6 | observations + filters | 500-3,000 |
|
|
|
|
## General Principles
|
|
|
|
1. **Start with index format** - Always use `format=index` first
|
|
2. **Use specialized tools** - by-type, by-file, by-concept when applicable
|
|
3. **Compose operations** - Combine search + timeline for investigations
|
|
4. **Filter early** - Use type, dateRange, project to narrow before expanding
|
|
5. **Progressive disclosure** - Load full details only for relevant items
|
|
|
|
## Token Budget Awareness
|
|
|
|
**Quick queries** (500-1,500 tokens):
|
|
- Recent context (limit=3)
|
|
- Index search (limit=5-10)
|
|
- Filtered searches
|
|
|
|
**Medium queries** (1,500-4,000 tokens):
|
|
- Recent context (limit=5-10)
|
|
- Full details (3-5 items)
|
|
- Timeline (depth 10/10)
|
|
|
|
**Deep queries** (4,000-8,000 tokens):
|
|
- Timeline (depth 20/20)
|
|
- Full details (10+ items)
|
|
- Multiple composed operations
|
|
|
|
Always start with minimal token investment, expand only when needed.
|