ship

/ship

You are shipping completed work: Commit, push, and open a pull request.

---

Prerequisites

Run the pre-ship check script to validate readiness:

${CLAUDE_SKILL_DIR}/scripts/pre-ship-check.sh [test-command]

This checks: feature branch, debug code, secrets, .env files, and optionally runs tests. If any check fails, fix before proceeding.

If the script is not available, verify manually:

git branch --show-current   # must be feat/{issue-number}-{name}

All tests must be passing. Run the project's test command and confirm zero failures. If tests fail, stop immediately and ask the user to fix them.

---

Step 1 — Review changes

git status
git diff
git diff --staged

Read the diff carefully. Understand every change. Look for and remove:

• Debug code (console.log, print statements, debugger)
• Commented-out code
• Temporary files
• Unintentional changes to unrelated files

---

Step 2 — Stage changes

Stage specific files — do not blindly git add .:

git add <file1> <file2> ...

Group logically related changes. Each commit should represent one coherent unit of work.

If the changes span multiple logical units, create multiple commits (one per unit).

---

Step 3 — Commit using Conventional Commits

Use the Conventional Commits format:

<type>(<optional scope>): <short description>

<optional body>

<optional footer>

Types:

Type	When to use
feat	New feature visible to users or consumers
fix	Bug fix
refactor	Code change that neither adds a feature nor fixes a bug
test	Adding or updating tests only
chore	Build process, dependencies, CI, config changes
docs	Documentation only
perf	Performance improvement

Rules:

• Description: imperative mood, lowercase, no period at end
• Max 72 characters for the first line
• Body: explain what and why, not how
• Footer: Closes #<issue-number> to auto-close the issue on merge

---

Step 4 — Verify repository and push to remote

Before pushing, confirm you are in the correct repository:

git remote get-url origin   # verify this is the expected repository

In multi-repo projects (e.g., frontend + backend), show the remote URL to the user and confirm before pushing. A push to the wrong remote is hard to undo and creates confusion.

git push -u origin "$(git branch --show-current)"

---

Step 5 — Create the pull request

Extract the issue number from the branch name and create the PR.

PR title format

Use conventional commit style for the PR title — it should match the primary commit type:

<type>(<scope>): <imperative description>

• type: feat, fix, refactor, chore, perf, docs, test — same as conventional commits
• scope: the module, component, or area affected
• description: imperative mood, lowercase, no period, under 70 characters

Examples:

• feat(auth): add OAuth2 login with Google and GitHub
• fix(checkout): prevent double-charge on concurrent submissions
• refactor(api): migrate REST endpoints to GraphQL schema

PR body template

gh pr create \
  --title "<type>(<scope>): <imperative description>" \
  --body "## Summary

<1-2 sentence high-level description of what this PR does and why>

### What changed

- \`path/to/file\`: <what changed and why>
- \`path/to/file\`: <what changed and why>

### Change overview

\`\`\`mermaid
graph TD
    A[Modified: component/module] -->|calls| B[Modified: component/module]
    C[New: component/module] -->|depends on| A
\`\`\`

> Show how the changed/new components relate to each other.
> Use labels like 'New:', 'Modified:', 'Deleted:' to clarify the type of change.
> Omit this section if the change is trivial (e.g., single-file fix, config change).

## How to test

1. <step-by-step instructions to verify the change>
2. <include specific commands, URLs, or inputs>
3. Run \`<test command>\` — all tests pass

## Breaking changes

> _None_ — or describe what breaks and how consumers should migrate.

## References

Closes #<issue-number>"

Diagram guidelines

Include the change overview diagram when it adds clarity:

Include diagram when	Skip diagram when
PR touches 3+ files across modules	Single-file change
New component integrates with existing ones	Simple bug fix
Data flow or control flow changes	Config or docs change
Reviewer needs visual context for architecture	Straightforward refactor

PR title rules (summary)

• Conventional commit format: type(scope): description
• Imperative mood, in English
• Under 70 characters
• Same type as the primary commit

Language rule: All commit messages, PR titles, and PR descriptions must be written in English, regardless of the language the user communicates in. This is non-negotiable — Git history and PRs are the shared record across teams and sessions.

---

Step 6 — Refresh the issue description

Update the GitHub issue to reflect the final state of the shipped work. The issue was created before implementation — it must now match what was actually built.

1. Read the current issue body:

gh issue view <issue-number>

2. Update the issue body with gh issue edit:
   • Check off all completed task checkboxes (- [x])
   • Update any descriptions that diverged from the original plan during implementation or review
   • Add any new files, components, or constraints discovered during development
   • Ensure the "Context for implementers" section reflects the final branch and key files

gh issue edit <issue-number> --body "<updated body>"

Rules:

• Preserve the original issue structure — update in place, do not rewrite.
• All content must remain in English.
• If nothing changed from the original issue, skip the edit.

---

Step 7 — Confirm

✓ Committed: <commit message first line>
✓ Pushed to: feat/<issue-number>-<name>
✓ PR created: <PR URL>
✓ Issue #<number>: description refreshed

The issue #<number> will be closed automatically when the PR is merged.

---

Step 8 — Refresh the PR description (post-review updates)

If additional commits are pushed to the branch after the PR was created (e.g., from review feedback, CI fixes, or follow-up changes), the PR description may become stale. In that case, update it:

1. Check if the PR already exists and if new commits were added since creation:

gh pr view --json number,url,body,commits

2. If the PR body no longer matches the actual changes, update it with gh pr edit:
   • Regenerate the "What changed" section to include all files modified across all commits
   • Update the "Change overview" diagram if the component relationships changed
   • Update "How to test" if the testing steps changed
   • Keep Closes #<issue-number> in the References section

gh pr edit <pr-number> --body "<updated body>"

Rules:

• Preserve the PR body structure from the /ship template — update in place.
• All content must remain in English.
• Only refresh if there are meaningful changes since the PR was created. Cosmetic or formatting-only commits do not warrant a refresh.
• If this is the initial ship (PR was just created), skip this step — the description is already fresh.

---

Step 9 — Wiki ingestion prompt (optional)

/ship is not terminal. The PR is a live artifact until merge — review feedback, CI fixes, and follow-up commits are expected. Still, the spec, plan, and tasks-summary produced earlier in this session are stable now and worth archiving to the repo-scoped wiki for future sessions to consult.

Ask the user:

"Ingest this session's spec/plan/tasks to .wiki/ for future consultation?"

• If the user accepts, invoke /sdd:wiki-ingest --preliminary. That skill handles initialization, confirmation, collision, and file writes.
• If the user declines, exit cleanly — .wiki/ stays untouched.
• If there is no .wiki/ directory and no explicit user consent, do nothing. Ingestion is always opt-in.

Remember: the final wiki entry (review findings and lessons learned) is written post-merge via /sdd:wiki-close-loop, not here. Skipping Step 9 does not prevent that later step.

---

Gotchas

These are common failure modes when shipping. Watch for them:

• Commit messages that describe the diff, not the intent. "Update auth.ts" tells the reviewer nothing. "fix(auth): reject expired tokens instead of silently renewing" tells them everything. The commit message explains WHY, not WHAT — the diff already shows what.
• Staging everything with git add . Despite the constraint, Claude defaults to this when there are many files. Always list files explicitly — this forces you to review what's being committed and catches accidental inclusions (.env, debug files, unrelated changes).
• Vague PR titles. "Fix bug" or "Update code" are not PR titles. Use conventional commit format: fix(checkout): prevent double-charge when user clicks pay twice. The title should read like a changelog entry — type, scope, and a clear imperative description.
• Forgetting Closes #issue in PR body. Without this, the issue stays open after merge and someone has to manually close it. Always extract the issue number from the branch name and include it.
• Bundling unrelated fixes. "While I was in there, I also fixed..." creates PRs that are hard to review and hard to revert. If you noticed another bug, note it — don't fix it in this PR.
• Shipping without running tests first. Claude sometimes assumes tests pass because they passed during implementation. Dependencies, environment, or other changes may have broken them since. Always re-run before shipping.
• Pushing to the wrong repository. In multi-repo projects, always verify git remote get-url origin before pushing. A push to the wrong remote creates duplicate branches and confusion. Use absolute paths for all git operations when working across repos.
• Writing commits or PR descriptions in the user's language. Even if the user communicates in Spanish, Portuguese, or another language, all commit messages, PR titles, and PR bodies must be in English. Git history is the shared record — it must be universally readable.
• Treating /ship as the end of the workflow. It is not. The PR still needs review, CI, and potentially post-review commits. After merge, run /sdd:wiki-close-loop to consolidate review findings and lessons into the wiki. See .claude/rules/sdd-workflow.md Phase 7.
• Auto-ingesting without asking. Step 9 must prompt the user. Silent ingestion defeats the opt-in design and may archive specs the user didn't intend to publish.

---

Important constraints

• Never ship with failing tests.
• Never use --no-verify to skip pre-commit hooks. Fix the issue instead.
• Never git add . or git add -A without reviewing what's being staged.
• One PR per feature/issue. Don't bundle unrelated changes.

---

Automatic safety hook

This plugin includes a PreToolUse hook that automatically blocks dangerous git operations:

• git push --force
• git reset --hard
• git add . / git add -A
• --no-verify

The hook is active whenever the plugin is enabled — no manual configuration needed.