# Workflows & Use Cases

End-to-end playbooks for running Graphify as a one-person operation across code, documents, and a personal knowledge base. Every command below is verbatim from the v8 README; concepts are covered in the sibling docs and cross-linked rather than re-explained.

> **Provenance:** commands are tagged `[github]` (verified from the [v8 README](https://raw.githubusercontent.com/safishamsi/graphify/v8/README.md)). Claims from the creator interview are tagged `[interview]` and headline savings numbers are **sales claims**, not benchmarks. See [00-README](00-README.md) for the tagging scheme.

> **Skill vs. CLI prefix:** commands written `/graphify ...` run through the IDE skill (your assistant's model provides the LLM calls for documents — no separate API key). Commands written `graphify ...` are the plain CLI. `graphify extract ...` is the headless form used in CI or when you want to pin a backend explicitly. `[github]`

---

## Playbook 1 — Onboard fast to an unfamiliar codebase

For a new hire, contractor, or your own first hour in a repo you inherited. The interview frames this as the flagship use case: replace days of code-spelunking and Slack pings with one map. `[interview]`

1. Map the whole repo. Code is parsed locally via AST — no API calls, no token cost. `[github]`
   ```bash
   /graphify .
   ```
   This writes `graphify-out/graph.html`, `graphify-out/GRAPH_REPORT.md`, and `graphify-out/graph.json`. `[github]`
2. Read the report first, not the source. Open `graphify-out/GRAPH_REPORT.md` for architectural highlights. `[github]`
3. **God nodes first.** Ask the graph for its most-connected concepts before reading any file — these are the architectural chokepoints "everything flows through." `[github]` See [06-querying-and-god-nodes](06-querying-and-god-nodes.md) for the god-node querying pattern.
   ```bash
   /graphify query "what are the god nodes / most connected components?"
   ```
   Heuristic from the creator: a *huge* pile of god nodes signals weak cohesion or a structural mess; a *modest* set means the architecture is sane. `[interview]`
4. Trace the architecture from those hubs outward.
   ```bash
   /graphify explain "AuthService"
   /graphify query "what connects auth to the database?"
   ```
5. Generate a readable architecture page with Mermaid call-flow diagrams to skim the system visually.
   ```bash
   graphify export callflow-html
   ```
   `[github]`

**ROI framing (sales claim):** the creator pitches this as replacing a $150/hr engineer's multi-day ramp-up with a few free minutes. Treat the dollar figure as illustrative. `[interview]`

---

## Playbook 2 — Fix a bug / ticket by tracing dependencies

You have a ticket ("users hitting an error on the backend") and need the blast radius before you touch code.

1. Make sure the graph reflects current `HEAD` (see [Playbook 4](#playbook-4--build-a-persistent-digital-twin--second-brain) for keeping it fresh):
   ```bash
   /graphify --update
   ```
   `[github]`
2. Locate the suspect component via god nodes / a targeted query, then expand its neighborhood:
   ```bash
   /graphify explain "RateLimiter"
   ```
   `[github]`
3. Trace the dependency chain between the failing area and its likely root using shortest path:
   ```bash
   /graphify path "UserService" "DatabasePool"
   ```
   This returns the shortest connection between two entities — the chain of files/functions the bug can propagate through. `[github]`
4. Confirm the blast radius before editing:
   ```bash
   /graphify query "what depends on DatabasePool?"
   ```
5. Query the graph, don't dump the corpus. Ask the assistant to **extract from the graph** rather than read every file — the graph is your context. `[interview]` Token mechanics in [07-token-economics-and-updates](07-token-economics-and-updates.md).

---

## Playbook 3 — Audit AI-generated "slop" / junk code

The creator's pitch for non-experts shipping AI-written code fast: map it, then let the graph surface what's wrong. `[interview]`

1. Map the suspect tree:
   ```bash
   /graphify .
   ```
2. Look at god-node count as a smell test. An unusually large or sprawling set of god nodes points at poor cohesion — a hallmark of slop. `[interview]`
3. Hunt for orphans and dead ends — nodes with no meaningful connections often mean dead or duplicated code:
   ```bash
   /graphify query "which components are disconnected or have no dependents?"
   ```
   `[github]`
4. Use relationship confidence tags. Every inferred edge is marked `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`, so you can tell what was found in the code vs. guessed — `AMBIGUOUS` clusters are good places to look for confusion. `[github]`
5. For shell scripts (no AST support yet): ingest them as **documents** so the model does a semantic extraction instead of AST parsing. `[interview]` The creator calls shell scripts "flat" and treats document-mode as the temporary workaround. Note `.sh`/`.bash` *do* appear in the v8 supported-extensions list `[github]`, so behavior may have shifted since the interview — verify on your version.

---

## Playbook 4 — Build a persistent "digital twin" / second brain

The cross-project setup you actually want: one queryable memory spanning your code repos, documents, and a personal KB, kept fresh over time. The creator's framing is a "digital twin" that "gets smarter with time" via incremental updates. `[interview]`

### Recommended structure: many local graphs, one global view

Don't try to cram everything into a single monolithic extraction. **Build a graph per project, then fold them into one cross-project global graph.** This keeps each project's `--update` cheap and isolated while still giving you one place to query across everything. `[github]`

1. In each repo / doc folder / KB vault, build its own graph:
   ```bash
   /graphify .            # in a code repo
   /graphify ./notes      # in your personal KB / Obsidian vault
   ```
   Code is free/local; documents and notes go through a model — use a **local backend** to keep this free and private (see [Playbook 6](#playbook-6--the-creators-day-to-day-workflow) and [05-local-models-and-backends](05-local-models-and-backends.md)). `[github]` `[interview]`
2. Register each project's graph into the global graph with a memorable name:
   ```bash
   graphify global add graphify-out/graph.json my-api
   graphify global add graphify-out/graph.json my-notes
   graphify global list      # see all registered repos + node/edge counts
   ```
   The global graph lives at `~/.graphify/global.json`. `[github]`
3. (Alternative one-step form) Extract and register in a single command:
   ```bash
   graphify extract ./notes --global --as my-notes
   ```
   `[github]`
4. Query across the whole twin via your normal `query` / `path` / `explain` calls, leaning on god nodes to navigate. `[github]` `[interview]`

### Ingest cadence (keep the twin from going stale)

The user's real concern is assets going stale. Split the cadence by content type:

- **Code — automate it.** Install the git hook once per repo so the graph rebuilds on every commit (AST only, no API cost), and `graph.json` auto-merges instead of conflicting:
  ```bash
  graphify hook install
  ```
  `[github]`
- **Docs / KB / papers — refresh on demand.** These need a model call, so run them deliberately after you add or change material. `--update` re-extracts only changed files using SHA-256 hashing, so it resumes where it left off rather than rebuilding: `[interview]` `[github]`
  ```bash
  /graphify --update            # or: /graphify ./notes --update
  ```
- **Re-register after a doc refresh** so the global view picks up the new nodes:
  ```bash
  graphify global add graphify-out/graph.json my-notes
  ```
- **Ingest in splits, not one giant dump.** The creator recommends splitting a large repo or document set and re-ingesting in pieces rather than pushing the whole corpus in one shot — it merges in more cleanly and avoids context dilution. `[interview]`

### Pulling external knowledge into the brain

Add papers and videos straight into a graph (videos transcribed locally via faster-whisper): `[github]`
```bash
/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>
/graphify add https://... --author "Name" --contributor "Name"
```
`[interview]` describes this as turning a Stanford lecture or any video/audio into a queryable section-by-section map instead of re-watching it.

---

## Playbook 5 — PR impact analysis

For reviewing your own or a team's pull requests with graph-aware impact. Requires the GitHub CLI auth your repo already uses.

1. See the dashboard — every open PR with CI state, review status, worktree mapping, and graph impact:
   ```bash
   graphify prs
   ```
2. Deep-dive a specific PR's blast radius:
   ```bash
   graphify prs 42
   ```
3. Let the graph rank your review queue (auto-detects backend from env):
   ```bash
   graphify prs --triage
   ```
4. Spot merge-order risk — PRs touching the same graph communities are likely to conflict:
   ```bash
   graphify prs --conflicts
   ```
5. Scope it when you have many branches:
   ```bash
   graphify prs --base main          # only PRs targeting main
   graphify prs --worktrees          # worktree → branch → PR mapping
   graphify prs --repo owner/repo    # a different repo
   ```
All `[github]`. To pin the triage backend (e.g. keep it local/cheap):
```bash
GRAPHIFY_TRIAGE_BACKEND=ollama graphify prs --triage
```
`[github]`

---

## Playbook 6 — The creator's own day-to-day workflow

The distilled habit the creator described for himself. `[interview]`

1. **Local LLM for documents.** Extract docs/notes with Ollama so it's free and stays on your machine — no cloud, no per-token cost: `[interview]` `[github]`
   ```bash
   graphify extract ./docs --backend ollama
   ```
   Code never needs this (it's local AST already). Tuning for small GPUs:
   ```bash
   GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama
   GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama   # unload after each chunk
   graphify extract ./docs --backend ollama --token-budget 4000            # smaller chunks for local models
   ```
   `[github]` Full backend setup in [05-local-models-and-backends](05-local-models-and-backends.md).
2. **God nodes first.** Always open with the most-connected concepts to get the map before drilling in. `[interview]`
3. **Query the graph, not the corpus.** Prompt the assistant to *extract from the graph* — the graph is the context/memory. Never ask the LLM to read the whole corpus again. `[interview]`
4. **Always `--update` when ingesting new material** so a later query doesn't force a full re-read. `[interview]`
   ```bash
   /graphify --update
   ```
5. **Lock the query-first behavior in.** Register Graphify with your assistant so it consults the graph before grepping/reading files:
   ```bash
   graphify install            # or: graphify claude install
   ```
   `[github]` The creator notes he's working toward hard-wiring "go to the graph first" into the agent's behavior. `[interview]`

---

## Token-savings note

The interview's headline figures — "71.5x" in the README, with reports of "20x to 90x" from users — are **sales claims** and explicitly described as corpus-dependent with "no ceiling or floor." Do not treat them as guarantees. `[interview]` See [07-token-economics-and-updates](07-token-economics-and-updates.md).

---

## Open questions / unverified

- **Shell-script handling drift.** The interview says shell scripts aren't AST-supported and must be ingested as documents, but the v8 supported-extensions list includes `.sh`/`.bash`. `[github]` The document-mode workaround in Playbook 3 may be obsolete on current versions — confirm against your installed build. `[unverified claim]`
- **`graphify-out/` reuse across projects in the global graph.** Each `graphify .` writes to a local `graphify-out/`; the exact path you register with `graphify global add` matters. Confirm whether re-running `global add` with the same name *replaces* or *appends* — not stated in the README. `[unverified claim]`
- **`/graphify add` for KB sources** (arxiv/youtube) is documented `[github]`, but whether added external sources are automatically included when you fold the project into the global graph is unverified. `[unverified claim]`
- **Self-learning / domain-adapting "smarter over time" layer** and **Slack/Notion/meeting connectors** are described by the creator as in-progress/future, not shipped in v8. `[interview]` Do not build a workflow that depends on them yet.
- **Official site** (graphifylabs.ai) blocks plain fetch (403); documented workflows here are anchored on the v8 README rather than the marketing site.
