Graph

---
name: graph
description: Initialize or refresh the knowledge-graph snapshot for a repository. Ensures the codebase-memory-mcp engine is present (fetching it if needed), then builds draft/graph/ and reports engine, counts, hotspots, and cycles. Accepts an optional repo path.
---

# Draft Graph

Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a single repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` and does **not** re-inject doc diagram slots (both are `/draft:init`). For scope-aware, root-first graph memory across a monorepo (root spine + module→root links), use `/draft:init --graph-only`.

## Red Flags - STOP if you're

- Reporting counts without actually running `graph-snapshot.sh`
- Claiming the graph is built when the engine was unavailable
- Treating an engine-unavailable result as a hard failure (it degrades gracefully)
- Running against a path that isn't a directory

**Build, then report what the tools actually returned.**

---

## Step 1: Resolve the target repo

The command takes an optional path argument: `/draft:graph [path]`.

- No argument → use the current directory (`.`).
- With a path → use it as the repo root.

```bash
REPO="${1:-.}"
if [ ! -d "$REPO" ]; then
  echo "ERROR: '$REPO' is not a directory."
  exit 1
fi
REPO_ABS="$(cd "$REPO" && pwd)"
echo "Target repo: $REPO_ABS"

# Locate Draft's bundled helpers. Skills run with cwd = the user's project and
# ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
# and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
DRAFT_SCRIPTS="${DRAFT_TOOLS%/tools}"   # parent dir holds fetch-memory-engine.sh
```

## Step 2: Ensure the engine is present

Resolve the engine; if it is missing, fetch it once, then re-check. If it is still unavailable (e.g. offline, opted out via `DRAFT_MEMORY_DISABLE`), report and stop gracefully — graph features are optional everywhere in Draft.

```bash
if ! "$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
  echo "Graph engine not found — attempting to fetch it..."
  "$DRAFT_SCRIPTS/fetch-memory-engine.sh" || true
fi

ENGINE="$("$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null || true)"
if ! echo "$ENGINE" | grep -q '"status":"ok"'; then
  echo "Graph engine unavailable — skipping. Install with scripts/fetch-memory-engine.sh, or unset DRAFT_MEMORY_DISABLE."
  exit 0
fi
echo "Engine: $ENGINE"
```

## Step 3: Build / refresh the snapshot

One call resolves the engine, indexes the repo (incrementally on refresh), and updates the gate marker `<repo>/draft/graph/schema.yaml` (engine metadata + point-of-index counts; `access: engine-live`). All structural graph data is queried live from the engine — no snapshot files are committed beyond `schema.yaml`.

```bash
"$DRAFT_TOOLS/graph-snapshot.sh" --repo "$REPO_ABS"
```

If this exits non-zero, the engine became unavailable mid-run — report it and stop; do not fabricate results.

## Step 4: Report

Summarize what the snapshot contains. Read `draft/graph/schema.yaml` for engine/version/counts, and use the live tools for a quick health view:

```bash
echo "--- Snapshot ---"
cat "$REPO_ABS/draft/graph/schema.yaml"

echo "--- Top hotspots ---"
"$DRAFT_TOOLS/hotspot-rank.sh" --repo "$REPO_ABS" --top 5

echo "--- Cycles ---"
"$DRAFT_TOOLS/cycle-detect.sh" --repo "$REPO_ABS"

echo "--- Snapshot state ---"
git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null \
  && { git -C "$REPO_ABS" diff --quiet 2>/dev/null || echo "(working tree dirty — snapshot reflects uncommitted changes)"; }
```

Present a concise summary:

- **Engine**: version + resolution source (path / managed / bundled / override)
- **Graph**: node and edge counts (from `schema.yaml`)
- **Top hotspots**: the highest fan-in symbols
- **Cycles**: count, or `None ✓`
- **Freshness**: the commit the snapshot reflects, and whether the tree was dirty

Then point the user at the natural next steps:

- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `/draft:init refresh` (or `/draft:init --graph-only` to rebuild just the graph memory).
- For a first-time full context bootstrap (architecture + profiles): run `/draft:init`.

## Graceful Degradation

| Scenario | Behavior |
|----------|----------|
| Engine resolvable | Build snapshot, report counts/hotspots/cycles |
| Engine missing, fetch succeeds | Build proceeds after fetch |
| Engine missing, fetch fails / `DRAFT_MEMORY_DISABLE=1` | Report unavailable and exit 0 — no error, no partial snapshot |
| Path not a directory | Exit 1 with a clear message |

See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.