quantumbitcz/forge-graph-debug
skills/forge-graph-debug/SKILL.md
[read-only] Diagnose Neo4j knowledge graph issues — orphaned nodes, stale data, missing enrichments, relationship integrity. Use when /forge-graph-status shows anomalies, graph queries return unexpected results, or after a failed /forge-graph-rebuild.
development
Updated Apr 20, 2026
$ install --global
skillsauthnpx skillsauth add quantumbitcz/dev-pipeline forge-graph-debugInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 20, 2026, 5:16 AM5.5s1 file scanned
SKILL.md
- name:
- forge-graph-debug
- description:
- [read-only] Diagnose Neo4j knowledge graph issues — orphaned nodes, stale data, missing enrichments, relationship integrity. Use when /forge-graph-status shows anomalies, graph queries return unexpected results, or after a failed /forge-graph-rebuild.
- allowed-tools:
- ['Read', 'Bash', 'Glob', 'Grep']
/forge-graph-debug -- Graph Debug
Targeted diagnostic skill for the Neo4j knowledge graph. Provides structured diagnostic recipes without requiring raw Cypher knowledge.
Flags
- --help: print usage and exit 0
- --json: structured JSON output
Exit codes
See shared/skill-contract.md for the standard exit-code table.
Prerequisites
Before any action, verify:
- Git repository: Run
git rev-parse --show-toplevel 2>/dev/null. If fails: report "Not a git repository. Navigate to a project directory." and STOP. - Neo4j container running: Run
shared/graph/neo4j-health.sh. If unhealthy: report "Neo4j is not available. Run/forge-graph-initfirst." and STOP. - Graph initialized: Verify graph has nodes (check via node count query). If empty: report "Graph is empty. Run
/forge-graph-initto build the project graph." and STOP.
Diagnostic Recipes
1. Orphaned Nodes
Nodes with no relationships (potential data quality issue):
MATCH (n {project_id: $project_id})
WHERE NOT (n)--()
RETURN labels(n) AS type, count(n) AS count
LIMIT 50
2. Stale Nodes
Nodes not updated since the current HEAD:
MATCH (n {project_id: $project_id})
WHERE n.last_updated_sha <> $current_sha
RETURN labels(n)[0] AS type, n.name AS name, n.last_updated_sha AS stale_sha
LIMIT 50
3. Missing Enrichments
Expected enrichment properties absent on node types:
MATCH (n:Function {project_id: $project_id})
WHERE n.complexity IS NULL OR n.test_coverage IS NULL
RETURN n.name AS function, n.file_path AS file
LIMIT 50
4. Relationship Integrity
Check for expected relationship types:
MATCH (n {project_id: $project_id})
WHERE NOT (n)-[:DEFINED_IN]->()
RETURN labels(n)[0] AS type, n.name AS name
LIMIT 50
5. Node Count Summary
Quick health overview by label:
MATCH (n {project_id: $project_id})
RETURN labels(n)[0] AS label, count(n) AS count
ORDER BY count DESC
LIMIT 50
Instructions
- Run Neo4j health check via
shared/graph/neo4j-health.sh - If unhealthy: report status and suggest
/forge-graph-initor Docker troubleshooting - If healthy: derive
project_idfrom git remote origin URL - Run diagnostic recipes 1-5, report findings in table format
- If user provides a specific concern, run targeted Cypher (read-only, enforce LIMIT)
- Suggest remediation:
/forge-graph-rebuildfor widespread staleness, manual fixes for isolated issues
Safety
- All queries are READ-ONLY (no CREATE, MERGE, DELETE, SET)
- All queries enforce LIMIT (max 50 rows default, configurable)
- Never modify graph state -- diagnostic only
Error Handling
| Condition | Action |
|-----------|--------|
| Neo4j container not running | Report status and suggest /forge-graph-init or Docker troubleshooting |
| Neo4j unhealthy | Report error output. Suggest checking container logs |
| Cypher query fails | Display error output. Suggest /forge-graph-init if persistent |
| No project_id derivable (no git remote) | Fall back to basename of project root |
| Query returns too many rows | Enforce LIMIT (max 50 default). Suggest narrowing the diagnostic |
See Also
/forge-graph-status-- Quick overview of graph health and node counts/forge-graph-rebuild-- Rebuild the graph when debug shows widespread staleness or corruption/forge-graph-init-- Full initialization when the container is not running/forge-graph-query-- Run custom Cypher queries for deeper investigation
Related Skills
quantumbitcz/forge
development
VerifiedTrustedCommunity
[writes] Build, fix, deploy, review, or modify code in this project. Universal entry for the forge pipeline. Auto-bootstraps on first run; brainstorms before planning when given a feature description. Use when you want to take any productive action: implementing features, fixing bugs, reviewing branches, deploying, committing, running migrations.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-admin
tools
VerifiedTrustedCommunity
[writes] Manage forge state and configuration: recovery, abort, config edits, session handoff, automations, playbooks, output compression, knowledge graph maintenance. Use when you need to recover from broken pipeline state, edit settings, or manage long-lived state.
SKILL.mdUpdated Apr 30, 2026
quantumbitcz/forge-handoff
development
VerifiedTrustedCommunity
[writes] Create, list, show, resume, or search forge session handoffs. Use when context is getting heavy and you want to transfer a forge run or conversation into a fresh Claude Code session, or to resume from a prior handoff artefact. Subcommands - no args (write), list, show, resume, search.
SKILL.mdUpdated Apr 23, 2026
quantumbitcz/forge-graph
development
VerifiedTrustedCommunity
[writes] Manage the Neo4j knowledge graph. Subcommands: init, rebuild (writes); status, query <cypher>, debug (read-only). Requires Docker. No default — an explicit subcommand is required. Use when setting up the graph for the first time, rebuilding after major refactors, checking graph health, or running ad-hoc Cypher diagnostics.
SKILL.mdUpdated Apr 21, 2026