Compare commits
No commits in common. "be41d4877ce7b59adc5674fa03603794bce574b8" and "4e70a63ca4686dd481abe9a605a7e367cf493fa3" have entirely different histories.
be41d4877c
...
4e70a63ca4
12 changed files with 24 additions and 260 deletions
|
|
@ -63,13 +63,6 @@ libraries, concepts, systems. Create entity pages at
|
||||||
relationships between entities — `uses`, `depends_on`, `caused`,
|
relationships between entities — `uses`, `depends_on`, `caused`,
|
||||||
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
||||||
|
|
||||||
For recurring teams, clients, systems, or initiatives, consider whether a
|
|
||||||
plain project scope page under `wiki/projects/<name>.md` would make future
|
|
||||||
queries easier to route. A scope page should list when to use it, included
|
|
||||||
wiki/entity/source paths, exclusions, and refresh hints. Create one only
|
|
||||||
when the source material shows a real repeated scope; don't manufacture
|
|
||||||
scopes for one-off facts.
|
|
||||||
|
|
||||||
### Step 4 — Synthesize pages
|
### Step 4 — Synthesize pages
|
||||||
|
|
||||||
Convert the core knowledge into clean, modular Markdown files. Every page
|
Convert the core knowledge into clean, modular Markdown files. Every page
|
||||||
|
|
@ -85,20 +78,6 @@ gets frontmatter with:
|
||||||
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
||||||
kind (person, project, concept, library, decision, playbook, ...).
|
kind (person, project, concept, library, decision, playbook, ...).
|
||||||
|
|
||||||
For long conversations, meeting notes, transcripts, or chat exports, use a
|
|
||||||
structured distillation before writing the final page:
|
|
||||||
- `Question` or searchable problem statement, when there is one.
|
|
||||||
- `Summary` of the thread/note.
|
|
||||||
- `Resolution` or `Decision`, if the material contains one.
|
|
||||||
- `Systems and code references` mentioned.
|
|
||||||
- `People involved` or apparent owners/experts.
|
|
||||||
- `High-signal excerpts` for dense technical paragraphs or consecutive
|
|
||||||
messages that would be lost in a single summary.
|
|
||||||
|
|
||||||
If a high-signal excerpt is substantial enough to answer future questions
|
|
||||||
on its own, keep it as its own section or linked page rather than burying
|
|
||||||
it inside a broad transcript summary.
|
|
||||||
|
|
||||||
### Step 5 — Link and cross-reference
|
### Step 5 — Link and cross-reference
|
||||||
|
|
||||||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
||||||
|
|
@ -119,11 +98,6 @@ If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
||||||
create that subdirectory's `index.md` per the Recursive Index & Log
|
create that subdirectory's `index.md` per the Recursive Index & Log
|
||||||
Convention.
|
Convention.
|
||||||
|
|
||||||
If this step creates or updates a project scope under `wiki/projects/`,
|
|
||||||
also update `wiki/projects/index.md`. If ingest closes a previously
|
|
||||||
recorded question in `wiki/query-gaps.md`, move that entry from Open to
|
|
||||||
Resolved and mention the page or source that now answers it.
|
|
||||||
|
|
||||||
### Step 7 — Remind to review and sync
|
### Step 7 — Remind to review and sync
|
||||||
|
|
||||||
This is always the last step, every time this skill runs and made any
|
This is always the last step, every time this skill runs and made any
|
||||||
|
|
|
||||||
|
|
@ -61,13 +61,8 @@ Do **not** use this skill for:
|
||||||
|
|
||||||
Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins:
|
Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins:
|
||||||
1. `wiki/index.md` — match the question against the **Use when** column.
|
1. `wiki/index.md` — match the question against the **Use when** column.
|
||||||
2. `wiki/projects/index.md` — if a project scope matches the question,
|
2. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||||
use that project's listed pages, entity pages, raw/archive sources,
|
3. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
||||||
connector-backed libs, outputs, and graph areas as the first search
|
|
||||||
boundary. A project scope narrows the first pass only; it never hides
|
|
||||||
the rest of the cascade.
|
|
||||||
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
|
||||||
4. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
|
||||||
then each connector-backed `libs/<name>/entities/index.md` — for a
|
then each connector-backed `libs/<name>/entities/index.md` — for a
|
||||||
connector-backed lib this means its *generated* index (both the
|
connector-backed lib this means its *generated* index (both the
|
||||||
Documents and the Entities & Processes sections `ckb-index-external`
|
Documents and the Entities & Processes sections `ckb-index-external`
|
||||||
|
|
@ -85,14 +80,6 @@ only tangential can still be hiding the exact fact needed in its body or
|
||||||
its Sources. Keep the shortlist to what's plausibly relevant; this isn't
|
its Sources. Keep the shortlist to what's plausibly relevant; this isn't
|
||||||
"open everything," it's "don't stop at one."
|
"open everything," it's "don't stop at one."
|
||||||
|
|
||||||
If index/TLDR matching is not enough, run a local hybrid pass before
|
|
||||||
giving up: use `rg` for exact tokens across `wiki/`, `raw/archive/`,
|
|
||||||
`outputs/`, and readable upstream indexes; combine those hits with
|
|
||||||
project-scope matches, entity/title/TLDR matches, graph proximity,
|
|
||||||
freshness, confidence, and quality. Prefer exact text matches for error
|
|
||||||
strings, commands, flags, filenames, hostnames, IDs, and other literals;
|
|
||||||
prefer entity/semantic matches for paraphrased questions.
|
|
||||||
|
|
||||||
### Step 3 — Walk the graph for anything the shortlist missed
|
### Step 3 — Walk the graph for anything the shortlist missed
|
||||||
|
|
||||||
If a shortlisted page has edges in `wiki/graph/edges.json` (or a
|
If a shortlisted page has edges in `wiki/graph/edges.json` (or a
|
||||||
|
|
@ -100,22 +87,7 @@ connector's own `graph/edges.json`), follow `depends_on`/`uses`/`caused`
|
||||||
edges one hop out — the same way §5 Step 4 already directs — to catch a
|
edges one hop out — the same way §5 Step 4 already directs — to catch a
|
||||||
connected page the index text match alone wouldn't have surfaced.
|
connected page the index text match alone wouldn't have surfaced.
|
||||||
|
|
||||||
### Step 4 — Expand local context and build an evidence packet
|
### Step 4 — Follow every page on the shortlist to its source before answering from it
|
||||||
|
|
||||||
For every result that might ground the answer, keep a small evidence
|
|
||||||
packet with:
|
|
||||||
- source path or connector resource
|
|
||||||
- matched claim or short excerpt
|
|
||||||
- source date or `last_updated`
|
|
||||||
- freshness/confidence/quality signals, when available
|
|
||||||
- project-scope or graph relationship hints, when relevant
|
|
||||||
|
|
||||||
When a match is a section, heading, or snippet inside a larger Markdown
|
|
||||||
file, include nearby headings/paragraphs before deciding what it means.
|
|
||||||
Avoid answering from an isolated fragment when the neighboring context
|
|
||||||
changes the interpretation.
|
|
||||||
|
|
||||||
### Step 5 — Follow every page on the shortlist to its source before answering from it
|
|
||||||
|
|
||||||
This is the step this skill exists to enforce. For each page on the
|
This is the step this skill exists to enforce. For each page on the
|
||||||
shortlist that will actually ground part of the answer:
|
shortlist that will actually ground part of the answer:
|
||||||
|
|
@ -148,7 +120,7 @@ deck doesn't need a full read every time, just enough (search for the
|
||||||
name/topic, read the surrounding context) to confirm the point actually
|
name/topic, read the surrounding context) to confirm the point actually
|
||||||
being used.
|
being used.
|
||||||
|
|
||||||
### Step 6 — Reconcile and answer
|
### Step 5 — Reconcile and answer
|
||||||
|
|
||||||
If the source confirms the index, answer normally — but note what
|
If the source confirms the index, answer normally — but note what
|
||||||
grounded it (e.g. "per the kickoff transcript cited in
|
grounded it (e.g. "per the kickoff transcript cited in
|
||||||
|
|
@ -164,11 +136,7 @@ mid-answer unless the user asks for that separately.
|
||||||
|
|
||||||
If no page anywhere is even plausibly relevant, say so — don't verify
|
If no page anywhere is even plausibly relevant, say so — don't verify
|
||||||
against a source that has nothing to do with the question just to appear
|
against a source that has nothing to do with the question just to appear
|
||||||
thorough, and don't fabricate an answer either. For durable missing
|
thorough, and don't fabricate an answer either.
|
||||||
knowledge, add or propose a short `wiki/query-gaps.md` entry with the
|
|
||||||
question, date, search areas tried, and the smallest missing source/page
|
|
||||||
that would close the gap. If you edit `wiki/query-gaps.md`, update
|
|
||||||
`wiki/log.md` immediately.
|
|
||||||
|
|
||||||
## Edge cases
|
## Edge cases
|
||||||
|
|
||||||
|
|
@ -201,9 +169,8 @@ that would close the gap. If you edit `wiki/query-gaps.md`, update
|
||||||
- **Nothing in the index is even plausibly relevant** — say the knowledge
|
- **Nothing in the index is even plausibly relevant** — say the knowledge
|
||||||
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
|
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
|
||||||
material) or `ckb-index-external` (for a connector-backed source) if
|
material) or `ckb-index-external` (for a connector-backed source) if
|
||||||
that seems like the actual gap. For durable gaps, record or propose a
|
that seems like the actual gap. Don't stretch a weak match into an
|
||||||
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
|
answer just to have one.
|
||||||
just to have one.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
31
AGENTS.md
31
AGENTS.md
|
|
@ -40,8 +40,6 @@ The root directory contains exactly seven top-level entries. You must maintain t
|
||||||
│ ├── overview.md # High-level map of the knowledge base.
|
│ ├── overview.md # High-level map of the knowledge base.
|
||||||
│ ├── log.md # AGENT LOG. Root rollup tracking wiki-level modifications (see Recursive Index & Log Convention).
|
│ ├── log.md # AGENT LOG. Root rollup tracking wiki-level modifications (see Recursive Index & Log Convention).
|
||||||
│ ├── error-book.md # AGENT MAINTAINED. Records compilation errors and derived constraints.
|
│ ├── error-book.md # AGENT MAINTAINED. Records compilation errors and derived constraints.
|
||||||
│ ├── query-gaps.md # AGENT MAINTAINED. Failed or missing-answer questions that should drive future ingest.
|
|
||||||
│ ├── projects/ # AGENT POPULATED. Optional local query scopes for teams, clients, systems, or initiatives.
|
|
||||||
│ ├── entities/ # AGENT POPULATED. Typed entity pages (people, projects, concepts, libraries). Has its own index.md.
|
│ ├── entities/ # AGENT POPULATED. Typed entity pages (people, projects, concepts, libraries). Has its own index.md.
|
||||||
│ └── graph/ # AGENT MAINTAINED. Edge lists and relationship data for the knowledge graph. Has its own index.md.
|
│ └── graph/ # AGENT MAINTAINED. Edge lists and relationship data for the knowledge graph. Has its own index.md.
|
||||||
└── workload/ # MANAGED BY AGENT. Summaries of discussions and decisions.
|
└── workload/ # MANAGED BY AGENT. Summaries of discussions and decisions.
|
||||||
|
|
@ -72,7 +70,7 @@ This avoids blind filesystem scans and uses the index as a curated table of cont
|
||||||
### Recursive Index & Log Convention
|
### Recursive Index & Log Convention
|
||||||
Index-First Navigation only works if subdirectory indexes actually exist. Maintain them as follows:
|
Index-First Navigation only works if subdirectory indexes actually exist. Maintain them as follows:
|
||||||
|
|
||||||
- Every `wiki/` subdirectory that groups multiple pages (`projects/`, `entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
- Every `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
||||||
- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B.
|
- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B.
|
||||||
- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both.
|
- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both.
|
||||||
- The same convention applies verbatim inside a connector-backed `libs/<name>/` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both.
|
- The same convention applies verbatim inside a connector-backed `libs/<name>/` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both.
|
||||||
|
|
@ -120,7 +118,7 @@ retention: high|medium|low # How aggressively to deprioritize when old
|
||||||
- **`retention`** — `low` pages may be archived or deprioritized after the freshness window expires.
|
- **`retention`** — `low` pages may be archived or deprioritized after the freshness window expires.
|
||||||
|
|
||||||
### Schema Versioning
|
### Schema Versioning
|
||||||
`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.2"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field or optional reserved wiki scaffold (backward-compatible); bump the major version when changing or removing a required field or existing reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one.
|
`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.1"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field (backward-compatible); bump the major version when changing or removing a required field or reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -141,27 +139,10 @@ When the user says "Index external sources" (or "index libs", "refresh the exter
|
||||||
When answering a question or researching a topic:
|
When answering a question or researching a topic:
|
||||||
|
|
||||||
1. **Read the index** — `wiki/index.md` first. Match query keywords against **Use when** triggers.
|
1. **Read the index** — `wiki/index.md` first. Match query keywords against **Use when** triggers.
|
||||||
2. **Apply local project scope when obvious** — if `wiki/projects/index.md` has a matching project scope, use that scope's listed wiki pages, entities, raw/archive sources, libs, and graph areas as the first search area. If no scope matches, continue with the whole cascade.
|
2. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop.
|
||||||
3. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop after verifying the source when the answer matters.
|
3. **Load full pages** — only if the TLDR was insufficient.
|
||||||
4. **Run local hybrid search when index/TLDR routing is insufficient** — combine exact text search (`rg` over `wiki/`, `raw/archive/`, `outputs/`, and readable upstream indexes) with index/TLDR matches, freshness metadata, confidence, and graph proximity. Prefer exact matches for error strings, flags, IDs, filenames, commands, and hostnames; prefer semantic/entity matches for paraphrased questions.
|
4. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
||||||
5. **Load full pages with context expansion** — only if TLDRs were insufficient. When a section or snippet matches, include neighboring headings/paragraphs so the answer is grounded in a complete local context rather than an isolated fragment.
|
5. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
||||||
6. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
|
||||||
7. **Build an evidence packet** — before answering, normalize the supporting material into source path, matched claim, source date or `last_updated`, confidence/quality/freshness, and relationship/project-scope hints. Use this internally to compare evidence and cite the strongest sources.
|
|
||||||
8. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
|
||||||
9. **Record durable gaps** — if no page or source plausibly answers the query, add or propose a short entry in `wiki/query-gaps.md` with the question, date, attempted search areas, and the smallest missing source/page that would close the gap. If you edit `wiki/query-gaps.md`, log it immediately in `wiki/log.md`.
|
|
||||||
|
|
||||||
### Project Scope Pages
|
|
||||||
Project scopes are optional local-first retrieval aids, inspired by the "project" concept in large knowledge systems but implemented as plain Markdown. A project page lives at `wiki/projects/<name>.md` with normal frontmatter (`type: project_scope`) and should include:
|
|
||||||
|
|
||||||
- `## Use when` — keywords or situations that should route to this scope.
|
|
||||||
- `## Scope` — relevant wiki pages, entity pages, graph nodes, raw/archive paths, outputs, linked KBs, and libs.
|
|
||||||
- `## Exclusions` — sources that look related but should not be searched by default.
|
|
||||||
- `## Refresh hints` — which sources are likely to go stale first and how often to re-check them.
|
|
||||||
|
|
||||||
Scopes narrow the first pass only; they never hide the rest of the cascade when the scoped search is insufficient.
|
|
||||||
|
|
||||||
### Long-Note Distillation
|
|
||||||
When ingesting long conversations, meeting notes, transcripts, or chat exports, prefer a structured distillation over embedding or summarizing raw text as one blob. Capture the searchable question, short summary, resolution/decision, systems or code references, people involved, and high-signal excerpts. For very long notes, preserve important "bursts" — consecutive paragraphs or messages with dense technical signal — as separate sections or linked pages when they would otherwise be lost in a thread-level summary.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
31
MANUAL.md
31
MANUAL.md
|
|
@ -172,21 +172,6 @@ ingest incorporates it. This keeps the wiki demand-driven: it grows around
|
||||||
what you actually ask, not everything that could theoretically be written
|
what you actually ask, not everything that could theoretically be written
|
||||||
down.
|
down.
|
||||||
|
|
||||||
Durable misses can also be tracked in `wiki/query-gaps.md`. A good gap
|
|
||||||
entry is tiny: the question, where the agent looked, and the smallest
|
|
||||||
source or page that would make the answer available next time.
|
|
||||||
|
|
||||||
### D. Create a local project scope
|
|
||||||
|
|
||||||
When a topic, client, system, or initiative comes up often, ask:
|
|
||||||
|
|
||||||
> "Create a project scope for payments integration."
|
|
||||||
|
|
||||||
The agent creates or updates a plain Markdown page under `wiki/projects/`
|
|
||||||
listing the pages, entities, raw/archive files, connector indexes, and graph
|
|
||||||
areas that should be searched first for that scope. You still keep one
|
|
||||||
local wiki; this just gives repeated questions a better starting area.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Keeping it tidy
|
## 3. Keeping it tidy
|
||||||
|
|
@ -361,17 +346,11 @@ Just ask, in plain language:
|
||||||
|
|
||||||
> "What do we know about the Q3 migration risk?"
|
> "What do we know about the Q3 migration risk?"
|
||||||
|
|
||||||
The agent reads `wiki/index.md` first to find relevant pages. If a matching
|
The agent reads `wiki/index.md` first to find relevant pages, checks their
|
||||||
project scope exists under `wiki/projects/`, it searches that scope first.
|
one-line `tldr` before loading the full page, walks the knowledge graph for
|
||||||
Then it checks one-line `tldr` fields, runs exact local search for literal
|
connected facts, and falls back to `linked/`/`libs/` if the local wiki has
|
||||||
tokens when needed, expands context around matching sections, walks the
|
nothing. You get an answer grounded in what's actually written down, not a
|
||||||
knowledge graph for connected facts, and falls back to `linked/`/`libs/` if
|
guess.
|
||||||
the local wiki has nothing. You get an answer grounded in what's actually
|
|
||||||
written down, not a guess.
|
|
||||||
|
|
||||||
When there is still no answer, the agent should tell you what is missing
|
|
||||||
and either add/propose a short entry in `wiki/query-gaps.md` or suggest the
|
|
||||||
smallest source to drop into `raw/inbox/`.
|
|
||||||
|
|
||||||
### Learn from the wiki
|
### Learn from the wiki
|
||||||
|
|
||||||
|
|
|
||||||
44
README.md
44
README.md
|
|
@ -31,8 +31,6 @@ worked examples for every use case — see [MANUAL.md](MANUAL.md)
|
||||||
│ ├── overview.md # High-level map
|
│ ├── overview.md # High-level map
|
||||||
│ ├── log.md # Root rollup change log
|
│ ├── log.md # Root rollup change log
|
||||||
│ ├── error-book.md # Compilation errors & derived constraints
|
│ ├── error-book.md # Compilation errors & derived constraints
|
||||||
│ ├── query-gaps.md # Failed or missing-answer questions for future ingest
|
|
||||||
│ ├── projects/ # Optional local query scopes
|
|
||||||
│ ├── entities/ # Typed entity pages (people, projects, concepts) + own index.md
|
│ ├── entities/ # Typed entity pages (people, projects, concepts) + own index.md
|
||||||
│ └── graph/ # Edge lists and relationship data + own index.md
|
│ └── graph/ # Edge lists and relationship data + own index.md
|
||||||
└── workload/ # Session summaries & decisions
|
└── workload/ # Session summaries & decisions
|
||||||
|
|
@ -74,12 +72,6 @@ Implemented as a Claude Code Skill — see
|
||||||
actually invoked. Distinct from the `ckb-sync-changes` skill, which is a
|
actually invoked. Distinct from the `ckb-sync-changes` skill, which is a
|
||||||
pure git-level operation with no wiki synthesis.
|
pure git-level operation with no wiki synthesis.
|
||||||
|
|
||||||
For long conversations, meeting notes, transcripts, or chat exports, ingest
|
|
||||||
uses a structured distillation rather than treating the whole file as one
|
|
||||||
undifferentiated blob: searchable question, short summary, resolution or
|
|
||||||
decision, systems/code references, people involved, and high-signal excerpts
|
|
||||||
that deserve to stay findable on their own.
|
|
||||||
|
|
||||||
### Lazy-Loading Index with "Use When" Triggers
|
### Lazy-Loading Index with "Use When" Triggers
|
||||||
`wiki/index.md` is a routing table. Each entry has a **Use when** column
|
`wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||||
listing trigger keywords. The agent reads the index first (stays in context),
|
listing trigger keywords. The agent reads the index first (stays in context),
|
||||||
|
|
@ -91,40 +83,6 @@ Every page carries a one-sentence `tldr` in frontmatter. When querying, the
|
||||||
agent reads TLDRs first. If the TLDR already answers the question, the full
|
agent reads TLDRs first. If the TLDR already answers the question, the full
|
||||||
body is never loaded. Fallback chain: TLDR → body → raw source.
|
body is never loaded. Fallback chain: TLDR → body → raw source.
|
||||||
|
|
||||||
### Local Project Scopes
|
|
||||||
For recurring teams, clients, systems, or initiatives, the wiki can keep
|
|
||||||
plain Markdown scope pages under `wiki/projects/`. A scope page lists the
|
|
||||||
wiki pages, entities, raw/archive sources, connector-backed libs, outputs,
|
|
||||||
and graph areas that should be searched first for that project. This gives
|
|
||||||
the same practical benefit as a project workspace in a larger retrieval
|
|
||||||
system while staying local, transparent, and editable with any text editor.
|
|
||||||
|
|
||||||
Scopes only narrow the first pass. If the scoped search does not answer the
|
|
||||||
question, the agent falls back to the full cascade.
|
|
||||||
|
|
||||||
### Local Hybrid Retrieval
|
|
||||||
When index/TLDR routing is not enough, the agent can combine several local
|
|
||||||
signals before answering:
|
|
||||||
- exact text search with `rg` for error strings, commands, flags, filenames,
|
|
||||||
hostnames, ticket IDs, and other literal tokens
|
|
||||||
- semantic/entity matches from page titles, TLDRs, project scopes, and graph
|
|
||||||
relationships
|
|
||||||
- freshness and confidence metadata, so stale or weak pages are treated with
|
|
||||||
care
|
|
||||||
- context expansion around a matched section, so answers are grounded in the
|
|
||||||
neighboring headings and paragraphs rather than a lone snippet
|
|
||||||
|
|
||||||
The result is normalized internally as an evidence packet: source path,
|
|
||||||
matched claim, date/freshness, confidence/quality, and relationship or scope
|
|
||||||
hints. No server, vector database, or dedicated client is required.
|
|
||||||
|
|
||||||
### Query Gaps
|
|
||||||
If the cascade cannot answer a question, the agent records or proposes a
|
|
||||||
short entry in `wiki/query-gaps.md`: what was asked, where it looked, and the
|
|
||||||
smallest source or page that would close the gap. This makes failed searches
|
|
||||||
useful demand signals for the next ingest instead of disappearing into chat
|
|
||||||
history.
|
|
||||||
|
|
||||||
### Page Frontmatter Schema
|
### Page Frontmatter Schema
|
||||||
Every wiki page uses YAML frontmatter. `type` is required; the rest are optional:
|
Every wiki page uses YAML frontmatter. `type` is required; the rest are optional:
|
||||||
|
|
||||||
|
|
@ -151,7 +109,7 @@ retention: high|medium|low
|
||||||
- **freshness_window_days** — pages older than this get flagged during lint
|
- **freshness_window_days** — pages older than this get flagged during lint
|
||||||
- **retention** — low pages are archived after 2× freshness window
|
- **retention** — low pages are archived after 2× freshness window
|
||||||
|
|
||||||
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.2"`), declaring
|
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.1"`), declaring
|
||||||
which revision of this schema the wiki was authored against — bump minor for
|
which revision of this schema the wiki was authored against — bump minor for
|
||||||
additive optional fields, major for breaking changes.
|
additive optional fields, major for breaking changes.
|
||||||
|
|
||||||
|
|
|
||||||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
||||||
1.2.0
|
1.1.0
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
kb_schema_version: "1.2"
|
kb_schema_version: "1.1"
|
||||||
---
|
---
|
||||||
|
|
||||||
# Knowledge Base Index
|
# Knowledge Base Index
|
||||||
|
|
@ -11,8 +11,6 @@ kb_schema_version: "1.2"
|
||||||
| [Overview](overview.md) | High-level map of the knowledge base | Getting started, understanding the structure |
|
| [Overview](overview.md) | High-level map of the knowledge base | Getting started, understanding the structure |
|
||||||
| [Log](log.md) | Chronological record of root-level changes | Reviewing recent modifications |
|
| [Log](log.md) | Chronological record of root-level changes | Reviewing recent modifications |
|
||||||
| [Error Book](error-book.md) | Known compilation errors and fixes | Debugging a bad ingest or lint issue |
|
| [Error Book](error-book.md) | Known compilation errors and fixes | Debugging a bad ingest or lint issue |
|
||||||
| [Projects](projects/index.md) | Optional local query scopes grouping related wiki pages, sources, libs, and graph areas | Narrowing search to a team, topic, client, system, or initiative |
|
|
||||||
| [Query Gaps](query-gaps.md) | Questions the wiki could not answer yet, used to drive demand-driven ingest | Tracking failed searches, missing knowledge, future ingest targets |
|
|
||||||
| [Entities](entities/index.md) | Typed entity pages (people, projects, libraries, concepts) | Looking up a specific person, project, library, or concept |
|
| [Entities](entities/index.md) | Typed entity pages (people, projects, libraries, concepts) | Looking up a specific person, project, library, or concept |
|
||||||
| [Graph](graph/index.md) | Edge lists and relationship data between entities | Finding what depends on / relates to a given entity |
|
| [Graph](graph/index.md) | Edge lists and relationship data between entities | Finding what depends on / relates to a given entity |
|
||||||
|
|
||||||
|
|
|
||||||
12
wiki/log.md
12
wiki/log.md
|
|
@ -1,16 +1,4 @@
|
||||||
# Wiki Change Log
|
# Wiki Change Log
|
||||||
|
|
||||||
## [2026-07-29 22:47] - [UPDATE]
|
|
||||||
- **File Affected:** `wiki/index.md`
|
|
||||||
- **Description:** Bumped `kb_schema_version` from `1.1` to `1.2` for the new optional project-scope and query-gap scaffold conventions.
|
|
||||||
- **Source:** Chat conversation follow-up asking whether the wiki version was updated.
|
|
||||||
---
|
|
||||||
|
|
||||||
## [2026-07-29 22:30] - [CREATE/UPDATE]
|
|
||||||
- **File Affected:** `wiki/index.md`, `wiki/overview.md`, `wiki/projects/index.md`, `wiki/query-gaps.md`
|
|
||||||
- **Description:** Added local-first project scope and query-gap scaffolds inspired by the Cerebras knowledge base concept while keeping the wiki file-based and agent-driven.
|
|
||||||
- **Source:** Chat conversation comparing Cerebras knowledge base ideas to this local Cascade KB.
|
|
||||||
---
|
|
||||||
|
|
||||||
All modifications to the local `wiki/` directory are recorded here
|
All modifications to the local `wiki/` directory are recorded here
|
||||||
in reverse chronological order (most recent first).
|
in reverse chronological order (most recent first).
|
||||||
|
|
|
||||||
|
|
@ -26,8 +26,6 @@ When the same entity exists in multiple layers, the local version wins.
|
||||||
│ └── inbox/ # Drop zone for unprocessed material
|
│ └── inbox/ # Drop zone for unprocessed material
|
||||||
├── tmp/ # Temporary files, caches (gitignored)
|
├── tmp/ # Temporary files, caches (gitignored)
|
||||||
├── wiki/ # Local structured wiki (agent-managed)
|
├── wiki/ # Local structured wiki (agent-managed)
|
||||||
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
|
|
||||||
│ ├── projects/ # Optional local query scopes
|
|
||||||
│ ├── entities/ # Typed entity pages
|
│ ├── entities/ # Typed entity pages
|
||||||
│ └── graph/ # Edge lists and relationship data
|
│ └── graph/ # Edge lists and relationship data
|
||||||
└── workload/ # Summaries of discussions and decisions
|
└── workload/ # Summaries of discussions and decisions
|
||||||
|
|
@ -41,13 +39,6 @@ declares `kb_schema_version` for the bundle as a whole.
|
||||||
See AGENTS.md for the full schema.
|
See AGENTS.md for the full schema.
|
||||||
|
|
||||||
## Recursive Indexes
|
## Recursive Indexes
|
||||||
`entities/`, `graph/`, and optional topic folders such as `projects/` each
|
`entities/` and `graph/` each carry their own `index.md` so navigation stays
|
||||||
carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
|
lazy — read `wiki/index.md` first, then only descend into a subdirectory
|
||||||
first, then only descend into a subdirectory index if its contents are
|
index if its contents are relevant to the current task.
|
||||||
relevant to the current task.
|
|
||||||
|
|
||||||
## Local-First Retrieval Aids
|
|
||||||
Project scope pages in `wiki/projects/` can group related sources so a query
|
|
||||||
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
|
|
||||||
records questions the wiki could not answer yet, turning failed searches into
|
|
||||||
small ingest targets.
|
|
||||||
|
|
|
||||||
|
|
@ -1,8 +0,0 @@
|
||||||
# Projects
|
|
||||||
|
|
||||||
Optional local query scopes. A project page groups related wiki pages,
|
|
||||||
entity pages, raw/archive source paths, connector-backed libs, and graph
|
|
||||||
areas so retrieval starts from the most relevant slice of the cascade.
|
|
||||||
|
|
||||||
*(No project scopes yet — create one when a topic, team, client, system, or
|
|
||||||
initiative starts recurring often enough to deserve a default search scope.)*
|
|
||||||
|
|
@ -1,24 +0,0 @@
|
||||||
---
|
|
||||||
type: log
|
|
||||||
tldr: Local queue of questions the wiki could not answer yet, used to drive demand-driven ingest.
|
|
||||||
confidence: 1.0
|
|
||||||
quality: 0.8
|
|
||||||
last_updated: 2026-07-29
|
|
||||||
freshness_window_days: 30
|
|
||||||
retention: medium
|
|
||||||
---
|
|
||||||
|
|
||||||
# Query Gaps
|
|
||||||
|
|
||||||
Use this page for questions that the cascade could not answer from
|
|
||||||
`wiki/`, `linked/`, or `libs/`. Each entry should stay short and point to
|
|
||||||
the smallest missing source or page that would close the gap.
|
|
||||||
|
|
||||||
## Open
|
|
||||||
|
|
||||||
*(No query gaps recorded yet.)*
|
|
||||||
|
|
||||||
## Resolved
|
|
||||||
|
|
||||||
*(Move entries here after an ingest, page update, or connector index makes
|
|
||||||
the answer available.)*
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
## 2026-07-29 22:08 CEST
|
|
||||||
|
|
||||||
- Compared Cerebras' "How We Built Our Knowledge Base" concept against the current local Cascade KB scaffold.
|
|
||||||
- Read `wiki/index.md`, `wiki/overview.md`, `wiki/entities/index.md`, and `wiki/graph/index.md`; found the wiki currently covers cascade layering, schema, lazy indexes, empty entity pages, and empty graph scaffolding.
|
|
||||||
- User requested only a list of ideas not currently covered but compatible with a local-first wiki that does not require dedicated user software; no wiki implementation was performed.
|
|
||||||
- Noted existing unsynchronized working-tree state from session start: deleted `.claude/skills` and typechanged `CLAUDE.md`.
|
|
||||||
|
|
||||||
## 2026-07-29 22:10 CEST
|
|
||||||
|
|
||||||
- User asked to commit changes.
|
|
||||||
- Checked working-tree status before committing; planned to include the current tracked changes plus this workload summary in a single git commit.
|
|
||||||
|
|
||||||
## 2026-07-29 22:17 CEST
|
|
||||||
|
|
||||||
- User asked again to commit changes.
|
|
||||||
- Checked working-tree status; found deletions for `CLAUDE.md`, `.claude/skills/export-okf/SKILL.md`, and `.claude/skills/sync-changes/SKILL.md`.
|
|
||||||
- Planned to commit the current working tree, including this session note.
|
|
||||||
|
|
||||||
## 2026-07-29 22:23 CEST
|
|
||||||
|
|
||||||
- User asked which ideas from the Cerebras knowledge base concept could be easily implemented in the current local wiki.
|
|
||||||
- Re-read the current wiki scaffold and git status; identified low-effort, local-first ideas that fit Markdown files and CLI/agent workflows without requiring dedicated user software.
|
|
||||||
|
|
||||||
## 2026-07-29 22:44 CEST
|
|
||||||
|
|
||||||
- User asked to implement the selected local-first changes and update README/instruction files.
|
|
||||||
- Added `wiki/projects/index.md` for optional project query scopes and `wiki/query-gaps.md` for durable missing-answer tracking.
|
|
||||||
- Updated `wiki/index.md`, `wiki/overview.md`, and `wiki/log.md` to register the new scaffolds.
|
|
||||||
- Updated `README.md`, `MANUAL.md`, `AGENTS.md`, `ckb-retrieve`, and `ckb-ingest` instructions to cover project scopes, local hybrid retrieval, evidence packets, context expansion, query-gap capture, and long-note distillation.
|
|
||||||
|
|
||||||
## 2026-07-29 22:47 CEST
|
|
||||||
|
|
||||||
- User asked whether the wiki version had been updated.
|
|
||||||
- Confirmed it had not been bumped yet, then updated `wiki/index.md` from `kb_schema_version: "1.1"` to `"1.2"` and `VERSION` from `1.1.0` to `1.2.0`.
|
|
||||||
- Updated README/AGENTS schema-version examples and logged the wiki schema bump in `wiki/log.md`.
|
|
||||||
|
|
||||||
## 2026-07-29 22:48 CEST
|
|
||||||
|
|
||||||
- User asked to commit changes and push to `origin`.
|
|
||||||
- Began the `ckb-sync-changes` git-level workflow: pre-flight checks passed, `origin` was configured, and `git fetch origin` completed.
|
|
||||||
Loading…
Add table
Reference in a new issue