Upgrade

Answers what should I work on next? It reads TELOS goals, CURRENT_STATE, IDEAL_STATE, and PROBLEMS, then surfaces a ranked list of next builds — the gaps that close the most distance for the least effort. Output is tiered (CRITICAL/HIGH/MEDIUM/LOW) with Discoveries and Technique Details that include before/after code. Workflows: Recommend, Upgrade, AlgorithmUpgrade, MineReflections, ResearchUpgrade, FindSources, TwitterBookmarks.

There's always more you could build than time to build it, and the loudest input — the newest Anthropic feature, the trending repo, the bookmarked tweet — is rarely the highest-leverage one. Without a way to rank candidates against where you're actually trying to go, you chase novelty and re-implement things you already shipped. This skill ranks every candidate by how many of your real goals it moves and how cheap it is to do, and filters out work that's already done.

It answers what should I work on next? by holding three layers in mind simultaneously — TELOS goals (where I'm trying to go), CURRENT_STATE (where I actually am, including PAI infrastructure), and IDEAL_STATE (what "good" looks like per dimension) — and ranking the gaps that close the most distance with the least effort.

The skill runs four parallel threads that converge on personalized recommendations:

• Thread 0 — Prior-Work Audit. Algorithm, PATTERNS.yaml, hooks, skills, recent ISAs, KNOWLEDGE, feedback memory. Filters every candidate so already-shipped items go to Skipped, never re-recommended.
• Thread 1 — User Context (now gap-aware). TELOS goals, IDEAL_STATE/* dimensions, CURRENT_STATE/* (including INFRASTRUCTURE.md), active projects, PAI state. Computes per-goal (metric | current | target | direction) gap tuples — the load-bearing input.
• Thread 2 — Source Collection. Anthropic blog/changelog/docs (sources.json), GitHub trending, YouTube channels (youtube-channels.json), custom sources.
• Thread 3 — Internal Reflections. algorithm-reflections.jsonl mining for repeated friction patterns.

Thread 1 is the load-bearing change from the older PAIUpgrade skill. PAIUpgrade ranked recommendations by source recency. Upgrade ranks by (impact_on_goal × ease_of_implementation × confidence), where impact_on_goal comes from how many active TELOS goals a recommendation touches and how far it moves their gap, and ease comes from CURRENT_STATE rows already tagged partial (improve) vs missing (build new).

Extract, don't summarize. Techniques, not recommendations. Verify prior state before recommending.

1. Every output item is a technique — a specific pattern, code snippet, configuration, or approach.
2. Quote or code-block the actual content.
3. Map every technique to a specific PAI component (file path, skill, workflow, INFRASTRUCTURE.md row).
4. Verify Prior State (Thread 0 gate) — Before emitting ANY recommendation, confirm against Thread 0 inventory. Items already DONE go to Skipped, not Recommendations.
5. Two mandatory description fields, ≤2 sentences each:
   • What It Is — the technique itself
   • How It Helps PAI — which gap it closes, citing INFRASTRUCTURE row or IDEAL_STATE target
6. Provide implementation — show before/after code or specific steps.
7. Skip, don't dilute — content with no extractable technique goes in Skipped Content with reason.

Source Type Labels:

Skill Files:

• sources.json — Anthropic + base sources config (30+ sources)
• youtube-channels.json — Base YouTube channels (empty by default)
• State/last-check.json — Anthropic state
• State/youtube-videos.json — YouTube state
• State/github-trending.json — GitHub trending state (seen repos)
• State/twitter-bookmarks-seen.json — Previously processed bookmark URLs

User Customizations (~/.claude/PAI/USER/CUSTOMIZATIONS/SKILLS/Upgrade/):

• EXTEND.yaml — Extension manifest
• youtube-channels.json — User's personal YouTube channels
• user-sources.json — Additional source definitions (e.g., github_trending block)

1. Gap-aware before source-aware. A great Anthropic feature that doesn't close a TELOS gap loses to a small infrastructure fix that does.
2. Extract, don't summarize.
3. Quote the source.
4. PAI-contextualized. Every technique maps to a specific PAI file, skill, INFRASTRUCTURE row, or component.
5. TELOS-connected. Reference the user's goals and challenges when explaining relevance.
6. Skip boldly. No extractable technique → skip.
7. Implementation-ready. Actual code changes, not vague recommendations.
8. Claude Code freshness via claude-code-guide. When discoveries involve Claude Code internals, spawn Agent(subagent_type="claude-code-guide") to verify references match the latest API surface.

• Recommend.md — primary gap-driven workflow; reads TELOS + IDEAL_STATE + CURRENT_STATE/INFRASTRUCTURE.md and ranks recommendations by impact × ease × confidence. Use this when the question is "what should I work on?"
• Upgrade.md — legacy four-thread source-driven flow; reads sources first, then maps to PAI components. Use when the question is "what's new in the ecosystem?"
• MineReflections.md — Thread 3 standalone (deep reflection mining)
• AlgorithmUpgrade.md — Algorithm-version-bump-focused upgrade flow
• ResearchUpgrade.md — deep dive on a specific upgrade opportunity
• FindSources.md — discover and evaluate new sources to monitor
• TwitterBookmarks.md — bookmark scan via _X skill, then four-thread analysis

• Hard-merge of PAIUpgrade. This skill replaces the older PAIUpgrade skill. The old skills/PAIUpgrade/ directory remains as a redirect stub so no external reference breaks. The /pu command shortcut now points here. If you find a stale reference to PAIUpgrade in another skill or doc, treat it as a string-replace candidate.
• Recommend vs Upgrade routing. Both workflows run the same four threads. The difference is whether Thread 1 (gap analysis) or Thread 2 (source collection) drives the ranking. When the user asks "what should I work on?", lead with Thread 1. When they ask "what's new?", lead with Thread 2.
• INFRASTRUCTURE.md is part of CURRENT_STATE. PAI components (capture devices, processing endpoints, storage, output workflows) live as CURRENT_STATE/INFRASTRUCTURE.md rows. The recommender reads them the same way it reads CONSUMPTION or ACTIVITY rows. Do not invent a separate inventory primitive.
• Check ALL sources in parallel. Anthropic blog, changelog, YouTube, GitHub releases — never sequentially.
• Recommendations must not break existing skills or workflows. Verify backward compatibility before applying.
• Full upgrade check can take 5–7 minutes. Use run_in_background: true for the outer agent.
• Ranking ties on impact × ease × confidence. Prefer items with gap_distance: near and high telos_links count. Stale partial items (no movement in 30 days) get a small recency penalty so they don't perpetually outrank fresh missing items.