Closing the Final Mile: From Running Code to Shipping with /ship, /document-release, and /retro

Why the Final Mile Reveals Engineering Maturity

Earlier steps (problem definition, solution review, code writing, review, testing) usually feel rewarding, but in real development the hardest part is the "troublesome but necessary" tasks that get postponed.

Base branch not merged

Tests not rerun after merging

Review‑readiness not checked

CHANGELOG not written

PR not opened

README not synchronized

Weekly summary not performed

These actions are crucial yet unglamorous, and teams often let them die with the excuse "do it later".

The Three Core Skills

The article introduces three commands that automate the missing steps and turn them into a repeatable process:

/ship

/document-release

/retro

What /ship Actually Does

/ship

is not a simple git push; it is a heavyweight delivery workflow that transforms a near‑complete feature branch into a state that is truly reviewable, mergeable, and deliverable.

Key responsibilities include:

Pre‑flight checks

Viewing the review‑readiness dashboard

Merging the base branch into the feature branch first

Running tests on the merged state

Bootstrapping a test framework when none exists

Coverage audit

Pre‑landing review

Handling VERSION and CHANGELOG updates

Pushing the changes

Creating or updating the PR

Automatically invoking /document-release This is a full delivery pipeline, not just a command wrapper.

Critical ordering: merging the base branch before testing prevents the common mistake of testing a local green branch that later fails after merging main. /ship enforces the correct order, reducing "it worked locally but broke after merge" incidents.

Uncommitted changes: /ship always includes uncommitted changes. This ensures nothing is silently ignored, but it also means you must be aware of what is in your working directory before running the command.

When to use: suitable for a ready branch where the problem is clarified, the solution is reviewed, code is written, and QA is mostly done. Not suitable for experimental, dirty, or unfinished branches.

Institutionalizing the Process

All the steps that /ship performs can be done manually, but without a formal process they depend on individual attention and patience. By automating them, the actions become stable, repeatable, and independent of personal discipline.

What /document-release Actually Does

Many treat documentation sync as a peripheral task, but in practice docs drift quickly (out‑of‑date README, stale architecture diagrams, wrong setup steps, unfinished TODOs). /document-release ensures that after code changes, every piece of documentation that reflects factual state is updated.

Scope of automation:

Directly fix obvious factual updates (e.g., a changed command name, a moved file path, a version number mismatch)

Leave high‑risk, narrative, or subjective changes for manual review

CHANGELOG policy: NEVER clobber existing entries. The tool may polish wording but must never rewrite history.

VERSION policy: VERSION bumps must be explicitly asked for; the tool will not silently increment the version.

What /retro Actually Does

/retro

is not a casual "feel‑good" summary; it generates a data‑driven weekly engineering report.

Collected metrics include:

Commit history on the default branch

Number of contributors

Insertions / deletions

Test coverage ratio

Regression‑test commits

PR count

Hotspot files

Commit‑time distribution

Shipping streak

Skill‑usage telemetry

Greptile history (if present)

TODOS backlog (if present)

It also identifies who ran the retro, what each contributor did, and where each person can improve. The output looks like:

What was the biggest ship this week?

Who contributed most in which directory?

Whose PRs were most restrained?

Who needs more test coverage?

Is the team’s shipping streak improving?

The tool stores a snapshot in .context/retros/, enabling trend analysis across weeks (e.g., commit count trend, test health trend, hotspot concentration, overall stability).

Thus /retro functions as an engineering‑rhythm tracker rather than a simple result display.

How the Three Skills Divide Work

/ship

: Execute the delivery actions. /document-release: Synchronize documentation with the code. /retro: Perform post‑delivery retrospection.

Combined they form a closed loop: delivery, doc sync, and data‑backed review.

Recommended Usage Chain

/review

/qa

/ship

/retro

In many cases /document-release is automatically triggered by /ship.

Common Pitfalls

Running /ship too early: experimental or dirty branches amplify chaos.

Forgetting that uncommitted changes are included: always check the working directory first.

Misunderstanding /document-release as a simple README fix: it updates the whole documentation set.

Overlooking CHANGELOG and VERSION boundaries: never rewrite CHANGELOG entries; always ask before bumping VERSION.

Treating /retro as an optional ceremony: it converts "feeling busy" into concrete data about what actually happened.

Conclusion

By institutionalizing these three skills, teams can turn the chaotic "last mile" into a reliable, repeatable process, reducing missed steps and improving overall delivery rhythm. The article hints that AI can take over many of these automation tasks, and the next installment will explore safety‑related skills such as /careful, /freeze, /guard, /unfreeze, and /gstack-upgrade.