graphify-triage
Use this skill when the user wants to turn code graph analysis into tracked GitHub issues — "audit the architecture", "find god nodes", "triage architectural debt", "run graphify and log issues", "wha
SKILL.md.claude/skills/graphify-triage/SKILL.md
GitHubGraphify Triage
What This Skill Does
Graphify Triage is a two-phase pipeline:
- Audit — runs graphify on the codebase, reads
graphify-out/GRAPH_REPORT.md, and extracts god nodes (high-centrality over-coupled components) and suggested audit questions. Saves structured issue payloads to a JSON file for review. - Sync — pushes the reviewed payloads to GitHub as labelled issues via the
ghCLI.
The separation matters: always audit first and review the payloads before syncing. This gives the user a chance to prune or edit before issues appear in the tracker.
Dependencies
- graphify — AST extraction and graph generation. Must be installed and on PATH.
- gh (GitHub CLI) — authenticated (
gh auth login) before running sync.
Quick Start
# Phase 1: generate and review proposed issues
uv run ~/.claude/skills/graphify-triage/scripts/triage.py audit --path . --output payloads.json
# Inspect payloads.json, edit or remove entries as needed, then:
# Phase 2: push to GitHub
uv run ~/.claude/skills/graphify-triage/scripts/triage.py sync --input payloads.json
To target a specific repo (e.g. when the CWD origin differs):
uv run ~/.claude/skills/graphify-triage/scripts/triage.py sync --input payloads.json --repo owner/repo
Workflow Steps
- Confirm graphify is installed (
graphify --version). If missing, install it first — the audit step will fail silently otherwise. - Run
audit. The script callsgraphify . --updateinternally, so the graph is always fresh. - Open
payloads.jsonand review the proposed issue titles and bodies. Remove or edit any that are false positives. - Confirm
gh auth statusshows authenticated before proceeding to sync. - Run
sync. Issues are created witharchitecture/auditlabels. If the repo lacks those labels,ghmay prompt interactively — create them in advance to keep the run non-interactive.
What the Audit Parses
The script extracts three sections from graphify-out/GRAPH_REPORT.md:
| Section | What it becomes |
|---|---|
## God Nodes |
One issue: "[Architectural Refactor] Decouple God Nodes…" listing the top 3 |
## Surprising Connections |
Captured but currently informational only (not converted to issues) |
## Suggested Questions |
One issue per question: "[Audit] …" with context from the report |
Pitfalls to Avoid
Stale graph: if you made significant changes since the last graphify run, the report may not reflect them. The audit command always passes --update to graphify, so this is only a risk if you're re-syncing an old payloads.json.
Missing labels: gh issue create --label architecture fails silently if the label doesn't exist in the target repo. Create labels upfront:
gh label create architecture --color 0075ca
gh label create audit --color e4e669
Wrong repo: sync infers the repo from the git remote. Pass --repo owner/repo explicitly when running from a clone that points somewhere other than the intended tracker.