Erich Blume cb343a2e35 Rename doc-* mise tasks to docs-check-* / docs-review-* (#113 )

## Summary
- Rename 4 automated-check tasks: `doc-titles` → `docs-check-titles`, `doc-filenames` → `docs-check-filenames`, `doc-links` → `docs-check-links`, `doc-index` → `docs-check-index`
- Rename 3 interactive-review tasks: `doc-random` → `docs-review-random`, `doc-tags` → `docs-review-tags`, `doc-stale` → `docs-review-stale`
- Update all references in `.pre-commit-config.yaml`, `ai-assistance-guide.md`, and `review-documentation.md`
- Historical changelog entries left as-is

## Test plan
- [x] `mise run docs-check-titles` exits 0
- [x] `mise run docs-check-links` exits 0
- [x] `mise run docs-review-tags` exits 0
- [x] `mise run doc-titles` fails with "no task found"
- [x] All pre-commit hooks pass (including renamed hook IDs)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/113

2026-02-06 07:08:46 -08:00

2.2 KiB

Raw Blame History

title

Review Documentation

How to periodically review and maintain the BlumeOps knowledge base.

Quick Random Review

Select a random documentation card for review:

mise run docs-review-random

This displays a random card with a review checklist to guide your assessment.

Review Checklist

When reviewing a documentation card, consider:

Check	Description
Accuracy	Is the information current and correct?
Links	Are wiki-links working? Should more be added?
Scope	Is the card appropriately sized (not too large/small)?
Category	Is it in the right section (reference/how-to/tutorial/explanation)?
Frontmatter	Are title and tags appropriate?
Related	Should it link to related cards?

Verify Deployed State

For service reference cards, verify the documentation matches reality:

ArgoCD Apps (Kubernetes services)

Check if the app is synced and healthy:

argocd app get <app-name>
argocd app diff <app-name>  # Show pending changes

If out of sync, either the docs are stale or a deployment is pending.

Ansible Roles (indri services)

Check if the role applies idempotently (no changes needed):

mise run provision-indri -- --tags <role> --check --diff

If changes would be made, either the docs are stale or the host has drifted.

Pulumi (Tailscale ACLs, DNS)

Check for drift:

# Tailscale ACLs
cd pulumi/tailscale && pulumi preview

# DNS (Gandi)
cd pulumi/gandi && pulumi preview

If changes are pending, investigate whether docs or infrastructure is stale.

When to Review

Consider running mise run docs-review-random during:

Start of work sessions (quick maintenance)
After major infrastructure changes (verify docs reflect reality)
When learning the system (random exploration)

Making Changes

If a card needs updates:

Create a feature branch
Make the edits
Run mise run docs-check-links to verify links
Create a PR for review

See update-documentation for publishing changes.

update-documentation - Publishing documentation changes
exploring-the-docs - Navigating the documentation

2.2 KiB Raw Blame History