knowledge-ops

# Knowledge Operations

Knowledge bases do not fail by being incomplete. They fail by becoming untrustworthy: once a
reader has been burned twice by a confidently wrong page, they stop reading and start asking
in chat, and every subsequent doc you write is written into a void. This skill treats the KB
as an operational system with owners, freshness SLAs, and a measurable health score — not as
a writing backlog.

The core insight is that **deletion is the highest-value action available**. Most struggling
knowledge bases need 30% fewer pages, not more pages.

## When to use this skill

- The wiki is **large and distrusted** — people ask in chat rather than search, and are right to
- A **doc audit** is due before onboarding a cohort, an acquisition merge, or a compliance review
- **Search returns the wrong page** consistently, usually because three near-duplicates compete
- **Nobody owns** large parts of the KB and nobody can say what is current
- Planning a **documentation-debt sprint** and needing a ranked backlog rather than a wish list
- **Migrating** between wiki platforms and needing to decide what survives the move

## Inputs the skill expects

- A **doc inventory**: path, title, owner, last-updated date, and outbound links
- **Criticality tier** per doc, or enough signal (traffic, area) to infer it
- **Usage data** if available — 90-day views separate the load-bearing pages from the archive
- The **as-of date** for the audit, so results are reproducible
- Your **freshness SLA policy**, or acceptance of the default tiering below
- Whether **deletion is politically possible**, which changes the entire remediation plan

## Clarify First

Before generating, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Which docs are load-bearing vs archival** — a stale onboarding runbook is an incident; a stale 2019 retro is fine, and treating them identically produces a backlog nobody works
- [ ] **Whether pages can be deleted or only archived** — deletion authority roughly halves the remediation effort, so the plan differs structurally
- [ ] **Who can be assigned as an owner** — ownership assigned to a team alias rather than a person is the same as no owner, and the audit will keep reporting it
- [ ] **The as-of date for the audit** — staleness is relative, and an undated audit cannot be compared against the next one

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Workflows

### Workflow 1 — Score KB health

1. Build a doc inventory as JSON, or point the auditor at a directory of markdown with
   YAML frontmatter (`owner`, `updated`, `tier`).
2. Run the auditor with an explicit `--as-of` date so the run is reproducible.
3. Read the health score as a trend, not an absolute. A first run below 60 is normal;
   what matters is the direction across quarterly runs.
4. Triage the `critical` findings first — a stale critical-tier doc is the class of failure
   that causes real incidents.

```bash
python3 business-operations/knowledge-ops/scripts/kb_health_auditor.py \
  --input business-operations/knowledge-ops/assets/sample_kb.json \
  --as-of 2026-07-21 --format text
```

To scan a real directory of markdown instead:

```bash
python3 business-operations/knowledge-ops/scripts/kb_health_auditor.py \
  --root ./docs --as-of 2026-07-21 --format json
```

### Workflow 2 — Find orphans, dead links, and duplicates

1. Run the orphan detector over the same inventory. It builds the link graph and reports
   pages nothing links to, links pointing at pages that do not exist, and hub pages.
2. Cross-reference orphans against traffic. **An orphan with traffic is a findability bug**
   (people reach it by search or bookmark but the IA does not connect it). **An orphan with
   no traffic is a deletion candidate.** These need opposite fixes.
3. Fix dead links before anything else — they are cheap and they are the most visible
   signal of an unmaintained KB.

```bash
python3 business-operations/knowledge-ops/scripts/orphan_detector.py \
  --input business-operations/knowledge-ops/assets/sample_kb.json \
  --format text
```

### Workflow 3 — Build a ranked documentation-debt backlog

1. Run the debt ranker over the inventory. It scores each issue on value (traffic ×
   criticality × severity) and effort, then sorts into do-now / schedule / batch / drop.
2. Take the top 10 into a debt sprint. Do not attempt the whole backlog — the backlog is a
   measurement instrument, not a plan.
3. Re-run the auditor after the sprint with the same `--as-of` convention to show movement.

```bash
python3 business-operations/knowledge-ops/scripts/doc_debt_ranker.py \
  --input business-operations/knowledge-ops/assets/sample_kb.json \
  --as-of 2026-07-21 --top 10 --format text
```

## Decision frameworks

### Freshness SLA by tier [PROVEN]

Uniform review cycles fail because they generate more review work than any team will do, so
nothing gets reviewed. Tier the SLA instead.

| Tier | Examples | Review SLA | Stale at | Action when stale |
|------|----------|-----------|----------|-------------------|
| **Critical** | On-call runbooks, incident procedures, security policy, payroll process | 90 days | 120 days | Page the owner; a stale runbook is an incident risk |
| **Core** | Onboarding, architecture overviews, team charters, release process | 180 days | 270 days | Owner review ticket in the next sprint |
| **Reference** | How-tos, tool guides, FAQs | 365 days | 540 days | Batch review annually |
| **Archive** | Retros, past project docs, historical decisions | Never | Never | Mark archived; exclude from search and from the score |

The single most valuable configuration change in most knowledge bases is moving 40% of pages
into Archive and excluding them from search. Search quality is a ratio, and the denominator is
usually the problem.

### Orphan triage [PROVEN]

| Inbound links | 90-day traffic