updating-internal-docs

Updating Internal Documentation

Review internal documentation files against the actual codebase state and propose fixes for outdated, incorrect, or missing information.

When to use

• After significant codebase changes (new features, refactors, tooling updates)
• When documentation drift is suspected
• After updating make targets, folder structure, dependencies, skills, or workflows
• When a PR adds or modifies Streamlit features — check if bundled skills (lib/streamlit/.agents/skills/) need updates

Key files to check

Priority files (most likely to contain codebase-specific instructions):

• **/AGENTS.md - AI agent instructions
• **/README.md - Package/directory documentation
• .claude/skills/*/SKILL.md - Skill definitions for Streamlit library development
• .claude/agents/*.md - Subagent definitions
• wiki/**/*.md - Developer wiki
• CONTRIBUTING.md - Contributor guide
• lib/streamlit/.agents/skills/*/SKILL.md - Bundled skills for Streamlit app development (shipped with the library)
• lib/streamlit/.agents/skills/*/references/*.md - Reference docs for bundled skills

Files to skip (synced copies, updated separately):

• .github/copilot-instructions.md
• .github/instructions/*.md
• .cursor/rules/*.mdc

Verification checklist

• Make commands exist and work (make help)
• File and folder paths exist
• Tool/dependency references are valid
• Tool version numbers match config files (see below)
• Testing instructions are correct
• Code examples match actual patterns
• Links resolve (internal and external)
• Skill/agent cross-references use current names
• .github/workflows/AGENTS.md reflects actual workflow files
• CONTRIBUTING.md skill/agent overview matches .claude/skills/*/ and .claude/agents/
• Bundled skills (lib/streamlit/.agents/skills/) reflect current Streamlit API and features

Bundled skills and feature changes

When a PR adds or changes a Streamlit feature (new widget, API change, deprecation, new capability), check if the bundled skills need updates:

• Reference docs in lib/streamlit/.agents/skills/developing-with-streamlit/references/ — update the relevant existing reference to document the new feature or API change

Common triggers for bundled skill updates:

• New st.* commands or widgets
• Parameter changes to existing commands
• Deprecated APIs or patterns (add warnings, remove outdated examples)
• New layout or theming capabilities
• Performance-related changes (caching, fragments)

Quick verification commands

# Check path exists: test -e path && echo ok || echo missing
# Check URL reachable: curl -sI -o /dev/null -w "%{http_code}" <url>

Tool version sources

Issue types

Workflow

1. Enumerate: Find all markdown documentation files
2. Verify: Cross-reference documented commands, paths, and examples against the codebase
3. Report: Present findings grouped by priority
4. Fix: Apply changes after user approval

Presenting findings

List all issues and let the user choose which to fix:

Documentation Review: {SCOPE}
═══════════════════════════════════════════════════════════════

Found {N} issues across {M} files:

1. [OUTDATED] AGENTS.md:42
   Current:  `make python-check`
   Actual:   Command renamed to `make python-lint`

2. [INCORRECT] wiki/testing.md:15
   Current:  Tests in `lib/tests/unit/`
   Actual:   Path is `lib/tests/streamlit/`

3. [BROKEN_LINK] CONTRIBUTING.md:88
   Current:  Link to `./docs/setup.md`
   Actual:   File does not exist

Which issues should I fix?
Recommended: "all"
Options: "1" | "1,2,3" | "all" | "skip 3"

Rules

• Verify before proposing: Always check the codebase before suggesting a fix
• Minimal changes: Only change what's actually wrong
• Test commands: Run commands before documenting them
• Keep style consistent: Match existing documentation style

After completing review

1. Present all findings to user
2. Get approval before making changes
3. Apply fixes incrementally
4. Run /checking-changes to validate

Example summary:

Fixed 3 of 4 issues:

- #1 [OUTDATED]: Updated make command in AGENTS.md
- #2 [INCORRECT]: Fixed test path in wiki/testing.md
- #3 [BROKEN_LINK]: Removed dead link in CONTRIBUTING.md
- #4 [INCONSISTENT]: Skipped - requires manual verification

Files modified:
  AGENTS.md         |  2 +-
  wiki/testing.md   |  4 ++--
  CONTRIBUTING.md   |  1 -