Alex Newman
7fd0f28343
Update all documentation to reflect the new simplified URL parameter format: - Replace dateRange[start]/dateRange[end] with dateStart/dateEnd - Clarify that concepts, files, and obs_type accept comma-separated values - Update all code examples in skill documentation - Update comments in search-server.ts Files updated: - SKILL.md - Main skill documentation - operations/*.md - 8 operation guides (observations, prompts, sessions, by-file, by-type, by-concept, common-workflows, help) - principles/progressive-disclosure.md - Design pattern doc - src/servers/search-server.ts - Code comment All examples now use clean URLs without bracket encoding: - Old: ?dateRange[start]=2025-11-01&concepts[]=decision - New: ?dateStart=2025-11-01&concepts=decision 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
125 lines
4.0 KiB
Markdown
125 lines
4.0 KiB
Markdown
# Search Observations (Semantic + Full-Text Hybrid)
|
|
|
|
Search all observations using natural language queries.
|
|
|
|
## When to Use
|
|
|
|
- User asks: "How did we implement authentication?"
|
|
- User asks: "What bugs did we fix?"
|
|
- User asks: "What features did we add?"
|
|
- Looking for past work by keyword or topic
|
|
|
|
## Command
|
|
|
|
```bash
|
|
curl -s "http://localhost:37777/api/search/observations?query=authentication&format=index&limit=5"
|
|
```
|
|
|
|
## Parameters
|
|
|
|
- **query** (optional): Natural language search query - uses semantic search (ChromaDB) for ranking with SQLite FTS5 fallback (e.g., "authentication", "bug fix", "database migration"). Can be omitted for filter-only searches.
|
|
- **format**: "index" (summary) or "full" (complete details). Default: "full"
|
|
- **limit**: Number of results (default: 20, max: 100)
|
|
- **project**: Filter by project name (optional)
|
|
- **dateStart/dateEnd**: Filter by date range (optional) - `dateStart` and/or `dateEnd` (YYYY-MM-DD format or epoch timestamp)
|
|
- **obs_type**: Filter by observation type (comma-separated): bugfix, feature, refactor, decision, discovery, change (optional)
|
|
- **concepts**: Filter by concept tags (comma-separated, optional)
|
|
- **files**: Filter by file paths (comma-separated, optional)
|
|
|
|
**Important**: When omitting `query`, you MUST provide at least one filter (project, dateStart/dateEnd, obs_type, concepts, or files)
|
|
|
|
## When to Use Each Format
|
|
|
|
**Use format=index for:**
|
|
- Quick overviews
|
|
- Finding IDs for deeper investigation
|
|
- Listing multiple results
|
|
- **Token cost: ~50-100 per result**
|
|
|
|
**Use format=full for:**
|
|
- Complete details including narrative, facts, files, concepts
|
|
- Understanding the full context of specific observations
|
|
- **Token cost: ~500-1000 per result**
|
|
|
|
## Example Response (format=index)
|
|
|
|
```json
|
|
{
|
|
"query": "authentication",
|
|
"count": 5,
|
|
"format": "index",
|
|
"results": [
|
|
{
|
|
"id": 1234,
|
|
"type": "feature",
|
|
"title": "Implemented JWT authentication",
|
|
"subtitle": "Added token-based auth with refresh tokens",
|
|
"created_at_epoch": 1699564800000,
|
|
"project": "api-server",
|
|
"score": 0.95
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## How to Present Results
|
|
|
|
For format=index, present as a compact list:
|
|
|
|
```markdown
|
|
Found 5 results for "authentication":
|
|
|
|
1. **#1234** [feature] Implemented JWT authentication
|
|
> Added token-based auth with refresh tokens
|
|
> Nov 9, 2024 • api-server
|
|
|
|
2. **#1235** [bugfix] Fixed token expiration edge case
|
|
> Handled race condition in refresh flow
|
|
> Nov 9, 2024 • api-server
|
|
```
|
|
|
|
**Include:** ID (for follow-up), type emoji (🔴 bugfix, 🟣 feature, 🔄 refactor, 🔵 discovery, 🧠 decision, ✅ change), title, subtitle, date, project.
|
|
|
|
For complete formatting guidelines, see formatting.md (documentation coming soon).
|
|
|
|
## Filter-Only Examples
|
|
|
|
Search without query text (direct SQLite filtering):
|
|
|
|
```bash
|
|
# Get all observations from November 2025
|
|
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-01&format=index"
|
|
|
|
# Get all bug fixes from a specific project
|
|
curl -s "http://localhost:37777/api/search?type=observations&obs_type=bugfix&project=api-server&format=index"
|
|
|
|
# Get all observations from last 7 days
|
|
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-11&format=index"
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
**Missing query and filters:**
|
|
```json
|
|
{"error": "Either query or filters required for search"}
|
|
```
|
|
Fix: Provide either a query parameter OR at least one filter (project, dateStart/dateEnd, obs_type, concepts, files)
|
|
|
|
**No results found:**
|
|
```json
|
|
{"query": "foobar", "count": 0, "results": []}
|
|
```
|
|
Response: "No results found for 'foobar'. Try different search terms."
|
|
|
|
## Tips
|
|
|
|
1. Be specific: "authentication JWT" > "auth"
|
|
2. Start with format=index and limit=5-10
|
|
3. Use project filtering when working on one codebase
|
|
4. If no results, try broader terms or check spelling
|
|
|
|
**Token Efficiency:**
|
|
- Start with format=index (~50-100 tokens per result)
|
|
- Use format=full only for relevant items (~500-1000 tokens per result)
|
|
- See [../principles/progressive-disclosure.md](../principles/progressive-disclosure.md)
|