/ship

What it does

Reads git status, git diff, and git diff --cached. Categorises changes. Auto-updates relevant docs itself instead of just asking. Validates every  citation in docs/** is still accurate. Drafts a why-focused commit message.

When to use

Before every commit that touches multiple files, especially after sessions with:

Schema changes
API additions/modifications
External service integration
Design choices
Non-obvious bug fixes

Smart doc updates

When routes, components, or schema change, /ship offers to update the relevant doc itself:

/api/invite changed — update docs/api.md?

Preview:
  ### POST /api/invite (updated)
  Rate limit: 5 requests/min/user (429 on exceed)
  <!-- src: app/api/invite/route.ts:8-65 -->

Add to docs/api.md? (y/n/edit)

Citation validator

Walks every docs/**.md and re-checks each  marker. Flags:

Files that are gone
Line ranges out of bounds

Doesn’t block commit — just warns.

Adaptive checklist

Skips items that don’t apply. Only asks about the things your diff actually touched:

Code changed → run tests / type checker / linter
API route changed → update docs/api.md (auto-offered above)
Schema changed → migration tested? docs/database.md updated? backfill plan?
External service added → docs/integrations.md updated?
Non-obvious bug fixed → add to KNOWN-ISSUES.md with prevention rule
Gap shipped → mark shipped YYYY-MM-DD (commit: <hash>) in docs/*-GAPS.md

Commit message drafting

Reads the last 5 commit messages to match your project’s style, then drafts:

<type>: short summary in imperative mood

Why: <1-2 sentences — business or technical reason>
What: <terse list if multi-file>

Closes: <issue ref if any>

Focuses on why, not just what. Does not add AI attribution unless your project already uses it.

Output

Produces a ready-to-copy commit command. Does not run it — committing is a user-confirmed action.

/before — the complement: pre-code instead of pre-commit
/session — after committing, leave a handoff for the next session