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

Gate check first - claudikins-kernel:verify must have passed. No exceptions.
Code integrity - Ship exactly what was verified. No sneaky changes.
GRFP everywhere - Section-by-section approval at every stage.
Human decides - No auto-merging. Human approves final merge.
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:

Deep-dive on current docs
Identify gaps from changes
Pen-wielding for updates
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. | | "Skip docs, nobody reads them" | Docs are part of shipping. GRFP them. | | "The gate check is too strict" | The gate exists for a reason. Pass it properly. |

All of these mean: Follow the methodology. Shortcuts create incidents.

Red Flags — STOP and Reassess

If you're thinking any of these, you're about to violate the methodology:

"Let me just push this one change..."
"Verify is probably still valid"
"CI will pass next time"
"I'll do the PR properly next time"
"Auto-merge saves time"
"Docs can wait"
"Force push will fix it"
"The human already approved something similar"

All of these mean: STOP. Gate check exists. Human decides. Follow the stages.

Gate Check Pattern (CRITICAL)

The ship-init.sh hook enforces the claudikins-kernel:verify gate with code integrity validation.

Required Checks

# 1. Verify state exists
if [ ! -f "$VERIFY_STATE" ]; then
  echo "ERROR: claudikins-kernel:verify has not been run"
  exit 2
fi

# 2. Unlock flag is set
UNLOCK=$(jq -r '.unlock_ship // false' "$VERIFY_STATE")
if [ "$UNLOCK" != "true" ]; then
  echo "ERROR: claudikins-kernel:verify did not pass or was not approved"
  exit 2
fi

Code Integrity (C-5, C-7)

Ensure we ship exactly what was verified:

# C-5: Commit hash validation
VERIFY_COMMIT=$(jq -r '.verified_commit_sha' "$VERIFY_STATE")
CURRENT_COMMIT=$(git rev-parse HEAD)
if [ "$VERIFY_COMMIT" != "$CURRENT_COMMIT" ]; then
  echo "ERROR: Code changed since verification"
  exit 2
fi

# C-7: File manifest validation
VERIFIED_MANIFEST=$(jq -r '.verified_manifest' "$VERIFY_STATE")
CURRENT_MANIFEST=$(sha256sum "$MANIFEST_FILE" | cut -d' ' -f1)
if [ "$VERIFIED_MANIFEST" != "$CURRENT_MANIFEST" ]; then
  echo "ERROR: Source files changed after verification"
  exit 2
fi

If integrity check fails:

Code has changed since verification.

Verified commit: abc123
Current commit:  def456

[Re-run claudikins-kernel:verify] [Abort]

Commit Message Patterns

Feature

feat(scope): Short description

- Bullet point of what changed
- Another change

Closes #123

Bug Fix

fix(scope): Short description

Root cause: What was wrong
Fix: What we did

Fixes #456

Breaking Change

feat(scope)!: Short description

BREAKING CHANGE: What breaks and migration path

- Change 1
- Change 2

Chore (no user-facing change)

chore(scope): Short description

- Internal refactor
- Dependency update

See commit-message-patterns.md for full guide.

CHANGELOG Format

Follow Keep a Changelog format:

## [Unreleased]

## [1.2.0] - 2026-01-17

### Added

- Authentication middleware with JWT support (#42)

### Changed

- Updated error messages for clarity

### Fixed

- Token refresh race condition (#38)

## [1.1.0] - 2026-01-10

...

See changelog-merge-strategy.md for merging entries.

External Service Failures

GitHub API Failure (E-6, E-7, E-8)

PR creation failed.

Error: GitHub API returned 503

Retry 1/3...

Pattern: Max 3 retries with exponential backoff.

If persistent:

GitHub API unavailable after 3 retries.

[Try again] [Save as draft PR] [Manual merge]

Save state with pending_merge: true for recovery.

CI Failure

CI failed.

Failed checks:
- lint: 2 errors
- test: 1 failure

[View logs] [Fix and retry] [Skip CI] [Abort]

See ci-failure-handling.md for recovery patterns.

Force Push Protection (S-23)

Never force push to protected branches.

# Check if target is protected
PROTECTED_BRANCHES="main master release"
if echo "$PROTECTED_BRANCHES" | grep -q "$TARGET"; then
  if [ "$FORCE" = "true" ]; then
    echo "ERROR: Cannot force push to $TARGET"
    exit 2
  fi
fi

See force-push-protection.md for safeguards.

Breaking Change Detection (S-24)

Detect breaking changes before shipping:

| Signal | Indicates | | -------------------------- | -------------------- | | Removed public function | Breaking | | Changed function signature | Breaking | | Removed config option | Breaking | | Changed default behaviour | Potentially breaking |

If breaking change detected:

Breaking change detected!

- Removed: authenticate() function
- Changed: login() now requires email

This requires a MAJOR version bump.

[Acknowledge and continue] [Abort]

See breaking-change-detection.md for detection patterns.

Anti-Patterns

Don't do these:

Shipping without claudikins-kernel:verify passing
Modifying code after verification
Force pushing to main/master
Auto-merging without human approval
Skipping documentation updates
Ignoring CI failures
Using vague commit messages ("fix stuff")
Forgetting to delete feature branches

State Tracking

ship-state.json

{
  "session_id": "ship-2026-01-17-1130",
  "verify_session_id": "verify-2026-01-17-1100",
  "target": "main",
  "phases": {
    "pre_ship_review": { "status": "APPROVED" },
    "commit_strategy": { "status": "APPROVED", "strategy": "squash" },
    "documentation": {
      "status": "APPROVED",
      "files_updated": ["README.md", "CHANGELOG.md"]
    },
    "pr_creation": { "status": "CREATED", "pr_number": 42 },
    "merge": { "status": "MERGED", "sha": "abc123" }
  },
  "cleanup": {
    "branches_deleted": ["execute/task-1-auth", "execute/task-2-routes"]
  },
  "shipped_at": "2026-01-17T11:46:00Z"
}

References

Full documentation in this skill's references/ folder:

commit-message-patterns.md - Full commit message guide
grfp-checklist.md - GRFP integration checklist
pr-creation-strategy.md - PR body templates
deployment-checklist.md - Pre-deploy checks
gate-failure-recovery.md - Recovering from gate failures (S-19)
ci-failure-handling.md - Handling CI pipeline failures (S-20)
message-generation-fallback.md - When commit message generation fails (S-21)
changelog-merge-strategy.md - Merging CHANGELOG entries (S-22)
force-push-protection.md - Preventing accidental force pushes (S-23)
breaking-change-detection.md - Detecting breaking changes (S-24)

shipping-methodology

Shipping Methodology

When to use this skill

Core Philosophy

The Five Principles

The Five Stages

Stage 1: Pre-Ship Review

Stage 2: Commit Strategy

Stage 3: Documentation (git-perfectionist)

Stage 4: PR Creation

Stage 5: Final Merge

Rationalizations to Resist

Red Flags — STOP and Reassess

Gate Check Pattern (CRITICAL)

Required Checks

Code Integrity (C-5, C-7)

Commit Message Patterns

Feature

Bug Fix

Breaking Change

Chore (no user-facing change)

CHANGELOG Format

External Service Failures

GitHub API Failure (E-6, E-7, E-8)

CI Failure

Force Push Protection (S-23)

Breaking Change Detection (S-24)

Anti-Patterns

State Tracking

ship-state.json

References