shipping-methodology

# 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"
-