---
name: graph-align
effort: medium
description: >
  On-demand documentation alignment via the Graphify code knowledge graph.
  Rebuilds the graph offline (graphify update .), then cross-checks graph
  structure against the docs + wiki overlay to surface (1) core code (god nodes /
  communities) with no doc coverage, (2) docs referencing code no longer in the
  graph (stale), (3) drift vs the SSOT registry — emitting a report + synthesis
  candidates. The interactive twin of the nightly doc-graph-align routine. Use
  when the user says /graph-align, "allinea la documentazione", "doc graph align",
  "check doc coverage", or wants an on-demand graph/doc reconciliation. Gated on
  features.has_code_graph.
---

# /graph-align — Doc ↔ Code-Graph Alignment

Reconcile documentation with the **real** code structure on demand. This is the
manually-invoked twin of the nightly `doc-graph-align` routine; both delegate to
the `doc-graph-aligner` agent. It does NOT duplicate Graphify's native `/graphify`
query skill — it orchestrates a doc-alignment pass on top of the graph.

## Project Context

**Reads from `baldart.config.yml`:** `features.has_code_graph`, `graph.output_dir`, `paths.wiki_dir`, `paths.references_dir`, `paths.docs_dir`.
**Gated by features:** `features.has_code_graph` — refuses to run when the flag is `false` (point the user to `/graphify-bootstrap`).
**Overlay:** loads `.baldart/overlays/graph-align.md` if present.
**On missing keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth — detect once at kickoff, strip the token before consuming input.
See `framework/agents/effort-protocol.md`.

## Workflow

1. **Refusal check.** If `features.has_code_graph: false`/missing, or `graphify`
   is not installed:
   ```
   The code graph layer isn't set up. Run /graphify-bootstrap first.
   ```
   Stop. (If the flag is true but the binary is missing, suggest `baldart doctor`.)

2. **Delegate to the agent.** Invoke the `doc-graph-aligner` agent (via Task tool,
   `mode: "bypassPermissions"`). It refreshes the graph (`graphify update .`),
   reads `${graph.output_dir}/GRAPH_REPORT.md`, and cross-checks graph → docs.

3. **Surface results.** Present the agent's report: uncovered core code (proposed
   synthesis candidates), stale docs (for `doc-reviewer`), registry drift. Offer
   to act on the top candidates via `/capture` (synthesis pages) — never auto-write
   canonical docs.

## Output Contract

A compact summary (not a multi-page dump), in `identity.language` (English
default):

```
Graph align (graphify-out, built @ <commit>):
  Uncovered core code: 3 god nodes / 1 community without a page → synthesis candidates queued
  Stale docs: 2 references to deleted symbols (docs/references/foo.md) → doc-reviewer
  Registry drift: 1 community with no ssot-registry entry
Next: run /capture to distil the queued candidates; hand stale-doc findings to doc-reviewer.
```

## Notes

- Offline / 0 API cost for the structural pass (graph + GRAPH_REPORT.md).
- Propose, don't author: the skill never rewrites canonical SSOT or wiki pages
  directly — it queues candidates and hands drift to `doc-reviewer`.
- The graph is never canonical; candidates cite repo SSOT (`canonicality: derived`).

## See Also

- `framework/.claude/agents/doc-graph-aligner.md` — the agent this skill drives
- `framework/routines/doc-graph-align.routine.yml` — the scheduled twin
- `framework/agents/code-graph-protocol.md` — graph retrieval contract
- `framework/agents/llm-wiki-methodology.md` — how the graph feeds the wiki
