/shipping-methodology

name: shipping-methodology
description: Use when running claudikins-kernel:ship, preparing PRs, writing changelogs, deciding merge strategy, or handling CI failures — enforces GRFP-style iterative approval, code integrity validation, and human-gated merges
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - AskUserQuestion
  - Skill
  - mcp__plugin_claudikins-tool-executor_tool-executor__search_tools
  - mcp__plugin_claudikins-tool-executor_tool-executor__get_tool_schema
  - mcp__plugin_claudikins-tool-executor_tool-executor__execute_code

Shipping Methodology

When to use this skill

Use this skill when you need to:

• Run the `claudikins-kernel:ship` command
• Prepare commit messages and PR descriptions
• Update changelogs and documentation
• Decide merge strategy (squash vs preserve)
• Handle CI failures or merge conflicts
• Validate code integrity before shipping

Core Philosophy

> "Ship with confidence, not hope." - Shipping philosophy

Shipping is the final gate. Apply GRFP-style iterative workflow to every stage.

The Five Principles

1. **Gate check first** - claudikins-kernel:verify must have passed. No exceptions. 2. **Code integrity** - Ship exactly what was verified. No sneaky changes. 3. **GRFP everywhere** - Section-by-section approval at every stage. 4. **Human decides** - No auto-merging. Human approves final merge. 5. **Clean up after** - Delete branches, update docs, celebrate.

The Five Stages

Stage 1: Pre-Ship Review

Show what's being shipped. Human confirms ready.

| Check | What to Show | | ------------------- | ----------------------------------------------- | | Verification status | All phases PASS from claudikins-kernel:verify | | Branches to merge | List all execute/task-\* branches | | Evidence summary | Screenshots, curl responses from catastrophiser | | Code delta | Lines added/removed, files changed |

**Checkpoint:**

Ready to ship?

Verified: ✓ All checks passed
Branches: 3 branches to merge
Changes: +450 / -120 lines

[Continue] [Back to Verify] [Abort]

Stage 2: Commit Strategy

Draft commit message(s). Human approves.

**Decision:**

How should we commit?

[Squash into single commit] [Preserve commit history]

**Squash (recommended for features):**

• Single clean commit on main
• Clear feature boundary
• Easier to revert if needed

**Preserve (for large multi-part work):**

• Keeps granular history
• Better for debugging
• Use for multi-feature batches

**Checkpoint:**

Commit message:

feat(auth): Add authentication middleware

- JWT token validation
- Role-based access control
- Session management

Closes #42

[Accept] [Revise] [Back]

Stage 3: Documentation (git-perfectionist)

Update README, CHANGELOG, version. GRFP-style.

**git-perfectionist uses github-readme plugin:**

1. Deep-dive on current docs 2. Identify gaps from changes 3. Pen-wielding for updates 4. Section-by-section approval

**Files to update:**

| File | What to Update | | ------------------------------------------ | ---------------------------------------- | | README.md | Features, usage, installation if changed | | CHANGELOG.md | Add entry in Keep a Changelog format | | package.json / Cargo.toml / pyproject.toml | Version bump if needed |

**Checkpoint:**

Documentation updates:

README.md:
- Added: Authentication section
- Updated: Installation (new deps)

CHANGELOG.md:
- Added: v1.2.0 entry

Version: 1.1.0 → 1.2.0 (minor)

[Accept] [Revise] [Skip]

Stage 4: PR Creation

Draft PR title and body. Section-by-section approval.

**PR Title Pattern:**

feat(scope): Short description

**PR Body Structure:**

## Summary

[2-3 bullet points of what changed]

## Changes

[Detailed breakdown]

## Testing

[How it was verified]

## Screenshots

[If applicable]

**Checkpoint:**

PR ready to create:

Title: feat(auth): Add authentication middleware

Body:
## Summary
- Added JWT token validation
- Implemented role-based access control
...

[Create PR] [Revise] [Back]

Stage 5: Final Merge

CI passes. Human approves. Merge and cleanup.

**CI Status Check:**

CI Status: ⏳ Running...

[Wait for CI] [View logs] [Merge anyway]

**On CI pass:**

CI Status: ✓ All checks passed

Ready to merge PR #42 to main?

[Merge] [Request review first] [Cancel]

**After merge:**

• Delete feature branches (unless --no-delete-branch)
• Update ship-state.json
• Celebrate

**Final output:**

Done! Shipped to main.

PR #42 merged ✓
Branches cleaned up ✓
Version: 1.1.0 → 1.2.0

Nice work!

Rationalizations to Resist

Agents under pressure find excuses. These are all violations:

| Excuse | Reality | | ------------------------------------------- | ------------------------------------------------------------------------ | | "Verify passed yesterday, close enough" | Stale verification = no verification. Re-run claudikins-kernel:verify. | | "Just a tiny fix after verify, no big deal" | Any change after verify invalidates it. Re-run claudikins-kernel:verify. | | "CI is flaky, I'll merge anyway" | Flaky CI hides real failures. Fix or explicitly skip with caveat. | | "It's just a typo, skip the PR" | All changes go through PR. No exceptions. | | "Both reviewers passed, auto-merge is fine" | Human approves final merge. Always. | | "I'll update the changelog later" | Changelog is part of shipping. Do it now. | | "Force push is fine, it's my branch" | Never force push to protected branches. Ever.