project-lens

name: project-lens category: dev description: Write an article about the project through a surprising lens — connecting it to current events, trends, philosophy, or comparable projects var: "" tags: [content, dev]

${var} — Specific angle or lens (e.g. "unix philosophy", "regulation wave", "open source funding"). If empty, auto-select from trending topics + angle rotation.

Read memory/MEMORY.md, the last 7 days of memory/logs/, memory/watched-repos.md, and memory/project-lens-angles.md (may not exist on first run — treat absence as empty history).

What this skill does

Writes articles that explain the project through a different lens each time — framed so a reader who's never heard of the project understands why it matters, via something they already care about. NOT a repo progress update (that's repo-article / push-recap).

Why models fail at this by default: they slide into feature-listing wrapped in philosophical language, forced parallels with no mechanism, and marketing tone. This skill prevents that with a research → thesis → draft → self-edit pipeline where each phase has hard gates. If the gates can't pass, abort — don't publish a weak article.

Phase 1 — Context

Read before deciding anything:

• Last 14 days of articles/project-lens-*.md and memory/project-lens-angles.md — know which angle categories and theses are exhausted.
• 2-3 most recent articles/repo-article-*.md and articles/push-recap-*.md — know what shipped lately.
• Repo state: gh api repos/{owner}/{repo} --jq '{name, description, stargazers_count, forks_count, open_issues_count, updated_at}'. If unreachable, continue with memory only and log the gap.

If memory/watched-repos.md is empty or missing, abort and notify: "project-lens: no watched repo configured."

Phase 2 — Pick the lens

If ${var} is set, use it verbatim. Classify into one of the 8 categories below for logging.

If ${var} is empty:

1. Run 2-3 WebSearch queries on what's being debated right now in tech, crypto, AI, regulation, open source, or philosophy (e.g., "AI agents" autonomy debate last 7 days, crypto regulation April 2026, open source funding model 2026).
2. From results, identify 3 candidate angles with non-obvious connections to the project.
3. Pick the one that (a) hasn't appeared in the last 14 days and (b) has the strongest concrete connection. Record the choice and the rejected candidates with one-line reasons.

Angle categories (no repeat within 14 days)

1. Current events — Something happening this week/month.
2. Philosophy / big ideas — Unix philosophy, cathedral vs bazaar, composability, anti-fragility, skin in the game, swarm intelligence, etc.
3. Industry comparison — How a well-known company/project solved a similar problem differently.
4. User story — POV of a specific persona (solo dev, DAO, research lab, crypto community) with and without this tool.
5. Contrarian take — Challenge a common assumption; use project as evidence.
6. Technical deep-dive for non-technical readers — One architectural decision, plain language, bigger implications.
7. Historical parallel — Computing / internet / non-tech history with a concrete mechanism (not surface resemblance).
8. Ecosystem map — Where the project sits: adjacent, complementary, competing.

Phase 3 — Research (gate: collect evidence before drafting)

External side — required minimums:

• 3+ WebSearch queries on the lens topic (different framings, not rewordings)
• WebFetch on the 2+ most relevant sources
• ≥3 distinct domains across cited sources
• ≥3 concrete facts extracted: names, numbers, dollar amounts, dated quotes, specific events
• Recency: ≤30 days old for "current events"; ≤180 days for industry comparison / contrarian / ecosystem; ≤5 years for philosophy / historical
• Log every URL consulted

Project side — required minimums:

• 2+ recent articles in articles/ read end-to-end
• gh api repos/{owner}/{repo}/commits --jq '.[0:10] | .[] | {sha: .sha[0:7], msg: (.commit.message|split("\n")[0])}' — last 10 commits
• ≥3 specific project references you plan to use: named features, file paths, commit hashes, architectural choices. Not vague claims like "the project uses AI" or "it has good UX."

If you cannot hit these minimums, abandon the angle and re-run Phase 2 with a different category. Log the abandoned angle and why.

Phase 4 — Thesis lock (hard gate)

Before drafting, write ONE falsifiable claim in ≤30 words that links the lens to the project. Example:

"Running agents as scheduled GitHub Actions — rather than as persistent servers — trades a few seconds of latency for a property the AI industry barely has: versioned, audit-trailed, publicly forkable autonomy."

Rules:

• Falsifiable: a reasonable critic could argue the opposite.
• Specific: names concrete things (cron jobs, not "infrastructure"; audit-trailed, not "better").
• Not a tautology. Not marketing. Not "this is cool because X."

If you can't state the thesis in one sentence, the angle isn't working — return to Phase 2. Do not proceed with a fuzzy thesis.

Phase 5 — Draft (700-1000 words)

Save to articles/project-lens-${today}.md with this structure:

# [Title: leads with the lens, works for a reader who doesn't know the project]

[¶1-2: external hook. Start with the trend/idea/event/question the reader already cares about. Do NOT name the project yet.]

## [Section: establishes the external frame]
[Build the lens with one or more of your concrete facts — a quote, a number, a specific event.]

## [Section: introduces the project through the frame]
[Project enters here — but through the lens, not as a feature list. Describe how it embodies, challenges, or extends the idea with specific code/design references.]

## [Section: one non-obvious technical or strategic detail]
[Where the article earns its existence. Point to something in the code, architecture, or approach a reader wouldn't get from the README.]

## [Section: zoom back out]
[A concrete forward claim — specific enough to be wrong. Not "this is exciting." Something like "this suggests X won't happen for 2-3 years because Y" or "this is the same mistake [named case] made, and it took [duration] to recover."]

---
*Sources:*
- [source title](url) — what it was used for
- ...

Draft requirements:

• Title must work for a reader who doesn't know the project name.
• ≥3 external citations rendered as inline links.
• ≥3 specific project references (named features, file paths, commit hashes, named decisions).
• 700-1000 words (count before submitting).

Phase 6 — Self-edit (hard gates — all must pass)

Go through this checklist after the first draft. If any gate fails, rewrite the affected section once. If the second pass still fails, abort and log — do not publish a weak article.

• Title does NOT name the project
• First 2 paragraphs do NOT name the project
• ≥3 external citations with URLs (inline)
• ≥3 specific project references (named, not vague)
• Falsifiable thesis visible in the article text
• 700-1000 words
• No banned phrases: revolutionary, groundbreaking, game-changing, paradigm shift, disrupting, unlocks, empowers, the future of X, leverage / leveraging, at scale, democratize (unless quoting a source that used the word)
• Every parallel/comparison states a concrete mechanism — not surface resemblance
• Closing section makes a specific forward claim (not generic optimism or "time will tell")
• No feature-list paragraphs ("the project does X, Y, Z") — if found, cut and keep ONE element

Phase 7 — Output

1. Save articles/project-lens-${today}.md.
2. Append to memory/project-lens-angles.md (create if missing):

   ## ${today}
   - Angle: [category]
   - Thesis: [one-line falsifiable claim]
   - Title: [article title]
   - Sources: [3-5 URLs]
   

3. Notify via ./notify:

   *New Article: [title]*
   
   [3-4 sentence summary: the external thing the article connects to, the thesis claim, one specific project detail.]
   
   Read: [URL to articles/project-lens-${today}.md — use `git remote get-url origin` for this repo]
   

4. Log to memory/logs/${today}.md:

   ## Project Lens
   - Angle: [category]
   - Thesis: [one-line]
   - External sources: [count] across [N] distinct domains
   - Project references: [count]
   - Self-edit gates: all passed | failed at [gate name] → rewrite → [passed | aborted]
   - Status: published | aborted
   - Notification: sent | skipped
   

Anti-patterns (prevention beats self-edit catch)

• Forced parallels — every comparison needs a concrete mechanism, not surface resemblance. "X is like Y because both are new" fails; "X is like Y because both decoupled [specific function] from [specific bottleneck]" passes.
• Feature-dump via the lens — pick ONE architectural decision and interrogate it, don't list what the project does.
• Marketing tone — aim for trade-publication prose, not a company blog.
• False novelty — if you can't point to what's actually new, name what's old that still works and why.
• Vague closings — the final section must make a claim specific enough that a reader could come back in six months and say "you were wrong" or "you were right."

Sandbox note

Use WebFetch if curl fails for any URL. The gh CLI handles GitHub API auth internally — prefer it over raw curl for repo metadata.

Constraints

• Never publish if Phase 6 self-edit fails twice — abort cleanly.
• Never reuse an angle category within 14 days (check memory/project-lens-angles.md).
• Never invent facts to fill the citation minimum — if research is thin, abandon the angle.