Structuring KB for best retrieval - what actually works?

Things that moved the needle for us:

1. One topic per file. Don't mix 'how to reset password' with 'how to change billing address' in the same doc. Splits retrieval.
2. H1 = the customer question, not the internal term. 'Why am I getting charged twice' beats 'Duplicate charge investigation runbook'. Customers phrase things their way, and the manifest generator picks up the h1 as a topic.
3. Include edge cases in the same file. Manifests track entities. If 'refund' and 'chargeback' both appear in the same doc, Jarvis will pull it for both topics.
4. No split procedures. If the fix is 10 steps, keep all 10 in one file. Cross-file procedures break when only half the files get loaded.
5. Examples > prose. Actual command snippets and payload samples retrieve better than abstract descriptions.

Also: resist the urge to split by team or by role. KB files should be organized by topic, not by who wrote them.