KnowledgeOps

KnowledgeOps is running an organisation’s working knowledge (answers to recurring questions, troubleshooting articles, runbooks, procedures) as an operated asset: captured while the work happens; owned, with a state and an audience; reviewed in proportion to risk; findable by people and AI assistants in their own words; and retired on purpose rather than left to rot.

A useful test: a new engineer hitting a known problem at 03:00 finds a current, validated answer in a minute, instead of waiting for the one person who knows or picking the wrong one of three conflicting pages.

Where to start. Beginners: glossary, Lab 1. Practitioners: playbooks, reference implementation. Leaders: decision framework, judgement call. Last verified 2026-10-23.

Without an operating model, knowledge fails in five ways:

• It stays in heads. Experts answer the same question again and again. In the professional-developer section of Stack Overflow’s 2024 survey, “61% of all respondents spend more than 30 minutes a day searching for answers or solutions to problems”, including asking colleagues and waiting^[7].
• It is written but not owned. On Google’s early internal wiki, “Because there were no true owners for documents, many became obsolete”^[8].
• It is owned but not findable. The answer uses the author’s vocabulary, not the asker’s.
• It is missing exactly when it matters. GitLab’s 2017 outage report notes that a key pg_basebackup behaviour “was not clearly documented in our engineering runbooks”^[9]; Atlassian’s 2022 review: “We have playbooks for product-level incidents, but not for the events of this scale”^[10].
• It leaks or misleads at machine speed. An AI assistant repeats whatever is stale and shows whatever its index can reach.

What good looks like. Google’s SRE book reports that a playbook written ahead of time “produces roughly a 3x improvement in MTTR as compared to the strategy of ‘winging it’” (MTTR: mean time to repair)^[11], one company’s experience. Consortium members report “50 - 60% improved time to resolution” after adopting KCS^[12], self-reported, so a ceiling to test, not a forecast.

• Not a product category. Buying a knowledge base does not create owners, states or review habits.
• Not ContentOps. The split is by origin, an editorial distinction shared with that page: knowledge captured while solving cases or running operations (KCS articles, runbooks) is KnowledgeOps, even when published to customers; editorially planned content is ContentOps.
• Not retrieval engineering or the self-service channel. KnowledgeOps owns what goes into a corpus or help centre (versions, states, access labels); LLMOps and SupportOps own what happens next.
• Not AI-agent memory. An agent skill named “knowledge ops” syncs files, memory stores and Git repositories^[13], a different sense of the words.

The label is recent; the practice is not.

• Tacit knowledge. Polanyi’s “we can know more than we can tell” (1966) and Nonaka and Takeuchi’s SECI model of converting tacit to explicit knowledge (1995) are the usual intellectual roots^[14].
• KCS rests on “more than thirty years of Consortium Member experience with KCS”, mainly in support^[6]. In April 2026 the Consortium announced Knowledge-Centered Success: a new name, a Solve Loop that begins with Reuse, a “proficiency model” instead of the “licensing model”, and no version number for the method; v6 certifications remain valid^[15][16].
• Standards. ISO 30401:2018 (amended 2022 and 2024) sets requirements for knowledge management systems; its revision, ISO/DIS 30401, closed its DIS ballot (stage 40.60) on 2026-09-18, so a new edition may follow^[5][17].
• The vendor label. V. Mary Abraham’s notes on a KMWorld Connect 2021 session (2021-11-16) have Pryon’s chief executive discussing “knowledge ops, an AI-enabled, process-oriented methodology”^[2]. ScreenSteps’ Greg DeVore wrote in 2023: “Instead of calling it just a knowledge base we refer to it as a knowledge operations platform”^[18]; ScreenSteps’ coinage claim is its own, and the 2021 use predates the earliest ScreenSteps use we found. Knowmax wrote “KnowledgeOps” as one word in August 2026^[3].
• AI assistants made freshness and access control a security concern^[19].

Mental model: knowledge is inventory that spoils. Each item has a carrying cost (someone must keep it true), a shelf life (its systems change) and a blast radius (the harm a wrong copy does). Stock what is demanded, rotate what spoils, label what is hazardous, and discard deliberately.

%%{init: {"flowchart": {"wrappingWidth": 150, "nodeSpacing": 18, "rankSpacing": 34, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  SRC["Where knowledge is born: tickets, incidents, chat answers, changes"]:::neutral
  KO["KnowledgeOps: capture, owners, states, review, findability, retirement"]:::core
  SRC --> KO
  subgraph USE["Who consumes it"]
    direction LR
    SUP["SupportOps: help centre, bots, deflection"]:::neutral
    LLM["LLMOps: retrieval, evaluation"]:::neutral
    INC["IncidentOps and SRE: runbooks in use"]:::neutral
  end
  subgraph RULES["Who sets adjacent rules"]
    direction LR
    CON["ContentOps: editorial content, same owner rules"]:::neutral
    PRI["PrivacyOps: deletion duties"]:::neutral
    ITO["ITOps: articles inside ITSM records"]:::neutral
  end
  KO --> USE
  RULES -.-> KO

These boundaries are this Atlas’s editorial distinctions.

No official KnowledgeOps manifesto exists; ScreenSteps publishes its own principles, such as “Performance First”^[28]. What follows is this Atlas’s proposal, built mostly on KCS and Google’s documentation practice.

1. Capture in the flow of work. KCS: “If we are creating articles after the request is resolved, we have missed vital information”^[29].
2. Write in the asker’s words. The issue statement records “the requestor’s view of what is happening”^[30]; insider terms become alternative labels.
3. Every live item has a current owner. “Documents without owners become stale and difficult to maintain”^[8].
4. Review follows risk. Reuse reviews what is used; rare, critical items need dates and rehearsal.
5. Goals on outcomes, never on activities. KCS says it in capitals: “DO NOT PUT GOALS ON ACTIVITIES!”^[31]
6. Access travels with the item. Audience labels are enforced in every copy and index.
7. Retire deliberately. Archive linked items, delete wrong unlinked ones, and always remove them from retrieval.

Trade-offs. Capture in the flow and coaching cost capacity while people learn^[32]; collective editing trades polish for speed; strict ownership adds a hand-off when people move.

• The knowledge item. KCS articles hold issue, environment, resolution and cause, plus metadata such as state, dates and use counts^[30].
• A metadata contract, checked by machine (reference implementation).
• Ownership: a person or group per item or domain, synced with the people directory.
• A review policy by tier (table below).
• Findability: the asker’s vocabulary, a light taxonomy (preferred and alternative labels, broader and narrower terms in SKOS^[27]) and failed-search analytics.
• Feedback: links, flags, search logs and assistant feedback, reviewed in the Evolve Loop.

The tiers are this Atlas’s proposal, encoded in the metadata tier field; governance uses KCS’s “Experience Based” and “Compliance Based” values^[22].

KCS has proficiency levels (Candidate, Contributor, Publisher), Coaches, Knowledge Domain Experts and a KCS Council; a coach looks after five to eight people at first and about fifty when mature^[33]. Runbooks and AI add operational roles:

R = responsible, A = accountable, C = consulted, I = informed. Proficiency is “not linked or related to the levels, job roles, or positions in an organization”^[33], so a senior engineer can be a Candidate.

KCS defines confidence states from Work in Progress to Archived; an article can move “from the Not Validated to Validated qualities several times throughout its life cycle”^[22]. Operations adds a flagged state and removal from every index on archiving.

stateDiagram-v2
  direction TB
  [*] --> WIP: issue captured, no answer yet
  WIP --> NotValidated: answer found, low confidence
  WIP --> Validated: answer confirmed, meets standard
  WIP --> [*]: nothing reusable, deleted
  NotValidated --> Validated: reused and confirmed
  Validated --> Flagged: a user finds it wrong
  NotValidated --> Flagged: a user finds it wrong
  Flagged --> Validated: owner fixes it
  Validated --> Archived: obsolete; removed from search and indexes
  NotValidated --> Archived: obsolete
  Archived --> Validated: restored

KCS argues for speed: “the value of support knowledge begins to diminish 30 days after the issue is first discovered”^[22], a claim from members’ experience, not a measured constant.

Escalation: an article that “poses an active risk of harming customers” goes to a Coach or domain expert at once, who unpublishes or archives it^[22].

The essential idea: one system of record per item, a machine-readable metadata contract, and every downstream copy treated as a derived view that can be reconciled against the record.

%%{init: {"flowchart": {"wrappingWidth": 140, "nodeSpacing": 16, "rankSpacing": 30, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef risk fill:#fbeceb,stroke:#b4332b,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  subgraph WORK["Systems where work happens"]
    direction LR
    TK["Tickets and incidents"]:::neutral
    CH["Chat"]:::neutral
    RP["Code repositories"]:::neutral
  end
  KB["System of record: knowledge base or docs repo; items with owner, tier, state, audience, version"]:::core
  REG["Owner register synced with the people directory"]:::core
  subgraph VIEWS["Derived views, rebuilt from the record"]
    direction LR
    SE["Search with synonyms"]:::neutral
    HC["Help centre for customers"]:::neutral
    AI["AI index: chunks keep id, version, audience"]:::risk
  end
  FB["Feedback: links, flags, failed searches, assistant logs"]:::neutral
  WORK -->|"capture, link"| KB
  REG --> KB
  KB --> VIEWS
  VIEWS --> FB
  FB -->|"Evolve Loop"| KB

Alternatives. Docs as code suits runbooks; a knowledge-base product suits support, with ticket links and external audiences. Many organisations run both and federate search; KCS accepts links to non-KCS content that is maintained, findable, accessible and in context^[23].

The KCS double loop: the Solve Loop runs inside each request, the Evolve Loop over many.

%%{init: {"flowchart": {"wrappingWidth": 130, "nodeSpacing": 16, "rankSpacing": 28, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef risk fill:#fbeceb,stroke:#b4332b,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  R["Request arrives; search in the asker's words"]:::core
  F{{"Relevant item found?"}}:::decision
  OK{{"Does it work as written?"}}:::decision
  L["Link it; add missing symptoms"]:::core
  FX["Fix it, or flag it if not allowed to edit"]:::risk
  W["Create a WIP item from the search terms"]:::neutral
  S["Solve; complete the item; set state"]:::core
  E["Evolve Loop: top links, gaps, duplicates, root causes"]:::neutral
  R --> F
  F -->|"yes"| OK
  F -->|"no"| W --> S
  OK -->|"yes"| L
  OK -->|"no"| FX --> L
  L --> E
  S --> E

Playbook: turning an incident into a runbook. Every incident review gets one knowledge action: create or fix the runbook that would have shortened it (trigger in the responders’ words, ordered checks, decision points, rollback), with a tier, an on-call owner and a rehearsal. Follow-up tracking is on IncidentOps.

Playbook: a duplicate cluster. The KDE picks the best item as canonical, merges unique symptoms and environments into it, archives the others (still viewable from linked tickets) and adds “see also” pointers. KCS treats uniqueness as “a critical part” of its content checklist^[34].

Some knowledge cannot be fully written down^[14]. Google: “Tribal knowledge exists in the gap between what individual team members know and what is documented”; the two “complement each other”, and the danger is a single point of failure, “A bottleneck that occurs when critical information is available from only a single person”^[37].

Playbook: an expert is leaving (Atlas proposal). Trigger: a resignation or role change, or an audit showing one person owns many tier-1 items. Owner: the expert’s manager, with the KnowledgeOps lead. Steps, within the notice period: (1) list the items they own and the questions only they answer (tickets and chat where they responded); (2) reassign every item; (3) run walk-through interviews for tier-1 and tier-2 procedures, written up by the successor so gaps show; (4) pair the successor on real work; (5) have the successor rehearse each tier-1 procedure. Output: a handover list, rewritten items (Not Validated until reused or rehearsed), a successor per domain. Acceptance: no live item owned by the leaver; every tier-1 item rehearsed by its new owner.

When knowledge should stay tacit. Fast-changing judgement and design taste spread more cheaply by pairing, rotation and swarming than by documents. Then the job is to record who knows and to stop single points of failure forming^[37].

Mandatory versus optional. None is mandatory unless a contract, certification or regulation requires it; regulated document-control rules set review periods for compliance-based items. KCS says ITIL “is a framework, not a methodology” and that KCS “plugs in” to it, especially incident management^[42].

Lock-in. Knowledge bases keep links, states and analytics in proprietary schemas: insist on exporting items with metadata and links, and test an export yearly.

Automate the crisp rules (overdue reviews, ownerless items, broken links, missing metadata, archived items still indexed) in scheduled jobs (Lab 1). AI changes two things:

1. Drafting. A draft from a ticket or incident timeline stays Not Validated until a proficient person confirms it.
2. Retrieval. An assistant answers fluently from whatever its index holds. Four controls follow:
   • Permission-aware retrieval. OWASP calls for “permission-aware vector and embedding stores”^[19]; Microsoft tells customers to ensure “the right users or groups have the right access to the right content”^[47].
   • Freshness and deletion. Index updates must meet compliance requirements “such as right to be forgotten requests”^[48]. Archiving is not enough until the index is rebuilt.
   • Trusted sources only. OWASP: “Accept data only from trusted and verified sources”^[19], hence a corpus allowlist.
   • Checkable claims. Anthropic’s guidance has the model cite a quote per claim and retract unsupported ones^[49]; that needs chunk IDs that map to stable item IDs and versions.

Retrieval tuning is on LLMOps; re-embedding cost on FinOps for AI.

A docs-as-code implementation for runbooks and procedures in one Git repository; a knowledge-base product follows the same contract through its API. Assumptions: GitHub, Markdown items with front matter, Python 3.8 or later on the runner.

1. The metadata contract. Every item’s front matter carries these fields. The Lab 1 audit enforces the first five; its stdlib parser reads flat key: value lines and drops # comments; production code should use a YAML library.

Example status: YAML syntax-checked by the validator, and parsed by the Lab 1 audit on 2026-10-23; field names are this Atlas’s proposal.

id: KB-105                  # stable; never reused, survives renames
owner: payments-oncall      # a person or group in the directory
tier: 1                     # 1 rare and critical, 2 periodic, 3 reused
state: validated            # wip, not_validated, validated, archived
last_reviewed: 2026-09-20   # set by the owner, in review
version: 7                  # incremented on every published change
audience: internal          # public, customers, internal, restricted
governance: compliance      # experience or compliance (KCS terms)
supersedes: [KB-071]        # items this one replaced

2. Ownership in the repository. CODEOWNERS requests review from owners when their files change; the last matching pattern wins. It works in public repositories on GitHub Free and in private ones on paid plans^[43]. Owner review is real only when “Require review from Code Owners” is enabled, owners (including teams) have write permission, and administrators cannot bypass the rule (“Do not allow bypassing the above settings”)^[43][50]. GitHub adds that “you also need to define an owner for the CODEOWNERS file itself”^[43]; /.github/ covers it and the workflow.

Example status: format checked against GitHub’s documentation; not executed.

# .github/CODEOWNERS  (last match wins)
*                         @example-org/knowledge-leads
/runbooks/payments/       @example-org/payments-oncall
/runbooks/dr/             @example-org/sre-dr
/procedures/payroll/      @example-org/payroll-ops
/.github/                 @example-org/knowledge-leads

3. Scheduled checks. Two independent weekly jobs: the audit and a link check. They are separate because the audit normally fails (its findings are the worklist), and a later step in the same job would be skipped under the default success() status check^[51]. Scheduled workflows run in UTC by default, on “the latest commit on the default branch”, and public repositories disable them after 60 days without activity^[52]. The lychee action fails its job on broken links by default^[53].

Example status: YAML syntax-checked; action versions are the latest releases on 2026-10-23 (checkout v7.0.1, lychee-action v2.9.0); not executed. kb_audit.py is the Lab 1 script; the directory URL is a placeholder.

name: knowledge-health
on:
  schedule:
    - cron: "30 6 * * 1"        # Mondays 06:30 UTC
  workflow_dispatch: {}
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    environment: directory-read  # the only place the directory token lives
    steps:
      - uses: actions/checkout@v7.0.1
      - name: Fetch active people and groups (never committed)
        env:
          DIRECTORY_TOKEN: ${{ secrets.DIRECTORY_READ_TOKEN }}
        run: >-
          curl -fsS -H "Authorization: Bearer $DIRECTORY_TOKEN"
          -o "$RUNNER_TEMP/roster.txt"
          https://directory.example.com/api/active-handles
      - name: Owners, tiers and review dates
        run: >-
          python3 tools/kb_audit.py "$RUNNER_TEMP/roster.txt" "$(date -u +%F)"
          runbooks procedures
  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7.0.1
      - uses: lycheeverse/lychee-action@v2.9.0
        with:
          args: --no-progress 'runbooks/**/*.md' 'procedures/**/*.md'

Design notes. The roster is fetched at run time into the runner’s temporary directory, so no staff list is committed for repository readers. The read-only token is a secret of the directory-read environment; environment secrets reach only jobs that reference the environment^[54], so the links job never sees it. Limit the environment’s deployment branches to the default branch, so other branches’ workflows cannot use it (in private repositories, environment secrets and deployment branches need a paid plan), and clear “Allow administrators to bypass configured protection rules”, which is on by default (Free, Pro and Team plans offer that switch only for public repositories)^[54]. Administrators can still reconfigure the environment^[55], so count them among the token’s readers. Run logs name departed owners and are readable by anyone with read access^[56]. An empty audit exits 2, so a wrong path fails loudly. It is not a pull-request check, which would block authors for others’ overdue items. Pin actions to commit SHAs if policy requires.

Three labs, runnable on a laptop with Python 3.7 or later and no network, on invented data. All three were executed on 2026-10-23 with Python 3.8.10 (Lab 1 again after its revision); the outputs shown are the real outputs.

Objective. Find items with missing metadata, departed owners or overdue reviews under the tier policy. Prerequisites. Python 3.7+, Bash. Cost and risk. None; it reads files only. Steps. Save the script as kb_audit.py, then run the generator: it creates seven items in nested folders (the CODEOWNERS layout above) and a roster, and audits them as of 2026-10-23.

Example status: executed on 2026-10-23 (Python 3.8.10).

"""Audit owners and review dates in Markdown knowledge items (stdlib only)."""
import re
import sys
from datetime import date
from pathlib import Path

REQUIRED = ["id", "owner", "tier", "state", "last_reviewed"]
WINDOW_DAYS = {"1": 90, "2": 180, "3": None}  # tier 3: reviewed on reuse only


def front_matter(path):
    """Flat 'key: value' lines between --- fences; '  # comments' dropped."""
    lines = path.read_text(encoding="utf-8").splitlines()
    if not lines or lines[0].strip() != "---":
        return {}
    meta = {}
    for line in lines[1:]:
        if line.strip() == "---":
            break
        key, sep, value = re.sub(r"\s+#.*$", "", line).partition(":")
        if sep:
            meta[key.strip()] = value.strip().strip('"')
    return meta


def check(meta, active, today):
    if meta["owner"] not in active:
        yield "owner not active: " + meta["owner"]
    if meta["tier"] not in WINDOW_DAYS:
        yield "unknown tier: " + meta["tier"]
        return
    try:
        age = (today - date.fromisoformat(meta["last_reviewed"])).days
    except ValueError:
        yield "bad date: " + meta["last_reviewed"]
        return
    window = WINDOW_DAYS[meta["tier"]]
    if window is not None and age > window:
        yield "tier %s overdue by %d days" % (meta["tier"], age - window)


def audit(dirs, roster_file, today):
    active = set(Path(roster_file).read_text(encoding="utf-8").split())
    findings, live = [], 0
    for path in sorted(p for d in dirs for p in Path(d).rglob("*.md")):
        meta = front_matter(path)
        missing = [k for k in REQUIRED if not meta.get(k)]
        if missing:
            findings.append((path, "missing " + ",".join(missing)))
        elif meta["state"] != "archived":
            live += 1
            findings += [(path, p) for p in check(meta, active, today)]
    return live, findings


if __name__ == "__main__":
    roster, as_of, dirs = sys.argv[1], date.fromisoformat(sys.argv[2]), sys.argv[3:]
    live, findings = audit(dirs, roster, as_of)
    for path, problem in findings:
        print("%-36s %s" % (path, problem))
    print("live items: %d, findings: %d" % (live, len(findings)))
    if live == 0:
        print("no live items found: check the directory arguments")
        sys.exit(2)
    sys.exit(1 if findings else 0)

Example status: executed on 2026-10-23 (Bash 5).

#!/usr/bin/env bash
set -uo pipefail
item() {  # path id owner tier state last_reviewed
  mkdir -p "$(dirname "$1")"
  printf -- '---\nid: %s\nowner: %s\ntier: %s\nstate: %s\nlast_reviewed: %s\n---\n' \
    "$2" "$3" "$4" "$5" "$6" > "$1"
  printf 'Body text.\n' >> "$1"
}
item runbooks/dr/failover.md      KB-101 sre-dr      "1 # rare" validated     2026-05-02
item runbooks/payments/restore.md KB-105 sam         1          validated     2026-09-20
item procedures/it/vpn-reset.md   KB-102 li          3          validated     2025-01-15
item procedures/payroll/cutoff.md KB-103 payroll-ops 2          validated     2026-08-30
item procedures/it/legacy-ftp.md  KB-104 dev         2          archived      2023-03-01
item procedures/it/laptop-enc.md  KB-106 li          2          not_validated 2026-02-10
printf -- '---\nid: KB-107\nstate: validated\n---\nNo owner.\n' > procedures/it/printer.md
printf 'sre-dr\nli\npayroll-ops\n' > roster.txt
status=0
python3 kb_audit.py roster.txt 2026-10-23 runbooks procedures || status=$?
echo "exit=$status"

Expected output (the last line is printed by the generator; exit code 1 because findings exist):

procedures/it/laptop-enc.md          tier 2 overdue by 75 days
procedures/it/printer.md             missing owner,tier,last_reviewed
runbooks/dr/failover.md              tier 1 overdue by 84 days
runbooks/payments/restore.md         owner not active: sam
live items: 5, findings: 4
exit=1

Validation. cutoff.md (tier 2, 54 days) and vpn-reset.md (tier 3) must not appear; archived legacy-ftp.md is skipped; the # rare comment does not break failover.md’s tier. Add sam to roster.txt: the owner finding disappears. An empty folder prints no live items found and exits 2. Troubleshooting. bad date: not YYYY-MM-DD; unknown tier: not 1–3; a byte-order mark before --- hides the front matter. Teardown. Delete the lab directory.

Objective. Compute link rate, known share, sampled link accuracy and the Content Standard Checklist score from a ticket export and a five-article sample. Prerequisites. Lab 1 environment. Cost and risk. None. Steps. Save both scripts and checklist.csv, generate tickets.csv, run kb_metrics.py.

Example status: executed on 2026-10-23 (Python 3.8.10).

"""Write tickets.csv: 40 closed tickets, 26 linked (19 existing, 7 new)."""
import csv

rows = []
for i in range(40):
    kind = "existing" if i < 19 else "new" if i < 26 else ""
    article = "KB-%d" % (100 + i % 6 if kind == "existing" else 200 + i) if kind else ""
    sample = ("no" if i == 3 else "yes") if i < 10 else ""  # 10 links sampled
    rows.append([f"T-{1000 + i}", article, kind, sample])
with open("tickets.csv", "w", newline="", encoding="utf-8") as handle:
    writer = csv.writer(handle)
    writer.writerow(["ticket_id", "article_id", "link_kind", "sample_ok"])
    writer.writerows(rows)

article_id,unique,complete,clear,title,links_valid,metadata
KB-201,yes,yes,yes,yes,yes,yes
KB-202,yes,no,yes,yes,yes,yes
KB-203,no,yes,yes,no,yes,yes
KB-204,yes,yes,yes,yes,yes,no
KB-205,yes,yes,yes,yes,yes,yes

"""Knowledge health metrics from a ticket export and a checklist sample."""
import csv
import sys


def ratio(part, whole):
    return part / whole if whole else float("nan")


def ticket_metrics(path):
    rows = list(csv.DictReader(open(path, newline="", encoding="utf-8")))
    linked = [r for r in rows if r["article_id"]]
    known = [r for r in linked if r["link_kind"] == "existing"]
    sampled = [r for r in linked if r["sample_ok"] in ("yes", "no")]
    accurate = [r for r in sampled if r["sample_ok"] == "yes"]
    return {
        "closed": len(rows),
        "link_rate": ratio(len(linked), len(rows)),
        "known_share": ratio(len(known), len(linked)),
        "link_accuracy": ratio(len(accurate), len(sampled)),
        "accuracy_sample": len(sampled),
    }


def checklist_score(path):
    """Content Standard Checklist %: misses weigh double (KCS convention)."""
    rows = list(csv.DictReader(open(path, newline="", encoding="utf-8")))
    checks = [k for k in rows[0] if k != "article_id"]
    possible = len(rows) * len(checks)
    yes = sum(r[k] == "yes" for r in rows for k in checks)
    return 1 - 2 * (possible - yes) / possible


if __name__ == "__main__":
    m = ticket_metrics(sys.argv[1])
    for key in ("closed", "link_rate", "known_share", "link_accuracy"):
        value = m[key]
        print("%-14s %s" % (key, value if key == "closed" else "%.1f%%" % (100 * value)))
    print("accuracy based on %d sampled links" % m["accuracy_sample"])
    print("checklist      %.1f%%" % (100 * checklist_score(sys.argv[2])))

Expected output of python3 make_tickets.py && python3 kb_metrics.py tickets.csv checklist.csv:

closed         40
link_rate      65.0%
known_share    73.1%
link_accuracy  90.0%
accuracy based on 10 sampled links
checklist      73.3%

Validation. By hand: 26 of 40 linked (65.0 %); 19 of 26 reuse an existing item (73.1 %); 9 of 10 sampled links accurate (90.0 %); 30 checks with 4 misses give 1 − 2 × 4 ÷ 30 = 73.3 %, below the 90 % at which KCS suggests coaching attention^[34]. Troubleshooting. KeyError means a header differs from the script; keep empty cells empty.

Teardown. Delete the files. Caution. Ten sampled links are far too few (sample size).

Objective. Before an index goes live, prove every chunk comes from a live item, at its current version, with an audience no wider than the item’s: the KnowledgeOps half of the LLMOps permission test. Prerequisites. Lab 1 environment; in real use, exports of the knowledge base and index manifest. Cost and risk. None here; in production, a blocking build step. Steps. Save the script and the two CSV files, then run the gate.

Example status: executed on 2026-10-23 (Python 3.8.10).

"""Block an AI index build whose chunks disagree with the knowledge base."""
import csv
import sys

RANK = {"public": 0, "customers": 1, "internal": 2, "restricted": 3}


def load(path, key):
    with open(path, newline="", encoding="utf-8") as handle:
        return {row[key]: row for row in csv.DictReader(handle)}


def gate(kb_path, index_path):
    kb = load(kb_path, "article_id")
    problems = []
    for chunk_id, chunk in load(index_path, "chunk_id").items():
        article = kb.get(chunk["article_id"])
        if article is None:
            problems.append((chunk_id, "article no longer exists"))
            continue
        if article["state"] in ("archived", "deleted"):
            problems.append((chunk_id, "article is " + article["state"]))
        if chunk["version"] != article["version"]:
            problems.append((chunk_id, "stale: v%s indexed, v%s current"
                             % (chunk["version"], article["version"])))
        if RANK[chunk["audience"]] < RANK[article["audience"]]:
            problems.append((chunk_id, "audience widened: %s -> %s"
                             % (article["audience"], chunk["audience"])))
    return problems


if __name__ == "__main__":
    found = gate(sys.argv[1], sys.argv[2])
    for chunk_id, problem in found:
        print("%-10s %s" % (chunk_id, problem))
    print("blocking problems: %d" % len(found))
    sys.exit(1 if found else 0)

article_id,version,state,audience
KB-101,4,validated,internal
KB-102,2,validated,customers
KB-103,7,archived,internal
KB-104,3,validated,restricted

chunk_id,article_id,version,audience
c-0001,KB-101,4,internal
c-0002,KB-102,1,customers
c-0003,KB-103,7,internal
c-0004,KB-104,3,internal
c-0005,KB-099,1,public

Expected output of python3 corpus_gate.py kb.csv index.csv; echo "exit=$?":

c-0002     stale: v1 indexed, v2 current
c-0003     article is archived
c-0004     audience widened: restricted -> internal
c-0005     article no longer exists
blocking problems: 4
exit=1

Validation. Fix the four rows (re-index KB-102 at version 2, drop c-0003 and c-0005, label c-0004 restricted): the gate prints blocking problems: 0 and exits 0. Troubleshooting. KeyError on an audience means an unknown label: rank it, never default it to public. Teardown. Delete the files. Limits. The gate checks labels, not query-time permissions, which LLMOps tests.

Two are documented real events; three are illustrative scenarios and say so.

A. Support team adopts KCS (illustrative scenario). Sixty agents; two writers publish articles months late. The team moves capture into the ticket form, starts agents as KCS Candidates with coaches, and lets reuse drive review. Trade-off: a capacity dip while coaching. Success: link accuracy ≥ 90 %, time to publish and known share falling. Pitfall: an article quota produces what KCS predicts: articles “created on the last few days of the month” with “little or no valuable information”^[57].

B. Runbooks for rare events (real lessons). GitLab’s 2017 report records that replication behaviour responders needed “was not clearly documented in our engineering runbooks”, and that a backup procedure had been silently failing^[9]. Atlassian’s 2022 review found playbooks for product-level incidents but none for an event of that scale; its actions include to “Conduct a quarterly audit to verify readiness at all times”^[10]. Method: tier 1, because demand never reviews knowledge nobody uses until the worst day. Trade-off: review cost for items rarely read. Success: rehearsal findings closed. Pitfall: reviewing on paper only; a rehearsal finds the step that no longer works.

C. Engineering docs move to source control (real). Google moved important documentation from its GooWiki into source control, where “Documents began to have their own owners, canonical locations within the source tree, and processes for identifying bugs and fixing them”; documentation “began to dramatically improve”, and freshness metadata sends reminders when a document “hasn’t been touched in, for example, three months”^[8]. Pitfall: engineers feared the higher bar to edit would hurt quality; the book reports it did not^[8].

D. AI assistant over internal knowledge (illustrative scenario). The assistant shows only what each user can open^[47], so the risk lies in the permissions: a restricted salary procedure saved in an open space is one prompt away for everyone. The judgement call works through the method. Trade-off: coverage starts small. Success: zero restricted answers in quarterly red-team prompts; the “no answer” rate falls as domains join. Pitfall: adding domains without the gate because the first month went well.

E. Chat answers become runbooks (illustrative scenario). A platform team answers the same questions in its help channel every week. Each Friday the on-call engineer lists questions answered twice; the team lead assigns each to an owner, who writes or fixes an item in the asker’s words, and the channel answers with links from then on. Trade-off: writing time. Success: repeat questions per week fall. Pitfall: pasting chat threads into a wiki unedited, with no owner, no tier and one conversation’s context. Chat mechanics are on ChatOps.

KCS separates activities (leading indicators, never goals) from outcomes (lagging, goal-worthy) and triangulates them with the Content Standard Checklist; an indicator that is “Easy to measure and easy to manipulate or game” is probably an activity^[57].

Targets with evidence. For credible input to product teams KCS wants “link rates that exceed 60% and link accuracy that exceeds 90%”^[34]; for assisted support its ideal is “85% new”^[31]. Both come from support experience.

Sample size (Atlas arithmetic). A sampled accuracy p from n links has a 95 % margin of about 1.96 × √(p(1 − p) ÷ n): at p = 0.9, ±8 points for 50 samples and ±5 for about 140. Fifty links cannot tell 85 % from 90 %.

Worked example (illustrative). One month: 2,000 closed tickets, 1,240 linked: link rate 62 %. A coach samples 80 links; 68 resolve the issue: accuracy 85 %, ±8 points (77–93 %), so the 90 % bar is not shown; fix search and coaching and sample more before any product report. 930 links reuse an existing item: known share 75 %, so publish those items to customers (with SupportOps) rather than write more. 31 of 40 tier-1 runbooks were reviewed within 90 days: freshness 77.5 %, a gap to escalate.

Data limitations. Accuracy needs human sampling; self-service success needs click-path or survey methods^[31].

Evidence retention. To show what you told someone, keep the version delivered: KCS suggests a snapshot in the incident or article version control^[22]. Legal duties differ by jurisdiction; PrivacyOps and ComplianceOps own them.

The costs are mostly people’s time:

• Capture and coaching cost capacity in each adoption wave^[32].
• Review. Calendar review scales with item count, reuse review with demand. Illustrative, at 10 minutes per review: 3,000 items once a year cost 500 hours; 50 tier-1 items four times and 100 tier-2 items twice a year cost about 67 hours, plus rehearsals.
• Re-indexing. An embedding “must be recomputed whenever the document changes or whenever the embedding model is upgraded”, a significant recurring cost at scale^[58]; see FinOps for AI.
• Benefits need your own baseline before you claim them.

Beyond the KPIs:

• Process Alignment Review: “how well and how often knowledge workers are contributing to the Solve Loop”^[21].
• Stagnation. KCS warns that “the system slowly dies” when articles stop flowing to self-service and participation drops^[22]; watch the monthly snapshot of states and time to publish.
• Rehearsal findings for tier-1 items, tracked like incident actions.
• Index reconciliation results (Lab 3) on every build, plus a quarterly red-team of the assistant with restricted questions.
• Owner hygiene: ownerless ratio after every reorganisation.

Situation (illustrative). The internal assistant answers “how do I get a production database credential?” with the old ticket-based process and cites a page the platform team archived last month. Two people have already sent requests to an unmonitored queue.

%%{init: {"flowchart": {"wrappingWidth": 140, "nodeSpacing": 16, "rankSpacing": 28, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef risk fill:#fbeceb,stroke:#b4332b,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  A["1 Report: answer cites item KB-412"]:::risk
  B["2 Trace chunk id to item id, version, state, audience"]:::core
  C{{"3 Is the source archived, outdated or wider than its audience?"}}:::decision
  D["4 Contain: delete the chunks; block the item id at query time"]:::risk
  E["5 Correct: tell people who acted; fix or point to the current item"]:::core
  F["6 Find the gap: why did archiving not reach the index?"]:::core
  G["7 Prevent: gate every build; add a test case"]:::core
  H["Content is current: route to LLMOps as a retrieval fault"]:::core
  A --> B --> C
  C -->|"yes"| D --> E --> F --> G
  C -->|"no"| H

What the figure leaves out:

1. Trace: chunk → KB-412, version 6 indexed, archived since 2026-09-28.
2. Contain within the hour; search the index for copies under other ids (a team wiki had pasted the text).
3. Correct: tell the two requesters the current route, check the queue, add a “retired, see KB-530” banner.
4. Root cause: the index sync handled edits but not state changes. A restricted item makes this a data exposure for security and PrivacyOps.
5. Prevent and verify: Lab 3 gate as a blocking step and an LLMOps regression case; re-ask and expect KB-530 cited.

• “Write everything down.” Unowned documents become obsolete^[8]; capture what is demanded.
• Article quotas. Goals on activities “corrupt the knowledge base”^[57].
• Annual review of everything. Wastes effort on unused items and misses the runbook that changed last month.
• Shrinking the base to fix search. KCS calls archiving old articles treating “the symptoms of findability, not the cause”^[59]. (AI corpora differ; see the judgement call.)
• The hero expert. KCS: “The new hero in the organization is the person who creates value through their contribution to the knowledge base”^[34].
• “The AI will organise it.” An assistant inherits your permissions and your stale pages^[47][48].

Use it when the same questions recur, when people wait for a few experts, when onboarding is slow, when incidents last longer because procedures are missing, or before connecting an AI assistant to internal content.

Do not invest in a programme when the work is mostly novel, when a handful of people sit together, or when the knowledge changes faster than anyone can write it (then pair or swarm). KCS says the key value factor is “the degree to which knowledge or experience plays a role in responding to user’s or customer’s requests for assistance”^[32]. Hidden costs: coaching, owners’ review time, tool integration, and the politics of removing activity quotas. Alternatives: a well-owned FAQ, recorded walkthroughs, or pairing.

The key decision is which review engine each class of knowledge gets; the tree is this Atlas’s proposal.

%%{init: {"flowchart": {"wrappingWidth": 140, "nodeSpacing": 16, "rankSpacing": 28, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  Q1{{"Could following a wrong copy cause serious harm?"}}:::decision
  Q2{{"Is it used at least monthly?"}}:::decision
  Q3{{"Does it change on a known schedule or with known systems?"}}:::decision
  T1["Tier 1: 90-day owner review plus rehearsal; compliance-based edits"]:::core
  T2["Tier 2: review on every dependent change, 180-day backstop"]:::core
  T3["Tier 3: reuse is review; archive on obsolescence"]:::neutral
  Q1 -->|"yes"| Q2
  Q1 -->|"no"| Q3
  Q2 -->|"no"| T1
  Q2 -->|"yes"| T2
  Q3 -->|"yes"| T2
  Q3 -->|"no"| T3

For tool choice, weight: ticket or incident linking, export with metadata and links, and an audience and state model (high); verification reminders and failed-search analytics (medium); AI features (low until the basics work).

This Atlas’s model, not an official one. ScreenSteps publishes three stages (Tribal, Document, Guide)^[60]; KCS describes adoption phases (Plan and Design, Adopt in Waves, Build Proficiency, Optimize and Innovate)^[32].

Quick start

• One domain, a named KnowledgeOps lead and a sponsor
• Metadata contract published; tiers defined; audit (Lab 1) running weekly
• Linking available in one click from tickets or incidents

Before connecting an AI assistant

• Corpus allowlist by domain, state and audience; nothing ownerless
• Index chunks carry item id, version and audience; Lab 3 gate blocks the build
• Archive and deletion reach the index within an agreed time; erasure route agreed with privacy
• Red-team prompts for restricted content run before launch and quarterly

Monthly review

• Scorecard reviewed (metrics), with sample margins
• Ten worst failed searches turned into items or synonyms
• Duplicates merged; flags older than 14 days resolved; no tier-1 domain with a single capable person

Item template (KCS-style structure: issue in the asker’s words, environment, resolution, cause^[61]):

Title:        <main issue> on <main environment>
Issue:        <the asker's words; exact error text in quotes>
Environment:  <product, version, platform; one per line>
Resolution:   1. <present-tense step>  2. <step>
Cause:        <optional; one cause per item>
Metadata:     id | owner | tier | state | audience | last_reviewed | version

Tier-1 review form

Item / version:      KB-____ v__        Reviewer (owner): ________
Systems it touches:  ________  Changed since last review?  yes / no
Walked through on:   paper / staging / game day (date ____)
Steps that failed or were unclear: ________
Outcome:  confirmed | corrected (new version __) | archived
Next review due:     ____-__-__   Next rehearsal: ____-__-__

Retirement request

Item: KB-____   Requested by: ____   Reason: obsolete | duplicate | wrong
Replacement item: KB-____ (or none)   Linked records exist? yes / no
Action: archive (linked) | delete (unlinked and wrong)
Remove from: search | help centre | AI index (verify chunk count = 0)

Two maintenance philosophies disagree. Google advises “Default to delete or leave behind if migrating”^[62]; KCS says “Archiving an article is better than deleting it” when tickets link to it^[22]. Deletion suits unlinked engineering pages; archiving suits items in a service record.

Is KnowledgeOps a job title? Rarely. ScreenSteps names a “Knowledge Ops Manager”^[1]; most say knowledge manager or KCS programme lead.

Is KCS only for customer support? No. Members are “adopting KCS across their entire company, including HR, legal, marketing, sales, product management and development organizations”^[6], though the evidence comes mostly from support.

Do we need ISO 30401 certification? Only if a customer or regulator asks for it. You can adopt the management-system discipline without certifying, and a revised edition is close (as of October 2026)^[17].

Our most experienced engineer leaves in a month. What first? Reassign everything they own this week, then walk-through interviews and pairing for their tier-1 procedures (tacit knowledge).

Can AI write our knowledge base? It can draft from tickets and incidents; drafts stay Not Validated until a proficient person confirms them. Volume without validation is an activity goal in disguise.

• Knowledge-Centered Success (new edition): certifications roll out in late 2026 and 2027^[16].
• Knowledge graphs (established technique, uneven practice): SKOS-style vocabularies link items, systems and terms^[27]; most teams need synonyms first.
• Agentic assistants that edit knowledge (emerging): “Empower to Improve” in the new KCS guide includes “permissioned people and systems”^[20]; an editing agent needs the same proficiency rules as a person.
• Answer-level freshness (speculative): a corrected item invalidates past answers that cited it. Little published practice exists.

• Decide: which domains first; tier policy; who owns what; goals on outcomes only.
• Practise: search early, link, flag or fix, capture in the asker’s words, rehearse tier-1 runbooks, hand over before people leave.
• Measure: the scorecard, with sample margins.
• Tool classes: knowledge base with verification; docs as code with CODEOWNERS; link and metadata checks; gated AI index.
• Watch out: article quotas, annual review of everything, experts leaving unannounced, archived items in AI indexes.
• Next action: run Lab 1 against your real repository this week.

Situation (illustrative). A 3,000-person company switches on an internal assistant in six weeks. Its wiki holds about 40,000 pages; a third have no active owner, and nobody knows how many are restricted but openly shared. Option A (the vendor’s default): index everything users can open; clean up as complaints arrive. Option B: index an allowlist of owned, labelled domains (about 6,000 items) and grow it monthly.

Assumptions. The assistant trims results to each user’s permissions^[47]; wiki permissions are loose; leadership will judge the launch by month-one coverage.

Reasoning. (1) Worst failure. A: an over-shared restricted page is one question away for everyone, and stale pages answer fluently. B: “I don’t know” outside the allowlist. (2) Does demand-driven cleanup rescue A? “Reuse is review” works because a trained responder judges each article in context^[24]; an assistant user sees a fluent paragraph without age or state, so errors surface only after someone acts. (3) Cost of B. Lower launch coverage, owner work on 6,000 items. (4) What would change the answer. Recently audited permissions and mostly owned content.

Decision: B, with the wiki’s ordinary search, which shows dates and authors, left for everything else. The attractive choice, A, buys coverage with risks invisible until the first leak. Uncertainty: how fast the allowlist can grow; let weekly “no answer” questions choose the next domains.

After this page you can explain the label and its boundaries, design a metadata contract and tier policy, operate the Solve and Evolve loops, measure knowledge health without quotas, retain an expert’s knowledge, and evaluate a corpus before an AI launch.

“KnowledgeOps” is a vendors’ word for an old problem. It adds no new method: the method is knowledge management, codified for service work by KCS. The operations framing helps: run knowledge as an operated asset, with owners, states, service levels and incident handling. The hard part is choosing which knowledge needs calendar review, keeping owners real as people leave, and making every copy, especially the one an AI reads, carry an item’s state and audience. Product facts are dated October 2026; re-check them, and the KCS facts once the 2027 certifications ship.

Ledger: research/knowledgeops-ledger.md. KCS library pages show no dates; “v6” marks the KCS v6 Practices Guide, “KCS 2027” the Knowledge-Centered Success guide published in 2026.

Changelog. 2026-10-23: first complete draft (Blueprint v2, 13 H2 parts, six diagrams, three executed labs); term status vendor-specific confirmed; KCS facts updated for the April 2026 Knowledge-Centered Success edition. 2026-10-23 (r1 revision): Lab 1 audit recurses, strips comments, fails on zero items; two-job workflow, roster fetched at run time; tacit-knowledge section; 2021 “knowledge ops” use, ISO status; encodable tiers; KCS departure stated; shortened. 2026-10-23 (final-QA revision): empty footnote fixed; environment administrator-bypass precondition; KCS “proficient” wording; trimmed. 2026-10-23, post-score polish: UTC “by default”; paid-plan note covers environment secrets; three-column methods table.