agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/draft-weekly-ship/SKILL.md

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.

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
  1. Very specific:

    All 6 workstream-NNN memos are in mailboxes/exec/inbox/ and a theme has been agreed

    line 27
  2. Very specific:

    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 …

    line 128
  3. Very specific:

    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 …

    line 144
  4. Distinctive:

    Anti-pattern explicit: do NOT pattern-match to a prior Ship's External-section shape (Sat insight / Sun insight / Tue narrative / Thu …

    line 176
  5. Distinctive:

    If a workstream has no activity, INCLUDE it with a brief "No significant changes this week" note rather than omitting it.

    line 243
  6. Distinctive:

    Verify before declaring done:

    line 263

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

draft-weekly-ship

Formatting rules have one source: template-audit (PM, 2026-10-12, CIO's R6 decision D-C). Where this skill and template-audit disagree on a formatting rule (tease, metrics, title case, glosses, word count), template-audit wins, 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

#WhatPath
1Process guidedocs/internal/development/weekly-ship-process-guide.md
2Template v4.1knowledge/weekly-ship-template-v4.1.md
3Voice & tone guidedocs/internal/planning/comms/xian-voice-tone-guide.md
4Most recent published Shipdocs/public/comms/drafts/published/weekly-ship-{N-1}*.md (look up actual filename)

Sources for synthesis

#WhatPath
5All 6 workstream memosmailboxes/exec/inbox/workstream-{NNN}-{role}-{date}.md (for roles: arch, cio, comms, cxo, host, ppm)
6Omnibus logs for Fri–Thu windowdocs/omnibus-logs/2026-MM-DD-omnibus-log.md for each day in the window
7Editorial calendar CSV (REQUIRED for the External section)docs/internal/planning/comms/editorial-calendar.csv
8Published-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.py and 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, plus liPubDate if LinkedIn-syndicated)
  • Exact URL (blogURL for canonical, mediumURL and linkedinURL for syndication)
  • Theme/category (theme column — insight / building / ship)
  • Status — anything with status other than published is 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:

![alt text]({slug}.webp URL — NOT the frontmatter image: value)
*"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):

  1. Frontmatter (image + alt + caption)
  2. 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
  3. Dateline: *{Month DD–DD, YYYY}*
  4. Opening: 2–3 paragraphs capturing the theme or major milestone. Reference the previous Ship's theme for continuity if natural.
  5. # 🚀 Shipped this week with 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.

  6. # 🎯 Coming up next week — brief paragraph
  7. # 🚧 Blockers & asks — brief paragraph
  8. # 🔎 This week's learning pattern with 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
  9. 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)
OpeningName 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 weekThis 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 patternAs now.Draw it from the lanes' retro lines when one fits. Don't print the retro as a list.
Coming up next weekThe 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 linePhase: Production, sprint {N}, week 1 of 2Phase: 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 anonymous one 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 and one role throughout, 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}.md on the claude/{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}.md on 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-calendar skill (or its quick-add script) to add a row with title (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-audit skill 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 draftPath goes in the same commit, and so does the discussed marker.

Anti-Patterns

Don't Do ThisWhyDo This Instead
Draft from memory of past ShipsPure 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 memosTheme bias toward early arrivalsWait for all 6; read all 6 before writing
Trust memo claims as-isMemos are perspectives, not sourcesCross-check substantive claims against omnibus logs
Use "First time" / "longest" / "most" without checkingUnverified superlative is a common error30-second history check, or soften the claim
Use Title Case on workstream headingsTemplate specifies sentence case"Product & experience" not "Product & Experience"
Omit a workstream with no activityBreaks week-over-week comparisonInclude with "No significant changes this week"
Metrics as a table, or skippedMedium/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 prosePM voice discipline May 13Split into two sentences or use em-dash
Refer to Chief of Staff as "CoS"PM directive May 15Use "Exec" or "the Chief"
Bullet-list a reflection-shaped pieceVoice guide May 11: reflection favors declarative paragraphsBullets 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 skill
  • feedback_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 discipline
  • feedback_load_bearing_is_crutch_word_in_public_prose.md — voice discipline
  • feedback_exec_nickname_is_exec_or_the_chief_not_cos.md — naming discipline
  • feedback_parenthetical_gloss_on_first_use.md — voice discipline
  • feedback_temporal_relationship_over_date_stamps_in_public_prose.md — voice discipline
  • feedback_affirmative_direct_over_disclaim_then_affirmative.md — voice discipline
  • feedback_workstream_review_cadence.md — Fri–Thu window discipline
  • feedback_workstream_review_scope.md — Exec synthesizes; 6 leadership roles author
  • feedback_ship_needs_all_workstream_reviews_no_partial_draft.md — Step 2b's hard gate
  • docs/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:

  1. 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.
  2. 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)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.