Knowledge

What this skill does

# Knowledge Skill

Manage the PAI Knowledge Archive at `~/.claude/PAI/MEMORY/KNOWLEDGE/`.

**Archive schema:** `~/.claude/PAI/MEMORY/KNOWLEDGE/_schema.md`

## Command Routing

| Input | Command | Action |
|-------|---------|--------|
| `/knowledge` (no args) | **status** | Health dashboard |
| `/knowledge <query>` | **search** | Search for notes matching query |
| `/knowledge search <query>` | **search** | Explicit search |
| `/knowledge add <type>` | **add** | Create a new note (People, Companies, or Ideas) |
| `/knowledge harvest` | **harvest** | Run KnowledgeHarvester on all sources |
| `/knowledge develop` | **develop** | Surface seedlings and enrich them |
| `/knowledge ingest <url-or-file>` | **ingest** | Read source, create note, ripple updates to related notes |
| `/knowledge contradictions` | **contradictions** | Find and review conflicting claims across notes |
| `/knowledge graph` | **graph** | Knowledge graph stats and navigation |
| `/knowledge graph <slug>` | **graph** | Traverse graph from a note |
| `/knowledge retrieve <query>` | **retrieve** | Compressed context retrieval |
| `/knowledge mine` | **mine** | Mine recent conversations for memory candidates |

If `$ARGUMENTS` doesn't match a subcommand, treat it as a search query.

---

## status (default, no args)

Run the harvester status command and display results:

```bash
bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts status
```

Also show:
- Quick summary of domains with note counts
- Any orphan wikilinks
- Any stale seedlings
- Time since last harvest

Present in NATIVE mode.

---

## search <query>

Search the Knowledge Archive for notes matching `$ARGUMENTS`.

**Step 1 — Lexical search:**
```bash
rg -i "$ARGUMENTS" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l
```

**Step 2 — Frontmatter search (tags and titles):**
```bash
rg -i "title:.*$ARGUMENTS|tags:.*$ARGUMENTS" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l
```

**Step 3 — Wikilink search:**
```bash
rg "\[\[.*$ARGUMENTS.*\]\]" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l
```

Deduplicate results across all three. For each match, read the first 5 lines of frontmatter to show title, domain, status, tags.

Present results as a table:
```
| Note | Domain | Status | Tags | Relevance |
```

If no results found, say so and suggest checking the full MEMORY/ system or running a harvest.

---

## add <type>

Create a new note manually in the specified entity type.

1. Validate type is one of: People, Companies, Ideas, Research
2. Ask for a title (or use remaining args after type)
3. Generate kebab-case filename from title
4. **MANDATORY: Find 2-3 related notes first.** Before writing the new note, grep existing Knowledge for related entities by topic/tags/name. This becomes the `related:` frontmatter array. No Knowledge note ships without typed links. See Canonical Linking Requirement below.
5. Create the note with proper frontmatter from `_schema.md` — schemas require: `title`, `type`, `tags` (min 1), `created`, `updated`, `quality` (0-10), plus type-specific body sections.
6. Write the file to `KNOWLEDGE/<Type>/<kebab-case-title>.md` — slug max 60 chars
7. Verify every slug in `related:` exists in the archive before saving
8. Regenerate the type's MOC:
```bash
bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts index
```

**Topic is a tag, not a type.** A security insight is an Idea with a `security` tag. A security company is a Company with a `security` tag. The entity type determines the schema; the tag determines the topic.

## Canonical Linking Requirement (MANDATORY)

**Every new Knowledge note must ship with typed cross-links.** This is not optional. The architecture is defined in `MEMORY/KNOWLEDGE/Ideas/pai-knowledge-linking-architecture.md` (quality 9) and the schema in `_schema.md`.

**Every write must include:**

1. **`related:` frontmatter array** — 2-4 typed entries linking to other Knowledge entries (any domain: People, Companies, Ideas, Research)
2. **Body wikilinks** — 1-3 `[[slug]]` references woven into the prose where natural (Implications, Evidence, or Context sections)

**8 relationship types** (pick the most accurate, prefer specific over generic):

| Type | Meaning |
|------|---------|
| `related` | Generic association (default only if no better fit) |
| `supports` | Provides evidence for the linked note |
| `contradicts` | Conflicts with the linked note |
| `extends` | Builds upon the linked note |
| `part-of` | Component of a larger whole |
| `instance-of` | Example of a pattern |
| `caused-by` | Result of the linked note |
| `preceded-by` | Came before temporally |

**Frontmatter format:**
```yaml
related:
  - slug: other-note-slug
    type: extends
  - slug: another-note-slug
    type: supports
```

**How to find related notes before writing:**
```bash
# By topic/keyword
rg -l "TOPIC" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md

# By tag overlap
rg "^tags:.*TAG" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l

# For People/Companies — grep by name
rg -l "Person Name" ~/.claude/PAI/MEMORY/KNOWLEDGE/
```

**Enforcement:**
- Writes that skip `related:` are incomplete and must be fixed before the skill/workflow returns success
- The `ingest` workflow runs this as part of the ripple pass
- The Algorithm LEARN phase includes this in its knowledge capture step
- All agents writing Knowledge entries must follow this rule — it is part of the schema, not an optional enhancement

---

## harvest

Run the KnowledgeHarvester to pull new knowledge from all PAI sources:

```bash
bun ~/.claude/PAI/TOOLS/KnowledgeHarvester.ts harvest
```

Display results. If nothing was harvested, explain that sources are already up to date.

Optionally accept `--source` filter: `/knowledge harvest work` or `/knowledge harvest memory`.

---

## develop

The weekly gardening workflow. Surface seedling notes that are ready for enrichment.

**Step 1 — Find seedlings:**
```bash
rg "^status: seedling" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l
```

**Step 2 — For each seedling:**
- Read the note
- Read related notes (follow wikilinks, search for same tags)
- Check if newer WORK/ ISAs or auto-memory entries have relevant context
- Enrich the note: add context, suggest wikilinks, flesh out content

**Step 3 — Present the diff to the user for approval.**

**Step 4 — If approved:**
- Write the updated note
- Promote status from `seedling` to `budding` (or `evergreen` if comprehensive)
- Update the `updated` date
- Regenerate affected MOCs

If no seedlings exist, report archive is clean.

---

## ingest <url-or-file>

Ingest a source into the Knowledge Archive. This is the key Karpathy-inspired upgrade: reading a source doesn't just create one note — it **ripples updates through existing related notes**.

**If no argument provided:** Show usage: `/knowledge ingest <url-or-file-path>`

### Step 1 — Fetch the source

- **URL:** Use WebFetch to retrieve and read the content. If WebFetch fails, try `curl -sL` via Bash.
- **File path:** Use Read tool to read the local file.

Summarize the source in 2-3 sentences. Identify key entities, claims, and insights.

### Step 2 — Classify and create primary note

Determine entity type (People, Companies, Ideas, or Research) using the classification rules in `_schema.md`. Most ingested sources become Ideas.

Create the primary note using the schema for that type:
- Generate kebab-case slug from title (max 60 chars)
- Write to `KNOWLEDGE/<Type>/<slug>.md` with proper frontmatter
- Include `source_url:` or `source_path:` in frontmatter
- **MANDATORY: Include `related:` array with 2-4 typed links** — the ripple pass (Step 3) identifies these, and they must be baked into the frontmatter of the primary note at creation time, not added after

### Step 3 — Ripple pass (the key innovation)

Search for existing notes that relate to this new content:

```bash
# Search by extracted tags
rg -i "TAG1|TAG2|TAG3" ~/.claude/PAI/MEMORY/KNOWLEDGE/ --type md -l --glob '!_*'

# Search by key entities/concepts mentioned
rg -i "ENTITY1|ENTITY