---
name: realm-facts
description: >
  Organization-wide knowledge facts: GitLab review, Microsoft Teams notifications,
  agent-ingestable. Deterministic crawler/writer (scripts/facts.py, no LLM) owns fact-file
  parsing, schema validation, facts-index.json/facts-graph.json generation, and the
  factsRepo pointer in a product repo's realm-state.json. LLM only interviews the user for
  new fact content and judges reviewer quality — every write, count, and status transition
  is a script call. Use to connect, create, link, review, synchronize, query, or bundle
  organization-wide facts. Routes to load-on-demand procedures for each operation.
---

# realm-facts

Team knowledge facts, GitLab-reviewed, Teams-notified, agent-ingestable. Script owns state; LLM interviews and judges.

Host invocation: Claude Code and Gemini use `/realm-facts`; Codex uses `$realm-facts`.
Resolve `realmFactsSkillDir` to the directory containing this `SKILL.md`; every
fragment uses `<realmFactsSkillDir>/scripts/facts.py` and never assumes a host-specific install root.

## Syntax

```bash
/realm-facts forge                              # connect this repo to a central facts repo
/realm-facts new <domain> <id>                   # interactively author a draft fact
/realm-facts link <id> --related <id2>           # relate two facts
/realm-facts submit <id>                         # branch + MR + Teams notify
/realm-facts review <id> [--approve | --request-changes "..."]
/realm-facts sync                                # pull latest approved facts
/realm-facts recall <query>                      # search facts
/realm-facts ingest <id> [--bundle impl|context|full]  # FACT_BUNDLE for coding agents
```

## When to Use

| Trigger | Example |
|---|---|
| First time in this repo | "connect facts", `/realm-facts forge` |
| Document a team decision/behavior | `/realm-facts new platform jwt-token-rotation` |
| Relate two facts | `/realm-facts link jwt-token-rotation --related session-refresh-policy` |
| Ready for team review | `/realm-facts submit jwt-token-rotation` |
| Asked to review a fact MR | `/realm-facts review jwt-token-rotation` |
| Pull latest after Teams approval notice | `/realm-facts sync` |
| "What do we know about X?" | `/realm-facts recall jwt` |
| Hand a fact to a coding agent | `/realm-facts ingest jwt-token-rotation --bundle impl` |

## When NOT to Use

- Querying this project's own architecture/ADR history → `/realm-recall` (different store: vault, not facts repo)
- Investigating live code behavior → `/realm-fathom`
- No facts repo connected yet → `/realm-facts forge` first (every other subskill guards on this)

---

## Routing

Load only the fragment the trigger matches — never the whole skill.

| Trigger | Load |
|---|---|
| `forge`, "connect facts", first run | `forge/PROCEDURE.md` |
| `new`, "create a fact", "document X" | `new/PROCEDURE.md` |
| `link`, "relate facts" | `link/PROCEDURE.md` |
| `submit`, "submit for review" | `submit/PROCEDURE.md` |
| `review`, `--approve`, `--request-changes` | `review/PROCEDURE.md` |
| `sync`, "pull latest facts" | `sync/PROCEDURE.md` |
| `recall`, "what do we know about" | `recall/PROCEDURE.md` |
| `ingest`, "bundle for agent" | `ingest/PROCEDURE.md` |

## Ground rules (apply across every subskill)

1. **Script does everything mechanical.** Fact-file parsing, schema validation, index/graph
   generation, status transitions, and the `factsRepo` pointer all go through
   `scripts/facts.py`. Never hand-edit a fact file's frontmatter, `facts-index.json`,
   `facts-graph.json`, `.realm/facts-state.json`, or the `factsRepo` block in
   `realm-state.json`.
2. **No direct push to `main`.** Every fact change goes through `submit` → MR → `review`
   → merge. `submit`/`review` never push straight to the default branch.
3. **State reads go through `facts.py state`.** Never `Read` the whole `realm-state.json`
   just to check facts-repo connectivity — one script call prints `FACTS_CONNECTED`,
   `FACTS_URL`, `FACTS_LOCAL_PATH`, `FACTS_BRANCH`, `FACTS_LAST_SYNC` as shell-friendly lines.
4. **`recall`/`ingest` read the index, never the tree.** `facts-index.json` is the cache;
   `facts.py index` is its only writer. A live `find`/`grep` over `facts/` is a bug.
5. **Interviews stay inline.** `forge` and `new` hold a back-and-forth with the user —
   never delegate those to a subagent; subagents cannot converse.

## Guard (every subskill except `forge`)

```bash
python3 "<realmFactsSkillDir>/scripts/facts.py" state --project-root .
```

If stdout starts with `FACTS_CONNECTED=false`:

```
No facts repo connected. Run /realm-facts forge first.
```

STOP.

## Memory model

- `<facts-repo>/facts/<domain>/<id>/index.md` — one fact node. Frontmatter + `## Compressed`
  (required, ≤400 chars, agent-ingestable) + `## Context` + `## Evidence`. Script-owned schema.
- `<facts-repo>/facts-index.json`, `facts-graph.json` — script-rendered, regenerated by every
  write command (`new`, `link`, `set-status`). Read-only cache for `search`/`recall`/`ingest`.
- `<facts-repo>/.realm/facts-state.json` — last index timestamp + counts, for `/realm-status`-style
  health checks.
- `<project>/.realm/realm-state.json` → `factsRepo` block — this product repo's pointer to the
  central facts repo (`url`, `localPath`, `branch`, `lastSync`). Written once by `forge`,
  stamped by `sync`. Every other key in that file is untouched — `facts.py connect`/`state`
  only ever read or write the `factsRepo` key.

→ `/realm-facts forge` to connect · `/realm-status` for this project's own pipeline health