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:**

```markdown
## 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

```bash
# 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:

```bash
# 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](references/commit-message-patterns.md) for full guide.

## CHANGELOG Format

Follow Keep a Changelog format:

```markdown
## [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](references/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](references/ci-failure-handling.md) for recovery patterns.

## Force Push Protection (S-23)

Never force push to protected branches.

```bash
# 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](references/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](references/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

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