Graphify Usage

Suggestions (from 2026-05-13 session)

1. Add --update to session-close workflow

The current session-close skill doesn’t include a Graphify update step. Any session that creates, moves, or modifies KB files leaves the graph stale until the next manual /graphify --update. Adding it to the session-close checklist would keep the graph current automatically.

Suggested addition to session-close skill: after writing the log and updating _tmp.md, run /graphify /mnt/d/FSS/KB/MBR --update (and same for the FSS Business KB if files changed there). It only re-extracts changed files so the cost is low.

2. Remove the stale reference warning from Branding Decisions.md note in task context

When writing task Background sections, the current process flags stale references found during research. These warnings become noise once the underlying issue is fixed. Consider a pattern where: (a) fix the stale reference immediately (as we did), and (b) omit the warning from the task file entirely rather than noting it as resolved. The task file should describe current truth, not history.

3. Consider a task-prep step that auto-generates Background from Graphify

The workflow of “graphify query → Claude reads files → Claude writes Background” is manual. A /task-prep skill enhancement could:

1. Take the task filename as input
2. Run a graphify BFS query derived from the task title/keywords
3. Read the top 4–5 connected files
4. Auto-write the Background section

This would reduce task prep from ~10 minutes to ~2 minutes for any well-indexed task.

4. Run graphify on the FSS Business KB

The MBR KB is now indexed. The FSS Business KB (/mnt/d/FSS/KB/Business/) is not. Tasks that span both vaults (e.g. $MART DEBT brand work that informs MBR positioning) have no cross-vault graph path. Running a full index on the Business KB and keeping both updated would enable cross-vault context queries.

5. Explore --wiki output for agent-crawlable context

The --wiki flag generates graphify-out/wiki/index.md plus one article per community — designed as an agent entry point. This could replace the manual “read these files” step in task prep: a future session’s first action would be read graphify-out/wiki/index.md to orient on the whole KB in ~1k tokens, then drill into community articles as needed. Worth evaluating against the current BFS query approach.

6. Hook graphify update to git post-commit

Graphify supports graphify hook install which adds a git post-commit hook that auto-rebuilds the graph after every commit. Since the MBR KB is a git repo with regular commits, this would eliminate the need to remember /graphify --update entirely — the graph stays current as a side effect of normal commit hygiene.

To install: cd /mnt/d/FSS/KB/MBR && graphify hook install

---

Including Dev Repos in the Graphify Graph

The current graph covers the KB vault only. To connect KB docs to actual source code (components, utilities, rate scanner), there are three practical approaches.

Option A: Symlinks into the KB vault (recommended for targeted inclusion)

Create symlinks inside the KB vault pointing at specific monorepo directories. Graphify follows symlinks transparently — it sees those code files as part of the vault scan.

# From the MBR KB root — add only what the current task touches
ln -s ~/projects/monorepo/sites/template/src/components/brand  _WorkingOn/refs/brand-components
ln -s ~/projects/monorepo/src/brand/mbr                        _WorkingOn/refs/brand-mbr

On the next /graphify --update, the AST extractor picks up .astro/.ts/.js files automatically — no LLM needed for code, so it’s fast and free. The graph then has direct edges from KB doc nodes (e.g. “Bar-Blink Animation spec”) to the actual component code nodes (MyBetterRates.astro). Add symlinks for the current task; remove when done to keep the graph lean.

Tradeoff: Symlinks need updating when monorepo paths change. Scoped inclusion keeps the graph focused.

Option B: Separate graph per repo, merged on demand

Run graphify independently on the monorepo, then merge with the KB graph when cross-repo queries are needed:

# Build monorepo graph (once, then --update on commits)
cd ~/projects/monorepo && /graphify .

# Merge KB + monorepo graphs for a cross-repo query session
graphify merge-graphs \
  /mnt/d/FSS/KB/MBR/graphify-out/graph.json \
  ~/projects/monorepo/graphify-out/graph.json \
  --out /mnt/d/FSS/KB/MBR/graphify-out/graph-merged.json

Tradeoff: Two graphs to maintain; cross-repo edges only exist in the merged output and must be regenerated manually. Better if the monorepo is large and cross-repo queries are occasional.

Option C: Git post-commit hook on the monorepo

graphify hook install (run inside the monorepo) adds a post-commit hook that auto-rebuilds the monorepo graph after every commit — code only, AST, no LLM. Keeps the monorepo graph perpetually current as a side effect of normal commits. Then Option B’s merge step is the only manual action needed.

cd ~/projects/monorepo && graphify hook install

Recommended approach for MBR

Option A (symlinks) for active task work — the relevant surface per task is always small. Option B merge when a full cross-repo picture is needed (e.g. tracing a concept from KB strategy doc → product spec → actual implementation).

Task type	Symlink target
Brand component work	sites/template/src/components/brand/, src/brand/mbr/
Rate scanner work	Rate scanner package src dir
Utility work (pdf2md, etc.)	Utility src/ dir

Also consider running Option C’s graphify hook install on the monorepo now — one-time setup, zero ongoing cost.