weekly-shipped

This skill turns a week's worth of shipped commits into a short report that reads like a person wrote it, not like a release-note generator dumped a template.

What this is for

• Weekly "what shipped" recaps from main
• "Top 3/5/10 improvements that landed"
• End-user framing: what changed, what got easier, what got safer, what got less annoying
• Founder/operator updates where commit detail matters less than practical impact

What this is not for

• A raw commit log
• A PR-by-PR changelog
• A code review
• A roadmap or "what's next" memo unless the user asks for that separately

Workflow

1. Pull the shipped window from main, not the current feature branch. Use exact dates when the user says "this week", "last week", or similar.
2. Cluster commits into improvements. A good report item usually maps to a fix/theme/outcome, not a single tiny commit.
3. Rank by user-facing consequence. Prefer reliability, safety, usability, cost, clarity, and time-saved over internal cleanup.
4. Write from the outside in. Start with what changed for a normal user, then explain why it matters.
5. Write the finished report to PROJECT/3-COMPLETED/WEEKLY-YYYY-MM-DD.md. The date in the filename is the date the report is generated, not the start of the shipped window.

Sourcing

Default starting point:

git log main --first-parent --since="<start>" --until="<end>" --oneline
git log main --since="<start>" --until="<end>" --stat --format='%h %ad %s' --date=short

Use --first-parent when the question is about what actually landed on main. Drop to fuller history only when you need extra detail to understand a merged theme.

Two gotchas that silently produce a truncated or stale window:

• --since/--until can prune too early. If the first-parent chain isn't perfectly date-monotonic (a merge pulling in an older branch), git log --since=X can stop walking before reaching commits that are actually in range, with no error or warning. If the returned list looks suspiciously short, cross-check with a plain git log <ref> --first-parent -20 --format='%h|%ad|%s' --date=short (no since/until) and pick the boundary commit by eye, then use a <boundary>..<ref> range instead of date flags.
• A local main can be behind origin/main. Check git rev-list --count main..origin/main (or git log main..origin/main --oneline) before trusting local history. If it's behind, fetch or read origin/main directly rather than reporting stale content as this week's ship list — don't push/reset local main to "fix" it.

If the repo maintains a human-authored CHANGELOG.md (or similar) with one entry per shipped change, check it before falling back to raw commits — it's usually already clustered and written in plain language, which is closer to the report's final shape than a commit log is.

How to choose the top items

Prefer items that changed one of these:

• The default path got more reliable
• The tool became safer to trust
• Setup or usage got easier
• Output got easier to understand
• Cost or surprise went down

Skip items that are mostly:

• bookkeeping
• doc reshuffles with no user-visible effect
• tiny follow-ups unless they close a painful edge case

Writing style

The report should sound natural even though the process is structured.

• Do not sound like a release-note template.
• Do not repeat the same sentence frame in every item.
• Do not open every second paragraph with the same stock phrase.
• Vary the rhythm: one item can lead with the pain removed, another with the new behavior, another with the downstream effect.
• Prefer concrete language over abstract praise.

Avoid robotic filler like:

• "Users should care because ..."
• "This improvement enhances ..."
• "This feature provides ..."
• "Net impact:"
• "Overall, this means ..."

Instead, write more directly:

• "The default path is less brittle now."
• "This cuts a common failure case."
• "The tool is less likely to surprise you here."
• "Reading the output takes less work."

Output shape

Unless the user asks otherwise:

• Write the report to PROJECT/3-COMPLETED/WEEKLY-YYYY-MM-DD.md
• Use the current local date for YYYY-MM-DD
• Make the file Markdown
• Start with a short title that names the shipped window
• Use a numbered list
• One improvement per item
• Lead with the shipped improvement itself
• Keep each item short
• Frame it in everyday-user terms, not implementation trivia

Example output path on July 17, 2026:

PROJECT/3-COMPLETED/WEEKLY-2026-07-17.md

Good pattern:

1. What shipped. One or two sentences on the visible change.

   One short paragraph on why that change matters in normal use.

Bad pattern:

1. "Commit X changed Y and Z and then commit A updated B and then commit C..."

Tone

• Crisp, not breathless
• Specific, not generic
• Calmly opinionated about why something matters
• No hype
• No canned "why you should care" wording unless it genuinely fits that one item

Final check before writing

Before writing the file and returning its path, scan for repetition:

• repeated openers
• repeated "this means" constructions
• repeated "users" phrasing
• too many items with the exact same two-paragraph cadence

If it sounds patterned, rewrite for variation before sending.