Erich Blume
cb343a2e35
## 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
88 lines
2.6 KiB
Text
Executable file
88 lines
2.6 KiB
Text
Executable file
#!/usr/bin/env -S uv run --script
|
|
# /// script
|
|
# requires-python = ">=3.12"
|
|
# dependencies = ["rich>=13.0.0"]
|
|
# ///
|
|
#MISE description="Select a random documentation card for review"
|
|
"""Select a random documentation card for review.
|
|
|
|
This script scans all markdown files in the docs/ directory (excluding
|
|
changelog.d/), selects one at random, and displays it for review.
|
|
|
|
Useful for periodic knowledge base maintenance and verification.
|
|
|
|
Usage: mise run docs-review-random
|
|
"""
|
|
|
|
import random
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
from rich.console import Console
|
|
from rich.markdown import Markdown
|
|
from rich.panel import Panel
|
|
|
|
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
|
|
|
|
|
def get_all_docs() -> list[Path]:
|
|
"""Get all documentation markdown files, excluding changelog.d."""
|
|
docs = []
|
|
for md_file in DOCS_DIR.rglob("*.md"):
|
|
# Skip changelog fragments
|
|
if "changelog.d" in md_file.parts:
|
|
continue
|
|
docs.append(md_file)
|
|
return docs
|
|
|
|
|
|
def main() -> int:
|
|
console = Console()
|
|
|
|
docs = get_all_docs()
|
|
if not docs:
|
|
console.print("[bold red]No documentation files found![/bold red]")
|
|
return 1
|
|
|
|
# Select a random document
|
|
selected = random.choice(docs)
|
|
rel_path = selected.relative_to(DOCS_DIR)
|
|
|
|
# Display header
|
|
console.print()
|
|
console.print(Panel(
|
|
f"[bold cyan]{rel_path}[/bold cyan]\n"
|
|
f"[dim]{len(docs)} total docs in knowledge base[/dim]",
|
|
title="[bold]Random Documentation Card[/bold]",
|
|
border_style="cyan",
|
|
))
|
|
console.print()
|
|
|
|
# Display the file content
|
|
content = selected.read_text()
|
|
console.print(Markdown(content))
|
|
|
|
# Review checklist
|
|
console.print()
|
|
console.print(Panel(
|
|
"[bold]Review Checklist:[/bold]\n\n"
|
|
"• Is the information accurate and up-to-date?\n"
|
|
"• Are there broken or missing wiki-links?\n"
|
|
"• Should this card link to other related cards?\n"
|
|
"• Is the card too large and should be split?\n"
|
|
"• Is the card too small and should be merged?\n"
|
|
"• Does the frontmatter (tags, title) make sense?\n"
|
|
"• Is the card in the correct category (reference/how-to/etc)?\n\n"
|
|
"[bold]Verify Deployed State:[/bold]\n\n"
|
|
"• If ArgoCD app: is it synced? (argocd app get <app>)\n"
|
|
"• If Ansible role: does it apply idempotently? (--check --diff)\n"
|
|
"• If Pulumi: is there drift? (pulumi preview)",
|
|
title="[bold yellow]Review Guidance[/bold yellow]",
|
|
border_style="yellow",
|
|
))
|
|
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|