94 lines
4.6 KiB
Markdown
94 lines
4.6 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.
|
|
|
|
Call `read_instructions` on `knowledge-database` to read the framework's
|
|
`AGENTS.md` and `AGENT_QUERY_GUIDE.md` before querying the vault. These documents
|
|
are not data-vault nodes. If unavailable, report the missing instructions.
|
|
This skill is read-only — do not modify notes here.
|
|
|
|
## Vault access
|
|
|
|
The `knowledge-database` MCP server is the only interface for vault access. Use `graph_summary` to orient, `graph_search_nodes` to find notes,
|
|
`graph_neighbors` to traverse links, and `read_note` to read the source.
|
|
Use `refresh_graph` when the generated index is stale. Skills and operational
|
|
documentation belong to the framework; never infer the data vault from this
|
|
skill's file location.
|
|
|
|
## 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)
|
|
|
|
```
|
|
|
|
Every note carries taxonomy frontmatter: `id`, `title`, `type`
|
|
(`hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference`, enforced by
|
|
`refresh_graph(validate=true)`), `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 `refresh_graph(validate=true)`.
|
|
|
|
## 1. Orient
|
|
|
|
Start broad, then narrow. Begin with `graph_summary`, then find hubs using
|
|
`graph_search_nodes(type="hub")` and read relevant ones with `read_note`.
|
|
Discover repo scopes and tags from the graph rather than assuming a particular
|
|
folder layout. An external data vault need not contain a root README or
|
|
framework operational documents.
|
|
|
|
## 2. Query the graph
|
|
|
|
Use the MCP tools directly:
|
|
|
|
| Need | Tool |
|
|
|------|------|
|
|
| Repo scopes, tag spellings, most-linked notes | `graph_summary` |
|
|
| Notes in a repo | `graph_search_nodes(repo="<repo>")` |
|
|
| Notes of a type | `graph_search_nodes(type="policy")` |
|
|
| Notes with a tag | `graph_search_nodes(tag="<tag>")` |
|
|
| Search ids, titles, paths and tags | `graph_search_nodes(query="<term>")` |
|
|
| Incoming/outgoing links, relationship types and annotations | `graph_neighbors(id="<note-id>")` |
|
|
|
|
`query` does not search note bodies. Read candidate notes with `read_note` and
|
|
follow their neighbors when metadata search is insufficient. Report any search
|
|
coverage limits; do not use filesystem or shell searches.
|
|
|
|
## 3. Read the source notes
|
|
|
|
The graph gives ids and paths; the ANSWER lives in the Markdown. Read matched
|
|
notes with `read_note(id="<note-id>")` or `read_note(path="<vault-relative-path>")`. 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, use `refresh_graph`. This updates
|
|
only the generated index; it 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/<resource>/index.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`.
|