Skip to content
Back to skills

Ship

ASecurity

Walk the change through the teach-back brief, then push to staging and open a DRAFT PR — never main/master/prod. Use when the user types /ship or asks to push, open a PR, or ship the change. Stops for explicit approval before pushing.

  • 3 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
toolsrustgonodegitdocumentation

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add developzone5/sanad --skill ship --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Ship?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Ship
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/developzone5-ship-sanad/badge)](https://www.skillsdirectory.com/skills/developzone5-ship-sanad)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: ship
description: Walk the change through the teach-back brief, then push to staging and open a DRAFT PR — never main/master/prod. Use when the user types /ship or asks to push, open a PR, or ship the change. Stops for explicit approval before pushing.
---

<!-- Author: Eng. Mohammed Almutairi - Developzone.net -->

# /ship — teach-back, then push to staging

This file is the single source for the shipping flow (moved from CLAUDE.md 2026-09-28): the teach-back brief, the integration-branch and draft rules, and the after-deploy smoke — see **Rules** below. CLAUDE.md's "Self-review your diff first" still applies before the brief.

**Pushing and opening a PR are explicit-approval steps. Brief first, ask, wait for a yes, then push. Never automatic — and a "yes" to the task is not a "yes" to the push; approval is per-action and expires.**

## Pre-flight — check all five before the brief

1. **Fresh base.** Synchronize before final verification/review per [execution.md](../sanad/reference/execution.md). This pre-flight is the final freshness check, not the first integration update. `git fetch origin` must succeed — a failed or timed-out fetch is a stop (report it; never publish on stale remote data). Then: (a) `gh pr view --json number,state,baseRefName` — if this branch's PR is already **MERGED**, do not push more commits to it: create a new branch off `origin/<integration>` (`git checkout -b <type>/<name> origin/<integration>`), cherry-pick/re-apply the work, and re-brief; (b) if the branch is **behind** `origin/<integration>` (`git rev-list --left-right --count origin/<integration>...HEAD`), check for a conflict without changing anything: `git merge-tree --write-tree --quiet origin/<integration> HEAD` (exit 1 = conflict). **No conflict → no merge** (2026-11-15: merging an unrelated staging commit made a new tree, and the full suite ran again for it): push as it is; the PR's own checks on GitHub test the combined code, and the brief says `behind <n>, no conflict — the PR checks test the merge`. Merge only on a conflict, when the change needs code that is only on the integration branch, or when the repository has no PR checks (no workflow under `.github/workflows` that runs on pull requests). Then merge it into the feature branch (never rebase a pushed branch), collect affected checks and the required review for changed content/context, and re-run `/gate`. If no relevant inputs changed, reuse the completed evidence. The `session-start.js` hook prints this state at startup; re-check here because it changes mid-session.
2. **Review + gate.** Both PASS for the current result, per `/gate` (it owns the evidence rules: completed independent review, source-bound evidence.mjs receipt, docs-only exception); each verdict line plain at line start in a text-only message. An already-reviewed cherry-pick follows [promotion.md](reference/promotion.md). Missing, pending or failed required checks block the push, drafts included. The one exception is a Small task's slow suite that is *left to CI* (one state, defined in [execution.md](../sanad/reference/execution.md), "Left to CI"; item 5).
3. **Identity.** Commit author is `developzone5` + the noreply email (CLAUDE.md Ground rules) — check `git config user.name` / `user.email` before the first commit; a fresh clone has none set. Never commit as `RND`.
4. **Spec.** Finalize its implementation milestones, actual verification evidence and `In review` status before independent review so the spec ships in the reviewed snapshot. Do not edit it during this pre-flight or after the gate. Necessary later changes require review again; final review/gate/approval results live in the conversation, saved evidence and PR body. Mark `Shipped` only after the feature actually ships, in a later documentation update.
5. **Required list (user rule 2026-10-30).** Print this list in the brief, each item `done` or `not done`, read from what actually ran on the final revision: the review this task's size requires (loop.md Step 3.5 — Small and Medium: one fresh-eyes review; Big: the full round with the other engine; a review the user asked for: [full-pr-review.md](../sanad/reference/full-pr-review.md). 2026-11-17: this list asked every push for both engines and the full suite, which undid the Small and Medium route), every note answered (the ones the note check closed as wrong are listed in the brief, each with its evidence, so the user can reopen one), the full suite on the final tree (a Small task whose slow suite is left to CI is listed as `left to CI: <job name>`, not as `not done`: it does not hold the push line, because the push is what starts CI (2026-11-18: the list blocked the push that its own check waited for); the PR is not called ready, and no merge is advised, until `pr-watch.mjs --require "<job name>"` prints PASS for the final commit: a PASS that does not name that job proves nothing about it), every push line's branch, and the PR body check (`node ~/.claude/skills/gate/scripts/check-pr-body.mjs <body file>` printed `PR BODY: clean`; user rule 2026-11-05: only the user parks a finding), the ticket-lines check when the task has a ticket (`check-ticket-lines.mjs` printed every line `✓`), and one commit per PR. Any `not done` item means no push line, even when the user will run the push: the push guard does not see a user's own commands, so this list is the check. Never say "all checks are done" without it.

## Flow

1. **Branch & commit.** On `main`/`master` or the integration branch → create a feature branch first. Stage named files only (no `git add .`); Conventional Commit messages (CLAUDE.md Ground rules).
   **One commit per PR (user rule 2026-11-05: "in this pr and previous one make it one commit then add it as rule").** Before every push, the PR's own commits become one Conventional Commit whose tree is the tested tree. Keep a `backup/<branch>-before-squash` branch, then build the commit with `git commit-tree <tested HEAD>^{tree} -p <merge base with origin/<integration>>`: the PR title is the subject and the why is the body. An integration merge already in the tree is folded in, never redone. Check that the new tree id equals the tested one, so no check reruns. Before the first push, amending the one commit does the same. Once the PR is pushed, the squash needs a force push with lease on the old head: the brief says so, and the user runs it after the yes.
2. **Discover the PR base — never assume.** Read the repo's branches: `staging` → `develop` → `dev`, first that exists is the base. **Never** `main` / `master` / `prod` / `production` / `release/*` — even if checked out on one. If no integration branch exists (only `main`/`master`), STOP and ask which branch is the integration target — never default to `main`.
3. **Self-review the staged diff** (CLAUDE.md), then give the **teach-back brief** (Rules below), stating the target out loud: `Pushing <branch> → PR base <integration branch>`. Then wait for explicit approval — do not push while waiting.
4. **The user pushes; the PR opens as DRAFT** with an explicit base. After the yes, give one fenced block with the two commands (`git push -u origin <branch>` and `gh pr create --draft --base <integration> …`) for the user to run (loop.md rule 6; run them yourself only when the user says so in this conversation) — never rely on the repo's default base. The PR body reuses the brief: `## Summary` / `## Test plan` / `## Risk / migrations / config` / `## Rollback`, per "Draft until proven" below. Test plan lists only what actually ran.
   **Follow-up push to an existing PR: update the body** from the current brief and gate (`gh pr edit <n> --body-file`). Read the existing body, remove invalidated claims, and preserve valid evidence with its original command/output, checked revision and source link. Label reused evidence honestly; never claim it ran again this session. Add a `## Review` section with findings/dispositions and reused source reviews when applicable.
5. **Check the PR head.** Right after the user's push, start `node ~/.claude/skills/gate/scripts/pr-watch.mjs --repo <repo>` in the background (2026-11-17: two PRs were merged with CI red or still running). It passes only when the repository's required jobs ran and passed on the final commit: their names come from `--require "<job name>"` or from `git config sanad.requiredChecks`; `NOT PROVEN` means none is named, or a required job was skipped, and is never read as a pass. `FAIL` prints the failing lines as soon as a job fails: reproduce them in a test, fix through the loop, and tell the user before they merge; a red or running check is always named before a merge. Read its head SHA, required CI and review findings after pushing. Pending or failing required checks keep it draft; when the repository's checks do not run on a draft (`pr-watch.mjs` prints `DRAFT`), say so: the user marks the PR ready to start them, and a red result goes back through the loop. Re-check the SHA before declaring CI green; after any new commit, repeat affected local proof and check CI on the new head. Never merge or change repository protection settings.
6. **Report** the PR URL plus what remains unverified (e.g. UI not browser-tested). Push rejected (non-fast-forward) → fetch and merge locally (never rebase a pushed branch), then re-brief if the diff changed; never force-push a shared branch.
   **Record task metrics (user choice 2026-09-28):** append one line to the project's `memory/task-metrics.md` — `date · task · PR · route (direct/review/braintrust) · agents (boss/panel/reviewer runs) · review rounds · full-suite runs · elapsed (first request → PR) · escaped bugs: 0`. Use real counts from this session; unknown stays `?`. Add the totals line of `node ~/.claude/skills/gate/scripts/review-score.mjs --repo <repo> --log` (notes per reviewer seat and how many led to a change), and offer what its `--repeats` names in the end list. Compare these lines before tuning the workflow further; no unmeasured speed or quality claims.

7. **Deferred expert maintenance.** After the PR is open, required task work is complete and the PR handoff above has been delivered, process pending boss coaching notes through [expert-learning.md](../braintrust/reference/expert-learning.md). Reuse existing findings and evidence; update only the responsible expert's skill guidance file. Report this separately from the task handoff. Do not delay PR creation or task completion, change the reviewed project snapshot, rerun the panel or reopen cleared reviews for skill-only maintenance. If there are no pending notes, skip it. If shipping or task completion is still pending, retain the notes as pending; do not claim background work will run after the session ends.

## Rules (single source; moved from CLAUDE.md 2026-09-28)

### Teach before you push

Pushing and opening a PR are **explicit-approval steps, never automatic.** Before a push, stop and tell the human **what you fixed and why** — that is the whole point of the brief. Lead with it, make it clear, then add only what's needed to approve:

- **What I changed and why** — the heart of the brief: each change and the reason behind it, one clear line each. Not a diff dump, not an essay — the fix and the decision. Name the tradeoff you rejected if it wasn't obvious.
- **How I checked it** — what you ran → what you saw (build, tests, the real run).
- **Risk** — migrations, config/env, deleted code, anything needing a manual step. `none` if nothing.
- **Not done** — what you didn't touch, guessed, or left for the human.
- **Time** — when the task kept a timer (Sanad loop "Speed", user rule 2026-11-09): the total line of `node ~/.claude/skills/gate/scripts/sanad-timer.mjs report <notes>` and its longest step, e.g. `52 min (work 44, waiting 8); longest: review 14 min`, then one plain sentence that says WHY it took that long: the stage that cost the most and its cause (user, 2026-11-17: "just tell me the time in the end and why it takes this time"), e.g. "Two fix rounds: the review found a timing bug, so the proof ran three times." No target is checked and no check is ever cut for time. The full report goes into the task-metrics line's notes.
- **Where it goes** — `Pushing <branch> → PR base <staging>. Approve?`

Talk like a peer explaining a change, not a form and not a wall of text. Use the plain words of CLAUDE.md "How you talk": no Sanad labels, each line readable without asking. Then **wait for the yes.** Told to "just push" with the task → still give the what-and-why first, then push. A "yes" to the task is not a "yes" to the push. (`/ship` runs this brief + the draft-PR flow, and still stops for the explicit yes.)

### Push only to the integration branch

Push branches and open PRs against the staging/dev integration branch ONLY — never `main`, `master`, `prod`, `production`, or any `release/*` branch, even if currently checked out on one.
- State the target out loud before acting: "Pushing `<branch>` → PR base `<integration>`."
- Discover the base, don't assume: read the repo's branches (default-branch ref, branch list). A `develop`/`staging`/`dev` branch is the base. If only `main` exists, STOP and ask which branch is the integration target — never default to `main`.
- PR-create MUST pass an explicit base; never rely on the default base.
- Never merge a PR, never merge into a shared/prod branch, never tag a release, never trigger a prod deploy. Promotion to prod is the human's call, per-action.
- If told to target prod directly, restate the target and require a one-time confirmation before acting.

#### Draft until proven
Open as a DRAFT unless every Definition-of-Done item passed. Mark ready only after the full gate is green, stating which items you verified vs. couldn't (e.g. UI not browser-tested). A branch that can't deploy cleanly stays draft. The PR body reuses the teach-back — don't invent new prose:
- `## Summary` — what + why.
- `## Test plan` — only what you actually ran, per the gate. Not aspirational. Opt-in tests that CI skips (environment-gated real-provider tests) are listed with their local result and the note "not run by CI".
- `## Risk / migrations / config` — migrations? new env/config keys? a manual step? Write "none" explicitly.
- `## Rollback` — how to undo; for an applied migration, the down/expand-contract path. "Irreversible" is a blocker — flag it.

No AI attribution (no session links or `Claude-Session:` trailers either), no internal agent notes.

### After the deploy

Merging isn't done. Once it deploys, smoke the primary happy path end to end against the deployed URL (the one flow this change touches, hit for real) and scan logs for new errors/warnings just after deploy; paste the result. Can't reach the environment → list the exact manual smoke steps, don't mark it verified.

For any new flow crossing a boundary (HTTP in, external call, background job, multi-step write), make it traceable without a debugger: a correlation/request id on every log line, a structured info event at the business start and end with key ids, an error event with that id on the catch — never a bare "failed". Surface the correlation id in the user-facing error so a report maps to a log line. No secrets/PII in any of it.

Files in this skill

  • SKILL.md15 KB
  • reference/pr-review.md6 KB
  • reference/promotion.md4.1 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in tools →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.