Docs

---
description: "Document hygiene — find stale, obsolete, duplicate, and scattered docs. Sync, consolidate, update, or remove. Interactive."
---

# Document Hygiene

Scan, classify, and clean up documentation across the repo. Find stale content, remove obsolete files, sync documents that have drifted, and consolidate scattered docs into the right locations.

**Interactive.** Every destructive action requires user approval.

> Follows `rules/integrity.md` — evidence-based detection (I1, I7), no cosmetic fixes (I3 — sync the source of truth, don't paper over drift), state assumptions on `UNCLEAR` verdicts (I8).

**Input:** Consumer repo (current working directory).
**Output:** Cleaned documentation with a summary of changes.

---

## When to Use

| Situation | Skill |
|---|---|
| Periodic doc cleanup | **`/docs`** |
| First-time hashb setup | `/hashb:init` (handles stray-doc consolidation during onboarding) |
| Compliance check | `/hashb:audit` (reports doc issues but doesn't fix them) |
| Writing new documentation | Not this — just write it directly |

`/docs` is the ongoing-maintenance counterpart to `/init`'s one-time consolidation and `/audit`'s read-only detection. Run it when docs feel stale, scattered, or bloated.

**Subcommand flags** (skip irrelevant categories; wizard flow still applies):
- `/docs stale` — Staleness only
- `/docs sync` — Sync drift only
- `/docs sweep` — Obsolescence + Duplication only

---

## Execution Flow (MANDATORY)

> **This is the ONLY valid sequence. Never skip or reorder phases.**
> Each gate marked **STOP** requires completion before proceeding.

```
Phase 1: Inventory
    |
    v
STOP -- User confirms scope
    |
    v
Phase 2: Classify
    |
    v
STOP -- User reviews findings
    |
    v
Phase 3: Act (per-document approval)
    |
    v
Phase 4: Verify & Report
```

---

## Presentation Rules

Follow the shared formatting rules in `skills/shared/formatting.md`.

1. **Wizard flow** — present one phase at a time. Never dump everything at once.
2. **Progress indicator** — every output starts with:

```
/docs ═══════════════════════════════════════════════════════════

  ▸ Phase 1    Inventory
  ○ Phase 2    Classify
  ○ Phase 3    Act
  ○ Phase 4    Verify & Report

═════════════════════════════════════════════════════════════════
```

Update `▸` (current), `✓` (done), `○` (pending) as phases progress.

---

## Phase 1: Inventory

Discover every document in the repo and understand the current state.

### 1A · Collect All Documents

```bash
# Markdown (excluding vendor/generated)
find . -name "*.md" \
  -not -path "./node_modules/*" -not -path "./.git/*" \
  -not -path "./vendor/*" -not -path "./dist/*" -not -path "./build/*" \
  2>/dev/null | sort

# Other doc formats
find . \( -name "*.txt" -o -name "*.rst" -o -name "*.adoc" \) \
  -not -path "./node_modules/*" -not -path "./.git/*" 2>/dev/null | sort

# Doc directories
ls -d docs/ doc/ documentation/ wiki/ guides/ .github/ 2>/dev/null
```

### 1B · Collect Reference State

Gather sources of truth that documents should be consistent with:

```bash
# Actual stack (for README/Profile staleness checks)
cat package.json 2>/dev/null | head -60
cat requirements.txt pyproject.toml go.mod Cargo.toml *.csproj 2>/dev/null | head -40

# Git history (for CHANGELOG sync)
git log --oneline -30

# Current CLAUDE.md Profile (for drift detection)
cat CLAUDE.md 2>/dev/null

# Existing rules (for overlap detection)
ls rules/**/*.md 2>/dev/null

# Recent file deletions (to detect abandoned docs)
git log --diff-filter=D --name-only --pretty=format: -- "*.md" | head -20
```

### 1C · Present Inventory

```
DOC INVENTORY ───────────────────────────────────────────────────

  Total documents    {N}
  hashb-managed        {N} (CLAUDE.md, rules/, CHANGELOG, TODOS, KORE.md)
  Project docs       {N} (README, CONTRIBUTING, LICENSE, etc.)
  Other docs         {N} (docs/, guides/, scattered .md files)
  Doc directories    {list}

─────────────────────────────────────────────────────────────────
```

> **STOP.** "I found {N} documents. Want me to check all of them, or focus on a specific area (e.g., just stale docs, just scattered docs, just sync)?"

---

## Phase 2: Classify

Read every in-scope document and run the Hygiene Checklist against it. Every doc receives a verdict per category; combine if multiple apply. Subcommand flags narrow this to the matching category.

### Hygiene Checklist

| Category | Verdict values | Signals (any one triggers the verdict) |
|---|---|---|
| **Staleness** | CURRENT / STALE / UNKNOWN | Refs deleted files/functions · version numbers outdated · stack description ≠ actual deps · instructions reference removed commands · past dates with no follow-through · no git updates 6+ months on an active repo |
| **Obsolescence** | ACTIVE / OBSOLETE / UNCLEAR | Describes completed migration · temp/draft marker in name (`draft`, `tmp`, `old`, `backup`, `deprecated`, `archive`) · superseded by newer/more-complete doc · references only removed features · empty or boilerplate-only · orphaned (nothing references it) |
| **Duplication** | KEEP BOTH / MERGE / MOVE | Lives in wrong canonical location (see table below) · duplicates another doc's content (full or partial) |
| **Sync** | OK / DRIFTED (HIGH/MEDIUM/LOW) | `package.json` ≠ README stack · scripts ≠ README usage · Profile fields ≠ actual config · git tags ≠ CHANGELOG · rule `paths:` ≠ codebase · `.env` ≠ `.env.example` · rule cross-refs broken · `.gitignore` ≠ `.claudeignore` |

**Detection mechanics (one-line each):**

- Staleness — grep doc → codebase; compare versions/dates/commands; `git log -1 --format=%cr -- {file}` for last-touched.
- Obsolescence — pattern-match filename; check inbound references; scan content for completed-migration phrasing.
- Duplication — match doc topic against the canonical-locations table; flag any content overlap with another doc.
- Sync — diff each pair listed above; severity by user-impact (HIGH if it misleads, LOW if cosmetic).

### Canonical Locations (Duplication MOVE/MERGE targets)

| Content type | Expected hashb location | Common stray locations |
|---|---|---|
| Coding standards | `rules/conventions.md` | `CONTRIBUTING.md`, `STYLE_GUIDE.md`, `docs/standards.md` |
| Security | `rules/security.md` | `SECURITY.md`, `docs/security.md` |
| Testing | `rules/testing.md` | `TESTING.md`, `docs/testing.md` |
| Architecture | `rules/business/` or `rules/architecture.md` | `ARCHITECTURE.md`, `docs/architecture.md` |
| Git workflow | `rules/git.md` | `CONTRIBUTING.md` (git section), `docs/git-workflow.md` |
| API | `rules/api.md` or `rules/business/` | `docs/api.md`, `API.md` |
| Setup / onboarding | `README.md` + `KORE.md` | `GETTING_STARTED.md`, `DEVELOPMENT.md`, `SETUP.md` |
| Changelog | `CHANGELOG.md` | `HISTORY.md`, `RELEASE_NOTES.md`, `NEWS.md` |

### Findings Summary

Group findings by severity:

```
DOC HYGIENE FINDINGS ────────────────────────────────────────────

  CRITICAL ({N})    findings that cause active confusion or broken workflows
  HIGH ({N})        stale content that misleads, significant duplication
  MEDIUM ({N})      minor staleness, partial overlaps, sync drift
  LOW ({N})         cosmetic issues, orphaned but harmless docs
  CLEAN ({N})       documents that passed all checks

─────────────────────────────────────────────────────────────────
```

> **STOP.** "These are the issues I found. Want me to proceed with fixes, or adjust the plan?"

---

## Phase 3: Act

Process each finding interactively. Group by action type for efficiency, but approve each action individually.

### Action Templates

For each finding, present in this format and ask `[action / skip]`:

**OBSOLETE** (delete):
```
OBSOLETE: {file} ({N} lines)
  Why:       {obsolescence reason}
  Evidence:  {what was checked}
  Risk:      LOW — no references | MEDIUM — N references exist
  References to update: {file:line — the reference}, ...   (only if any)
  Action? [delete / keep / skip]
```

**STALE** (update in place):
```
STALE: {file}
  Issue:    {what's stale}
  Current:  {what doc says}
  Actual:   {what codebase shows}
  Fix:      {proposed update}
  Action? [update / skip]
```

Show the diff before applying:
```diff
- Node.js 16+ required
+ Node.js 20+ required
```

**SYNC DRIFT** (align with source of truth):
```
SYNC DRIFT: {doc} ↔ {source of truth}
  Source says:    {value}
  Document says:  {different value}
  Fix:            update {doc} to match {source}
  Action? [sync / skip]
```

**CONSOLIDATE** (merge or move):
```
CONSOLIDATE: {file} → {target}
  File:      {source path} ({N} lines)
  Target:    {hashb target path}
  Overlap:   {description}

  If MERGE: unique content (lines X-Y) → append to {target} · duplicated content (lines A-B) → discard · delete {source} · update references in {list}
  If MOVE:  move to {target path} · add `paths:` frontmatter · update references in {list}

  Action? [merge / move / keep both / skip]
```

### Execution Order

Process approved actions in this order to avoid conflicts:

1. **Sync** — update content in place (no file moves)
2. **Update** — fix stale content in place
3. **Merge** — combine files, then delete originals
4. **Move** — relocate files
5. **Delete** — remove obsolete files
6. **Reference cleanup** — update all references to moved/deleted/merged files

Verify each action's correctness before proceeding to the next.

---

## Phase 4: Verify & Report

### 4A · Post-Action Verification

| Check | Status |
|---|---|
| No dead references in CLAUDE.md | {pass / fail} |
| No dead references in README.md | {pass / fail} |
| All rule `paths:` still match files | {pass / fail} |
| CHANGELOG.md in sync with recent releases | {pass / fail} |
| `.env.example` in sync with `.env` | {pass / fail} |
| No orphaned documents remain | {pass / fail} |
| CLAUDE.md still under 200 lines | {pass / fail} |

### 4B · Summary Report

```
✓ DOC HYGIENE COMPLETE ──────────────────────────────────────────

  REMOVED       {file} — {reason}
  UPDATED       {file} — {what changed}
  SYNCED        {doc} ↔ {source} — {what was aligned}
  CONSOLIDATED  {source} → {target} — {merged / moved}
  KEPT          {file} — {reason}
  SKIPPED       {file}

  STATS
  ─────────────────────────────────────────────────
  Documents scanned   {N}
  Issues found        {N}
  Issues resolved     {N}
  Documents removed   {N}
  Documents updated   {N}
  Documents moved     {N}

─────────────────────────────────────────────────────────────────
```

---

## Next Step

| Condition | Next | Why |
|---|---|---|
| Cleanup complete | `/hashb:audit` | Verify cleanup didn't introduce compliance regressions |
| Structural drift surfaced (stale Profile, missing rules) | `/hashb:init` | Fix structural issues |
| Code-level findings surfaced (e.g., dead scripts referenced) | `/hashb:fix` | Address the underlying code |
| No issues found | — | Done |

**Next:** `/hashb:audit` (recommended — verify cleanup landed){· `/hashb:init` (if structural drift) — only when flagged · `/hashb:fix` (if code findings) — only when flagged}

**Autonomous mode (Compliance recipe):** `/audit` → `/docs` → `/init` → manual fixes → `/audit` (verify). Auto-proceed to `/init` when structural drift is the dominant finding category.

---

## Rules

- **Interactive.** Every destructive action (delete, merge, move) requires individual user approval. Updates and syncs show diffs before applying.
- **Preserve content.** Merges and moves relocate content — they never discard unique information. Only true duplicates are removed.
- **Source of truth wins.** When syncing, code/config/git is always the source of truth. Documents adapt to match reality, never the other way around.
- **Don't touch code.** This skill modifies documentation files only. If a doc issue reveals a code problem (e.g., missing scripts), report it — don't fix it.
- **Respect user decisions.** If the user says "keep" on something flagged, accept it. Don't re-flag in the same session.
- **Be specific.** Every finding needs a concrete reference — file path, line number, exact stale value vs. actual value. No vague "consider reviewing."
- **Idempotent within session.** Running `/docs` twice in a session should find no new issues (assuming no code changes between runs).
- **Git-aware.** Use `git blame`/`git log` for modification dates, not filesystem timestamps. Check git history to distinguish "intentionally stable" from "forgotten."
- **Scope to docs only.** This is not a linter, not a code review, not an audit. Code quality is `/hashb:review`'s job; compliance is `/hashb:audit`'s job.