# Update Docs

> 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.

- Skill: `matrixorigin/update-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add matrixorigin/update-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixorigin/update-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: matrixorigin (https://skillmd.com/u/matrixorigin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/matrixorigin/update-docs

---


# 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:
1. Run `gh pr view PR_NUMBER` to get title, description, and labels
2. Run `gh pr diff PR_NUMBER --name-only` to get changed files
3. 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"
1. Reads marker: `abc1234`
2. Finds 5 PRs merged since then
3. PR #500 changed `src/op/sirius_physical_hash_join.cpp` -> updates `operators.md`
4. PR #501 titled "Optimize sort partition" -> updates `optimizations.md`
5. Updates marker to current HEAD

Example 2: User says "update docs" but no changes affect Super Sirius
1. Reads marker, finds 3 PRs
2. All PRs are CI/build changes with no `src/` modifications
3. 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.