Also identify the current branch and remote tracking status:

git branch --show-current
git rev-parse --abbrev-ref @{upstream} 2>/dev/null

Classify uncommitted changes from git status:

If the working tree is clean but unpushed commits exist, this is the doc catch-up path:

Run git diff @{upstream}..HEAD --name-status to list all files changed in unpushed commits
Analyze those files in Step 2 as if they were uncommitted changes
Proceed to Step 3 to check for missing documentation updates (CHANGELOG, README, CLAUDE.md, marketplace.json)
If documentation updates are needed, make them, commit, and push
If no documentation updates are needed, just push

If both the working tree is clean AND no unpushed commits exist, report "nothing to ship" and stop.

Read every modified/untracked file (or every file from unpushed commits in the doc catch-up path) to understand the nature of the changes.

Path pattern	Type
`posts/`, `articles/`, `content/`	content/writing
`.claude/skills/`	skill config
`src/`, `.go`, `.py`, `*.ts`	code
`*.md`	documentation
`.json`, `.yaml`, `*.toml`	config
`Resources/`, `resources/`	resource list
`*.ipynb`	notebook
`.r2-upload-map/`	resource mapping (commit with related content)

For each applicable documentation file, read the current contents first, then update.

When: Always, if the file exists in the repo root
Format: Follow Keep a Changelog
Add a new ## [YYYY-MM-DD] section (today's date) at the top of the log
If today's date section already exists, append to it instead of creating a duplicate
Subsections: Added, Changed, Removed, Fixed — only include relevant ones
Each entry: one concise line describing the change from a user/reader perspective

When: Changes affect project structure, dependencies, code patterns, or repo organization
Skip when: Changes are limited to content additions (e.g., adding a link to Resources)
Update only the affected sections — do not rewrite the entire file

When: Changes affect content described by that README
Examples: adding a notebook -> update the directory's README; renaming a section -> update root README
Skip when: The change is self-evident from the file itself (e.g., adding a row to a resource table — the table IS the README)

After identifying all changed, added, and deleted files, check documentation files for stale or missing references:

Deleted files: Search README.md, CLAUDE.md, and any doc that might reference them (folder trees, file lists, dependency mentions)
Renamed/moved files: Update all path references
Removed features or dependencies: Remove or update mentions in all docs
New directories or files: If CLAUDE.md or README.md contain folder trees, check whether newly added directories or files should appear in those trees
Run: git diff --name-status to get the full list of added (A/??), deleted (D), and renamed (R) files, then search docs for entries that need adding or removing

If any other documentation file is directly affected by the changes, update it too

Examine the changes identified in Step 2 and choose a strategy:

Grouping priority (highest first):

Content directories — one commit per article/document unit (e.g., each notebook directory, each post)
Skill directories — one commit per skill (.claude/skills/<name>/)
Code changes — merge all code changes into one commit
Config / documentation files — merge into one commit

Rules:

.r2-upload-map/*.json files belong with their related content group, not standalone
Documentation updates from Step 3 (CHANGELOG, README, etc.) go into the commit of the group that triggered them
If all changes fall under one group, use a single commit regardless of file count

Generate one message per commit group from Step 4.

Follow conventional commits:

<type>: <description>

Types: feat, fix, refactor, docs, test, chore, perf, ci

Rules:

Examples by group type:

For each commit group (from Step 4), in grouping-priority order:

git add <group-file1> <group-file2> ...
git commit -m "<group-message>"

Repeat for each group until all changes are committed.

Rules:

Stage files explicitly — never use git add . or git add -A
Include the documentation files updated in Step 3 with the commit group that triggered them
Exclude temp files (*.bak-*, .DS_Store, node_modules/, .claude/)
.r2-upload-map/*.json files go with their related content commit, not standalone

git push

If no upstream is set:

git push -u origin <current-branch>

Run: git log --oneline -3

Display the commit hash and message to confirm success.

ship

Ship Skill