DavidROliverBA/.claude/skills/graph-query

/graph-query

Query the vault's knowledge graph index using natural language or structured queries.

Usage

/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query orphaned notes
/graph-query broken links
/graph-query backlinks to Project - MyProject
/graph-query --type=Adr --status=accepted

Instructions

When the user invokes /graph-query or asks to query the graph index:

Phase 1: Ensure Index Exists

Before executing any query, check if the graph index exists:

1. Check if .graph/index.json exists

2. If not found, inform the user and offer to build it:

   The graph index needs to be generated first.
   Running: npm run graph:build
   

   Execute: npm run graph:build

3. If index exists but is stale (>1 day old), optionally suggest rebuilding

Phase 2: Parse the Query

Understand what the user is asking for. The query system supports:

Natural Language Patterns: | Pattern | Interpretation | |---------|----------------| | "ADRs with status proposed" | --type=Adr --status=proposed | | "high priority tasks" | --type=Task --priority=high | | "active projects" | --type=Project --status=active | | "orphaned notes" | --orphans | | "broken links" | --broken-links | | "stale notes" | --stale | | "meetings about kafka" | --type=Meeting --search=kafka | | "backlinks to X" | --backlinks="X" | | "notes mentioning aws" | --search=aws |

Structured Parameters: | Parameter | Description | Example | |-----------|-------------|---------| | --type= | Filter by note type | --type=Adr, --type=Project | | --status= | Filter by status | --status=proposed, --status=active | | --priority= | Filter by priority | --priority=high | | --search= | BM25 relevance search (ranked results) | --search="kafka integration" | | --backlinks= | Find notes linking to target | --backlinks="Project - MyProject" | | --orphans | List orphaned notes | | | --broken-links | List broken wiki-links | | | --stale | List notes >6 months old | | | --stats | Show index statistics | | | --json | Output as JSON with scores | |

Phase 3: Execute Query via CLI

Run the appropriate command:

# Natural language query
node scripts/graph-query.js "ADRs with status proposed"

# Structured query
node scripts/graph-query.js --type=Adr --status=proposed

# Special queries
node scripts/graph-query.js --orphans
node scripts/graph-query.js --broken-links
node scripts/graph-query.js --stats

# JSON output (for further processing)
node scripts/graph-query.js --type=Task --priority=high --json

Phase 4: Format Response

Present results as a markdown table. For search queries, results are ranked by BM25 relevance score:

## Search Results

Found **X** result(s) for: "kafka integration"

| Score | Type | Title |
|-------|------|-------|
| 14.65 | Page | Kafka Integration Solution Architecture |
| 11.32 | Integration | ERP → Data Lake |
| 9.45 | System | Data Platform |

*Results ranked by BM25 relevance score (higher = more relevant)*

For type/status queries (no search term), show standard format:

## Query Results

Found **X** result(s) for: "ADRs with status proposed"

| Type | Status | Priority | Title |
|------|--------|----------|-------|
| Adr | proposed | high | ADR - API Gateway Selection |
| Adr | proposed | medium | ADR - Event Streaming Platform |

### Quick Actions
- View a note: `[[ADR - API Gateway Selection]]`
- Find related: `/graph-query backlinks to "ADR - API Gateway Selection"`
- Check quality: `/graph-query --stats`

For special queries like orphans or broken links, format appropriately:

## Orphaned Notes Report

Found **8** orphaned notes (notes with no backlinks)

| Type | Title | Last Modified |
|------|-------|---------------|
| Page | Database Migration Checklist | 2025-11-15 |
| Project | Research - Event-Driven Architecture | 2025-10-20 |

### Recommendations
- Consider linking from relevant MOCs
- Archive if no longer needed
- Use `/archive <note>` to soft-archive

Query Examples

By Type

/graph-query all ADRs
/graph-query projects
/graph-query active tasks
/graph-query meetings

By Status/Priority

/graph-query ADRs with status proposed
/graph-query high priority tasks
/graph-query completed projects
/graph-query draft ADRs

Search

/graph-query notes about kafka
/graph-query mentions of aws bedrock
/graph-query "integration pattern"

Relationships

/graph-query backlinks to Project - MyProject
/graph-query orphaned notes
/graph-query broken links

Quality

/graph-query stale notes
/graph-query --stats

Notes

• The graph index is stored in .graph/ directory (git-ignored)
• Index is automatically excluded from vault searches
• Rebuild index after major changes: npm run graph:build
• Use npm run graph:watch for automatic rebuilding during active work
• Results are limited to 50 items by default; use --json for full results
• Search uses BM25 ranking - results are sorted by relevance score, not just filtered
• BM25 weights rare terms higher (IDF) and normalises for document length
• JSON output includes relevance scores for programmatic use

Related Skills

• /orphans - Dedicated orphan analysis with recommendations
• /broken-links - Detailed broken link analysis with fixes
• /quality-report - Comprehensive vault quality report
• /vault-maintenance - Full maintenance check including graph analysis