Manuel GanterandClaude Opus 5
1cb6369282
Ports two changes from the knowledge-base vault this skeleton is extracted from, keeping the shared scripts byte-identical across the pair: - `graph_summary` reports `by_tag` and `tag_count`, sized by `topTags`, and drops the `by_type`/`by_status` breakdowns. An MCP-only agent could not otherwise discover the tag spellings that `graph_search_nodes` matches verbatim. - `generate-graph.py --validate` now enforces a controlled vocabulary for a note's `type`, which is where the drift signal `by_type` used to give now lives. `AGENT_QUERY_GUIDE.md`, both skills and the-knowing-one quote the enforced enum. `tests/test_generate_graph.py` is new; `make test` is 50 tests. Regenerating the graph also drops a stale `GLOBAL_AGENTS` node for a file this skeleton does not carry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
---
|
|
name: knowledge-base-read
|
|
description: Read and query the knowledge-base vault — a personal docs-as-code knowledge database (PARA-organized). Use when the user asks what is known about a repo, policy, decision (ADR), area, or project; wants context before working in a repo; or asks to find/navigate notes by tag, type, repo, or link. Resolves the question against the Markdown notes and the generated graph index.
|
|
---
|
|
|
|
# Read the Knowledge Base
|
|
|
|
This vault is a personal docs-as-code knowledge database,
|
|
organized with the [PARA method](https://fortelabs.com/blog/para/).
|
|
Markdown is the source of truth; `index/graph.json` is a generated navigation
|
|
index. Use this skill to answer questions FROM the vault and to surface the
|
|
exact notes that back the answer.
|
|
|
|
Obey `AGENTS.md` (read them if not loaded this
|
|
session). This skill is read-only — do not modify notes here.
|
|
|
|
## Layout (PARA)
|
|
|
|
```
|
|
01_projects/ active efforts with a goal and an end
|
|
02_areas/ ongoing standards: policies, value-stream areas, decisions
|
|
02_areas/decisions/ global ADRs
|
|
03_resources/meta/ taxonomy + note templates
|
|
03_resources/repos/<repo>/ per-repo info.md (+ decisions/)
|
|
03_resources/repos/repo-landscape.md index of documented repos
|
|
04_archives/ inactive items
|
|
index/graph.json generated graph (nodes + edges)
|
|
README.md vault hub; AGENT_QUERY_GUIDE.md graph query reference
|
|
```
|
|
|
|
Every note carries taxonomy frontmatter: `id`, `title`, `type`
|
|
(`hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference`, enforced by
|
|
`generate-graph.py --validate`), `status`
|
|
(`active|draft|deprecated`), `tags`, `last_reviewed`, optional `repo`. Notes are
|
|
linked with typed markdown links — `[text](note-id){"type":"…"}` — that resolve
|
|
by `id`. Legacy `[[wiki links]]` are rejected by `make validate-graph`.
|
|
|
|
## 1. Orient
|
|
|
|
Start broad, then narrow:
|
|
|
|
- `README.md` — vault hub and entry points.
|
|
- `03_resources/repos/repo-landscape.md` — index of every documented repo, grouped.
|
|
- `02_areas/ways-of-working.md` — global engineering policy.
|
|
- `03_resources/meta/taxonomy.md` — what the frontmatter fields and PARA buckets mean.
|
|
|
|
For a repo question, read `03_resources/repos/<repo>/info.md` directly
|
|
(`ls 03_resources/repos/` to confirm the repo is documented; if absent, say so —
|
|
it is not yet in the vault).
|
|
|
|
## 2. Query the graph
|
|
|
|
`index/graph.json` is for navigation by tag / type / repo / links. Use `jq`.
|
|
Full schema and more examples are in `AGENT_QUERY_GUIDE.md`.
|
|
|
|
```bash
|
|
# all documented repos
|
|
jq -r '.nodes[].repo' index/graph.json | sort -u
|
|
|
|
# every note in one repo
|
|
jq -r '.nodes[] | select(.repo=="tenant-controller") | "\(.id)\t\(.path)"' index/graph.json
|
|
|
|
# all notes of a type (e.g. policies, decisions, projects)
|
|
jq -r '.nodes[] | select(.type=="policy") | "\(.id)\t\(.path)"' index/graph.json
|
|
|
|
# notes carrying a tag
|
|
jq -r '.nodes[] | select(.tags[]? == "kcp") | "\(.id)\t\(.path)"' index/graph.json
|
|
|
|
# most-linked (central) notes
|
|
jq -r '.nodes | sort_by(-(.inbound_count // 0))[] | "\(.inbound_count // 0)\t\(.id)"' index/graph.json | head
|
|
|
|
# outgoing links from a note, with relationship type + annotation
|
|
NOTE_ID="repo/controller-util/info"
|
|
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id) | "\(.type)\t\(.to)\t\(.annotation)"' index/graph.json
|
|
|
|
# incoming links to a note (who references it, and how)
|
|
jq -r --arg id "$NOTE_ID" '.edges[] | select(.to==$id) | "\(.type)\t\(.from)\t\(.annotation)"' index/graph.json
|
|
|
|
# edges of a specific relationship type (e.g. supersedes, depends-on)
|
|
jq -r '.edges[] | select(.type=="supersedes") | "\(.from) -> \(.to)"' index/graph.json
|
|
```
|
|
|
|
Full-text fallback when you do not know the tag/type/id:
|
|
|
|
```bash
|
|
grep -rIl "<term>" 01_projects 02_areas 03_resources 04_archives
|
|
```
|
|
|
|
## 3. Read the source notes
|
|
|
|
The graph gives ids and paths; the ANSWER lives in the Markdown. Open the
|
|
matched `.path` files and read them. Follow the typed markdown links
|
|
`[text](id){"type":"…"}`, resolving each to its node `path` to pull in related
|
|
policies, decisions, and repo info. Use each edge's `type` and `annotation` to
|
|
judge which links are worth following; links are the intended navigation, so
|
|
traverse them rather than guessing.
|
|
|
|
If the graph looks stale or a path is missing, you may regenerate read-only:
|
|
`python3 scripts/generate-graph.py` (does not touch Markdown). Do not commit.
|
|
|
|
## 4. Answer with citations
|
|
|
|
- Answer the question directly from what the notes say.
|
|
- Cite the backing notes by vault-relative `path` (e.g.
|
|
`03_resources/repos/gittea/info.md`) and/or `id` so the user can verify.
|
|
- Distinguish vault facts from inference. If the vault does not cover it, say so
|
|
plainly — do not invent. Note `status: draft`/`deprecated` when relevant.
|
|
- For "what links to / relates to X" questions, report the inbound/outbound
|
|
edges you found, including each edge's relationship `type` and `annotation`.
|