| name | update-docs |
| description | Use this skill to update Super Sirius documentation after code changes. Trigger when the user says "update docs", "refresh documentation", "sync docs with code changes", or after merging PRs that changed the Super Sirius codebase. Inspects merged PRs since the last update and patches affected doc files.
|
Update Super Sirius Documentation
Instructions
Step 1: Read Last Update Marker
Read docs/super-sirius/README.md and extract the commit hash from the HTML comment at the bottom:
<!-- last-updated-commit: COMMIT_HASH -->
If no marker exists, ask the user which commit to start from, or default to the initial docs commit.
Step 2: Identify Changed PRs
Run git log --oneline --merges LAST_COMMIT..HEAD to find merge commits.
Run gh pr list --state merged --limit 100 --base dev to list merged PRs.
Cross-reference to find PRs merged since the last update.
Step 3: Inspect Each PR
For each PR found:
- Run
gh pr view PR_NUMBER to get title, description, and labels
- Run
gh pr diff PR_NUMBER --name-only to get changed files
- Classify the PR using the change classification guide in
references/change-classification-guide.md
Step 4: Update Documentation
For each classified change:
- Component rename/restructure: Update class names, file paths, method names in affected docs
- Functional/design changes: Update the relevant component document with new behavior
- New operators: Add to
operators.md; if custom get_next_task_hint(), also update task-creator.md
- New optimizations: Add entry to
optimizations.md with: PR#, motivation, mechanism, code path, config
- Pipeline splitting changes: Update
physical-plan-generation.md Part 3
- Config changes: Update
configuration.md
CRITICAL: Read the actual source code for any changed files before updating documentation. Do not guess based on PR titles alone.
IMPORTANT: Present proposed changes one file at a time for user review. Do not apply all changes at once. Show the user what will change in each file and wait for approval before proceeding to the next file.
STYLE: Do not use changelog language ("replaced X with Y", "extracted from", "previously X, now Y"). Describe the current design as-is. These are reference docs, not a changelog. Only include PR numbers in optimizations.md entries.
DEPTH: Keep descriptions at the right level of abstraction for the doc file. Don't add overly detailed implementation specifics (e.g., specific deadlock fixes, internal bug fixes) — focus on concepts, interfaces, and behavior that a developer reading the docs needs to understand.
Step 5: Update Commit Marker
Replace the commit hash in docs/super-sirius/README.md:
<!-- last-updated-commit: NEW_HEAD_HASH -->
Step 6: Report Summary
Print a summary of:
- Number of PRs inspected
- Which doc files were updated
- What was added/changed in each file
- Any PRs that were skipped (e.g., build-only, CI changes)
Examples
Example 1: User says "update the docs"
- Reads marker:
abc1234
- Finds 5 PRs merged since then
- PR #500 changed
src/op/sirius_physical_hash_join.cpp -> updates operators.md
- PR #501 titled "Optimize sort partition" -> updates
optimizations.md
- Updates marker to current HEAD
Example 2: User says "update docs" but no changes affect Super Sirius
- Reads marker, finds 3 PRs
- All PRs are CI/build changes with no
src/ modifications
- Reports "No documentation updates needed" and updates marker
Common Issues
No commit marker found
If docs/super-sirius/README.md doesn't contain the marker comment, ask the user which commit to use as baseline, or use git log --oneline docs/super-sirius/ | head -1 to find when docs were last modified.
PR diff too large to inspect
For PRs with 50+ changed files, focus only on files matching the source paths in the classification guide. Skip test files, build files, and third-party changes.
Ambiguous changes
If a PR touches multiple areas, update all affected docs. If unsure whether a change warrants a doc update, err on the side of updating.
