agentleFS
mediajunkiemediajunkie/piper-morgan-product/.claude/skills/update-calendar/SKILL.md

update-calendar

Skill8 starsChanged 11 days agoApache-2.0View on GitHub

Update the editorial calendar CSV when PM reports a publication,

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Update the editorial calendar CSV without the PM touching a spreadsheet.

    line 16
  2. Distinctive:

    Use this skill when:

    line 20
  3. Distinctive:

    Write your own columns yourself, through this skill: Do not route routine updates through another agent's inbox.

    line 43
  4. Distinctive:

    If not found and PM is adding a new entry, proceed to Step 3.

    line 106
  5. Very specific:

    Always read and write through Python's csv module, and always address fields by header name:

    line 112
  6. Distinctive:

    Run a whole-file scan after every edit:

    line 172
  7. Distinctive:

    Treat any assertion failure as a stop-and-investigate signal, not something to paper over — a semantic anchor tripping means content is …

    line 193
  8. Distinctive:

    Both were fixed in the checker, not in the data: If this script reports a warning on a historical row, the default assumption is that the …

    line 211
  9. Distinctive:

    Verify with the validator (it now reports non-resolving paths) or directly:

    line 224
  10. Distinctive:

    Update: mediumURL → [URL], status → published (if not already)

    line 271

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

update-calendar

Update the editorial calendar CSV without the PM touching a spreadsheet.

When to Use

Use this skill when:

  • PM says "published [title] on [platform] at [URL]"
  • PM says "add [title] to the calendar" (new draft or queued piece)
  • PM provides Medium/LinkedIn URLs after syndication
  • PM says "mark [title] as published" or changes status
  • PM provides alt text or caption for an image
  • Any editorial calendar metadata needs updating

CSV Location

docs/internal/planning/comms/editorial-calendar.csv

Column ownership — who writes what (PM-RATIFIED 2026-07-29)

This calendar is multi-writer by design. There is no single owner, and proposals to make one have been considered and rejected.

OwnerColumns
Comms (editorial authorship)title · theme · workDate · endWorkDate · pubDate · cartoon · chatDate · draftPath · notes · altText · caption
Docs (publish / syndication transaction)blogURL · blogPath · canonicalSite · mediumURL · liPubDate · linkedinURL
Shared, SEQUENTIALLYstatus — Comms owns it through drafted → ready-for-docs; Docs owns it from published → distributed

Write your own columns yourself, through this skill. Do not route routine updates through another agent's inbox. Send a memo only to cross the boundary — to ask for a change to a column you don't own, or to propose a structural change such as adding a column.

⚠️ status is the one column to be most careful with. It is the lifecycle field the publish pipeline routes on, so a wrong value there misroutes work rather than merely being inaccurate. If you are not sure whether a transition is yours, ask before writing it.

Why this is ownership-by-column and not ownership-by-agent

Docs proposed sole-Docs-ownership on 2026-07-29 and PM rejected it, correctly. The empirical case against it: the calendar took 170 commits in 60 days, 57 tagged (comms) against 4 tagged (docs) — Comms is the incumbent primary writer, and a single-writer rule would have made one agent's inbox a bottleneck on work others already do correctly. It would also have added a second failure mode: the memo that sits unread. That is not hypothetical — on the same day, Docs published a post ten minutes after Comms had already delivered the answer to its one open blocker, in an unopened memo.

And plurality of writers was never the cause of the corruption anyway. Both documented incidents came from positional access, which one writer can do just as destructively:

  • 2026-07-14 — row[-2] used for notes (index 15) landed on altText (index 16).
  • 2026-07-28 — Weekly Ship #050: notes held a duplicate draftPath, altText held 1,000+ chars of prose, caption held the real alt text. Field count stayed 18 throughout, so every count-based check passed.

The mechanism that prevents this is by-name access through this skill plus the validator (Step 4), not a restriction on who may write. Address every field by header name; never by position.

CSV Schema (18 columns)

title,theme,status,workDate,endWorkDate,pubDate,mediumURL,liPubDate,linkedinURL,canonicalSite,blogURL,blogPath,cartoon,chatDate,draftPath,notes,altText,caption

Field Reference

ColumnValues/FormatNotes
titleFree textQuote if contains commas
themebuilding, insight, shipContent type
statusplanned, drafted, queued, ready-for-docs, published, distributed, not-syndicatedLifecycle state — see below. Shared column: Comms writes through ready-for-docs, Docs from published on.
workDateYYYY-MM-DDWhen the piece was written
endWorkDateYYYY-MM-DDEnd of work period (optional)
pubDateYYYY-MM-DDPublication date
mediumURLFull URLMedium publication link
liPubDateYYYY-MM-DDLinkedIn publication date
linkedinURLFull URLLinkedIn post link
canonicalSitedistributed or emptySet to distributed when on blog + syndicated (pipeline dedup signal; independent of status)
blogURLFull URLe.g., https://pipermorgan.ai/blog/{slug}
blogPathPathe.g., /blog/{slug}
cartoonSlugImage slug (no extension)
chatDateM/D/YYYYDate of source chat session
draftPathRelative pathe.g., docs/public/comms/drafts/draft-name.md. Deliberately a live pointer, not an authoring-history record — it must always resolve on origin/main. When Step 9 archives a published draft to drafts/published/, update draftPath to match in the same pass (see Step 4b). A path that stops resolving after publish is a miss, not an accepted tradeoff — confirmed 2026-09-13 after Dispatch-PM asked rather than assumed.
notesFree textAny notes
altTextFree textImage alt text (quote if contains commas)
captionFree textImage caption (quote if contains commas)

Procedure

Step 1: Find the Row

grep -n "SEARCH_TERM" docs/internal/planning/comms/editorial-calendar.csv

If not found and PM is adding a new entry, proceed to Step 3.

Step 2: Update Existing Row — via the csv module, keyed by column NAME, never by position

Never use the Edit tool or hand-spliced string surgery on a CSV row, and never index a row by a raw number or [-N] offset. A quoted field can contain commas, and a raw string edit or positional index (row[-2], row[15]) silently breaks the moment the row's shape doesn't match what you assumed — no error, just quiet semantic drift that a field-count check won't catch (see the 2026-07-14 incident below: two same-day edits by Comms did exactly this, corrupting a live row for hours before a peer agent caught it).

Always read and write through Python's csv module, and always address fields by header name:

import csv
PATH = 'docs/internal/planning/comms/editorial-calendar.csv'
with open(PATH, newline='', encoding='utf-8') as f:
    rows = list(csv.reader(f))
hdr = rows[0]
idx = {name: hdr.index(name) for name in hdr}
row = next(r for r in rows[1:] if r and r[0] == TITLE)
assert len(row) == len(hdr)          # bail loudly if the row is already malformed
row[idx['status']] = 'published'     # BY NAME — never row[2], never row[-2]
with open(PATH, 'w', newline='', encoding='utf-8') as f:
    csv.writer(f, lineterminator='\n').writerows(rows)

Always read the current row first to avoid clobbering existing data. Only change the fields PM specified — preserve everything else. When appending to a free-text field (like notes), append to row[idx['notes']] specifically — never assume its position relative to the end of the row.

Status lifecycle (PM-ratified 2026-07-19; planned added 2026-09-19):

  • planned → a pre-seeded future slot with a sequential number and a pubDate, but no draft yet — currently only used for the Wednesday Ship cadence (PM's ask, routed via Exec 2026-09-19: pre-seed upcoming Ship slots so an empty Wednesday becomes a real gap signal instead of the default pre-draft state, which was previously indistinguishable from a stall). Deliberately excluded from reconcile-drafts-calendar.py's ACTIVE_STATUSES — a planned row's empty draftPath is correct, not a defect, and must never be flagged as MISSING DRAFTPATH.
  • drafted → piece is in draft
  • queued → scheduled but not yet published
  • published → live at pipermorgan.ai (blog-first)
  • distributed → live at pipermorgan.ai AND cross-posted to Medium/LinkedIn
  • not-syndicated → terminal, PM-ruled "don't backfill" on a missed crosspost (added 2026-10-01, decisions.log). Live at pipermorgan.ai; the crosspost was a lapse PM decided not to rectify — Medium is not the canonical version, and a late backfill only gets more out of date as the narrative rolls on. Neither crossposted nor pending: it is NOT a gap and must never resurface as one. Docs's duty-cycle Step 1f and Exec's rollup scan both key on status=published, so this value drops out of both automatically; the website admin dashboard's syndicationGaps() does the same. Only PM sets a row to this — Docs applies it on PM's ruling, never on its own judgment that a backfill "isn't worth it." The first case was "Drained on Paper" (08-07), which PM had ruled on when it first came up but nobody recorded durably, so it resurfaced four times across two roles before this status existed to lock it.

⚠️ canonicalSite=distributed means "on blog AND syndicated" — do NOT set it at blog-first publish. (Corrected 2026-08-26, Docs — this section previously instructed setting it at blog-first publish, directly contradicting the Field Reference definition above. Following that wrong instruction is exactly how #1683's 145-row undercount happened at scale via the 2026-07-19 migration, and how Weekly Ship #057 picked up the same inconsistency same-day: canonicalSite got set to distributed at blog publish, hours before its LinkedIn leg actually ran.) It's a separate pipeline signal (used for RSS dedup) from status, but it belongs on the SAME event as the syndication leg, not the blog-first publish.

Common updates:

  • Blog-first publish: Set status→published, blogURL, blogPath. Leave canonicalSite empty — a post with no syndication leg planned should stay canonicalSite='' indefinitely; that's the correct end state, not a gap. Also remind PM the crosspost is still owed (PM does this by hand — Medium+LinkedIn for narratives/insights, LinkedIn-only for Ships, per reference_syndication_targets_by_category): if PM is present in the current conversation, mention it right here. If PM isn't present, this is caught automatically by duty-cycle-tick's Docs-only Step 1f, which resurfaces any post published in the last 7 days still sitting at status=published until it flips to distributed — don't rely on remembering to mention it once and never checking again. (PM-ratified 2026-09-29, in conversation, after a same-day miss where a post published and sat unsyndicated for hours before PM noticed independently — neither Exec's rollup nor a Janus conversation surfaced it. The memory pin feedback_remind_pm_to_crosspost_unsyndicated_publications records the human context; this skill step + the duty-cycle check are the durable, git-tracked, portable mechanisms — per PM's own stated preference for visible/portable over opaque/locked-in, memory alone isn't relied on here.)
  • Cross-posted to Medium/LinkedIn (any leg, not necessarily both — e.g. Ship theme routes LinkedIn-only): Set status→distributed, add mediumURL/liPubDate/linkedinURL for whichever leg ran, and set canonicalSite→distributed here.
  • New draft: Set status→drafted, workDate, theme, draftPath
  • Scheduled: Set status→queued, pubDate
  • Pre-seed a future placeholder slot (e.g. an upcoming Ship number): append a new row with status→planned, title/theme/pubDate filled, everything else (workDate, draftPath, cartoon, altText, caption) left empty. When the piece is actually drafted, this row is updated in place (status→drafted, draftPath, workDate) — it is not a second row.

Step 3: Add New Row (if entry doesn't exist)

Build the new row as a Python list in schema order (18 elements, empty string for unset fields) and append it via csv.writer — the module handles quoting automatically, so you never hand-quote commas or embedded quotes yourself.

Step 4: Verify — count AND semantics, whole file, not just the touched row

A field-count check on the one row you touched is not sufficient — it cannot detect a row where content has drifted into the wrong column while the total count stays correct (exactly what happened 2026-07-14: an append landed in altText instead of notes, field count stayed at 18, and the drift went undetected until a later, unrelated edit collapsed the count and made it visible).

Run a whole-file scan after every edit:

import csv, re
with open('docs/internal/planning/comms/editorial-calendar.csv', newline='', encoding='utf-8') as f:
    rows = list(csv.reader(f))
hdr = rows[0]
idx = {n: hdr.index(n) for n in hdr}
bad = [i for i, r in enumerate(rows[1:], start=2) if r and len(r) != len(hdr)]
assert not bad, f"field-count mismatch at rows {bad}"
for i, r in enumerate(rows[1:], start=2):
    if not r or len(r) != len(hdr):
        continue
    cs = r[idx['canonicalSite']]
    assert cs in ('', 'distributed'), f"row {i}: canonicalSite={cs!r}"
    st = r[idx['status']]
    assert st in ('planned', 'drafted', 'queued', 'ready-for-docs', 'published', 'distributed', 'not-syndicated', ''), f"row {i}: status={st!r}"
    bu = r[idx['blogURL']]
    assert not bu or bu.startswith('http'), f"row {i}: blogURL={bu!r}"

Treat any assertion failure as a stop-and-investigate signal, not something to paper over — a semantic anchor tripping means content is very likely sitting in the wrong column.

⭐ The inline snippet above is now the FALLBACK. The canonical check is the script (extended 2026-07-29 to cover per-column shape + reference integrity — it supersedes the hand-rolled asserts):

python3 scripts/validate-editorial-calendar.py            # errors fail, warnings print
python3 scripts/validate-editorial-calendar.py --strict   # warnings also fail

It adds what the inline version cannot see: per-column shape (enums, YYYY-MM-DD vs chatDate's M/D/YYYY, URL/path prefixes, and the Ship #050 repo-path-in-prose signature) and reference integrity (draftPath actually resolves on disk).

Errors block; warnings never do — and that split is deliberate. A heuristic that hard-fails causes false corrections, which are worse than the drift they claim to fix. Two live examples, both from the validator's own first run: it flagged 8 historical Ships carrying the pre-ship value theme='shipping news', and a notes field holding a claude.ai URL that happens to end in .md. Both were fixed in the checker, not in the data. If this script reports a warning on a historical row, the default assumption is that the row is fine and the heuristic is coarse.

⚠️ Step 4b: If you MOVED a draft file, update draftPath in the same pass

This is the single most common way this calendar goes stale. Archiving a draft to docs/public/comms/drafts/published/ without updating its row leaves the row pointing at a path that no longer exists — silently, since nothing used to check.

  • 7 stale paths were found and repaired on 2026-07-29 (3 Weekly Ships + 4 narrative posts). Every one had this cause.
  • A 2026-07-12 pass fixed 22 instances and did not fix the cause, which is why it recurred within three weeks.
  • publish-to-blog Step 9 is where the move happens; the row update belongs in the same commit.

Verify with the validator (it now reports non-resolving paths) or directly:

python3 -c "
import csv, os
bad = [(r['title'][:44], r['draftPath']) for r in csv.DictReader(open('docs/internal/planning/comms/editorial-calendar.csv'))
       if (r.get('draftPath') or '').strip() and not os.path.exists(r['draftPath'])]
print(f'{len(bad)} unresolvable draftPaths'); [print('  ', t, p) for t, p in bad]
"

Expected: 0 unresolvable draftPaths.

Step 5: Rebuild the calendar view

python3 scripts/build-editorial-calendar-view.py

This regenerates docs/internal/planning/comms/editorial-calendar-view.html from the CSV. Always run after any CSV change to keep the admin view current.

Step 6: Commit

git add docs/internal/planning/comms/editorial-calendar.csv \
        docs/internal/planning/comms/editorial-calendar-view.html
git commit -m "editorial calendar: [what changed]"

Anti-Patterns

Don'tDo Instead
Ask PM to edit the CSVUpdate it yourself from their verbal instructions
Overwrite fields PM didn't mentionRead current row first, preserve existing data
Forget to quote commas in titlesUse "Title, With Comma" (or let csv.writer handle it)
Leave status as queued after blog publishUpdate to published
Leave status as published after cross-postingUpdate to distributed
Skip the blogURL for blog-first postsAlways set blogURL + blogPath (leave canonicalSite empty — only cross-post sets it)
Edit a row with the Edit tool, or index it by number/[-N]Use the csv module, address every field by header name
Verify only the touched row's field countWhole-file scan: field count + semantic anchors on every row

Examples

PM says: "Published Are We Doing It Backwards on Medium at [URL]"

  1. Find row: grep -n "Backwards" editorial-calendar.csv
  2. Update: mediumURL → [URL], status → published (if not already)
  3. Commit

PM says: "Add 'The Quiet Before the Question' to the calendar, narrative, work dates Mar 5-10"

  1. Append: The Quiet Before the Question,building,drafted,2026-03-05,2026-03-10,,,,,,,,,,,,
  2. Commit

PM says: "Here are the Medium and LinkedIn URLs for Wiring vs Wizardry: [URLs]"

  1. Find row, update mediumURL + linkedinURL + liPubDate
  2. Commit

v1.1 — Added Step 5: rebuild calendar view HTML after every CSV change (2026-06-29). v1.2 — Replaced Edit-tool/positional-index row surgery with csv-module-by-name access (Steps 2-3), and upgraded verification to a whole-file field-count + semantic-anchor scan (Step 4) (2026-07-14). Root-caused from a real incident: two same-day Comms edits used row[-2] for the notes field, which actually landed on altText (18-column schema, notes at index 15, altText at 16) — the drift stayed invisible under a single-row field-count check until a later edit collapsed the count, at which point a peer session caught and repaired it. See docs/internal/planning/comms/editorial-calendar.csv "The Migration Wave" row's own notes for the full incident trace. v1.6 — not-syndicated status added (2026-10-01, PM ruling, decisions.log). A third terminal status for a missed crosspost PM has ruled not worth backfilling — Medium isn't the canonical series, a late backfill only decays. Lifecycle table, the inline verification snippet, and scripts/validate-editorial-calendar.py's STATUSES set all updated. First row: "Drained on Paper". The real lesson is the one PM named: the ruling had been given when the question first arose and nobody wrote it down, so it resurfaced four times across two roles. A ruling needs a durable home the moment it's made, not the fourth time it's asked.

v1.5 — Crosspost reminder added to the blog-first-publish step (2026-09-29, PM-ratified in conversation). A post published blog-first and sat unsyndicated long enough for PM to notice independently — neither Exec's rollup nor a Janus conversation had surfaced it. New instruction: remind PM about the owed crosspost right at the publish step if PM is present; if not, the recurring Docs-only Step 1f in duty-cycle-tick (added same day) catches it at every subsequent fire until status flips to distributed. Per PM's explicit preference for visible/git-tracked/ portable mechanisms over opaque ones: the memory pin recording this ask (feedback_remind_pm_to_ crosspost_unsyndicated_publications) is a human-context note, not the primary mechanism — this skill step and the duty-cycle check are.

v1.4 — Column ownership PM-RATIFIED (2026-07-29). Added the ownership table (Comms = editorial columns; Docs = publish/syndication columns; status shared sequentially) plus the reasoning for why it is ownership-by-column rather than by-agent. Docs proposed sole-Docs-ownership and PM rejected it: 170 commits in 60 days, 57 tagged (comms) vs 4 (docs), so a single writer would bottleneck the incumbent primary writer — and both documented corruptions came from POSITIONAL ACCESS, which one writer can do just as destructively. Also: Step 4 now names scripts/validate-editorial-calendar.py as the canonical check (extended same day with per-column shape + draftPath-resolves checks; errors block, warnings never do, because a hard-failing heuristic causes false corrections). New Step 4b: if you moved a draft file, update draftPath in the same pass — 7 stale paths repaired 2026-07-29, all from archival moving files without updating rows, after a 7/12 pass fixed 22 instances without fixing the cause.

v1.3 — Added distributed status value (PM-ratified 2026-07-19): published = live on pipermorgan.ai; distributed = blog + cross-posted. Bulk-migrated 243 rows from status=published to status=distributed (all rows with canonicalSite=distributed). Added status semantic anchor to Step 4 verification. Updated lifecycle table and anti-patterns. v1.5 — Fixed a self-contradiction in the Common Updates section (2026-08-26, Docs). The Field Reference table always said canonicalSite=distributed means "on blog + syndicated," but Common Updates instructed setting it at blog-first publish — before syndication. This is the root cause of both directions of #1683: the 2026-07-19 migration's 145-row undercount (rows genuinely fully-synced but never selected because canonicalSite was never reliably set at the right moment), and a same-day fresh instance on Weekly Ship #057 (published this skill's own prior instructions, canonicalSite set to distributed hours before its LinkedIn leg actually ran, caught by Dispatch-PM). Moved the canonicalSite→distributed action from the blog-first-publish bullet to the cross-post bullet, where it matches the field's own definition. Historical rows are NOT touched by this fix — see #1683 for the separate, deliberately-not-rushed remediation of existing data.

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.