Kb Answer

KB Answer Workflow

Follow these steps in order for every question. For multiple independent questions, use parallel agents.

Prerequisites

Check that kb/ exists in the project root. If not, tell the user to run /setup-knowledge-base first.

Step 1: Navigate Using the Index

Always start by reading the KB index:

kb/index.md

The index provides:

• Keyword Lookup: find the right file by keyword
• Category overview: all files grouped by topic

If the index is empty or outdated, run the index script first:

python3 scripts/kb-index.py

Quick Navigation

1. Check the keyword lookup table for matching terms
2. Go to the matching file(s)
3. If no keyword match, browse the category that best fits the question. Categories can be nested (e.g., security/access/) — drill down into sub-groups when a broad category has them.

Step 2: Read Relevant Files

Based on the index navigation:

1. Read the most relevant file first
2. Check related: links in the frontmatter if the file references other entries
3. Read additional files if the first doesn't fully cover the question

Step 3: Search (if needed)

If the index doesn't point to the right file, run the search script to rank entries by keyword across title, tags, description, category, and body:

python3 scripts/kb-search.py "your keyword"

Options worth knowing:

• --category security restricts to a category (matches nested children like security/access too).
• --tag mfa filters by frontmatter tag (repeatable).
• --limit 5 caps results.
• --json for a machine-readable list (useful when chaining into another step).

Fall back to the Grep tool with path kb/ only if the search script misses a term (e.g., regex-only patterns).

Step 4: Check Active Scope

If kb/scopes/ contains scope files beyond _default.yaml:

1. Ask the user which scope applies (if not already established in this conversation)
2. Read the active scope file
3. Apply in_scope, out_of_scope, and notes to shape your answer

If only _default.yaml exists, skip this step.

Step 5: Formulate Answer

Answer Format

Yes/No questions: Start with "Yes" or "No", followed by 1 sentence.

Other questions: Answer directly in 1-3 sentences. Add detail only if needed.

If format requirements are provided: Follow them exactly.

Citation Requirements

Every claim in your answer MUST be backed by a literal quote from a KB file.

Format each citation as:

> "exact quote copied from the KB file"
> Source: kb/category/filename.md

Rules:

• Copy the quote character-for-character. Do not paraphrase, summarize, or rephrase.
• If you cannot find a literal quote supporting a claim, do not make that claim.
• Include markdown formatting verbatim. If the source says **Confidential**: ..., your quote must be **Confidential**: ..., not Confidential: .... If the source uses bullet list dashes, include them. Missing markdown is the #1 reason kb-verify.py flags citations. The script has a normalized-match fallback that will PASS with a warning, but strict mode will FAIL, so always copy formatting literally.
• For long passages, prefer quoting a single self-contained sentence. When a multi-line quote is unavoidable (e.g., a bulleted list that must be cited as one block), use the multi-line form:

  > "first line of the quote
  > second line
  > last line"
  > Source: kb/category/filename.md

  The verifier joins the > lines back into one quote and checks the whole block. Single-line blocks are still preferred for robustness.