draft-weekly-ship
Skill8 starsChanged 11 days agoApache-2.0View on GitHub
Draft the Piper Morgan Weekly Ship newsletter from collected workstream memos. Use when PM says "draft the Ship", "draft Ship #NNN", "synthesize the workstream memos", or when all 6 workstream-NNN memos have landed in `mailboxes/exec/inbox/` and a theme has been picked. Loads the canonical artifacts before drafting so memory-of-past-Ships doesn't substitute for structure.
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- cut-releaseSkill
- delete-module-safelySkill
- deliver-mailSkill
- discovered-work-captureSkill
- doc-sync-sweepSkill
- draft-blog-postSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-draft-specSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- publish-to-blogSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
All 6 workstream-NNN memos are in mailboxes/exec/inbox/ and a theme has been agreed
- Very specific: line 128
If an omnibus log is missing for a day in the window (gaps happen), flag it explicitly and supplement from dev/2026/MM/DD/ session logs for …
- Very specific: line 144
If the omnibus for a day is shallow OR a workstream memo references substantive work that doesn't appear in the omnibus, open the relevant …
- Distinctive: line 176
Anti-pattern explicit: do NOT pattern-match to a prior Ship's External-section shape (Sat insight / Sun insight / Tue narrative / Thu …
- Distinctive: line 243
If a workstream has no activity, INCLUDE it with a brief "No significant changes this week" note rather than omitting it.
- Distinctive: line 263
Verify before declaring done:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
draft-weekly-ship
Formatting rules have one source:
template-audit(PM, 2026-10-12, CIO's R6 decision D-C). Where this skill andtemplate-auditdisagree on a formatting rule (tease, metrics, title case, glosses, word count),template-auditwins, and this skill gets fixed to match.
Draft the Weekly Ship newsletter using the canonical template, voice guide, process guide, and workstream memos — with all of them open before writing starts.
Origin: Ship #043 v0.1 was drafted from memory of past Ship feel rather than opening the template. Result: pure essay form where structured newsletter was required, missed 5-workstream structure, missed learning-pattern 5-component shape, missed metrics table, missed footer convention, missed phase tag. PM correction May 19 directed re-read of source + template + voice guide before re-draft. This skill mechanizes the discipline so the same failure doesn't recur.
Related memory: feedback_ship_drafting_canonical_artifacts_first.md — the vocabulary layer. This skill is the mechanism layer.
When to Use
Invoke this skill when:
- PM says "draft Ship #NNN" or "synthesize the workstream memos" or "draft the Weekly Ship"
- All 6 workstream-NNN memos are in
mailboxes/exec/inbox/and a theme has been agreed - You're picking up Ship drafting work after compaction or context loss
Do NOT skip the canonical-artifacts loading step under time pressure. This is exactly when the v0.1 failure mode fires.
The Ingredients (load ALL before drafting)
Canonical artifacts — read these FIRST
| # | What | Path |
| 1 | Process guide | docs/internal/development/weekly-ship-process-guide.md |
| 2 | Template v4.1 | knowledge/weekly-ship-template-v4.1.md |
| 3 | Voice & tone guide | docs/internal/planning/comms/xian-voice-tone-guide.md |
| 4 | Most recent published Ship | docs/public/comms/drafts/published/weekly-ship-{N-1}*.md (look up actual filename) |
Sources for synthesis
| # | What | Path |
| 5 | All 6 workstream memos | mailboxes/exec/inbox/workstream-{NNN}-{role}-{date}.md (for roles: arch, cio, comms, cxo, host, ppm) |
| 6 | Omnibus logs for Fri–Thu window | docs/omnibus-logs/2026-MM-DD-omnibus-log.md for each day in the window |
| 7 | Editorial calendar CSV (REQUIRED for the External section) | docs/internal/planning/comms/editorial-calendar.csv |
| 8 | Published-post drafts (for any post you'll describe in External) | docs/public/comms/drafts/published/{slug}.md |
Procedure
Step 0: Write the kickoff memo — REQUIRED FRAMING (do not paraphrase from memory)
The kickoff's deadline framing is a mechanism, not a style choice. PM has corrected the same failure three times (Ship #045 Jun 1, #046 Jun 5, #055 Aug 7). Every instance had the same shape: a stated backstop date read by recipients as the target, work deferred to it, reports arriving later and staler, PM's reading window compressed. Use this wording. Do not compose it fresh.
★ Required in every kickoff, added v1.12: any report making a claim about sprint, backlog, or roadmap progress must carry the output of python3 scripts/sprint-truth.py (or state explicitly what its claim excludes). Paste this into the kickoff body:
If your report makes any completeness or progress claim about the sprint, run
python3 scripts/sprint-truth.pyand paste its line. A claim without a denominator is the defect PM named on 2026-08-08: "we keep over-reporting completeness by mistaking the denominator… it is not great for planning to be told every few days that the sprint is complete when it is not." "The build queue is empty" was true and excluded six never-started items.
✅ Required — copy this into every kickoff:
Write your report as soon as possible — meaning immediately, or, if that would derail genuinely focused work, at your next opportunity. No later than {DATE}, but treat that as the point where I nudge you, not as when it's due.
Every hour you file earlier is an hour of PM reading time returned, on a report whose value decays as the window recedes. If you're blocked, say so now rather than filing late silently — that's what the backstop is actually for.
❌ Banned phrasings (each has produced the failure): "due at your Saturday day-close" · "target EOD {day}" · "by {date}" · "at your cadence" · "firm-preference / absolute-latest" · any framing where the date appears before the write-now instruction.
The boundary: this is not manufactured urgency (see feedback_time_lord_doctrine_no_false_urgency — PM's own pacing is never compressed, and no deadline is invented). The date is real and unchanged; what's corrected is that the ask leads with "now" and the date appears second, named as a nudge-threshold.
Why it's in the skill and not just in memory: it was only in memory (feedback_kickoff_deadlines_must_be_framed_procedurally, which even specified "the skill needs this section"), and it failed again on 2026-08-07 in a session that held the pin. A rule that depends on a future session reaching for the right memory at the right moment is vigilance. This section is the mechanism.
Step 1: Load the canonical artifacts
Open all 4 in order. Read the process guide first (it tells you what the deliverable IS), then template (structure), then voice guide (tone), then most recent published Ship (in-practice example).
Why this order matters: The process guide names the 5 workstreams as REQUIRED. The template shows the structure with emoji prefixes and learning-pattern 5-component shape. The voice guide names the discipline (no semicolons, no "load-bearing" in public prose, no "CoS" in public prose, agents named directly — the voice guide's parenthetical-gloss rule is for BLOG posts, NOT Ships (see the audit checklist), temporal-relationship over absolute-date stamps, affirmative direct over disclaim-then-affirmative, section headings as noun phrases not verb phrases). The recent published Ship shows what the in-practice format actually looks like (which may have evolved from the template).
Step 2: Confirm the window and theme
- Window: Friday through Thursday. Verify the dates in PM's request match.
- Theme: PM-picked, ideally from the 6 workstream memos' convergence. If theme isn't yet picked, surface candidates BEFORE drafting (don't draft on assumed theme).
Step 2b: HARD GATE — all 6 workstream memos must be in before drafting starts
Do not begin Step 3 with fewer than 6 of 6 memos present, regardless of deadline pressure. Check mailboxes/exec/inbox/ (and read/ for any already triaged) for workstream-{NNN}-{role}-*.md from all six roles: arch, cio, comms, cxo, host, ppm.
- 6 of 6 present → proceed to Step 3.
- Fewer than 6 → STOP. Do not draft, even partially, even as a "placeholder to be filled in." Notify PM directly (chat + a mail note if PM is not in the current conversation) naming exactly which role(s) are missing and how close the pubDate deadline is. Wait for PM's call: extend, PM nudges directly, or (PM's explicit decision only) proceed on a named partial set.
Why this is a hard gate, not a judgment call: Ship #051 (2026-07-14) was drafted in full with PPM's memo missing, reasoning that the pubDate was the next day and a nudge had already gone out. PM overrode this directly: "we cannot write the ship without all the workstream reviews." PM is the Ship's first audience, not just its final reviewer, and is specifically most interested in the portfolio-goals lens that PPM's §0 carries — a draft missing it is missing the part PM most wants to read, not a minor gap to route around under time pressure. See feedback_ship_needs_all_workstream_reviews_no_partial_draft.md. The Friday early-warning check in methodology-25 (workstream-review-cadence) exists to catch a missing memo early in the week, before it becomes a Tuesday-deadline crisis — this gate is the backstop for when that early warning didn't prevent the gap anyway.
Step 2c: HARD GATE — the internal report precedes the draft (PM's ten-step cycle, 2026-08-04)
Before drafting begins, the INTERNAL REPORT for PM must exist and Janus must be notified (steps 5-6 of PM's ten-step weekly-reporting cycle — see the process guide's canonical-cycle section). The report is an artifact: dashboard element on top (progress / challenges / at-a-glance), per-workstream detail, and anything needing a leadership/strategic/planning decision. The Ship draft follows the PM discussion of that report (step 7), or PM's async replies via Janus. Ship #054 skipped this — went straight from the 6/6 gate to the public draft — and PM named the full cycle as the standard the next day. Emphasis in both report and kickoff memos: progress toward goals and milestone status, not just activity.
Where it lives and how the cycle tracks it (v1.13, 2026-10-23): write the synthesis to docs/internal/planning/comms/ship-reviews/ship-NNN-week-review.html and publish it as an artifact. The day xian discusses it, add <!-- discussed: YYYY-MM-DD --> to that file. scripts/ship-kickoff.sh, which runs at the end of every Exec fire, prints a ship-status #NNN line from Friday to Wednesday: reviews filed, synthesis, discussed, draft, calendar, and the NEXT step. When that line says INVOKE the skill, invoke it; don't work from memory of last week's Ship. A pre-commit gate (.claude/hooks/pre-commit-ship-synthesis-gate.sh) refuses to add a new Ship draft until the synthesis exists and carries the discussed marker, and the editorial calendar has a row naming the draft. #066 skipped this step too (2026-10-23): Exec drafted from the reviews and last week's Ship without opening this skill, and a review's false privacy line reached the draft.
Step 3: Read ALL omnibus logs in the window — REQUIRED, FULL READ
This step is non-negotiable and not a spot-check. Per PM directive May 20: the Chief of Staff reads the actual logs, doesn't rely on staff reports alone. Workstream memos are perspectives — each role lens is real but partial. Engineering shipped arcs in particular tend to live in the omnibus + Lead Dev session logs, not in the methodology-focused workstream memos.
For each day in the Fri–Thu window, open docs/omnibus-logs/2026-MM-DD-omnibus-log.md and read at minimum:
- Day Type + Justification lines (the omnibus author's framing)
- Core Themes section (the substantive list — this is where shipped items live)
- Technical Details section (commits, merges, specific deliverables)
- Impact Measurement section (per-role day-net counts)
- Carry-Forward section (open threads)
Extract a working list, organized by the 5 Ship workstreams, of:
- Issues closed end-to-end (search "shipped" / "merged" / "closed end-to-end")
- ADRs ratified or filed
- Pattern catalog changes (new patterns, promotions, supersessions)
- Methodology entries filed
- Process artifacts shipped (skills, hooks, templates)
- Publications + their canonical URLs (cross-check Step 4b)
- Cohort-coordination events (workstream-review cycles, cross-role coordination)
- Operational incidents + recoveries
If an omnibus log is missing for a day in the window (gaps happen), flag it explicitly and supplement from dev/2026/MM/DD/ session logs for that day.
Step 4: Read all 6 workstream memos — WITH OMNIBUS CONTEXT ALREADY IN HEAD
Now read the memos. With the omnibus substrate already loaded, the memos become commentary on what you've already seen rather than your primary source. This is the intended use.
During the read:
- Cross-check each memo's claims against the omnibus you already read
- Note where a memo emphasizes something the omnibus under-weighted (or vice versa)
- Flag factual conflicts between memos
- Track metrics that appear in multiple memos (they may differ — use the most current or conservative figure, prefix "~" for approximations)
- Identify the learning pattern candidate (often the memo with the most concrete data point)
- Window-discipline: anything from the day AFTER the window or earlier sessions referenced in the memos belongs out of the Ship
Step 4-prime: Pull underlying session logs when something looks thin
If the omnibus for a day is shallow OR a workstream memo references substantive work that doesn't appear in the omnibus, open the relevant session log directly (dev/2026/MM/DD/YYYY-MM-DD-HHMM-{role}-{code|opus}-log.md). The session log is the ground truth.
No superlatives without verification: "longest," "most," "biggest," "first," "on record" all require 30-second history check. Soften to "substantial," "comparable to," "below" if you can't verify.
Step 4b: REQUIRED — Verify the External section against the editorial calendar CSV
This step is non-negotiable. The Ship #043 v0.2 fabrication caught May 20 was an entirely-invented External section because this step was skipped.
Open docs/internal/planning/comms/editorial-calendar.csv. Filter to publications whose pubDate OR liPubDate falls in the Fri–Thu window. For EACH publication you will list in the External section, pull from the CSV:
- Exact title (do not paraphrase, do not abbreviate; do not invent titles to fit a Sat/Sun/Tue/Thu rhythm if the actual cadence varied)
- Exact publication date (
pubDate, plusliPubDateif LinkedIn-syndicated) - Exact URL (
blogURLfor canonical,mediumURLandlinkedinURLfor syndication) - Theme/category (
themecolumn — insight / building / ship) - Status — anything with
statusother thanpublishedis held / queued / etc.; do not list as shipped
For a one-line content summary, open the actual post draft at docs/public/comms/drafts/published/{slug}.md and read the first 20–30 lines. Derive the description from the post's actual content. Do not infer content from the title alone.
Cross-check against Comms's workstream memo for the count (e.g., "four published, one held"). If your CSV-derived count doesn't match Comms's count, STOP and investigate before drafting — don't paper over.
Sample CSV query (Python):
import csv
with open('docs/internal/planning/comms/editorial-calendar.csv') as f:
r = csv.DictReader(f)
for row in r:
pub = row.get('pubDate', '')
if pub.startswith('2026-MM-') and 'DD' <= pub.split('-')[2][:2] <= 'DD':
print(row['pubDate'], row['status'], row['title'], row['blogURL'])Anti-pattern explicit: do NOT pattern-match to a prior Ship's External-section shape (Sat insight / Sun insight / Tue narrative / Thu narrative) and fill the bullets with plausible-sounding invented titles. The cadence varies week to week. Use the CSV.
Step 4c: REQUIRED — Select the hero image for the External section
Always follow the published-pieces list with one hero image, sourced from one of the window's Tuesday/Thursday narrative posts specifically — the category that publishes to Medium only, not directly to LinkedIn (publishing-cadence.md's slot map). Not any illustration from the window; not an insight post's image (those already go to LinkedIn on their own). If the window has two narrative posts, either is fine — pick the one with the stronger illustration or the one most relevant to the Ship's theme. If it has one, use that one. If it has zero, say so explicitly in the draft rather than omitting the element silently or substituting an insight-post image.
Pull alt text and caption verbatim from that post's own YAML frontmatter (docs/public/comms/drafts/published/{slug}.md) — same discipline as everywhere else in this skill: no paraphrasing, no inventing.
⚠️ The image URL is the one field NOT pulled verbatim from frontmatter — derive it instead. The frontmatter image: value (e.g. alpha-launches-before-opening.png) is the pre-conversion source filename fed to publish-post.js --image at draft time; it is never the deployed asset name and 404s if used directly (confirmed: 0 of 81 published posts' frontmatter image: values match a real file in public/assets/blog-images/ — the field's whole job is upstream of deployment, not a pointer to it). The deployed name is always https://pipermorgan.ai/assets/blog-images/{slug}.webp, where {slug} is the post's own slug (check blogURL/blogPath on its calendar row, or the filename it published as). Build the <img> src from that, never from the frontmatter string.
This is a live-404 defect class, not a hypothetical: it broke Ship #054's and Ship #056's hero teasers exactly this way (found + fixed 2026-08-19/20, piper-morgan-website#33). Verify the constructed URL resolves with a live HTTP check before shipping the draft — don't trust the derivation alone.
Link the image to the post on pipermorgan.ai. Format:

*"caption, quotation marks preserved"*(PM, Ship #053 review, 2026-07-29 — codified as a standing requirement in weekly-ship-template-v4.1.md (its hero-image checklist line; a planned v4.2 was never created, CIO R6 P4, 2026-10-08) and the process guide. Supersedes v1.5's softer "can be followed by" wording below. Image-URL derivation rule added 2026-08-20 after the Ship #054/#056 live-404 incidents — the original wording said "pull the image URL... verbatim," which is what caused both breakages.)
Step 5: Draft using the template structure
Required sections in this order (per template v4.1):
- Frontmatter (image + alt + caption)
- Title:
# Weekly Ship #{NNN}: {Theme}— title case for the whole H1, theme included (template-audit #2, after Ship #058 shipped in sentence case). Sentence case is for the section headings below, not the title - Dateline:
*{Month DD–DD, YYYY}* - Opening: 2–3 paragraphs capturing the theme or major milestone. Reference the previous Ship's theme for continuity if natural.
# 🚀 Shipped this weekwith the 5 workstreams in this order:## ⚙️ Engineering & architecture⬅ FIRST as of #058 (PM ratified 2026-08-29)## 🎯 Product & experience## 🔬 Methodology & process innovation## 🌍 External relations & community(publication list, then the REQUIRED hero image per Step 4c)## 📊 Governance & operations(includes metrics as a bullet list, never a table — PM 2026-07-08)
⚠️ Order changed at #058 — Engineering & architecture now leads. PM, 2026-08-29: "I did put product & experience first a while back when I wanted to emphasize that we weren't just yoloing the code but I do want to reemphasize shipping at this point so we can adjust the template." The original order was itself a deliberate signal (we are not just shipping code), and it did its job; the new order carries the opposite emphasis for the current phase. This is a phase-keyed choice, not a permanent truth — if the emphasis shifts back, expect this to flip again, and don't treat either order as the "correct" one absent PM's current intent.
# 🎯 Coming up next week— brief paragraph# 🚧 Blockers & asks— brief paragraph# 🔎 This week's learning patternwith name as## {Noun-phrase pattern name}and all 5 components:- Discovery: one-sentence description
- Example from this week: specific instance
- Why it matters: impact + what it addresses
- Application beyond this week: how to apply elsewhere
- Related patterns: links to similar patterns
- Footer:
**Thanks,** xian + Piper Morgan Development Team This is Weekly Ship #{NNN}. Previous: [#{N-1} "{TITLE}"](URL). *P.S. {Key takeaway or personal note}* *P.P.S. Full session logs and technical details available in the [GitHub repository](https://github.com/mediajunkie/piper-morgan-product) and [documentation site](https://pmorgan.tech). Yes, you can copy it. That just makes our protocol stronger.* --- **Week of {Month DD–DD, YYYY} | Phase: {Current phase}**
If a workstream has no activity, INCLUDE it with a brief "No significant changes this week" note rather than omitting it.
Step 5-sprint: Progress Ship or final-score Ship (two-week sprints, from Ship #070)
xian's ruling (11-06 10:33, via Exec): Production runs two-week sprints from Fri 11-13, and the Ship stays weekly. The mid-sprint Ship reports progress, and the closing Ship reports the final score. Ship #069 (11-06 to 11-12) is an ordinary weekly Ship. #070 (11-13 to 11-19) is the first progress Ship, and #071 (11-20 to 11-26) is the first final score. After that, odd numbers are final scores and even numbers are progress. Re-check this against the sprint plan if a sprint is ever cut short or stretched. The week-by-week inputs are in section 3 of docs/internal/planning/production-sprint-length-options-2026-11-06.md.
Both forms keep everything in Step 5: one week's window and dateline, the five workstreams, the learning pattern and the footer. Only these parts change:
| Progress Ship (week 1 of 2) | Final-score Ship (week 2 of 2) | |
| Opening | Name the sprint's goal and its named set. Say where the set stands halfway: served, in progress, blocked (with the blocker). | Give the score against the named set first: N of M served. Name each item that missed and why, in one line each. |
| Shipped this week | This week's work, as now. | This week's work, as now. Two-week totals go only in the metrics list, labelled as two weeks. |
| Learning pattern | As now. | Draw it from the lanes' retro lines when one fits. Don't print the retro as a list. |
| Coming up next week | The rest of this sprint's set. | The next sprint's named set if xian ratified it in the review; otherwise say it's being planned. |
| Footer bottom line | Phase: Production, sprint {N}, week 1 of 2 | Phase: Production, sprint {N}, week 2 of 2 |
The score counts what users can now use (served), not what merged. That follows feedback_product_delta_frame_for_reports_and_ship. Take the named set and each item's result from PPM's map and the lanes' closing-week reviews, never from memory.
Step 6: Run the template's audit checklist against the draft
Verify before declaring done:
- All 5 workstreams present under "Shipped this week"
- Workstreams use correct emoji prefixes (🎯 ⚙️ 🔬 🌍 📊)
- Sentence case on all section headings (not Title Case). The H1 title is the exception: title case (template-audit #2)
- Metrics included in Governance & operations as a bullet list (
**Issues closed:** 25) — NEVER a table; Medium/LinkedIn don't render markdown tables (PM 2026-07-08, supersedes template v4.1's table format). Don't force uninteresting metrics to pad the list. - Previous Ship linked in footer (title verified — do not trust memory)
- Phase tag at bottom matches current project phase
- Learning pattern has all 5 components (Discovery / Example / Why it matters / Application / Related)
- No semicolons in published prose (search the draft; should be zero)
- No "honest" stems (honest/honestly/honesty):
grep -n -i honest <draft>outside HTML comments, 0 or a stated verdict per match. A Claude-ism (PM 2026-09-29). Recurred in Ship #065's scaffold and in Comms' review of it on 2026-10-18, and xian caught it. Rephrase to what the honesty consists of. - No "load-bearing" in public-prose sections (internal docbase keeps it; Ships tilt to "critical" / "central")
- No "CoS" anywhere (use "Exec" or "the Chief")
- No "cohort" in prose — internal jargon; use "team" (added 2026-08-19 after Docs caught a live instance in #056's draft; not previously named in this checklist)
- No bare GitHub issue numbers (
#1536) in narrative prose — reserved for Ship self-references only (previous/next-issue footer links). Name the underlying thing instead ("the alpha-tester coldstart fix," not "#1536"). Precedent: 0 of the published Ships before #056 do this; Docs caught and fixed a live instance in #056's draft, first time this rule was stated explicitly rather than existing only as unbroken precedent (added 2026-08-19) - ⚠️ NAME AGENTS DIRECTLY — no parenthetical gloss.
Arch,CXO,Lead Dev, or the anonymousone role. NOT "my chief architect agent (Arch)" or "the product-management role (Piper Alpha)." ★ This line said the opposite until 2026-09-02 and produced a live error in #058's draft, which PM caught and fixed by hand while editing. Verified against every published Ship #054–#057: bare role names andone rolethroughout, zero instances of the gloss. The gloss is a BLOG convention, correct there ("My chief architect agent (Arch) noticed a pattern…") and imported into this skill by mistake. The Ship's reader is following an ongoing series and already knows the cast; a blog post's reader may be arriving cold. Different audience, different rule — don't let the voice guide's general prose discipline override the Ship's own observed practice. - Temporal-relationship language preferred over absolute-date stamps when the relationship is the point
- Affirmative direct preferred over disclaim-then-affirmative
- Section heading names are noun phrases, not verb phrases
- Word count check: no fixed range for Ships, norm ~1,630 (template-audit calibration table). Flag a notably long draft to PM as a question, not a defect
- External section sanity check — every title is character-for-character from the CSV; every date matches the CSV's
pubDate; every URL pasted from the CSV (no invented slugs); every description is grounded in the post's actual content (not inferred from title); any held/queued posts named separately - Hero image present, from the right source — one image follows the publication list, pulled from one of the window's Tue/Thu narrative posts (Medium-only, not LinkedIn-syndicated) specifically, not any insight post's image; alt text and caption verbatim from that post's frontmatter; linked to pipermorgan.ai (Step 4c)
- Day-of-week sanity check — every dated reference (e.g., "Tuesday May 13") matches the actual calendar; verify with
python3 -c "from datetime import date; print(date(YYYY,MM,DD).strftime('%A'))"if uncertain - Role-attribution sanity check — every "the X-role did Y" claim is traceable to a specific memo or omnibus entry (no invented attributions; no swapping who did what)
- Time-since-codification claims — any "the methodology was N days/weeks old when..." claim verified against the codification commit date (
git log -- docs/internal/development/methodology-core/methodology-NN-*if applicable)
Step 7: Save the draft and route for review
- Save location (canonical drafting):
dev/active/weekly-ship-{NNN}-draft-{YYYY-MM-DD}.mdon theclaude/{worktree-slug}branch per worktree-default discipline for substantive output - Public-comms copy: sync to
docs/public/comms/drafts/weekly-ship-{NNN}-draft-{YYYY-MM-DD}.mdon main so PM can read where they expect - Add the editorial-calendar entry in the SAME commit as the draft (Docs finding, 2026-07-21: Ship #052 sat drafted with no calendar row until PM noticed it missing from the admin view while looking for the next ship). Run the
update-calendarskill (or its quick-add script) to add a row withtitle(full ship title incl. subtitle),workDate/endWorkDate(the Fri–Thu window),pubDate(the Wednesday following the window's Thursday end — Ships #046–#053 are 8-for-8 Wednesday, verified from the calendar 2026-07-29; NEVER "target Tuesday" (this line's old text, wrong) and NEVER "day after drafting" (the #053 birth error: drafted late on a Wednesday, row born saying Thursday)),status: drafted,draftPath,theme: ship. Don't defer this to "after PM notices" — it's the same commit that creates the draft file, not a follow-up. - Commit immediately after Write per the May 17 memory
- Route to PM FIRST — PM gates the handoff to Comms. PM reads, fact-checks, voice-passes, and decides when the draft is ready to enter Comms review (PM, 2026-07-08, after Exec routed a draft to Comms prematurely: "It's not ready to go to comms yet. I decide that."). Exec never self-initiates the Comms handoff. Flag word count to PM if outside target.
- Comms pre-publish review happens on PM's go (PM clarification, same day: Exec generally drafts the Ship, but Comms reviews it before publish — a standing step). Comms's
template-auditskill is their review-of-record; Exec's own Step-6 checklist pass does not substitute for it. Sequence is fixed: draft → PM → Comms → publish.
Step 5-alt: Scaffold mode, when xian writes the Ship himself (added 2026-11-04, Ship #067)
xian may hold the pen himself. The order is: he reads the workstream reviews and the synthesis, you discuss the synthesis (the discussed marker is still required), then Exec writes a scaffold in place of a draft. Then xian writes, Exec edits, Comms fact-checks and audits, and the Ship publishes.
A scaffold is the template with the facts laid out, and no prose. In xian's words: "You don't need to write the prose but you do need to provide me with the facts that I am supposed to write about and any details or references... presented to me here as bullet items, talking points or prompts/reminders about what to address."
- In every section, two visible lists: ▸ Write about (the points to cover) and ▸ Facts (figures, issue numbers, links, each with its source). Bring over the synthesis's full content: the user-facing changes, the patterns, each lane's results, the numbers, and the disagreements among sources where they matter.
- Never put the facts in
<!-- -->comments. A rendered preview hides them, and that is how #067's first scaffold reached him looking empty. - Fixed elements go in ready to use: the title once he picks it, the dateline, the External list from the calendar (Step 4b), the hero image (Step 4c, link checked live), the footer and the previous-Ship link.
- Before the scaffold goes to him, re-check every fact against decisions.log and the issues. Pay most attention to lines carried from the synthesis that were written before the week ended. #067's scaffold carried a stale "screen waits for approval" line for a run that had already happened.
- Same commit rules as Step 7: the calendar row's
draftPathgoes in the same commit, and so does the discussed marker.
Anti-Patterns
| Don't Do This | Why | Do This Instead |
| Draft from memory of past Ships | Pure essay form will result; 5-workstream structure will be missed (v0.1 failure mode) | Open ALL 4 canonical artifacts BEFORE drafting |
| Start drafting after reading 3 of 6 memos | Theme bias toward early arrivals | Wait for all 6; read all 6 before writing |
| Trust memo claims as-is | Memos are perspectives, not sources | Cross-check substantive claims against omnibus logs |
| Use "First time" / "longest" / "most" without checking | Unverified superlative is a common error | 30-second history check, or soften the claim |
| Use Title Case on workstream headings | Template specifies sentence case | "Product & experience" not "Product & Experience" |
| Omit a workstream with no activity | Breaks week-over-week comparison | Include with "No significant changes this week" |
| Metrics as a table, or skipped | Medium/LinkedIn don't render markdown tables (template v4.1's table format is superseded, PM 2026-07-08) | Bullet list (**Issues closed:** 25), always included even if approximate |
| Use semicolons in published prose | PM voice discipline May 13 | Split into two sentences or use em-dash |
| Refer to Chief of Staff as "CoS" | PM directive May 15 | Use "Exec" or "the Chief" |
| Bullet-list a reflection-shaped piece | Voice guide May 11: reflection favors declarative paragraphs | Bullets for shopping lists, scoring rubrics, reference material only |
Quality Checklist (final, before handoff)
- All 4 canonical artifacts were open during drafting (process guide / template / voice guide / recent published Ship)
- All 6 workstream memos read in full
- Omnibus logs spot-checked for substantive claims
- Template structure followed in full (5 workstreams + emoji prefixes + sentence case + metrics bullet list + 5-component learning pattern + footer + phase tag)
- Voice discipline passes (no semicolons, no "load-bearing" in public prose, no "CoS")
- Word count: near the Ship norm (~1,630), or a long draft flagged to PM
- Draft committed to worktree branch immediately after Write
- Public-comms copy synced
- PM notified for voice-pass
Key Insight
LLMs struggle to follow templates while creating but excel at auditing against templates afterward (per the audit-cascade skill). Same insight applies here. Open the template AND keep it open during drafting. Then run the audit checklist against the draft before declaring done.
The Ship #043 v0.1 failure was not knowing the template existed — it was choosing to draft from memory instead of opening it. The mechanism layer (this skill) makes the template-loading step procedural rather than remembered. That's the lesson Ship #043 itself names — vocabulary plus mechanism plus sequence; each covers what the prior layer misses.
Related
feedback_ship_drafting_canonical_artifacts_first.md— the vocabulary layer for this skillfeedback_blog_template_and_voice_guide_canonical_for_proofreads.md— parent lesson (proofread version of the same shape)feedback_no_semicolons_in_published_prose.md— voice disciplinefeedback_load_bearing_is_crutch_word_in_public_prose.md— voice disciplinefeedback_exec_nickname_is_exec_or_the_chief_not_cos.md— naming disciplinefeedback_parenthetical_gloss_on_first_use.md— voice disciplinefeedback_temporal_relationship_over_date_stamps_in_public_prose.md— voice disciplinefeedback_affirmative_direct_over_disclaim_then_affirmative.md— voice disciplinefeedback_workstream_review_cadence.md— Fri–Thu window disciplinefeedback_workstream_review_scope.md— Exec synthesizes; 6 leadership roles authorfeedback_ship_needs_all_workstream_reviews_no_partial_draft.md— Step 2b's hard gatedocs/internal/development/methodology-core/methodology-25-WORKSTREAM-REVIEW-CADENCE.md— Friday kickoff trigger + PM notification + prior-cycle-gap check (the early-warning half of the same fix)- audit-cascade skill — the parent procedural pattern this skill mirrors
- create-omnibus skill — sibling skill for the omnibus log artifact
Version history
v1.15 (2026-11-06)
Two Ship forms for two-week sprints (Step 5-sprint). xian moved Production to two-week sprints from 11-13 and kept the Ship weekly: a progress Ship mid-sprint, a final-score Ship at the close. Exec assigned the forms to Comms. Written by Comms.
v1.14 (2026-11-04)
Scaffold mode (Step 5-alt). For Ship #067, xian chose to write the Ship himself from an Exec scaffold. The first scaffold hid its facts in HTML comments, and xian asked for them as visible bullets and talking points. The step also adds a re-check against decisions.log, after a stale synthesis line reached him.
v1.13 (2026-10-23)
Step 2c gets a fixed path, a discussed marker, a status line and a commit gate. Ship #066's draft was written straight from the ten reviews, skipping the synthesis, the omnibus read (Step 3) and the same-commit calendar row (Step 7). It was the second skip of Step 2c after #054, by an Exec working from habit. xian approved the two-part fix: scripts/ship-kickoff.sh prints the cycle's state and next step on every fire from Friday to Wednesday, and a pre-commit gate blocks a new draft until the synthesis exists and is marked discussed. The gate is written and waits for CIO's review before it's registered.
v1.12 (2026-08-08)
Kickoffs now require sprint-truth.py output on any progress claim. PM: "We keep over-reporting completeness on the beta blocker track by mistaking the denominator… It is not great that I am the only entity on this team with an accurate sense of what is in this sprint." Traced to a true-about-a-subset claim ("the build queue went to empty") restated as whole-sprint completeness — by Lead in their report and then by Exec in the report to PM. This is the structural half of the fix (the ambient-context half is with CIO); it covers the weekly cycle, which is where progress claims actually reach PM.
v1.11 (2026-08-07)
New Step 0: required kickoff-memo framing, with copy-this wording and a banned-phrasings list. Third instance of the same PM correction (#045, #046, #055): a stated backstop date reads as the target and licenses deferral, which compresses PM's reading window on staler reports. The rule had existed in memory since June — including a note that it belonged in this skill — and failed anyway in a session that held the pin. Mechanism now lives here. Also carries the contributor-role kickoff (Lead/Docs/PA/Web, added at PM's direction 2026-08-07: progress/setbacks/blockers in their own portfolios, without the leadership milestone apparatus).
v1.10 (2026-08-05)
New Step 2c: internal report precedes the draft — hard gate. PM's ten-step weekly-reporting cycle (stated 2026-08-04, relayed via Janus, codified in the process guide's canonical-cycle section): kickoff memos emphasize progress-vs-goals; Exec synthesizes the internal report as an artifact + notifies Janus BEFORE drafting; the Ship draft follows the PM discussion. Trigger: #054 went 6/6-gate straight to public draft; the internal report was produced only after PM asked where it was.
v1.9 (2026-07-29)
Fixed the pubDate derivation in the calendar-row step (Step: same-commit calendar entry). It said "target Tuesday"; the actual cadence is Wednesday, 8-for-8 across #046–#053 (verified against the calendar CSV, not memory). Trigger: Ship #053's row was born at 10:38 carrying 2026-07-30 (Thursday) — a day-after-drafting slip on a late-drafted Ship — flagged by Comms, corrected same day per PM's "due today." Comms' trace showed the window fields were right and only pubDate was wrong at birth, pointing at the derivation rule; this text was the only derivation rule in the pipeline, and it named the wrong day. #054's target: Wednesday 2026-08-05. Also fixed the stale "Skill version: 1.6" footer.
v1.8 (2026-07-29)
New Step 4c: hero image in External relations & community is now REQUIRED, not optional, and its source is constrained. During Ship #053 review, PM asked that the published-pieces list always be followed by a hero image — specifically from one of the window's two Tuesday/Thursday narrative posts (Medium-only, not directly syndicated to LinkedIn per publishing-cadence.md), with alt text and caption pulled verbatim from that post's frontmatter and linked to pipermorgan.ai. Supersedes v1.5's softer, optional phrasing ("the External section's publication list can be followed by one of the window's cartoon illustrations") with a hard requirement plus an explicit sourcing rule (narrative posts only, not any window illustration, not an insight post's image — insight posts already reach LinkedIn on their own). Codified in parallel in weekly-ship-template-v4.2.md (bumped from 4.1) and weekly-ship-process-guide.md Step 6, with the process guide framing it as a joint CoS-sources / Comms-verifies check, mirroring how template-audit verifies frontmatter on a standalone post. Added to the audit checklist.
v1.7 (2026-07-22)
Step 7: add the editorial-calendar entry in the same commit as the draft. Ship #052 was drafted 7/19 and sat in docs/public/comms/drafts/ with no calendar row until PM noticed it missing from the admin view on 7/21 while looking for the next ship. Docs added the entry retroactively and flagged the gap (memo-docs-to-exec-cc-pm-ship-calendar-update-step-2026-07-21.md) rather than let it recur silently. Fixed at the source: Step 7 now names the calendar update as a required same-commit action, not a follow-up someone has to remember or notice missing.
v1.6 (2026-07-14)
Step 2b: HARD GATE — all 6 workstream memos required before drafting starts, no exceptions for deadline pressure. Ship #051 was drafted in full (through the audit checklist, committed, pushed) with PPM's memo missing — Exec judged that a nudge had gone out and the pubDate was the next day, so proceeded on 5/6. PM overrode directly: "we cannot write the ship without all the workstream reviews... I am still the first audience for the weekly report and I am especially interested in the portfolio updates." Previously this was a should-wait norm (Anti-Patterns table: "Start drafting after reading 3 of 6 memos") without an enforced stop; v1.6 makes it a hard STOP-and-notify-PM gate at Step 2, before Step 3's omnibus read even begins. Paired with a Friday early-warning mechanism added the same day to methodology-25 (workstream-review-cadence) — that catches a missing memo early in the week; this gate is the backstop if the early warning didn't prevent the gap.
v1.5 (2026-07-08, same day as v1.3/v1.4)
Metrics are a bullet list, never a table (PM, during Ship #050 review): Medium and LinkedIn don't render markdown tables, so template v4.1's Governance metrics-table format is superseded — use **Issues closed:** 25 bullets. Don't force uninteresting metrics (e.g. a publications count) just to fill the list. Process guide's former "metrics table is the exception" line retired in the same pass. Also from the same review: the External section's publication list can be followed by one of the window's cartoon illustrations (image linked to its post, exact alt text from the calendar CSV, caption below with its quotation marks preserved).
v1.4 (2026-07-08, same day as v1.3)
Two corrections from live failures the same day v1.3 shipped:
- PM gates the Comms handoff. v1.3 named the Comms review step but let Exec self-initiate the routing ("either order"). Exec then routed a draft to Comms before PM had read it — a draft that turned out to contain a headline factual error. PM: "It's not ready to go to comms yet. I decide that." Sequence is now fixed: draft → PM (fact-check + voice-pass + handoff decision) → Comms review → publish.
- Evidence-tier discipline for claims (see
dev/2026/07/08/ship-050-fact-check-2026-07-08.md): the headline error traced to an inference in one agent's log that the omnibus printed as fact ("first external tester actively using it" — the tester had never successfully installed). The omnibus is the fact-check baseline, not ceiling: any claim resting solely on a log assertion with no artifact (commit/issue/URL/test output) and no PM witness gets softened, attributed, or cut before it enters a public draft. Step 4-prime's "session log is the ground truth" holds for what an agent did; it does not make an agent's inference about someone else's experience into ground truth.
v1.3 (2026-07-08)
Step 7: added the standing Comms pre-publish review step (PM clarification, in-conversation: "You generally do draft the weekly ship but Comms reviews it before we publish"). Previously the routing step named only PM's voice-pass; Comms's review had been happening implicitly via the publish pipeline but wasn't a named, mandatory step in this skill. Also relevant context from the same window: Ship #050's window error (see docs/internal/operations/ship-050-window-date-error-2026-07-08.md) — the fix there is upstream in the kickoff procedure (compute window formulaically, assert day-of-week, verify delivery landed), not in this skill; noted here so a future reader doesn't add redundant machinery to this file. Step 6's existing day-of-week sanity check already covers the drafting side.
v1.2 (2026-05-20, second update same day)
Reordered procedure: omnibus-logs-read is now Step 3 (BEFORE workstream memos), changed from "spot-check" to "REQUIRED, FULL READ." Workstream memos move to Step 4 with explicit guidance to read them "with omnibus context already in head." Added Step 4-prime: pull underlying session logs when omnibus looks thin or memos reference work the omnibus didn't surface.
Trigger for v1.2: PM caught Ship #043 v0.2's fab + coverage-gap structural issue same day v1.1 shipped. v1.1 added the CSV verification for publications but kept omnibus as "spot-check." That left the door open for me to lean on the methodology-focused workstream memos and miss the entire Engineering shipped arc of the week (#921, #857, #1071, #1021, M2f closure, M2g-A + M2g-B, #1070, #304, #1090) that lived in the omnibus logs and Lead Dev session logs. PM directive: "You are my chief and need to form your own views from reading the logs too!"
v1.1 (2026-05-20)
Added required Step 4b (Verify External section against editorial calendar CSV) and four new audit-checklist items (External-section sanity check, day-of-week sanity check, role-attribution sanity check, time-since-codification claims). v1.0 had the discipline named ("verify all claims against omnibus logs") but did NOT enforce CSV cross-reference for publications. PM caught the fabrication in Ship #043 v0.2 on May 20 morning during pre-publication review. The skill missed: every publication title, every date, and every URL in the External section was fabricated by pattern-matching to Ship #042's format. v1.1 closes the gap.
v1.0 (2026-05-19)
Initial skill. Lists canonical artifacts to load before drafting. Names voice-discipline checks. Procedure + audit checklist.
Skill version: 1.13 Created: 2026-05-19 (v1.0) Updated: 2026-05-20 (v1.1 — External-section verification step; v1.2 — omnibus is required full read, not spot-check); 2026-07-08 (v1.3 — Comms pre-publish review is a named mandatory step; v1.4 — PM gates the Comms handoff + evidence-tier discipline; v1.5 — metrics as bullet list, never a table); 2026-07-14 (v1.6 — Step 2b hard gate: all 6 memos required, no partial drafts under deadline pressure); 2026-10-12 (v1.13 — template-audit named the single source for formatting, per PM's D-C "yes"; H1 title is title case; Ship word count follows the ~1,630 norm, not 800–1,200) Scope: Exec (drafts); PM (gates); Comms (reviews)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

