| name | updating-internal-docs |
| description | Review internal documentation (*.md files) against the current codebase state and propose updates for outdated or incorrect information. |
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 definitionswiki/**/*.md - Developer wikiCONTRIBUTING.md - Contributor guidelib/streamlit/.agents/skills/AGENTS.md - Authoring instructions for bundled skillslib/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.claude/agents/reviewing-local-changes.md from ## Review Checklist onward (generated from scripts/assets/code-review-instructions.md)
If you edit a source AGENTS.md or scripts/assets/code-review-instructions.md, run uv run python scripts/generate_agent_rules.py so generated copies stay in sync.
Verification checklist
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:
- Read
lib/streamlit/.agents/skills/AGENTS.md before editing bundled skills. It decides which features get prominent guidance and how to update references, examples, routing, and public API summaries.
- Reference docs in
lib/streamlit/.agents/skills/developing-with-streamlit/references/ — update the relevant existing reference to document the new feature or API change
For periodic reviews, treat recently merged PRs as leads for documentation drift. Inspect those diffs, then verify the current code before updating docs. A merge does not by itself require a bundled-skill update; apply the prominence and scope rules in lib/streamlit/.agents/skills/AGENTS.md.
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
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
- Keep all documentation selective and brief: Not every codebase detail needs to be documented. Add information only when it is relevant to developer decisions, correct usage, maintenance, or preventing likely mistakes; do not expand docs with minor details merely for completeness.
- Prefer durable, high-level descriptions: Describe make commands and workflows briefly in terms of their purpose, trigger, and when to use them. Avoid documenting individual implementation steps, options, or mechanics unless they are important for correct use or maintenance.
- 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 -
