docs-align

Files (4)

• SKILL.md
• audit-checklist.md · references/
• writing-guide.md · references/
• audit-counts.sh · scripts/

SKILL.md (first lines)

# docs-align — Align all documentation with the codebase

## Overview
Audit every documentation file (`.md`) against the actual codebase, identify discrepancies,
and revise stale content so all docs accurately reflect the current code. Documentation must
be **clear, compact, jargon-free** — friendly to both humans and LLMs.

## When to use
Triggered by: "align docs", "sync documentation", "update README", "fix stale docs", "ensure
docs match code", "audit documentation", or any mention of docs being out of date vs the code.
Typically run after a major feature merge, a refactor, or before a release.

## Phase 1 — Parallel exploration (3 agents, simultaneously)

Launch 3 `Explore` agents in a **single message** (parallel) to build a complete picture:

### Agent 1: Code map
Map the current codebase structure. Focus on:
- Directory tree (`koboi/`, `tests/`, `configs/`, `examples/`, `docs/`, top-level files).
- File/module counts (use `find ... | wc -l`).
- New modules, new config sections, new CLI commands, new endpoints since the last doc update.
- Key public APIs (classes, functions, decorators, entry points).

### Agent 2: Doc inventory + staleness audit
Read every `.md` file that represents the codebase and cross-check against the code:
- `README.md`, `CLAUDE.md` (root), every `koboi/<subpackage>/CLAUDE.md`.
- `configs/CLAUDE.md`, `docs/architecture.md`, `docs/*.md` (skip pure planning/gap-analysis docs).
- For each file: list concrete discrepancies (wrong counts, missing modules, stale commands,
  missing config sections, dead references, broken examples).
- Verify counts with shell commands (`find`, `ls`, `grep`).

### Agent 3: Missing-coverage assessment
Identify subpackages/modules that have NO `CLAUDE.md` or doc coverage but should:
- Which `koboi/<dir>/` lack a `CLAUDE.md`?
- Are there new features with zero documentation?
- Are there examples that no longer exist or new examples not listed?

## Phase 2 — Consolidate findings

After agents return, synthesize into a **prioritized gap list**:
- **P0**: Wrong facts (counts, commands, module names) — factual errors that mislead.
- **P1**: Missing coverage (new subsystem with no docs; missing from directory map).
- **P2**: Stale style/examples (code examples that no longer work; references to removed files).
- **P3**: Optional polish (comment density, wording).

## Phase 3 — Gate new docs via AskUserQuestion

If the audit reveals that **new documentation files** should be created (e.g., a subpackage
missing a `CLAUDE.md`, or a new doc section), present the proposal via `AskUserQuestion`:
- List the proposed new files.
- Explain WHY each is needed (what gap it fills).
- Let the user approve/reject/modify before creating.

Do NOT create new doc files without this gate. Updating existing files does not require the gate.

## Phase 4 — Revise documentation

Apply the consolidated findings. For each file:

### Writing rules (non-negotiable)
- **Clear, compact, jargon-free.** No buzzwords. Write for a developer who is new to the project.
- **Imperative form** in procedural docs (CLAUDE.md, instructions). Third-person in descriptions.
- **Verify every claim** against the code before writing it. If unsure, check with `grep`/`find`/`Read`.
- **No duplication.** Information lives in ONE place. If a detail is in `architecture.md`, don't
  repeat it in `README.md` — link to it.
- **Compact.** README < 200 lines. CLAUDE.md < 300 lines. Folder CLAUDE.md < 100 lines.
- **LLM-friendly.** Use exact file paths, code blocks for structure, tables for quick reference.
  Avoid vague phrases ("various", "etc.", "and more") — be specific.

### What to fix per file type
- **README.md**: Features list, quickstart commands, config examples, examples table, architecture
  subsystem list, install instructions. The front door — must be accurate.
- **CLAUDE.md (root)**: Directory map (counts + new modules), Quick commands (all CLI subcommands),
  Gotchas (new conventions/gotchas from recent merges). The AI's primary reference.
- **`koboi/<subpackage>/CLAUDE.md`**: Module list, key abstractions, conventions, gotchas. Must
  match the actual files in the subpackage.
- **`configs/CLAUDE.md`**: Config list (all `.yaml` files), top-level sections list.
- **`docs/architecture.md`**: Subsystem graph, config-sections table, extension-points table,
  data-types. Must include new subsystems/sections.

### What NOT to touch
- Planning/gap-analysis docs (`docs/rest-sse-requirements.md`, `docs/server-adoption-gap-*.md`,
  `docs/eve-*.md`, `docs/skills-architecture-research.md`) — these are historical specs, not
  codebase docs. Leave them.
- Generated files (`docs/one-pager-api-platform.md` if marked SUPERSEDED).
- `benchmarks/results.json` (183MB — never read).

## Phase 5 — Validate

After revisions:
1. **Verify counts**: re-run `find koboi -name '*.py' | wc -l`, `ls configs/*.yaml | wc -l`,
   `ls examples/*.py | wc -l` — ensure the docs match.
2. **Check links**: any `docs/` or `examples/` references resolve to real files.
3. **Read each revised file** to confirm clarity + no jargon.
4. **Run `ruff` + `mypy`** — doc changes shouldn't affect code, but verify nothing broke.

## Phase 6 — Summary

Present:
- Files modified (list).
- Key changes per file (one-line summary).
- Any new files created (from the Phase 3 gate).
- Remaining gaps (if any were deferred).

## Additional resources

### Reference files
- **`references/audit-checklist.md`** — The exhaustive checklist for auditing each doc type.
- **`references/writing-guide.md`** — Detailed writing rules, examples of good vs bad doc prose.

### Scripts
- **`scripts/audit-counts.sh`** — Quick count of .py files, test files, configs, examples, CLAUDE.md coverage.

From hedypamungkas/koboi-agent, MIT.

More from hedypamungkas/koboi-agent