documentation-manager

name	Documentation Manager
description	Use when writing or reviewing pynchy documentation, deciding where to document things, updating the docs, checking doc consistency, or fixing broken links. Covers information architecture, writing philosophy, tree-shaped navigation, doc-code coupling, no hard-coded usernames, extensibility framing for pluggable subsystems, and when to add code comments.

Documentation Manager

Helps decide where to document things and maintain consistency across Pynchy docs.

Style Guide

• Write for a user trying to achieve a goal. Don't chronicle the evolution of the codebase. Don't go into unnecessary technical details that are not relevant to the user's goal.
• Follow the Google Style Guide. Write in the present tense. Don't use "we" or "they". Write in the active voice. Don't use "is" or "are".
• Read docs/contributing/contributing-docs.md for the full documentation philosophy and information architecture rules.

Where to Document What

Quick decision tree:

New feature?

• Architecture decision → docs/architecture/ (find the relevant topic file, or create a new one)
• Installation requirement → docs/install.md
• Security implication → docs/architecture/security.md
• Development workflow change → .claude/skills/pynchy-dev/SKILL.md

Bug fix?

• If it needs install change → docs/install.md
• Usually: No doc update needed

Refactoring?

• If user-visible → Update relevant docs
• If internal only → No doc update

File Purposes

File	What Goes There
README.md	Philosophy, quick start, high-level overview
docs/install.md	Complete installation guide
docs/architecture/security.md	Security model, threat analysis
docs/architecture/index.md	Architecture overview and links to topic pages
docs/architecture/*.md	One topic per file (containers, routing, tasks, etc.)
.claude/skills/	Development context skills for Claude Code agents

Information Architecture Rules

1. Single source of truth — Every concept explained in exactly one place. Cross-link, don't duplicate.
2. Tree-shaped navigation — Root files have links + short summaries. Leaf files have the actual content.
3. Small, focused files — One topic per file. If it covers multiple concerns, split it.

Validation

Before committing:

# Check for broken links
uv run mkdocs build --strict

After moving/renaming files:

1. Search for all references to old name
2. Update each reference
3. Update mkdocs.yml nav
4. Test with uv run mkdocs build --strict

Common Mistakes

• Duplicating content across files (link instead)
• Chronological explanations ("First we tried X...")
• Mixing audiences (keep README brief, details in docs/)
• Forgetting to update references after renames
• Writing mega-files that cover multiple topics

Link Checking

Link validation runs automatically in prek hooks. If docs have broken links, the commit will fail.

To manually check: uv run mkdocs build --strict