@gurupanguji

My Web This Week Design

Goal

Automatically generate a Sunday roundup post titled 🔗 My web this week - W<weeknumber> from that week’s existing 🔗 posts in _posts/, and publish it on Sunday at 05:00 PT.

Problem

Issue #99 asks for a weekly summary post that compiles the week’s quotes into one Sunday artifact.

The repository already has:

• scheduled posts in _posts/
• required social snippet companions in _snippets/
• scheduled deploy behavior in deploy_site.yml
• scheduled social publishing in publish_social.yml

What is missing is a content-generation step that creates the weekly roundup before the Sunday publish window.

Design

1. Add a dedicated weekly roundup generator

Add a small generator script, likely scripts/generate_my_web_this_week.py.

Responsibilities:

• accept an explicit target Sunday date, with a default that resolves to the next or current Sunday used by the scheduled workflow
• scan _posts/ for source posts inside that roundup week
• select only posts whose title starts with 🔗
• extract supported roundup material from each qualifying post
• render or refresh the weekly post in place
• render or refresh the companion snippet in place

The script should be deterministic and safe to rerun for the same Sunday.

2. Keep source extraction narrow in v1

Supported source shapes in v1:

• posts with a leading markdown blockquote
• posts with a leading embed block that Jekyll already handles

Unsupported in v1:

• legacy wp:quote HTML extraction

That older markup cleanup should stay separate as follow-up issue #100.

This keeps the generator simple and aligned with the repository’s native-markup direction.

3. Define the roundup window explicitly

For a given target Sunday:

• include source posts from the preceding Monday through Saturday
• sort them by post date ascending

The workflow’s normal scheduled run should happen before Sunday morning publish, so in practice it composes the week that just ended.

The generator should work from the target Sunday date instead of “today” so manual reruns stay predictable.

4. Generate a scheduled Sunday post

Write or refresh a post at:

• _posts/YYYY-MM-DD-my-web-this-week.md

Required front matter:

• layout: post
• title: "🔗 My web this week - W<weeknumber>"
• date: YYYY-MM-DD 12:00:00 +0000

The date must follow the repository’s scheduled-post rule so it will publish at 05:00 PT.

The body should use native markdown and stay minimal.

For each included source post:

• heading with the original post title
• extracted markdown quote when a leading markdown blockquote exists
• otherwise, for embed-led posts, a short line such as Linked artifact: followed by the visible source URL
• a link back to the original gurupanguji.com daily post for that day

The roundup should not invent new commentary.

5. Generate or refresh the companion snippet

Write or refresh:

• _snippets/YYYY-MM-DD-my-web-this-week.md

This repo already treats snippets as mandatory for future-dated posts, so the weekly generator should create both artifacts in the same pass.

The snippet should match the generated post’s front matter and canonical URL conventions.

6. Add a scheduled workflow that opens a PR

Add a workflow that runs before the Sunday morning publish window.

Responsibilities:

• check out the repository
• run the weekly generator for the target Sunday
• detect whether the post or snippet changed
• if files changed, create or update a feature branch
• open a PR instead of pushing to main

This should follow the repository’s PR-only automation policy.

Operational constraints:

• prefer PR plus auto-merge for this generated-content update
• verify that the repository setting allowing GitHub Actions to create pull requests is enabled before depending on the workflow
• fail clearly if PR creation is blocked by repository settings or permissions

7. Make reruns update in place

If the weekly post or snippet already exists for that Sunday:

• treat the existing files as the target artifacts
• refresh their generated content in place
• keep the same file paths and slug

This makes the job idempotent in a useful way. Reruns should rebuild the roundup instead of treating an existing file as an error.

8. Fail only on empty or broken generation

Failure conditions:

• no qualifying source posts exist for the roundup window
• source extraction fails in a way that prevents generating any valid content
• workflow automation cannot create or update the PR branch

Partial success behavior:

• if some source posts qualify and others do not, generate from the qualifying set only
• log skipped files with the reason, such as unsupported wp:quote markup or missing leading supported content

File Changes

New

• docs/superpowers/specs/2026-03-26-my-web-this-week-design.md
• scripts/generate_my_web_this_week.py
• a new GitHub Actions workflow for scheduled weekly generation

Modify

• test files covering the new generator behavior
• possibly scripts/validate_posts.py only if the weekly generation path needs explicit validation support

Testing

Add unit coverage for:

• target Sunday and roundup-week selection
• filename, slug, title, and scheduled timestamp generation
• markdown blockquote extraction
• embed-led source extraction
• canonical gurupanguji.com link generation for each included daily post
• update-in-place behavior when the weekly post or snippet already exists
• empty-week failure behavior

Risks

Source formats are inconsistent

Some older link posts still use legacy wp:quote markup. Deferring that extraction keeps v1 smaller, but it means the first version may skip some otherwise relevant posts.

Workflow write permissions may block automation

If GitHub Actions cannot create or update branches and PRs, the weekly generation workflow will not complete. The workflow should fail loudly with a clear message about the required repository setting or token permission.

Generated content can drift if reruns are manual and late

Because reruns refresh the target Sunday artifact in place, the generator must use an explicit target Sunday window so manual reruns stay deterministic.

Acceptance Criteria

1. A scheduled run before Sunday morning creates or refreshes _posts/YYYY-MM-DD-my-web-this-week.md for the target Sunday.
2. The generated post title matches 🔗 My web this week - W<weeknumber>.
3. The generated post uses YYYY-MM-DD 12:00:00 +0000 front matter for the target Sunday.
4. Each included roundup item contains either the extracted markdown quote or the embed-led artifact line, plus a link back to the original gurupanguji.com daily post.
5. Posts that only rely on legacy wp:quote extraction are skipped in v1 and logged as skipped.
6. The companion snippet is created or refreshed in _snippets/ during the same run.
7. Rerunning the generator for the same Sunday updates existing weekly artifacts in place.
8. If no qualifying source posts exist, the generator exits non-zero and creates no weekly artifacts.
9. The automation opens a PR instead of writing directly to main.