add-to-knowledge-base

# Add to knowledge base Create or update one feature document under `kb/<component>/<feature>.md`. The file is an OKF concept, so it starts with YAML frontmatter and is validated as part of the `kb/` bundle. Its body follows the template in [TEMPLATE.md](TEMPLATE.md). A reference example is `kb/platform-api/openapi-spec-management.md`. ## Steps Prerequisite: the `okf-open-knowledge-format` skill is not committed. If it is missing, run `make install-skills` from the repo root first. 1. **Create the initial document with the OKF skill.** Invoke `okf-open-knowledge-format` to produce the concept file, the directory `index.md`, and a `log.md` entry, and to validate the bundle. Bundle root is `kb/`, which already declares `okf_version: "0.2"`. Use `type: Feature`. Set `status: draft` unless told otherwise. Never add `verified` unless a human has actually compared the document against the code. 2. **Apply the rules below and rewrite whatever violates them.** Do this before shaping the body, because the OKF skill's default output does not know these rules. 3. **Apply the template.** Replace the body with [TEMPLATE.md](TEMPLATE.md), filled in. Keep exactly its sections and order. Do not add sections. If a section has nothing to say, write "None" under it rather than deleting it, so a reader can tell "considered" from "forgotten". 4. **Finish.** Confirm the `kb/<component>/index.md` entry and the dated `kb/log.md` entry from Step 1 exist and match the final document (update them rather than adding duplicates), and re-run the OKF validation. Report which `sources` paths do not exist yet. ## Rules These override anything the OKF skill or the template example suggests. 1. **Files only, never functions or methods.** Refer to code by file path. Do not name a Go function, method, struct, test function, or SQL statement. A test is referenced as "a test in `<file>`", never by its name. This applies to prose, tables, and shell commands (no `go test -run <Name>`). 2. **Never reference spec-kit artifacts.** Nothing under `specs/`, `.specify/`, or any `artifacts/` folder, and no mention of `spec.md`, `plan.md`, `research.md`, `data-model.md`, `tasks.md` or `quickstart.md`. Those files are removed from the repository. Carry the substance across in your own words; the Decisions table has a "Why" column instead of a citation column for this reason. 3. **Two audiences, one file.** The body is a shared header, then a Product view, then a Developer view. Nothing in the Product view names a file. Nothing in the Developer view re-explains a use case. Decisions are written in user terms ("uploading never changes how traffic is routed"), not implementation terms. 4. **Decisions versus open questions.** A choice that was made goes in Decisions with its reason. A choice not yet made goes in Open questions with options, owner and needed-by. When a question is answered, move it. 5. **Limitations are rows with tracking.** Each row links an issue or says "Not yet filed". Delete the row when fixed. Never leave a stale row. 6. **`sources` lists what the feature owns.** Anyone changing a listed path is expected to update the document (see `.claude/rules/feature-docs.md`), so every entry must be a file or directory whose change would plausibly invalidate the document. Include: - files and directories created for the feature; - a shared file only when it implements a behaviour stated in Decisions (for example, the file that holds the resolution order or the fixed error body). Leave out: - shared files the feature only wires into (`main.go`, storage interfaces, event dispatch, xDS snapshot, config templates, Helm values); - tests, except the one end-to-end feature file that serves as the executable specification; - generated code (list the contract it is generated from instead); - extra SQL dialect files (list the SQLite schema file only; the dialects change together). Prefer one directory entry (trailing `/`) over listing every file in a feature-owned package. Every `sources` entry appears in Entry points. Entry points may also show shared files for orientation; mark those rows "(shared, not tracked)". Planned paths that do not exist yet are allowed and are reported as warnings. 7. **Minimal.** One sentence per idea. No history, no dates in the body, no planning narrative, no session notes, no branch names. No marketing words. 8. **Preserve what exists.** When updating a document, change only what the code or decision change invalidates. Do not restructure or re-flow unrelated sections. ## Checklist before finishing - Frontmatter has `type`, `title`, `description`, `resource`, `status`, `sources`. - `sources` has no tests other than the end-to-end feature file, no generated code, one SQL schema file, and no shared file unless Decisions depends on it. - `grep -nE "specs/|\.specify|artifacts/|spec\.md|plan\.md|research\.md|tasks\.md|data-model\.md|quickstart\.md"` on the file returns nothing. - No function, method, struct or test name appears anywhere in the file. - Section list is exactly: Use cases, Decisions, Scope, Current limitations, Open questions, Entry points, Examples. - `kb/<component>/index.md` and `kb/log.md` are updated. - The OKF validation reports the bundle conformant.