# Kb Sweep

> Orchestrates a knowledge base housekeeping sweep: checks KB size and git log to scope the work, then delegates to one or more knowledge-base-house-keeper agents. Use when the user wants to audit the KB for duplicates, conflicts, stale content, or broken references.

- Skill: `allyoushawn/kb-sweep` (Agent Skill)
- Install (CLI): `npx skillmds@latest add allyoushawn/kb-sweep`
- Raw SKILL.md: https://api.skillmd.com/api/skills/allyoushawn/kb-sweep/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: allyoushawn (https://skillmd.com/u/allyoushawn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/allyoushawn/kb-sweep

---


# KB Sweep — Orchestration Skill

You are the **lead**. You scope the work and delegate to `knowledge-base-house-keeper` agents. You do not do the auditing yourself.

## KB root

`/path/to/works/for/you/knowledge_base/`

## Phase 1 — Assess scope

Run these in parallel:

- Use the **Glob tool** with pattern `**/*.md` scoped to `/path/to/works/for/you/knowledge_base/` to list all markdown files (sorted by path). Count files from the results rather than piping `find` to `wc`.
- Use this shell command for recent git activity:
  ```bash
  git -C /path/to/works/for/you/knowledge_base log --oneline -30
  ```

Use this to build a `kb_structure_summary` (one-line description of each folder's purpose).

## Phase 2 — Decide partitioning strategy

| KB size | Strategy |
|---|---|
| ≤ 15 files | Single housekeeper — full KB as scope |
| 16–40 files | Split by top-level folder — one housekeeper per folder |
| > 40 files | Use git log to identify **recently changed areas** — sweep those first; assign one housekeeper per changed area, skip untouched areas |

**Git log heuristic for large KBs:** group recent commits by folder. Assign housekeepers to folders with activity in the last 20 commits. Flag untouched folders as "not swept this run" in the final report.

## Phase 3 — Delegate to housekeeper(s)

Spawn each housekeeper via the **Task tool** with `subagent_type: knowledge-base-house-keeper`.

Each housekeeper Handoff block must include:

```
kb_root: /path/to/works/for/you/knowledge_base/
scope: <list of files or directory path(s) assigned>
kb_structure_summary: <your summary from Phase 1>
fix_mode: report_only   # or "fix" if user asked for fixes
```

Spawn all housekeepers **in parallel** when multiple are needed.

## Phase 4 — Consolidate reports

Collect all housekeeper reports. Merge into a single summary:

```markdown
## KB Sweep Report

### Scope coverage
- Swept: <folders/files covered>
- Skipped (unchanged): <folders not swept>

### Issues by category
#### Duplicates (<N>)
...
#### Conflicts (<N>)
...
#### Stale (<N>)
...
#### Broken references (<N>)
...
#### Misplaced content (<N>)
...
#### Convention (<N>)
...

### Total: <N> issues across <M> files
```

(`Convention` = README/`log.md` contract issues reported by `knowledge-base-house-keeper`; may be zero.)

## Phase 5 — Propose actions

For each issue, propose a concrete action:
- **Duplicates**: recommend which file to keep and which to merge/delete (ask user to confirm before acting)
- **Conflicts**: surface both versions, ask user which is correct
- **Stale/broken**: offer to fix automatically if unambiguous
- **Misplaced**: propose move destination

If the user says "fix it", apply unambiguous fixes directly. For merges or deletions, always confirm first.

## Phase 6 — Record completion (cadence marker)

After the sweep finishes (reports consolidated, user acknowledged or session ends), **write** `/path/to/works/for/you/knowledge_base/.last_sweep` with a single line: ISO-8601 UTC timestamp of completion (e.g. `2026-04-18T12:00:00Z`). If the file exists, overwrite it. This file is used by the session startup checklist in `user_info/claude-workflow.md` to prompt a new sweep if older than 7 days.