knowledge-base-framework/skills/knowledge-base-read/SKILL.md

name, description

name	description
knowledge-base-read	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. 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|guideline|policy|feature|roadmap|decision|note|meta), 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.

# 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:

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.