gh-witt3rd-claude-plugins-plugins-azkg/commands/search-notes.md

---
description: Search across all notes for a phrase or pattern with context
---

# Search Notes

You are tasked with searching across all notes in the Zettelkasten for a specific phrase or pattern, showing context for each match.

## 0. Locate AZKG Repository

**Check for AZKG_REPO_PATH environment variable:**

- Use bash conditional: `if [ -z "$AZKG_REPO_PATH" ]; then REPO_PATH=$(pwd); else REPO_PATH="$AZKG_REPO_PATH"; fi`
- **If AZKG_REPO_PATH is set:** Use that path as the repository root
- **If AZKG_REPO_PATH is not set:** Use current working directory (pwd)
- Store result as REPO_PATH for all subsequent file operations

**All file operations must use REPO_PATH:**

- Read: `Read(REPO_PATH/filename.md)` or `Read("$REPO_PATH/filename.md")`
- Write: `Write(REPO_PATH/filename.md)` or `Write("$REPO_PATH/filename.md")`
- Edit: `Edit(REPO_PATH/filename.md)` or `Edit("$REPO_PATH/filename.md")`
- Grep: `Grep(pattern, path=REPO_PATH)` or with explicit path
- Glob: `Glob(pattern, path=REPO_PATH)` or with explicit path

**Example usage:**

```
# Check environment variable
if [ -z "$AZKG_REPO_PATH" ]; then
  REPO_PATH=$(pwd)
else
  REPO_PATH="$AZKG_REPO_PATH"
fi

# Then use REPO_PATH for all operations
Read("$REPO_PATH/agents.md")
```

**Concrete examples:**

- If AZKG_REPO_PATH="/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg"
  → Read("/c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg/agents.md")
- If AZKG_REPO_PATH is not set and pwd is /c/Users/dothompson/OneDrive/src/witt3rd/donald-azkg
  → Read("agents.md") or use full path from pwd

## 1. Parse Search Input

**Input format:** User provides either:

- A simple phrase: `/search-notes "semantic routing"`
- A regex pattern: `/search-notes "async.*await"`
- Multiple terms: `/search-notes "MCP security authentication"`

**Extract:**

- Search pattern (the phrase or regex)
- Optional flags (case-sensitive, whole word, etc.)

## 2. Execute Search with Context

**Use Grep tool to search all markdown files:**

```
pattern: <user's search term>
glob: "*.md"
output_mode: "content"
-n: true  (show line numbers)
-C: 2     (show 2 lines of context before and after)
-i: true  (case insensitive by default)
```

**Search strategy:**

- Search all `.md` files in repository root
- Include line numbers for reference
- Show 2 lines context before and after each match
- Case-insensitive by default (unless user specifies otherwise)

## 3. Format Results

**Group results by file and present clearly:**

```
Found <N> matches across <M> notes:

## note_name.md (X matches)

Match 1 (line 45):
43: context before
44: more context
45: **matching line with PATTERN highlighted**
46: context after
47: more context

Match 2 (line 120):
118: context before
119: more context
120: **matching line with PATTERN highlighted**
121: context after
122: more context

---

## another_note.md (Y matches)

Match 1 (line 78):
...
```

**Formatting guidelines:**

- Use `##` headers for each file
- Show match count per file
- Include line numbers for easy navigation
- Bold or highlight the matching text
- Separate files with `---`
- Show total stats at top

## 4. Analyze Results

**Provide insights:**

**Thematic clustering:**

- Which tags/domains show up most?
- Are matches concentrated in certain batches?
- Example: "Most matches in MCP Protocol notes (5 files)"

**Related concepts:**

- Which notes frequently appear together in results?
- Suggest wikilinks between related notes if not already linked

**Coverage assessment:**

- Is this concept well-covered or sparse?
- Suggest potential new notes or expansions

## 5. Suggest Next Actions

**Based on search results, suggest:**

**If many matches (>10):**

- "This concept is well-covered. Consider creating a MOC for [topic]"
- "Consider using `/generate-moc` for this theme"

**If few matches (1-3):**

- "Limited coverage found. Consider `/create-note` for deeper treatment"
- "Consider `/expand-graph` on existing notes to add related content"

**If related concepts found:**

- "Found related notes that aren't linked. Consider `/link-notes`"
- List specific note pairs that should be connected

**If search term in multiple contexts:**

- "This term appears in different contexts: [list domains]"
- "Consider creating separate atomic notes for each context"

## 6. Advanced Search Options

**Support optional flags:**

**Case-sensitive search:**

- User specifies: `/search-notes --case-sensitive "Python"`
- Set `-i: false` in Grep

**Whole word only:**

- User specifies: `/search-notes --whole-word "test"`
- Adjust pattern to: `\btest\b`

**Regex mode:**

- User specifies: `/search-notes --regex "mcp.*server"`
- Pass pattern directly to Grep

**More context:**

- User specifies: `/search-notes --context 5 "pattern"`
- Set `-C: 5` for 5 lines of context

**Files only (no content):**

- User specifies: `/search-notes --files-only "pattern"`
- Set `output_mode: "files_with_matches"`

## 7. Output Summary

**Provide concise summary:**

```
Search Summary for "<search-pattern>"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Statistics:
- Total matches: <N>
- Files with matches: <M>
- Most matches: <filename> (<X> matches)

📁 Distribution by batch:
- MCP Protocol: 5 notes
- Python Stack: 3 notes
- Core AI/Agents: 2 notes

🏷️  Common tags in results:
#mcp, #python, #security, #api

💡 Suggestions:
- [Specific actionable next step based on results]
- [Another suggestion]

🔗 Potentially missing links:
- [[note_a]] ↔ [[note_b]] - both discuss same concept
```

## 8. Special Search Patterns

**Recognize common search needs:**

**Tag search:**

- Input: `/search-notes "#mcp"`
- Search in YAML frontmatter tags specifically
- List all notes with that tag

**Broken wikilinks:**

- Input: `/search-notes --broken-links`
- Find `[[wikilinks]]` that don't point to existing files
- Report with locations

**TODOs and incomplete sections:**

- Input: `/search-notes --todos`
- Find `TODO`, `FIXME`, `[placeholder]`, etc.
- Report what needs completion

**Missing related concepts:**

- Input: `/search-notes --no-relationships`
- Find notes with empty "Related Concepts" sections
- Suggest running `/expand-graph` on them

## Usage Examples

**Simple search:**

```
/search-notes "semantic routing"
```

**Regex search:**

```
/search-notes --regex "async.*(await|runtime)"
```

**Case-sensitive search:**

```
/search-notes --case-sensitive "Python"
```

**Find all notes about a technology:**

```
/search-notes --context 3 "FastMCP"
```

**Tag search:**

```
/search-notes "#agents"
```

**Find broken links:**

```
/search-notes --broken-links
```

**Find incomplete notes:**

```
/search-notes --todos
```

## Important Notes

**Performance:**

- Grep is fast even across 93+ notes
- Results should return quickly
- If >100 matches, consider limiting output or grouping

**Formatting:**

- Keep results scannable
- Use consistent formatting
- Include enough context to understand match
- Link to line numbers for easy navigation: `note.md:45`

**Accuracy:**

- Match user's search term exactly as specified
- Don't modify regex patterns unless clarifying with user
- Report if pattern yields no results

Execute the search for the pattern provided by the user.