knowledge-base.md

gistfile1.txt

---
name: knowledge-base
description: "Maintains and consults a personal Obsidian-style markdown knowledge base structured as a navigable graph (atomic notes, YAML frontmatter, wikilinks, hierarchical tags, Maps of Content), so agents can traverse it as graphRAG and pick up where prior sessions left off without the user repeating themselves. Use this skill aggressively whenever the user mentions a project, company, person, ongoing investigation, or recurring topic by name, whenever the user says \"log this\", \"remember this\", \"wrap up\", \"load context\", \"check the wiki\", \"check the knowledge base\", or similar, and whenever the user provides a durable fact (a decision, a preference, a stable piece of context, a partnership, a recurring constraint) that future agents would benefit from knowing. Also use it proactively at the start of any substantive conversation about work, strategy, analytics, or planning to load relevant prior context, and mid-conversation whenever you realize you're missing context the user expects you to have."
---

# Knowledge Base

A personal markdown knowledge base structured as an Obsidian-style graph that lets agents start where the last session ended and traverse the graph to pull only the context they need.

The user is tired of re-explaining the same context every conversation. This skill solves that by maintaining a structured graph the user controls, that any agent (with filesystem access) can read at the start of relevant conversations and write to when durable new context appears.

## Two jobs: read and write

You have two responsibilities. Both matter equally.

**Read** — when a conversation touches a topic the wiki might cover, traverse the graph from the relevant entry point and load just the notes you need.

**Write** — when durable new context surfaces (a decision, a stable fact, a working preference, an investigation result), capture it as one or more atomic notes and link them into the graph.

A skill that only writes is a journal. A skill that only reads goes stale. Do both.

---

## Locating the knowledge base

The wiki lives at a single absolute path the user has configured. Find it in this order:

1. **Check the configured path** (set by the user; e.g. `~/notes/knowledge-base` or wherever the user keeps it).
2. **If absent, ask the user once**: "Where's your wiki — what's the absolute path?"
3. **If the path doesn't exist on disk**, tell the user and stop — don't guess or create a new one elsewhere.

Treat the configured path as the single source of truth. Every read and write goes through it.

---

## The graph model

The wiki is a graph. Each markdown file is a **node**; every `[[wikilink]]` is an **edge**.

### Node types

Every note declares its `type` in frontmatter. The five canonical types:

| Type | What it is | Folder | Examples |
|---|---|---|---|
| `person` | An individual human | `people/` | `people/alex-rivera.md`, `people/sam-okafor.md` |
| `org` | A company, club, team, partner, vendor — any non-individual entity | `orgs/` | `orgs/northwind.md`, `orgs/contoso.md` |
| `decision` | A dated, reasoned decision | `decisions/` | `decisions/2026-04-12-vendor-selection.md` |
| `topic` | A concept, principle, feature, strategy, or living-fact reference page | `topics/` | `topics/onboarding-flow.md`, `topics/working-style.md` |
| `moc` | Map of Content — a curated entry point that links out to related notes | `moc/` | `moc/projectx-MOC.md`, `moc/people-MOC.md` |

When a new note doesn't obviously fit one of these types, prefer `topic` over inventing a new type.

### Atomic notes

**One concept per file.** Don't bundle five decisions into one log file, don't put three people on one page, don't mix a project's strategy with its metrics. Each atomic note has a single subject and links out to related notes.

This is the central design choice. Agentic traversal works because each node is small, scoped, and link-rich. A 500-line file with everything-about-a-project defeats the graph.

When in doubt, split.

### Edges (wikilinks)

Cross-reference everything with **full-path wikilinks**: `[[people/alex-rivera]]`, not `[./people/alex-rivera.md]` and not bare `[[alex-rivera]]`. Full paths make grep-based backlink discovery trivial and remove ambiguity when names collide.

Use the alias form when the natural prose would say something other than the filename: `[[people/alex-rivera|Alex]]`, `[[orgs/northwind|Northwind]]`.

Every meaningful entity reference in prose should be a wikilink. If the body of a note mentions a person, partner, decision, or topic that has its own note, link it. The link density *is* the graph.

### Frontmatter schema

Every note begins with YAML frontmatter. Required fields by type:

```yaml
---
type: person | org | decision | topic | moc
title: "Human-readable title"
aliases: ["Alt name", "Another way this is referenced"]
tags: [type/person, domain/projectx, status/active]
created: 2026-04-12
updated: 2026-04-12
related: ["[[orgs/northwind]]", "[[people/sam-okafor]]"]
---
```

Field rules:

- **`type`** — one of the five canonical types above.
- **`title`** — display title; can differ from filename. Required.
- **`aliases`** — every alternate way the entity gets referenced (nicknames, full names, abbreviations). Helps agents resolve ambiguous mentions to the right node. Optional but encouraged.
- **`tags`** — hierarchical tags from the taxonomy below. At minimum: `type/<node-type>`. Add `domain/*` and `status/*` where relevant.
- **`created`** — ISO date the note was first written. Never changes after.
- **`updated`** — ISO date of the last meaningful edit. Update when you edit.
- **`related`** — declared strong relationships, as wikilinks. Use this for the 1–6 most important neighbors. Don't try to enumerate every link in the body here; this list is curated, not exhaustive.

Decision notes additionally carry:

```yaml
decision_date: 2026-04-12   # when the decision was made (may differ from created)
status: active | superseded | reversed
supersedes: ["[[decisions/2026-02-08-old-decision]]"]   # if applicable
```

### Tag taxonomy

Hierarchical, slash-separated. Pick from these branches; extend only when none fit.

- `type/*` — `type/person`, `type/org`, `type/decision`, `type/topic`, `type/moc`
- `domain/*` — `domain/projectx`, `domain/profile`, `domain/personal`, `domain/dayjob`, etc. The "what part of the user's life is this."
- `status/*` — `status/active`, `status/deferred`, `status/superseded`, `status/draft`, `status/tbd`. Mostly for decisions and topics that change state.
- `role/*` — for people: `role/cofounder`, `role/partner`, `role/contact`, `role/vendor`.
- `relation/*` — for orgs: `relation/partner`, `relation/competitor`, `relation/vendor`, `relation/employer`.
- `topic/*` — open-ended thematic tags: `topic/launch`, `topic/positioning`, `topic/email`, `topic/onboarding`. Use sparingly; a wikilink to the relevant `topics/` note is usually better than a tag.

A tag is for **filtering across the graph** ("show me every active decision in the projectx domain"). A wikilink is for **declaring a specific relationship**. When both apply, use both.

---

## Maps of Content (MOCs)

MOCs replace the flat INDEX.md as the primary entry points for agents.

**An MOC is a curated, lightweight routing page.** It groups related notes under sections, with one-line context per link. It does *not* contain the substance of those notes — it points to them.

Every domain that has more than ~3 notes gets an MOC. Examples:

- `moc/projectx-MOC.md` — entry point to everything for a given project (the org note, people, partnerships, decisions, topic notes).
- `moc/people-MOC.md` — every person in the wiki.
- `moc/decisions-MOC.md` — every decision, grouped by domain, reverse-chronological inside each group.
- `moc/partners-MOC.md` — every partner org for a given project.

`INDEX.md` at the root is the **MOC of MOCs** — a shallow page listing each MOC and the user's own profile note. Agents start here.

### MOC structure

```markdown
---
type: moc
title: "Project X MOC"
tags: [type/moc, domain/projectx]
created: 2026-04-12
updated: 2026-04-12
---

# Project X

Entry point for everything related to Project X.

## The org
- [[orgs/projectx]] — product, model, current state

## People
- [[people/alex-rivera|Alex Rivera]] — co-founder
- [[people/sam-okafor|Sam Okafor]] — co-founder

## Topics
- [[topics/positioning]] — personas, competitive landscape, customer language
- [[topics/onboarding-flow]] — activation funnel
- [[topics/strategy]] — current direction (post-launch)

## Active decisions
- [[decisions/2026-04-12-retention-via-digest]]

## Partnerships
- See [[moc/partners-MOC]]
```

When you create a new note, also update the relevant MOC. The MOC is the cheap-to-scan map; without it, atomic notes are an unindexed pile.

---

## Reading: when and how

### When to read

- **At the start of any substantive conversation** that touches a known topic (project, person, ongoing investigation). Start at `INDEX.md`, jump to the relevant MOC, then load only the atomic notes you need.
- **Mid-conversation when you notice a context gap** — the user references something as if you should know it ("the Northwind partnership", "what we decided about budget"). Stop, traverse, then continue.
- **When the user says** "load context", "check the wiki", "what do we know about X".

Don't read for trivial conversations — a quick factual question or a one-off coding task doesn't need context.

### How to traverse the graph

The traversal pattern, in order:

1. **Read `INDEX.md`** to see what MOCs exist.
2. **Read the relevant MOC.** It points you at the 5–20 atomic notes in that domain.
3. **Pick the 1–5 atomic notes most relevant** to the current conversation. Read them.
4. **Follow wikilinks selectively.** If a loaded note links to `[[people/alex-rivera]]` and Alex is relevant to the user's question, read that note too. Don't follow every link — follow the ones that earn it.
5. **Use grep to find backlinks** when needed. To answer "what decisions touched the Northwind partnership," grep the wiki for `[[orgs/northwind]]` and inspect the inbound notes.
6. **Use tags to find clusters.** To find every active decision, grep for `tags:.*status/active` inside `decisions/`.

This is graphRAG. Don't bulk-load. Walk the graph.

### Don't narrate

Don't say "let me load your context" or "I've reviewed your wiki." Just absorb it and respond as if you already knew it. The user's whole point in maintaining this is to *stop* having to manage context loading.

---

## Writing: when and how

### When to write

Two triggers:

1. **Explicit** — the user says "log this", "remember this", "add to the wiki", "wrap up", "save this", or similar. Write immediately.

2. **Proactive detection** — you notice a durable fact has surfaced that the wiki doesn't yet have. Examples:
   - A decision with reasoning ("we're going 50/50 on the new venture because…")
   - A stable preference or working style
   - A new entity (a person, a partner, a vendor, a tool choice)
   - An ongoing investigation's conclusion or current state
   - A constraint or commitment that will affect future work

When you detect one of these, **propose the write before doing it**: "Sounds like a new decision — want me to add `decisions/2026-04-12-payments-vendor.md` and link it from the Project X MOC?" If they agree, write. If they decline, drop it.

Don't propose writes for ephemera: today's mood, a passing question, a half-formed thought, content already in conversation memory.

### The write decision tree

For every write:

1. **Identify the node type.** Person, org, decision, topic, or MOC?
2. **Check whether a node already exists.** Grep filenames in the relevant folder, then grep aliases in frontmatter. If the entity is already a node, **append/update — don't duplicate.**
3. **If it's a new node, create the atomic file.**
   - Filename: kebab-case, descriptive. Decisions: `YYYY-MM-DD-short-slug.md`. People/orgs: `<entity-slug>.md`.
   - Folder: matches the node type.
   - Frontmatter: required fields populated. Set `created` and `updated` to today.
4. **Write the body.** Wikilink every entity, decision, or topic mentioned. Keep it scoped to this one subject.
5. **Update the relevant MOC** to include the new note.
6. **Update neighbors' `related:` frontmatter** if the new note creates a strong relationship that should be navigable from the other side. (Don't try to maintain exhaustive backlinks — Obsidian-style traversal can find them via grep. Update `related:` only for the strong, intentional ones.)
7. **Bump `updated:`** on any note whose body or frontmatter you changed.

### Format by node type

**Person notes** — living facts. Overwrite in place when facts change. No history. Sections that usually appear: `## Role`, `## Background`, `## Working context`, `## Notes`. Wikilink every org and project they're connected to.

**Org notes** — living facts about the entity itself (what it is, current state, business model) plus links out to associated people, decisions, partnerships, topics. Overwrite in place. Don't mix multiple orgs.

**Decision notes** — single decision per file. Filename embeds the date. Standard body:

```markdown
---
type: decision
title: "Phased Northwind integration scope"
tags: [type/decision, domain/projectx, status/active]
created: 2026-03-25
updated: 2026-03-25
decision_date: 2026-03-25
status: active
related: ["[[orgs/northwind]]", "[[people/alex-rivera]]", "[[topics/native-organizer]]"]
---

# Phased Northwind integration scope

**Context:** ...
**Decided:** ...
**Why:** ...
**Open:** ...
```

When the user says "log this decision" but doesn't say *why*, capture the decision faithfully and write `**Why:** TBD` rather than fabricating reasoning. Then ask once: "Want to add the why, or leave it open?" Don't refuse to log without a reason — the decision itself is worth capturing.

When a later decision supersedes an earlier one, set `status: superseded` on the older note and add `supersedes: ["[[decisions/old-slug]]"]` to the newer note's frontmatter. Don't delete the old one.

**Topic notes** — concept, feature, principle, strategy, living-fact reference. Whatever shape the content needs. Wikilink heavily.

**MOC notes** — see the structure above. Mostly lists of wikilinks with one-line context.

### One write per turn

If a conversation surfaces multiple durable facts, batch them into one write session at a natural break (or when the user says "wrap up"). Don't interrupt the flow of a working conversation with five separate "want me to log this?" prompts.

---

## INDEX.md: the MOC of MOCs

The root `INDEX.md` is the shallowest entry point. It lists MOCs and the user's own profile note. No deep content lives here.

```markdown
---
type: moc
title: "Wiki Index"
tags: [type/moc]
updated: 2026-04-12
---

# Wiki Index

Persistent knowledge base. Start here, jump to the relevant MOC, then load atomic notes.

## You
- [[people/me|Profile]]
- [[topics/working-style]]

## Domains
- [[moc/projectx-MOC|Project X]] — primary venture
- [[moc/people-MOC|People]] — every person in the graph
- [[moc/decisions-MOC|Decisions]] — every dated decision
- [[moc/partners-MOC|Partners]] — partnership / ecosystem orgs

## Conventions
See `SKILL.md` (this skill). Atomic notes, full-path wikilinks, frontmatter required.
```

---

## Conventions (canonical)

**Filenames:** kebab-case, descriptive. Decisions prefixed with `YYYY-MM-DD-`. No `INDEX-` or `OV-` shorthand.

**Wikilinks:** full path, `[[folder/slug]]`, with aliases when prose needs a different display: `[[people/sam-okafor|Sam]]`. Never use markdown links for inter-wiki references.

**Dates:** ISO `YYYY-MM-DD`.

**Headings:** `#` for the file title (one per file), `##` for top-level sections, `###` for subsections.

**Frontmatter:** YAML, fenced with `---`. Required on every note.

**Tags:** hierarchical, slash-separated. Always include `type/<node-type>`.

**No secrets:** never write API keys, passwords, full credit card numbers, SSNs, or other sensitive credentials. If the user asks you to log something sensitive, push back and suggest a password manager instead.

**No PII drift:** the wiki may include the user's own personal info (that's the point), but don't accumulate third-party PII (other people's contact details, addresses, etc.) unless directly relevant and the user has authorized it.

---

## Examples

**Example 1 — Explicit log, new decision**

User: "Just decided we're going with Acme Pay for Project X payments instead of building our own — log this."

You: Grep `decisions/` for "acme" or "payments" — none. Create `decisions/2026-04-12-acme-pay-for-payments.md` with frontmatter (`type: decision`, `tags: [type/decision, domain/projectx, status/active]`, `related: ["[[orgs/projectx]]", "[[topics/tech-stack]]"]`) and the standard Context/Decided/Why/Open body. Wikilink any related notes. Update `moc/projectx-MOC.md` and `moc/decisions-MOC.md`. Briefly confirm: "Logged as `decisions/2026-04-12-acme-pay-for-payments.md` and linked from the Project X and Decisions MOCs."

**Example 2 — Proactive detection, new person**

User: "Met Riley Tan at the conference — they run the partnerships team at Globex."

You: This introduces a new person and connects to an existing org (`orgs/globex`). Propose: "Want me to add `people/riley-tan.md` and link them from the Globex org note?"

**Example 3 — Reading at start of conversation**

User: "Help me think through Q3 priorities for Project X."

You: Silently read `INDEX.md` → `moc/projectx-MOC.md` → `orgs/projectx.md`, `topics/strategy.md`, `topics/metrics.md`. Skip files that aren't relevant. Respond directly with informed recommendations — don't announce the read.

**Example 4 — Mid-conversation context gap**

User: "And of course Alex's API is the bottleneck."

You: You don't know who Alex is. Read `INDEX.md` → `moc/people-MOC.md` → `people/alex-rivera.md`. Continue: "Right — given Alex is solo on that side, we'd want to scope this so it doesn't block on their bandwidth..."

**Example 5 — Resolving an alias**

User: "What did we decide with the Northwind folks?"

You: Grep frontmatter `aliases:` and titles across `orgs/` for "Northwind" → resolves to `orgs/northwind.md`. Read it; follow the `related:` wikilinks to the relevant decisions. Answer.

**Example 6 — Declining to log ephemera**

User: "I'm wiped today, brain is mush."

You: Don't propose a wiki entry. Just respond.

---

## Anti-patterns

- **Don't bulk-load.** Use the graph. INDEX → MOC → atomic notes. Never read everything every time.
- **Don't write without checking for an existing node.** You'll create duplicate `alex-rivera-2.md` files. Grep first.
- **Don't bundle multiple subjects into one file.** Atomic means atomic. If a write covers two decisions and a person, that's three files.
- **Don't use markdown links for inter-wiki references.** `[Alex](./people/alex-rivera.md)` doesn't build the graph. `[[people/alex-rivera|Alex]]` does.
- **Don't skip frontmatter.** Type, tags, dates, related. Every note. Without frontmatter the graph is unreadable.
- **Don't narrate reads or writes.** "Let me check your wiki…" is exactly the noise the user is trying to eliminate. Just do it.
- **Don't propose logging mid-flow on minor details.** Batch at natural breaks.
- **Don't restructure the wiki unprompted.** If you think organization could be better, suggest it once and let the user decide. Don't move files around silently.
- **Don't write speculation as fact.** If the user is thinking out loud, it's not a durable decision yet. Wait until they commit.