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

| Tool | Config file |

|------|-------------|

| TypeScript, React, Vite, Vitest, ESLint, oxfmt, Emotion | frontend/package.json |

| Yarn | frontend/package.json (packageManager field) |

| Python, Ruff, mypy, pytest | pyproject.toml |

| Node.js | .nvmrc |

Issue types

| Type | Description |

|------|-------------|

| OUTDATED | Info no longer accurate (old make targets, renamed files) |

| INCORRECT | Factually wrong (wrong paths, invalid commands) |

| VERSION_MISMATCH | Documented version differs from actual |

| MISSING | Important info not documented |

| BROKEN_LINK | Links to non-existent resources |

| INCONSISTENT | Conflicts with other docs |

Workflow

• Enumerate: Find all markdown documentation files
• Verify: Cross-reference documented commands, paths, and examples against the codebase
• Report: Present findings grouped by priority
• 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

• Present all findings to user
• Get approval before making changes
• Apply fixes incrementally
• 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 -