star-momentum-alert

name: star-momentum-alert description: Project the date a watched repo crosses its next star milestone — alert only when projected date lands inside the Show HN dispatch window (7-14 days out, Tue/Wed/Thu) var: "" tags: [meta, growth]

${var} — Optional. Pass dry-run to skip the notification (article still writes, log still appends). Pass a positive integer to override the auto-picked milestone (e.g. var=500). Empty = audit every watched repo and auto-pick the next un-crossed ladder rung.

Today is ${today}. Convert the last 14 days of repo-pulse star-count data into a projected date for the next milestone crossing, and surface a single decision-ready alert: when should the operator dispatch show-hn-draft so the launch lands at the milestone moment?

The skill answers a question star-milestone and repo-pulse cannot. star-milestone celebrates a crossing after it happens. repo-pulse reports today's deltas. Neither tells the operator "the next milestone is on a Wednesday 9 days from now — that's the launch slot." Without that lead-time signal, the milestone passes reactively, and a dispatch-ready Show HN draft sits unused while the moment slips by.

Why this exists

show-hn-draft shipped May 1 (PR #151) as a workflow_dispatch skill. Its launch checklist requires Tue–Thu morning timing. Today there is no signal that tells the operator "the milestone you wanted to anchor the launch around is 9 days out, on a Wednesday — dispatch now so the post is ready Tuesday." This skill provides that signal — and only that signal. It is silent on every other day. The dispatch decision still belongs to the operator; this skill just makes the timing legible.

Config

No new secrets. No new env vars. No new state file beyond memory/topics/star-momentum-state.json for prior-run dedup. No outbound HTTP — pure local file I/O over memory/logs/ and memory/topics/.

Reads:

• memory/watched-repos.md — repos to track. Skip lines containing aeon-agent or ending in -aeon (agent repos, not project repos).
• memory/logs/YYYY-MM-DD.md for the last 14 days — extract the **owner/repo**: stargazers_count=N, forks_count=M lines that repo-pulse writes under its ## Repo Pulse blocks.
• Optional fallback: articles/repo-pulse-*.md if any fork writes them — same regex applies. Logs are the source of truth on the canonical instance.
• memory/topics/star-momentum-state.json — prior-run dedup state.

Writes:

• articles/star-momentum-${today}.md — the per-repo projection report (always written, even when no alert fires).
• memory/topics/star-momentum-state.json — last-alert timestamp per (repo, target_milestone) pair.
• memory/logs/${today}.md — log block.

Milestone ladder

50, 100, 150, 200, 250, 300, 400, 500, 750, 1000, 1500, 2000, 3000, 5000, 7500, 10000, 15000, 25000, 50000, 100000

Same ladder as star-milestone so the two skills agree on which numbers count as round-number moments worth marking.

Steps

1. Parse var

• If ${var} matches ^dry-run → MODE=dry-run. Strip the prefix; remainder is treated as a milestone override.
• Otherwise MODE=execute.
• If the remaining var is a positive integer → OVERRIDE_MILESTONE=$var. Otherwise OVERRIDE_MILESTONE=auto.
• If the remaining var is non-empty and non-numeric → log STAR_MOMENTUM_BAD_VAR: ${var} and exit (no notify, no article).

2. Load repos

mkdir -p memory/topics articles
[ -f memory/topics/star-momentum-state.json ] || echo '{"last_run_at":null,"alerts":{}}' > memory/topics/star-momentum-state.json

REPOS=$(grep -oE '^- [a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+' memory/watched-repos.md \
  | sed 's/^- //' \
  | grep -vE '(aeon-agent|-aeon$)' || true)

If REPOS is empty, log STAR_MOMENTUM_NO_REPOS and exit cleanly without notifying.

3. Per-repo: build the 14-day stargazer series

For each repo in REPOS:

SERIES=""
for D in $(seq 13 -1 0); do
  DATE=$(date -u -d "${today} - ${D} days" +%Y-%m-%d 2>/dev/null \
      || date -u -j -v-${D}d -f %Y-%m-%d "${today}" +%Y-%m-%d)
  LOG=memory/logs/${DATE}.md
  [ -f "$LOG" ] || continue
  # Extract: - **owner/repo**: stargazers_count=N, forks_count=M
  STARS=$(grep -oE "\\*\\*${REPO}\\*\\*: stargazers_count=[0-9]+" "$LOG" \
    | grep -oE '[0-9]+$' | head -1)
  [ -z "$STARS" ] && continue
  SERIES="${SERIES}${DATE} ${STARS}\n"
done

The result is a (date, stars) series sorted ascending, one row per day where repo-pulse ran. Days with no log entry are simply absent — gaps in the series are fine and do not require interpolation.

If the series has fewer than 4 data points: record this repo's verdict as INSUFFICIENT_DATA, write its section in the article anyway, and skip projection.

4. Compute deltas and rolling averages

For consecutive (date_i, stars_i), (date_{i+1}, stars_{i+1}) pairs:

• delta_i = stars_{i+1} - stars_i
• (No per-day normalization — repo-pulse runs daily, so each delta is a one-day delta. If two log entries are >1 day apart, divide by the gap so a 2-day gap doesn't double-count.)

Compute:

• current_stars = SERIES[-1].stars
• v3 = mean of the last 3 normalized deltas (or fewer if <3 are available)
• v7 = mean of the last 7 normalized deltas (or fewer if <7 are available)

If v7 <= 0 (zero or net-negative growth across the 7-day window): record verdict STALLED. Article still writes; no projection, no alert.

5. Pick the target milestone

If OVERRIDE_MILESTONE is set:

• If OVERRIDE_MILESTONE <= current_stars → record verdict BAD_TARGET, log STAR_MOMENTUM_BAD_TARGET: ${REPO} override=${OVERRIDE_MILESTONE} current=${current_stars}, skip projection.
• Otherwise target = OVERRIDE_MILESTONE.

Otherwise: target = smallest milestone in the ladder where milestone > current_stars.

gap = target - current_stars.

6. Project the crossing date

days_remaining_v7 = ceil(gap / v7)
days_remaining_v3 = ceil(gap / max(v3, 0.5))
projected_date_v7 = today + days_remaining_v7
projected_date_v3 = today + days_remaining_v3
day_of_week_v7   = weekday name of projected_date_v7
day_of_week_v3   = weekday name of projected_date_v3

v7 is the headline projection; v3 is a faster-bound sanity check. Both go in the article.

7. Decide whether to alert

Apply gates in this order. The first gate to fail records the verdict and skips notify for that repo.

a. STALLED / INSUFFICIENT_DATA / BAD_TARGET (from steps 4 / 3 / 5) → no alert. b. Out of window — if days_remaining_v7 < 7 OR days_remaining_v7 > 14 → record OUT_OF_WINDOW, no alert. (Under 7d is too late to dispatch show-hn-draft thoughtfully; over 14d is too far out and trades on noisy projection data.) c. Wrong day — projected_date_v7 weekday must be Tue, Wed, or Thu. Otherwise record OFF_DAY, no alert. d. Already alerted — if state.alerts.${repo}.${target}.alerted_at exists AND was set within the last 7 days → record ALREADY_ALERTED, no alert.

If all gates pass: verdict ALERT. Promote this repo into the notify list.

8. Build the article (always — even when zero alerts fire)

Path: articles/star-momentum-${today}.md. Overwrite if exists.

# Star Momentum — ${today}

**Verdict:** ${one of: ALERT — N repo(s) in launch window | NO_ALERTS — 0 repos in launch window today | INSUFFICIENT_DATA across the board}

*Audited ${repo_count} repos · ${alert_count} alerts · projection method: linear extrapolation from 7-day rolling average*

---

## ${repo} — ${current_stars}⭐ → ${target}⭐ in ~${days_remaining_v7}d

| Metric | Value |
|--------|-------|
| Current stars | ${current_stars} |
| Target milestone | ${target} |
| Gap | ${gap} |
| 3-day avg / day | ${v3} |
| 7-day avg / day | ${v7} |
| Days remaining (v7) | ${days_remaining_v7} |
| Projected date (v7) | ${projected_date_v7} (${day_of_week_v7}) |
| Days remaining (v3) | ${days_remaining_v3} |
| Projected date (v3) | ${projected_date_v3} (${day_of_week_v3}) |
| In Show HN window | ${YES — Tue/Wed/Thu inside 7-14d | NO — out of window | NO — off day} |
| Verdict | ${ALERT | OUT_OF_WINDOW | OFF_DAY | ALREADY_ALERTED | STALLED | INSUFFICIENT_DATA | BAD_TARGET} |

### Source data — ${repo}

| Date | Stars | Δ |
|------|-------|---|
| ${date_1} | ${s_1} | — |
| ${date_2} | ${s_2} | ${d_1} |
| ... | | |

(One section per repo. Repos with `INSUFFICIENT_DATA` show the partial series under the metrics table with a one-line note.)

---

## What this means

For each repo with verdict `ALERT`, one short paragraph:

> **${repo}** — ${current_stars}⭐ projected to cross ${target}⭐ on ${projected_date_v7} (${day_of_week_v7}), ${days_remaining_v7} days from today. Pace: ${v7}/day across the last 7 days, ${v3}/day across the last 3. ${day_of_week_v7} is inside the Show HN dispatch window (Tue/Wed/Thu morning). Suggested action: dispatch `show-hn-draft` 24-48 hours before ${projected_date_v7} so the post is ready when the milestone lands.

For each repo with verdict `OUT_OF_WINDOW`, one line:

> ${repo}: ${target}⭐ in ~${days_remaining_v7}d — outside the 7-14d launch window. No action.

For `OFF_DAY` / `STALLED` / `INSUFFICIENT_DATA` / `BAD_TARGET`: one line each, same format.

---
*Reads `memory/logs/YYYY-MM-DD.md` repo-pulse blocks. Pure local file I/O. Companion to `star-milestone` (post-crossing celebration) and `show-hn-draft` (the launch artifact this signal times).*

9. Notify (only on ALERT)

If MODE == dry-run: skip notify, log STAR_MOMENTUM_DRY_RUN, exit.

If alert_count == 0: log STAR_MOMENTUM_NO_ALERTS, do not notify (no signal = silence).

If alert_count >= 1: send one notification per alerting repo.

*Star Momentum — ${today} — ${repo}*

${current_stars}⭐ projected to cross ${target}⭐ on ${projected_date_v7} (${day_of_week_v7}) — ${days_remaining_v7} days from today.

Pace:
- 7-day avg: ${v7}/day
- 3-day avg: ${v3}/day
- Gap: ${gap} stars

${projected_date_v7} is a ${day_of_week_v7} — inside the Show HN dispatch window (Tue/Wed/Thu morning).

Suggested action: dispatch \`show-hn-draft\` 24-48 hours before ${projected_date_v7} so the post is ready when the milestone lands.

Article: articles/star-momentum-${today}.md

Cap each message at ~2500 chars. Notifications fan out via ./notify (Telegram/Discord/Slack — whichever are configured).

10. Persist state

Write memory/topics/star-momentum-state.json:

{
  "last_run_at": "${ISO timestamp}",
  "alerts": {
    "${repo}": {
      "${target_milestone}": {
        "first_seen_in_window_at": "${ISO}",
        "alerted_at": "${ISO or null}",
        "projected_date_v7": "${YYYY-MM-DD}",
        "v7_at_alert": ${v7}
      }
    }
  }
}

State invariants:

• first_seen_in_window_at is set the first run a (repo, milestone) pair enters the 7-14d window. Persists across runs while the pair stays in-window.
• alerted_at is set the run the notification fires. Stays set for 7 days; subsequent runs see ALREADY_ALERTED and skip notify.
• After 7 days alerted_at ages out — if the milestone still hasn't been crossed and the projection still lands in-window on a Tue/Wed/Thu, the alert re-fires as a periodic reminder.
• When current_stars >= target (milestone crossed), drop that entry from alerts.${repo} next run — star-milestone will emit the celebratory crossing notification, and this skill's job for that target is done.

Cap to last 20 milestone entries per repo to bound the file.

11. Log to memory/logs/${today}.md

## Star Momentum
- **Skill**: star-momentum-alert
- **Repos audited**: ${repo_count}
- **Per-repo verdicts**:
  - ${repo}: ${verdict} — ${current_stars}⭐ → ${target}⭐ in ~${eta}d (${projected_date_v7}, ${day_of_week_v7})
- **Alerts sent**: ${alert_count}
- **Article**: articles/star-momentum-${today}.md
- **Notification sent**: ${yes — N alerts | no — STAR_MOMENTUM_NO_ALERTS | no — dry-run}
- **Status**: ${STAR_MOMENTUM_OK | STAR_MOMENTUM_NO_ALERTS | STAR_MOMENTUM_DRY_RUN | STAR_MOMENTUM_NO_REPOS | STAR_MOMENTUM_BAD_VAR}

Exit taxonomy

Sandbox note

Pure local file I/O — no curl, no gh api, no env-var-in-headers, no prefetch script. Every read is a directory listing, file existence check, or grep over memory/logs/. Every write goes to articles/, memory/topics/, or memory/logs/. Works in the GitHub Actions sandbox without any of the network workarounds other skills need. The only outbound call is ./notify itself, which is already sandbox-safe (postprocess-notify pattern).

Constraints

• Only fires inside the launch window. Both gates (7-14 day projection AND Tue/Wed/Thu landing) must pass. A 5-day projection is too late to dispatch show-hn-draft thoughtfully; a 21-day projection is too far out and trades on noisy projection data.
• Per-milestone dedup. Once an alert fires for (repo, target_milestone) it stays silent for 7 days. Even if pace shifts, the operator already has the signal — re-pinging adds noise without adding information.
• Linear extrapolation only. No regression, no exponential model, no S-curve fitting. The goal is to convert today's pace into a date, not to forecast trajectory shape changes. If pace shifts, the alert simply fires (or doesn't) on a different day.
• Ignores agent repos. aeon-agent and *-aeon repos are filtered upfront; they are infrastructure mirrors, not project repos with growth narratives worth anchoring a launch around.
• Read-only across memory/logs/. This skill never edits past log files; it parses them. Today's log is the only target it appends to.
• Article writes regardless. Even on NO_ALERTS the article still writes — operators or other skills may read it for projection context without needing a notification to fire.
• Idempotent. Same-day reruns overwrite the article and the state's last_run_at; per-(repo, milestone) alerted_at timestamps persist so re-runs don't double-fire.