graphify claude install (v0.8.41): 26 validated bugs in the generated Claude Code skill (interpreter, --directed, shrink-guard, cleanup ordering) #1392

Bug bundle: graphify claude install skill (v0.8.41) — 26 validated issues in the generated Claude Code skill

The auto-generated Claude Code skill produced by graphify claude install (pinned .graphify_version = 0.8.41) ships several reproducible bugs in SKILL.md and the references/*.md runbooks. We vendored this snapshot into a monorepo and an automated reviewer (plus manual checks) surfaced the issues below. Each was verified against the installed graphify v0.8.41 Python source (build.py, export.py, etc.), not just read off the markdown.

Reporting upstream because the skill is regenerated by graphify claude install, so any downstream edit to the vendored copy is overwritten on the next install/upgrade — the fix has to live in the generator.

Happy to open individual issues or send a PR against the skill template if that's easier; grouping here so the pattern is visible.

A. Interpreter resolution — generated commands call system python3, which can't import graphify under uv tool install

1. SKILL.md interpreter bootstrap — uv tool run graphifyy python selects no package and falls through to system python3. The skill should resolve and persist the tool's interpreter (e.g. read the shebang of the installed graphify bin) — we use $(cat graphify-out/.graphify_python).
2. references/add-watch.md --watch — runs bare python3 -m graphify.watch; not importable under uv tool install. Must use the resolved interpreter.
3. references/exports.md --mcp — python3 -m graphify.serve and the generated Claude Desktop config command both point at system python; not importable. Must use the resolved interpreter / its absolute path.

B. Environment variables set but never exported — child Python reads os.environ and never sees the override

4. references/transcribe.md — GRAPHIFY_WHISPER_MODEL=base set as an unexported shell var; transcriber silently uses the default model.
5. references/transcribe.md — Step 1 sets WHISPER_PROMPT but the transcriber reads GRAPHIFY_WHISPER_PROMPT; domain hint silently ignored (name mismatch + missing export).

C. --directed not propagated — directed builds silently produce undirected graphs

6. SKILL.md Steps 4/5 — build_from_json(extraction) omits directed=, so --directed builds undirected.
7. references/update.md merge — the update-only merge calls build_merge(...) without directed=; build_merge(..., directed: bool = False) (build.py:448) then builds undirected via build(all_chunks, directed=directed). On --directed --update, reciprocal A↔B edges collapse to one when the merged graph is written back through G.edges(), and the later directed rebuild cannot recover the dropped edge.

D. Output path uses scan-root, but later steps read cwd graphify-out/ (or vice-versa)

8. SKILL.md (CHUNK_PATH) — chunk output path is derived from .graphify_root (the scanned dir) but Step B3 merges from cwd graphify-out/; a non-cwd scan (graphify <subdir>) writes chunks where the merge never looks → "no nodes".
9. references/add-watch.md ingest — /graphify add <url> ingests into cwd Path('./raw'), but the following --update scans $(cat .graphify_root); a non-cwd build saves the file outside the scanned root → "no new files". Ingest into root/'raw'.

E. File-list / category scoping

10. SKILL.md Step B0 — all_files flattens every detect['files'] category, including code, into the semantic-extraction list. code is already covered structurally by the AST pass, so LLM subagents re-read every source file — a repo-root run with even one README becomes unexpectedly expensive. Scope to content categories only ({document, paper, image}; video → document via transcription).
11. references/update.md / transcribe.md — on --update, the non-code branch jumps straight to extraction without running transcription, so changed .mp4/.mp3 stay in files.video and feed unreadable media paths into semantic extraction (and a video-only corpus hits the code-only fast path → empty graph). Route media through transcription, then rewrite .graphify_detect.json to move transcripts into files.document and drop files.video.
12. SKILL.md ~230 (stale semantic cache) — .graphify_cached.json is only (re)written when check_semantic_cache returns hits (if cached_nodes or ...:). If a prior run took the all-cached shortcut and skipped Part B cleanup, the file is left behind; on a later run with zero cache hits but some uncached files the conditional is false, the stale file survives, and Step B3 merges its unrelated nodes/edges into the new graph. Always rewrite (empty) or delete the cache file before the check.

F. Cleanup deletes intermediate files that later steps still read

13. SKILL.md / code-only path — code-only runs skip Part C but the merge reads .graphify_semantic.json / .graphify_extract.json → FileNotFoundError. Write an empty semantic file and run Part C so the merge input exists.
14. references/update.md --cluster-only — instructs "run Steps 5–9 as normal", but a prior build's Step 9 deletes .graphify_{extract,detect,analysis}.json that Step 5 reads → FileNotFoundError. The graphify cluster-only CLI is self-contained (re-clusters, regenerates outputs) — rely on it, don't re-run Steps 5–9.
15. references/update.md update tail — "run Steps 4–9 as normal" then "after Step 4 show the diff", but Step 9 cleanup deletes .graphify_extract.json which the diff block reads → every successful update fails at the diff. Order must be Steps 4–8 → diff (+ rm .graphify_old.json) → Step 9 last.

G. graph.json overwrite / shrink-guard safety (#479)

16. references/update.md prune — prune was built from deleted + changed. build_merge already drops every re-extracted source_file from the base before merging (re-extracted files replace their prior contribution), then applies prune_sources to the final merged graph — so passing changed files in prune deletes the freshly re-extracted nodes, leaving graph.json missing that file. prune should be deleted-files-only.
17. SKILL.md Step 4 — the to_json(...) return value was ignored; it returns False and writes nothing when the new graph is smaller than the existing graph.json (#479 shrink-guard, export.py). A deletion --update then saved the manifest/report over a stale graph.json. Capture the return; abort loudly on refusal.
18. SKILL.md Step 4 (zero-node guard) — the empty-extraction guard ran after GRAPH_REPORT.md, to_json(force=...), and .graphify_analysis.json were written, so an empty extraction on --update (with force=True) overwrote a good graph.json before aborting. Move the G.number_of_nodes() == 0 check to immediately after build_from_json(...), before any write.
19. SKILL.md is_update — force was decided by the mere presence of .graphify_old.json. An update that aborts after creating the backup but before cleanup leaves the file behind, so a later plain rebuild reads it, passes force=True, and bypasses the shrink-guard. Decide force from an explicit substituted IS_UPDATE flag instead (fail-safe: guard stays on if unset).
20. SKILL.md ~438 (report before export) — GRAPH_REPORT.md is written before the to_json shrink-guard runs. On a non---update rebuild that produces fewer nodes, to_json returns False and aborts without replacing graph.json, but the report has already been overwritten — leaving the report describing a graph that queries (still on the old graph.json) never see. Write the report only after a successful export (or stage it in a temp file).

H. Misc

21. references/extraction-spec.md — schema example uses a forbidden filename-only node ID (session_validatetoken), which the spec itself warns creates ghost/duplicate nodes. Use the immediate-parent+filename form (auth_session_validatetoken).
22. references/query.md fallback traversal — token filter len(t) > 3 drops valid 3-letter vocabulary tokens (api, jwt, ios); the vocab threshold is >= 3. Align to len(t) >= 3.
23. references/transcribe.md — the transcription block redirects all Python stdout to .graphify_transcripts.json via shell > ...json, but transcribe_all/download_audio print progress to stdout → polluted JSON → the next json.loads fails. Write the file from Python (Path.write_text(json.dumps(...))), send status to stderr.

Environment: graphifyy v0.8.41 (PyPI), installed via uv tool install graphifyy; skill generated by graphify claude install --platform claude. All line references are to the generated v0.8.41 skill files.