The Knowledge Base

The knowledge base is the accumulated know-how a project draws on when planning: the rules it commits to, the shared vocabulary it speaks, how the system is built, the traps to avoid, what past work taught, and why decisions were made. Spektacular (Spek) keeps it alongside your code, under .spektacular/knowledge/, so it lives and versions with the project.

It is a planning-time input. When you ask Spek to plan a feature, the planning agent reads the relevant knowledge and writes the parts that matter straight into the plan. The implement workflow then works only from the plan documents (it never re-reads the knowledge base), so the plan is the contract.

This is what it solves: without a knowledge base, every plan starts from a blank slate. The agent rediscovers your conventions, walks into gotchas you already mapped, and re-derives decisions you already made. Captured once and reused on every plan, the knowledge base is what lets Spek produce plans that fit your project instead of generic ones. It is also why you can trust the output enough to build on it.

Creating. A new entry is written with knowledge write, naming the tier and the store to put it in and the path within that store. The content comes from a file or standard input:

spektacular knowledge write \
  --data '{"tier": "repo", "name": "docs", "path": "gotchas/db-timeouts.md"}' \
  --file ./db-timeouts.md

You rarely run this by hand. The spek-knowledge skill proposes the tier, the store, the path, the tags and the body together, and waits for you to confirm all of it before anything is written.

The first segment of the path picks the category (gotchas/db-timeouts.md lands in gotchas) and the entry is stored as raw markdown at <location>/<category>/<name>.md, with any missing parent directories created for you. There is no required frontmatter; an entry’s title is taken from its first heading, falling back to its path. An entry may open with an optional frontmatter block declaring its tags, covered under Tagging an entry below.

Searching and retrieving. knowledge search runs a keyword query across the stores the request covers and returns ranked, one-per-document hits, each with a few short excerpts so an agent can scan many results cheaply. An entry does not have to contain every word of your query: it is returned if it carries evidence for any of them, and ranked on how good a match it is. How that ranking works is set out in full below. Every hit reports the tier and store it came from, which is exactly what knowledge read needs, so a result can be pulled back in full without a second lookup and with no risk of fetching a same-named entry from somewhere else. Add --tier and --filter to narrow what a search covers.

spektacular knowledge search "database timeout"

The two always-applied categories, conventions and glossary, are deliberately left out of search results. They are already loaded in full on every planning task (via knowledge always-applied), so surfacing them in search too would only repeat the same content.

Keeping it up to date. There is no separate update command: you write the entry again to the same tier, store name, and path, and the new content replaces the old. Because entries are identified by the exact bytes of their content, rewriting the same text changes nothing, while genuinely edited text supersedes the previous version.

Removing. An entry is removed with knowledge delete, addressed exactly as a read or a write is: the tier, the store, and the path within that store.

spektacular knowledge delete \
  --data '{"tier": "repo", "name": "docs", "path": "gotchas/db-timeouts.md"}'

Naming a store the project has not declared is refused, and the refusal lists the stores available in that tier. Naming a path that simply holds nothing is not an error: the removal reports success and changes nothing, so a maintenance pass that retries is safe. The result says which of the two happened, so you can tell a removal from a no-op without reading the store back.

The one entry that cannot be removed is a category’s own README.md. It is generated from the project’s definition of that category rather than written by anyone, so removing it would leave a gap nothing fills; the refusal points at spektacular init, which regenerates it. Removal is immediate and there is no undo, which is no worse than it sounds: every store in a normal setup is a directory under version control, so recovery is whatever git already gives you.

The frontmatter block. An entry may open with a YAML frontmatter block. It must be the very first thing in the file, opened and closed by a line containing only ---:

---
tags: [go, http, routing]
---

# HTTP routing standard

All Go services route HTTP endpoints through chi.

The block form of a YAML list works too:

---
tags:
  - go
  - http
  - routing
---

The rules.

• Tags are optional. An entry without a block is perfectly valid and fully searchable. There is nothing to migrate and no command to run.
• Tags are lower-cased and de-duplicated when read, so HTTP and http cannot both exist as separate tags.
• tags is the only key read. Any other key in the block is ignored, so the block is safe to use for your own metadata.
• A malformed or unclosed block is treated as no frontmatter, not as an error. An entry that happens to open with a horizontal rule keeps working, and one bad entry can never fail a search across a whole store.

Partial credit. A tag does not have to be typed exactly to be found. When a search term and a tag are prefix-related, the tag still counts, at a strength equal to the shorter string divided by the longer:

This is why plurals and word forms mostly look after themselves: apple and apples find each other without either being written down twice. It works in both directions, so it does not matter which form the tag uses.

Two limits are deliberate. The match must start at the beginning of the word, so test does not find latest. And the shorter of the two must be at least four characters, so very short terms like go or id match only exactly, rather than matching every tag that happens to start with them.

What it does not do is understand words. route does not find routing, because route is not a prefix of routing. Where a form is genuinely different rather than merely longer, carry both tags.

You rarely write this block yourself. The spek-knowledge skill proposes tags when it captures an entry, and shows them alongside the destination for you to confirm or edit before anything is written.

Auditing the tags you already have. Entries written before tags existed, or tagged carelessly, can be reviewed the same way. There is no separate command: invoke the spek-knowledge skill and ask it to audit the knowledge base tags. The skill works out the intent from the wording of the request, the same way it tells a lookup from a contribution.

Nothing is read-write until you approve it. The audit lists the entries in scope, loads the vocabulary in use, reads each entry, and reports two things per entry:

• Unsupported tags, a tag the entry’s content does not bear out, reported for removal.
• Missing tags, a subject the entry is clearly about but carries no tag for, proposed from the vocabulary already in use where something fits.

Changes are proposed and confirmed one entry at a time. Accepting one entry’s changes never applies another’s, and declining one does not carry to the next, so a suggestion you disagree with costs a “no” rather than a cleanup. Narrow what gets reviewed with --tier and --filter.

The audit is deliberately careful in two opposite directions. It will not tell an entry tagged https to use http instead, because those are different subjects and prefix matching already relates them at reduced strength. It will report apples sitting beside apple as removable, because prefix matching already reaches it and a redundant tag is how a vocabulary silently doubles.

Knowledge is a planning-time input, not a runtime one. The planning agent reads the knowledge base while producing a plan and writes the relevant parts into the plan itself; the implement workflow then works only from the plan. So the knowledge base shapes what gets planned, and the plan, not a live lookup, is the contract the implementation is held to. This keeps implementation reproducible: the same plan builds the same thing, regardless of how the knowledge base changes afterwards.

One registry is the single source of truth for the category model. The six categories and their tiers are declared once, in code. That single declaration scaffolds a new project’s directories and READMEs, decides each category’s retrieval behaviour, and tells the assistant where a new entry belongs. Adding a category, or moving one between tiers, is a change in exactly one place.

Two tiers, split by how knowledge is retrieved. Always-applied knowledge (conventions, glossary) is the small set every plan must reflect and the vocabulary needed to read everything else, so it is loaded in full each time. Looked-up knowledge (architecture, gotchas, learnings, decisions) is the larger reference body, fetched only when a query matches it. Because tier membership lives in that one registry, re-tiering a category is a single, self-consistent action: the full-load reader starts including it and search stops returning it at the same moment, so the two behaviours cannot drift apart.

De-duplication is exact, not fuzzy. This is a different question from ranking, and it gets a different tool. De-duplication asks whether two entries are the same, which is a yes-or-no fact. Ranking asks which entry is a better answer, which is a matter of degree, so it is scored rather than decided. The argument that follows is about the first question only, and is not an argument against inexact ranking.

When the same knowledge is written more than once, the mechanical check for “this is already here” matches on exact byte-identity rather than a similarity score. That is deliberate, because lexical similarity does not track meaning: “always retry” and “never retry” are nearly identical text but opposite instructions, while “add jitter to retries” and “randomize backoff intervals” share almost no words yet say the same thing. Exact matching claims the one thing it can prove, that two entries are byte-for-byte the same, and leaves every genuinely semantic judgement to a human or the assistant, which is where that judgement belongs.

The two tiers answer different questions. A repository’s own store answers what is true of that repository’s code; the project’s shared stores answer what spans repositories. Neither overrides the other, so nothing is dropped because of where it lives. When two stores hold related knowledge, a refinement is kept alongside what it refines and noted rather than hidden, while a genuine disagreement is surfaced as a conflict naming both stores instead of being silently resolved.