@gurupanguji

My Web This Week Backfill Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Extend the weekly roundup generator so it can backfill historical My web this week posts from 2025-01-01 through an explicit end date and commit the generated _posts/ files only.

Architecture: Keep scripts/generate_my_web_this_week.py as the single generator and add a backfill mode beside the existing single-Sunday path. Reuse the current source selection, extraction, and rendering logic, but route backfill writes through a post-only path so _snippets/ stay untouched.

Tech Stack: Python 3, unittest, Jekyll post files under _posts/

---

File Map

• Modify: scripts/generate_my_web_this_week.py Add range helpers, backfill CLI parsing, backfill execution, and post-only write support.
• Modify: tests/test_generate_my_web_this_week.py Add unit coverage for Sunday range derivation, backfill iteration, backfill dry-run reporting, and post-only writes.
• Modify: docs/superpowers/plans/2026-03-26-my-web-this-week-backfill-implementation-plan.md Check off completed steps during execution if the implementing agent uses this file as the task ledger.

Task 1: Add Backfill Range Helpers

Files:

• Modify: scripts/generate_my_web_this_week.py

• Test: tests/test_generate_my_web_this_week.py

• Step 1: Write the failing range-helper tests

def test_first_sunday_on_or_after_returns_same_day_for_sunday(self) -> None:
    self.assertEqual(
        self.gen.first_sunday_on_or_after(date(2025, 1, 5)),
        date(2025, 1, 5),
    )


def test_first_sunday_on_or_after_advances_to_next_sunday(self) -> None:
    self.assertEqual(
        self.gen.first_sunday_on_or_after(date(2025, 1, 1)),
        date(2025, 1, 5),
    )


def test_iter_sundays_in_range_yields_closed_range(self) -> None:
    self.assertEqual(
        list(self.gen.iter_sundays_in_range(date(2025, 1, 1), date(2025, 1, 19))),
        [date(2025, 1, 5), date(2025, 1, 12), date(2025, 1, 19)],
    )

• Step 2: Run the targeted tests to confirm they fail

Run: python3 -m unittest tests.test_generate_my_web_this_week.RangeHelperTest -v Expected: AttributeError or missing-test failures because the helpers do not exist yet.

• Step 3: Implement the minimal range helpers

def first_sunday_on_or_after(start_day: date) -> date:
    days_until_sunday = (6 - start_day.weekday()) % 7
    return start_day + timedelta(days=days_until_sunday)


def iter_sundays_in_range(start_day: date, end_day: date) -> list[date]:
    first = first_sunday_on_or_after(start_day)
    if first > end_day:
        return []

    current = first
    sundays: list[date] = []
    while current <= end_day:
        sundays.append(current)
        current += timedelta(days=7)
    return sundays

• Step 4: Run the targeted tests to confirm they pass

Run: python3 -m unittest tests.test_generate_my_web_this_week.RangeHelperTest -v Expected: PASS for all new helper tests.

• Step 5: Commit the helper groundwork

git add scripts/generate_my_web_this_week.py tests/test_generate_my_web_this_week.py
git commit -m "test: cover weekly backfill date helpers"

Task 2: Add Post-Only Backfill Writing And Reporting

Files:

• Modify: scripts/generate_my_web_this_week.py

• Test: tests/test_generate_my_web_this_week.py

• Step 1: Write the failing backfill behavior tests

def test_backfill_skips_empty_weeks_without_raising(self) -> None:
    results = self.gen.backfill_roundups(
        start_day=date(2025, 1, 1),
        end_day=date(2025, 1, 12),
        write=False,
    )
    self.assertEqual([result.status for result in results], ["skipped", "skipped"])


def test_backfill_writes_post_only(self) -> None:
    self.write_post("2025-01-06-alpha.md", "🔗 Alpha", body="> Quote")

    results = self.gen.backfill_roundups(
        start_day=date(2025, 1, 1),
        end_day=date(2025, 1, 12),
        write=True,
    )

    self.assertTrue((self.gen.POSTS_DIR / "2025-01-12-my-web-this-week.md").exists())
    self.assertFalse((self.gen.SNIPPETS_DIR / "2025-01-12-my-web-this-week.md").exists())
    self.assertEqual(results[-1].status, "generated")

• Step 2: Run the targeted tests to confirm they fail

Run: python3 -m unittest tests.test_generate_my_web_this_week.BackfillTest -v Expected: FAIL because backfill_roundups and post-only behavior do not exist yet.

• Step 3: Implement backfill execution and post-only writes

@dataclass(frozen=True)
class BackfillResult:
    target_sunday: date
    status: str
    skipped_warnings: tuple[str, ...] = ()


def write_roundup_post_only(metadata: RoundupMetadata, items: list[RoundupItem]) -> Path:
    if not items:
        raise EmptyRoundupError("weekly roundup requires at least one qualifying source item")
    metadata.post_path.parent.mkdir(parents=True, exist_ok=True)
    metadata.post_path.write_text(render_roundup_post(metadata, items), encoding="utf-8")
    return metadata.post_path


def backfill_roundups(start_day: date, end_day: date, write: bool) -> list[BackfillResult]:
    results: list[BackfillResult] = []
    for target_sunday in iter_sundays_in_range(start_day, end_day):
        metadata = build_roundup_metadata(target_sunday)
        existed = metadata.post_path.exists()
        items: list[RoundupItem] = []
        skipped: list[str] = []

        for source in select_source_posts(target_sunday):
            try:
                items.append(extract_roundup_item(source))
            except UnsupportedSourceError as exc:
                skipped.append(str(exc))

        if not items:
            results.append(BackfillResult(target_sunday=target_sunday, status="skipped", skipped_warnings=tuple(skipped)))
            continue

        if write:
            write_roundup_post_only(metadata, items)

        status = "updated" if existed else "generated"
        results.append(BackfillResult(target_sunday=target_sunday, status=status, skipped_warnings=tuple(skipped)))

    return results

• Step 4: Run the targeted tests to confirm they pass

Run: python3 -m unittest tests.test_generate_my_web_this_week.BackfillTest -v Expected: PASS for empty-week skipping and post-only writes.

• Step 5: Commit the backfill core

git add scripts/generate_my_web_this_week.py tests/test_generate_my_web_this_week.py
git commit -m "feat: add weekly roundup backfill mode"

Task 3: Extend The CLI Without Breaking Single-Date Mode

Files:

• Modify: scripts/generate_my_web_this_week.py

• Test: tests/test_generate_my_web_this_week.py

• Step 1: Write the failing CLI-mode tests

def test_parser_rejects_mixing_single_date_and_backfill(self) -> None:
    with self.assertRaises(SystemExit):
        self.gen.build_parser().parse_args(
            ["--date", "2026-03-29", "--backfill-start", "2025-01-01", "--backfill-end", "2026-03-29"]
        )


def test_main_backfill_dry_run_returns_zero(self) -> None:
    exit_code = self.gen.main(
        ["--backfill-start", "2025-01-01", "--backfill-end", "2025-01-12"]
    )
    self.assertEqual(exit_code, 0)

• Step 2: Run the targeted tests to confirm they fail

Run: python3 -m unittest tests.test_generate_my_web_this_week.CLIModeTest -v Expected: FAIL because the parser and main still only support --date.

• Step 3: Implement explicit mode validation and reporting

parser.add_argument("--backfill-start", help="Backfill start date in YYYY-MM-DD format")
parser.add_argument("--backfill-end", help="Backfill end date in YYYY-MM-DD format")


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    using_single = bool(args.target_date)
    using_backfill = bool(args.backfill_start or args.backfill_end)

    if using_single == using_backfill:
        raise SystemExit("choose exactly one mode: --date or --backfill-start/--backfill-end")

    if using_single:
        ...
        return 0

    start_day = datetime.strptime(args.backfill_start, "%Y-%m-%d").date()
    end_day = datetime.strptime(args.backfill_end, "%Y-%m-%d").date()
    if first_sunday_on_or_after(start_day) > end_day:
        raise SystemExit("backfill range does not include a Sunday")

    results = backfill_roundups(start_day=start_day, end_day=end_day, write=args.write)
    for result in results:
        print(f"{result.status.upper()}: {result.target_sunday.isoformat()}")
    return 0

• Step 4: Run the targeted tests to confirm they pass

Run: python3 -m unittest tests.test_generate_my_web_this_week.CLIModeTest -v Expected: PASS for CLI-mode validation and dry-run entrypoint behavior.

• Step 5: Commit the CLI integration

git add scripts/generate_my_web_this_week.py tests/test_generate_my_web_this_week.py
git commit -m "feat: add roundup backfill CLI"

Task 4: Generate Historical Posts And Run Repo Validation

Files:

• Modify: _posts/YYYY-MM-DD-my-web-this-week.md for each generated Sunday with qualifying inputs
• Verify: scripts/generate_my_web_this_week.py
• Verify: tests/test_generate_my_web_this_week.py

• Verify: tests/test_validate_posts.py

• Step 1: Run the focused automated tests

Run: python3 -m unittest tests/test_generate_my_web_this_week.py tests/test_validate_posts.py Expected: PASS with all new backfill tests and existing single-date tests passing together.

• Step 2: Run a dry-run backfill across the requested historical range

Run: python3 scripts/generate_my_web_this_week.py --backfill-start 2025-01-01 --backfill-end 2026-03-29 Expected: per-Sunday generated, updated, or skipped output plus final totals, with no file writes.

• Step 3: Run the write-mode backfill to create the historical posts

Run: python3 scripts/generate_my_web_this_week.py --backfill-start 2025-01-01 --backfill-end 2026-03-29 --write Expected: historical _posts/*-my-web-this-week.md files written or refreshed, with no _snippets/ changes.

• Step 4: Run repository validation after generation

Run: python3 scripts/validate_posts.py --today 2026-03-26 Expected: PASS, confirming historical weekly posts do not break current validators.

• Step 5: Inspect the changed files and commit the generated backfill

git status --short
git add scripts/generate_my_web_this_week.py tests/test_generate_my_web_this_week.py _posts/*-my-web-this-week.md
git commit -m "feat: backfill weekly roundup posts"