rsc-universal 0.1.1

package/skills/linkedin-strategy/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: linkedin-strategy
+description: "Use when a LinkedIn presence — personal brand or company page — needs an account-level decision over months: positioning/POV, defining 3-5 content pillars, posting cadence, whether content lives on the founder's profile or the company page, or the SSI / social-selling rhythm, read from and written back to the presence's own learning wiki. Triggers: 'what should I be known for on LinkedIn', 'what should I post about', 'how often should I post', 'company page or founder profile for content', 'my company page is dead where should content live', 'I post but nothing comes back / no inbound', 'my SSI is stuck how do I raise it', 'quarterly LinkedIn review which pillar is working', 'qué debería publicar en LinkedIn', 'cada cuánto publico per ser referent'. NOT writing the post copy or hook (that is linkedin-content), NOT building a carousel deck (that is linkedin-carousels), NOT sending DMs or sequences (that is linkedin-outreach), NOT pulling raw analytics (that is linkedin-api)."
+tags: [linkedin, positioning, content-pillars, cadence, thought-leadership, ssi, social-selling]
+recommends: [linkedin-content, linkedin-outreach, linkedin-api, content-engine, decision-records]
+origin: risco
+---
+
+# LinkedIn Strategy — The Presence as a System, Not the Next Post
+
+*You operate at account/presence altitude.* You decide the **territory** (what this presence is known for, who it is for) and the **system** (pillars, cadence, where content lives, the social-selling rhythm) over months. You never write the post, build the carousel, run the DMs, or hit the API — those are single-asset jobs you route out. Mixing altitudes is the #1 reason LinkedIn advice goes generic: an account-level question answered with a tactic about one post produces noise and regresses to blog-post defaults.
+
+Your spine is a read/write loop with the presence's own history. You **read** the accumulated learnings before deciding and **write** the decision back, so the next session compounds instead of restarting from a generic "post 3 times a week" template.
+
+## Altitude boundary — route single-asset work out
+
+| The ask | Skill | Why it is not you |
+|---|---|---|
+| Post copy, hook, body for one update | `../linkedin-content/SKILL.md` | You set the pillar and POV; content writes inside it. |
+| A carousel / document-post deck | `../linkedin-carousels/SKILL.md` | A single asset's format craft, not the system. |
+| Connection requests, DMs, sequences | `../linkedin-outreach/SKILL.md` | You set the social-selling *rhythm*; outreach runs the individual threads. |
+| Raw analytics, OAuth, rate limits | `../linkedin-api/SKILL.md` | You *consume* the numbers; the API *fetches* them. |
+| Cross-platform calendar / scheduling | `../content-engine/SKILL.md`, `../social-publisher/SKILL.md` | Multi-platform planning/posting, not LinkedIn presence architecture. |
+| Abstract tone/voice rules | `../brand-voice/SKILL.md` | Voice in the abstract; you decide positioning and pillars. |
+
+You are the only LinkedIn skill that operates at account altitude and persists its decisions to the wiki. Every sibling works on a single asset or a single thread.
+
+## 1. Read the wiki FIRST — before any decision
+
+Read `02-DOCS/wiki/linkedin/` before you decide anything. Why: a positioning or cadence call made without the account's own dwell-time and SSI history is just generic advice with a name on it. The whole value of this skill is that decisions compound.
+
+Extract, in this order:
+1. **Prior positioning / POV** — what was the presence supposed to be known for, and did it hold?
+2. **Current pillars** — the 3-5 topics in play; which carry engagement.
+3. **Stated cadence + whether it held at quality** — "3/week" that slipped to ~1 is the real signal, not the stated number.
+4. **Top dwell-time / engagement performers** — which specific posts and formats earned the most read time.
+5. **SSI trend** — the 0-100 score's direction over the trailing window.
+6. **Killed pillars / dead experiments** — so you do not re-propose what already failed.
+
+If the directory is empty or absent, **bootstrap it** — create `02-DOCS/wiki/linkedin/` with `positioning.md`, `decisions/`, and `what-worked.md`. Do not skip the read because the dir is missing; an empty wiki is a starting state, not a license to free-associate. When you decide, **cite what you grounded in** ("based on the two carousels that earned top dwell time…").
+
+Full file layout and templates: `references/wiki-records.md`.
+
+## 2. Positioning & POV + where content lives
+
+**Niche of authority.** Be known for a clear point of view in one domain. The 2026 algorithm cross-references each post's topic against your title, skills, and background — posting purposefully inside a demonstrated domain builds topical authority; posting about whatever trends suppresses it. Thought leaders post inside a POV; creators just post often. 95% of decision-makers say thought leadership influences purchasing — so the POV is the asset, not the post count.
+
+**Where the content lives — the distribution decision.** Personal profiles out-distribute company pages by a wide margin. Decide with this table, not by habit:
+
+| Goal / stage | Lean | Why |
+|---|---|---|
+| Build reach, inbound, trust | Founder / exec personal profile | Personal content engages ~8x more than the page; profiles get ~65% of feed allocation. |
+| Recruiting, official announcements, ad retargeting base | Company page (secondary) | Pages lost ~60-66% organic reach 2024-2026, now ~5% of feed; useful as a base, not a megaphone. |
+| Scale reach without paying | Employee advocacy | Advocacy yields ~561% greater reach and ~7x more lead conversion than the page alone; CEO/founder posts get ~4x the page's engagement. |
+
+**Rule: humans are the main event.** The page amplifies; it never carries.
+
+```text
+Bad:  All content posted on the company page; the founder reshares occasionally.
+Good: The founder posts the POV from their profile; the page reshares as amplification;
+      5 employees advocate the same week. Reach compounds across human graphs.
+```
+
+## 3. Content pillars — the territory, not the posts
+
+Define **3-5 pillars**. Fewer than 3 is a single-note feed; more than 5 dilutes topical authority and confuses the cross-reference. Each pillar must align to the professional graph — the title, skills, and background LinkedIn already knows — so the 2026 topic match rewards you instead of flagging you off-domain.
+
+Pillars are the **territory**. `../linkedin-content/SKILL.md` writes the individual posts inside them; you do not.
+
+```text
+Bad:  "I post about whatever's trending that week."
+Good: A B2B data-platform founder runs 4 pillars:
+      1. Pipeline reliability war stories   (graph-aligned: their actual job)
+      2. Hiring/scaling a data team
+      3. Build-vs-buy decision frameworks
+      4. Behind-the-scenes founder lessons
+```
+
+Worked pillar sets for a solo consultant and a company page: `references/ssi-and-pillars.md`.
+
+## 4. Cadence — the rate you can hold, not the rate a blog quotes
+
+Pick the **highest rate you can sustain for 8 weeks at quality**. The sweet spot is **2-5 posts/week**, with **3-4/week the highest-ROI band**; consistency beats volume — 8 posts/month for 24 months beats 20/month for 6 months then quitting, because the algorithm rewards a sustained schedule, not a burst. Aim ~20-28h between posts; Tue-Thu is strongest for B2B.
+
+Gate every cadence number through this checklist — answer all YES before you commit:
+
+- [ ] Is the idea backlog deep enough to feed this rate for 8 weeks?
+- [ ] Is there bandwidth to *engage* daily (see §5), not just publish?
+- [ ] Is there format bandwidth for carousels/documents, not only text?
+
+If any answer is NO, lower the cadence. A held 3/week beats an aspirational 5/week that collapses to 1.
+
+**Format weight.** Carousels and document posts earn 2-3x more dwell time than text or image — and dwell time is the primary 2026 quality signal, not likes. Weight the calendar toward them.
+
+**Tie the number to the wiki, not the blog.** If the account's own data shows carousels on one topic earning the best dwell time, the cadence recommendation weights toward that — a number justified by §1's read, never a default.
+
+## 5. The social-selling rhythm — engage-vs-create and SSI
+
+**Engagement outweighs raw posting frequency for inbound.** Accounts posting 3x/week *with* active inbound engagement beat daily-posting-no-engagement accounts by ~4.2x in lead gen. The split that works: roughly **~80% of LinkedIn time engaging** (commenting on others' posts, replying in your own threads), **~20% creating**. "20 min creating + 40 min engaging" beats "60 min creating + 0 engaging." Set this as the rhythm; the individual threads belong to `../linkedin-outreach/SKILL.md`.
+
+**SSI as a habit system, not a vanity number.** The Social Selling Index is a 0-100 score over four 25-point dimensions, refreshed daily on a trailing 90-day window, free at `linkedin.com/sales/ssi`:
+
+| Dimension (25 pts each) | Weekly habit |
+|---|---|
+| Establish a professional brand | Publish inside your pillars; complete profile. |
+| Find the right people | Targeted search + connect within your niche. |
+| Engage with insights | The ~80% engage block — comment with substance. |
+| Build relationships | Convert engagement into 1:1 conversations. |
+
+Targets: **65+** for active B2B sellers, **75+** is thought-leader territory, all-user average ~40-50. SSI is benchmarked relative to your industry (not absolute) and responds within ~90 days to habit changes — which makes it a usable steering metric, not a scoreboard. Deep per-dimension habit breakdown: `references/ssi-and-pillars.md`.
+
+## 6. The review & double-down loop
+
+On a quarterly or monthly review, read §1's what-worked + dwell/SSI trend, then branch:
+
+```text
+Engagement rising while cadence held?
+  RISING     -> a pillar/format is working. Double down: more slots to that pillar,
+                more of that format. Log which one and why.
+  PLATEAUED  -> diagnose, do not just post more. Weak pillar topical fit
+                (off-graph topic suppressed) OR weak format/dwell (text where a
+                carousel would earn read time)?
+  DECLINING  -> sunset the dead pillar. Reallocate its calendar slot to a rising
+                one. Log it KILLED so no future session re-proposes it.
+```
+
+"Post more" never fixes falling engagement — diagnose pillar fit vs format/dwell first.
+
+## 7. Write the decision back — on exit, always
+
+Append a dated decision record under `02-DOCS/wiki/linkedin/decisions/`. Every record names the **single metric it bets on** and a **review date** — a decision without a metric is an opinion, not a checkable bet.
+
+```markdown
+# 2026-06-02 — Move distribution to founder profile
+
+Context read: SSI 48 (flat 90d); top-2 dwell-time posts both carousels on
+"pipeline reliability"; stated cadence 3/week slipped to ~1; company page reach near zero.
+
+Decision: Founder profile carries the POV; company page amplifies; refine to 4 pillars
+weighted toward the reliability carousel topic; hold 3/week with carousels Tue/Thu.
+Social-selling rhythm: 80/20 engage/create.
+
+Bets on metric: SSI 48 -> 65 within 90 days (proxy for inbound).
+Review date: 2026-09-02.
+```
+
+After writing, run `scripts/verify.sh 02-DOCS/wiki/linkedin/` to confirm the record is structurally complete. Full templates and the what-worked format: `references/wiki-records.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Dumping content on the company page | ~5% feed allocation; reach is near dead | Founder/employee profiles carry it; the page amplifies |
+| Chasing daily posting | Hits a quality cliff, no bandwidth to engage | 3-4/week held + the engage split |
+| Posting outside your pillars / domain | 2026 topic cross-reference suppresses authority | Stay inside graph-aligned 3-5 pillars |
+| Optimizing for likes | Misses dwell time, the real 2026 signal | Weight carousels/docs; measure dwell time |
+| Treating SSI as a vanity score | Ignores it as a steerable habit system | Run the four dimensions as weekly habits |
+| Create-only, no engaging | ~4.2x worse inbound | ~80/20 engage-to-create split |
+| Deciding without reading the wiki | Regresses to generic blog advice | READ `02-DOCS/wiki/linkedin/` first |
+| Never writing the decision back | No compounding; every session restarts | Append a dated record + metric + review date |
+
+## References & routing
+
+- `references/wiki-records.md` — file layout under `02-DOCS/wiki/linkedin/`, decision-record and what-worked templates, and exactly what `verify.sh` checks.
+- `references/ssi-and-pillars.md` — the four SSI dimensions as concrete weekly habits with targets, pillar-design worked examples, and the personal-vs-page + employee-advocacy reach mechanics.
+
+Route single-asset work out: post copy → `../linkedin-content/SKILL.md`; carousels → `../linkedin-carousels/SKILL.md`; DMs/sequences → `../linkedin-outreach/SKILL.md`; raw metrics → `../linkedin-api/SKILL.md`; decision discipline → `../decision-records/SKILL.md`.

package/skills/linkedin-strategy/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — linkedin-strategy
+
+These cases are run by the skill-eval harness (or read by hand) to confirm three things. First, that `linkedin-strategy` loads on account-level prompts — positioning/POV, content pillars, cadence, the personal-vs-company-page distribution choice, and the SSI/social-selling rhythm — including the non-obvious "I post but get no inbound" framing and the Spanish phrasing. Second, that it stays off single-asset and API prompts, routing each to the named sibling (`linkedin-content`, `linkedin-carousels`, `linkedin-outreach`, `linkedin-api`, `social-publisher`) — every `route_to` id is a real skill in the catalog. Third, that the capability scenario exercises the full loop: read `02-DOCS/wiki/linkedin/` first, decide positioning/pillars/cadence/distribution/SSI-rhythm grounded in the account's own data, write a dated decision record back naming the metric it bets on and a review date, and route single-asset work out. There is no automated scorer here — judge `must_include` coverage against the model's output, and run `scripts/verify.sh 02-DOCS/wiki/linkedin/` to confirm any decision record the run produces is structurally complete.

package/skills/linkedin-strategy/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: linkedin-strategy
+
+should_trigger:
+  - prompt: "What should I be known for on LinkedIn and how often should I post?"
+    why: Positioning/POV plus cadence — two account-level decisions, the skill's core.
+  - prompt: "Should our content go on the company page or the founder's profile?"
+    why: The personal-vs-company-page distribution decision; humans-as-main-event with employee advocacy.
+  - prompt: "I post regularly but get no inbound — what's wrong with my LinkedIn rhythm?"
+    why: Non-obvious, no 'strategy' word; it is the engage-vs-create split and SSI rhythm, owned here.
+  - prompt: "Quarterly LinkedIn review — which content pillar is working and what should I double down on?"
+    why: The read-wiki + double-down loop, the skill's spine.
+  - prompt: "Qué debería publicar en LinkedIn y cada cuánto para que me tomen como referente?"
+    why: Spanish for pillars + cadence + thought-leadership positioning, all account-level.
+  - prompt: "My SSI is stuck at 48 — how do I build a habit system to raise it?"
+    why: SSI as a four-dimension weekly rhythm and steering metric, owned by this skill (fact 6).
+  - prompt: "My company page is basically dead — where should the content actually live?"
+    why: Non-obvious phrasing of the distribution decision; pages get ~5% feed, profiles carry reach.
+
+should_not_trigger:
+  - prompt: "Write the post copy and hook for tomorrow's update."
+    route_to: linkedin-content
+    why: Per-post craft fills a pillar; strategy sets the pillar, it does not write the post.
+  - prompt: "Build me a 10-slide carousel deck on this topic."
+    route_to: linkedin-carousels
+    why: Single-asset format craft, not the presence system.
+  - prompt: "Draft connection requests and a DM sequence for these 20 prospects."
+    route_to: linkedin-outreach
+    why: 1:1 thread execution; strategy sets the rhythm, not the individual messages.
+  - prompt: "Pull my last 90 days of post analytics from the LinkedIn API."
+    route_to: linkedin-api
+    why: Data plumbing / OAuth; strategy consumes the numbers, it does not fetch them.
+  - prompt: "Schedule and cross-post this to Twitter and Instagram too."
+    route_to: social-publisher
+    why: Cross-platform scheduling, not LinkedIn presence architecture.
+
+capability:
+  - scenario: >
+      A B2B founder has a near-dead company page and a personal profile with sporadic posting.
+      02-DOCS/wiki/linkedin/ already holds: SSI ~48, the top-2 dwell-time posts are both carousels
+      on one topic, and a stated cadence of "3/week" that slipped to ~1. Produce a strategy
+      decision for the presence.
+    must_include:
+      - Reads 02-DOCS/wiki/linkedin/ first (prior positioning, current pillars, whether cadence held, top dwell-time performers, SSI trend, killed experiments) — or bootstraps the dir if empty.
+      - Moves distribution to the founder's personal profile with the company page as amplification plus employee advocacy, grounded in the personal-vs-page reach gap (~8x engagement, ~5% vs ~65% feed).
+      - Defines or refines 3-5 content pillars aligned to the founder's professional graph, doubling down on the carousel topic that already earns the best dwell time.
+      - Gives a cadence recommendation justified by the account's own data (e.g. a holdable 3/week weighted toward carousels/docs for dwell time) with the 8-week sustainability gate, not a generic number.
+      - Sets a social-selling rhythm — the ~80/20 engage-vs-create split and SSI as a four-dimension weekly habit with a target (e.g. 48 -> 65).
+      - Writes a dated decision record back to 02-DOCS/wiki/linkedin/ naming the single metric it bets on and a review date.
+      - Routes single-asset work out: post copy -> linkedin-content, carousels -> linkedin-carousels, DMs -> linkedin-outreach, raw metrics -> linkedin-api.

package/skills/linkedin-strategy/references/ssi-and-pillars.md

@@ -0,0 +1,59 @@
+# SSI dimensions, pillar design, and distribution mechanics
+
+Offloaded depth for `SKILL.md` §3, §4, §5. Use it when a session needs the worked detail.
+
+## The four SSI dimensions as weekly habits
+
+SSI is 0-100, four 25-point dimensions, refreshed daily on a trailing 90-day window, free at `linkedin.com/sales/ssi`. It is benchmarked relative to your industry and your network, not absolute — so the target is *direction*, not a leaderboard rank. It responds within ~90 days to habit changes, which is what makes it steerable.
+
+Targets: **65+** active B2B seller, **75+** thought-leader territory, all-user average ~40-50.
+
+| Dimension | What it measures | Concrete weekly habit | Common failure |
+|---|---|---|---|
+| Establish a professional brand | Complete profile, content published inside a clear domain, post engagement | 100% profile; 3-4 posts/week inside your pillars; a carousel/week | Sporadic, off-topic posting that suppresses topical authority |
+| Find the right people | Using search/filters to reach the right prospects | A weekly targeted-connect block inside your niche | Mass-connecting outside the graph; inflates count, not score |
+| Engage with insights | Sharing and commenting with substance on others' content | The ~80% engage block — substantive comments daily | Like-only drive-bys; no dwell signal generated |
+| Build relationships | Connecting with and converting senior/relevant people | Convert engaged commenters into 1:1 threads (hand to outreach) | Never moving beyond the public feed |
+
+The dimension that moves most for stuck accounts is usually **Engage with insights** — it is the directly controllable lever and it feeds the others.
+
+## Pillar-design worked examples
+
+Pillars must align to the professional graph (title, skills, background) so the 2026 topic cross-reference reads them as on-domain authority. 3-5 pillars; each one a recurring theme, not a single post.
+
+**B2B SaaS founder (data platform):**
+1. Pipeline reliability war stories (graph-aligned: the actual job)
+2. Hiring and scaling a data team
+3. Build-vs-buy decision frameworks
+4. Behind-the-scenes founder lessons
+
+**Solo consultant (GTM advisor):**
+1. Diagnosed GTM failures (anonymized case teardowns)
+2. The one framework they are known for
+3. Contrarian takes on a common GTM myth
+4. Client-result proof, told as a story
+
+**Company page (secondary amplification only):**
+1. Customer outcomes / case studies
+2. Product/release notes for retargeting base
+3. Hiring and culture
+   (The page never carries reach — humans do. See distribution below.)
+
+A pillar that consistently underperforms on dwell time across a quarter is a sunset candidate: kill it, log it, reallocate the slot.
+
+## Personal-vs-company-page + employee-advocacy mechanics (2026 numbers)
+
+- Personal-profile content engages **~8x** more than company-page content.
+- Company pages lost **~60-66%** organic reach 2024-2026; they now get **~5%** of feed allocation vs **~65%** for personal profiles.
+- Employee advocacy yields **~561%** greater reach and **~7x** more lead conversion than the page alone.
+- CEO/founder content earns **~4x** more engagement than the average company-page post.
+
+Operating model that follows from the numbers:
+
+```text
+Founder profile  -> carries the POV and the reach (the main event)
+Company page     -> reshares as amplification + serves as the ad-retargeting base
+Employee advocacy-> N employees reshare/comment the same week -> reach compounds across graphs
+```
+
+Decision shortcut: if the goal is reach, trust, or inbound, the human profile carries it. The page is a base of record and an amplifier, never the primary channel.

package/skills/linkedin-strategy/references/wiki-records.md

@@ -0,0 +1,62 @@
+# Wiki records — `02-DOCS/wiki/linkedin/`
+
+The read/write loop's storage. Everything is append-only markdown so future strategy sessions compound instead of restarting from generic advice.
+
+## File layout
+
+```text
+02-DOCS/wiki/linkedin/
+  positioning.md        # current POV, niche of authority, who-it's-for; updated in place when it shifts
+  pillars.md            # the live 3-5 pillars + any KILLED pillars with the date and reason
+  decisions/            # one append-only file per decision (preferred), dated filenames
+    2026-06-02-distribution-to-founder.md
+    2026-09-02-q3-review.md
+  what-worked.md        # running log of what specific posts/pillars/formats earned dwell time + engagement
+```
+
+A running `decisions.md` log at the root is also accepted instead of `decisions/*.md` — pick one and stay consistent. `verify.sh` checks both shapes.
+
+## Bootstrap (empty/absent dir)
+
+When `02-DOCS/wiki/linkedin/` does not exist, create it with `positioning.md`, `pillars.md`, `decisions/`, and `what-worked.md` before you decide. Seed `positioning.md` with whatever the account already implies (title, current posts) so the first decision has a baseline to react to.
+
+## Decision-record template
+
+Every record carries: a dated heading, a context-read line (what you grounded in), a decision line, the single metric it bets on, and a review date. Missing the metric or the review date means it is not a checkable bet.
+
+```markdown
+# 2026-06-02 — <short decision title>
+
+Context read: <what you pulled from the wiki — prior positioning, current pillars,
+whether cadence held, top dwell-time performers, SSI trend, killed experiments>.
+
+Decision: <the concrete choice — positioning / pillars / cadence / distribution /
+social-selling rhythm, stated so the next session can act on it>.
+
+Bets on metric: <the single steering metric + from -> to + window, e.g.
+SSI 48 -> 65 within 90 days, or median dwell time +X%, or inbound DMs/week>.
+
+Review date: <YYYY-MM-DD — when the next session checks whether the bet paid>.
+```
+
+## what-worked template
+
+```markdown
+## 2026-09-02 review
+
+- Pillar "pipeline reliability" — RISING. 2 carousels in top-3 dwell time. Double down.
+- Pillar "founder lessons" — FLAT. Text-only; try carousel format before sunsetting.
+- Pillar "industry hot takes" — KILLED. Off-graph topic, suppressed reach. Slot reallocated to reliability.
+- Format: carousels ~2.4x dwell vs text on this account. Weight calendar toward them.
+- SSI: 48 -> 61 in 90 days. "Engage with insights" dimension moved most.
+```
+
+## What `scripts/verify.sh` checks
+
+Read-only, network-free, pure bash + grep. Given `02-DOCS/wiki/linkedin/`:
+
+1. The target directory exists.
+2. At least one decision record exists (`decisions/*.md` or a root `decisions.md`).
+3. Each record carries a date (`YYYY-MM-DD`), a `Decision:` line, and a named metric/bet field — a record missing the metric is a hard failure (a decision with no metric is an opinion).
+
+A missing or empty target (a fresh presence with no wiki yet) is reported and exits 0 — no false failure. It enforces the compounding loop's integrity, not strategy quality (that is the capability eval).

package/skills/linkedin-strategy/scripts/verify.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for a linkedin-strategy wiki under 02-DOCS/wiki/linkedin/.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free checks on the decision records this skill writes back.
+#     1. The target directory exists.
+#     2. At least one decision record is present: a file under decisions/*.md
+#        OR a running decisions.md log at the target root.
+#     3. Each decision record carries the required signals:
+#          - a date              (a YYYY-MM-DD anywhere in the file)
+#          - a Decision: line     (the concrete choice)
+#          - a named metric/bet   (a "Bets on metric:" / "metric" / "bet" field)
+#        A record missing the metric/bet is a HARD FAILURE — a decision with no
+#        metric is an opinion, not a checkable bet. Missing date or Decision line
+#        is also a hard failure. A missing review date is a soft warning.
+#
+#   A missing/empty target (a fresh presence with no wiki yet) is reported and
+#   exits 0 — no false failure. Pure bash + grep, no dependencies. It is a lint,
+#   not a strategy oracle: it never judges whether the strategy is good.
+#
+# HOW TO RUN
+#   ./verify.sh 02-DOCS/wiki/linkedin/   # lint a presence's strategy wiki
+#   ./verify.sh                          # no target -> nothing to check, exit 0
+#
+# EXIT CODES
+#   0  clean, or nothing to check
+#   1  a hard structural failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+summary_exit() {
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  [ "$fail_count" -gt 0 ] && exit 1
+  exit 0
+}
+
+# --- arg parse --------------------------------------------------------------
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown flag: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+# No target, or missing dir -> nothing to check, clean exit (no false fail).
+if [ -z "$TARGET" ]; then
+  ok "no wiki path given — nothing to lint"
+  summary_exit
+fi
+if [ ! -d "$TARGET" ]; then
+  warn "directory not found: $TARGET — nothing to lint (fresh presence?)"
+  summary_exit
+fi
+ok "wiki directory exists: $TARGET"
+
+# --- collect decision records ----------------------------------------------
+# Per-decision files under decisions/, plus an optional running decisions.md log.
+RECORDS=""
+if [ -d "$TARGET/decisions" ]; then
+  for f in "$TARGET"/decisions/*.md; do
+    [ -f "$f" ] && RECORDS="$RECORDS$f
+"
+  done
+fi
+[ -f "$TARGET/decisions.md" ] && RECORDS="$RECORDS$TARGET/decisions.md
+"
+
+# Trim blank lines / handle empty.
+RECORDS="$(printf '%s' "$RECORDS" | sed '/^$/d')"
+
+if [ -z "$RECORDS" ]; then
+  warn "no decision records yet (decisions/*.md or decisions.md) — nothing to lint"
+  summary_exit
+fi
+
+# --- per-record structural checks ------------------------------------------
+DATE_RE='[0-9]{4}-[0-9]{2}-[0-9]{2}'
+
+while IFS= read -r rec; do
+  [ -z "$rec" ] && continue
+  if [ ! -s "$rec" ]; then
+    fail "$rec: empty record"
+    continue
+  fi
+
+  miss=""
+  grep -Eq  "$DATE_RE"                       "$rec" || miss="$miss date"
+  grep -Eiq '^[[:space:]-]*Decision:'        "$rec" || miss="$miss decision-line"
+  grep -Eiq '(bets on metric:|metric|bet:)'  "$rec" || miss="$miss metric/bet"
+
+  if [ -n "$miss" ]; then
+    fail "$rec: missing required field(s):$miss"
+  else
+    ok "$rec: date + decision + metric present"
+    grep -Eiq 'review date:' "$rec" || warn "$rec: no review date — bet has no follow-up"
+  fi
+done <<EOF
+$RECORDS
+EOF
+
+summary_exit

package/skills/llm-pipeline/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: llm-pipeline
+description: "Use when wiring several LLM calls into one production flow, when random 429s/timeouts/provider outages take a feature down, when adding a fallback model or a gateway in front of OpenAI/Claude, or when the bill explodes from uncached or flagship-everywhere calls. Triggers: 'chain these LLM calls', 'step 1 extracts step 2 summarizes', 'add a fallback if GPT fails use Claude', 'route easy requests to Haiku escalate to Opus', 'put a LiteLLM gateway in front', 'our bill tripled because we re-call the model on every request', 'semantic cache the responses', 'encadenar llamadas y cachear respuestas', 'cadena de crides a l'LLM amb fallback'. NOT prompt wording (that is prompt-engineering)."
+tags: [llm-orchestration, llm-gateway, fallbacks, prompt-caching, cost-control, litellm, reliability]
+recommends: [prompt-engineering, structured-extraction, building-agents, cost-tracking, agent-eval, rag, observability, parallel]
+origin: risco
+---
+
+# llm-pipeline
+
+Wire multiple LLM calls into a reliable, controllable production pipeline. You chain steps where one call's validated output feeds the next, put a router in front of providers so an outage fails over instead of taking you down, and engineer the cross-cutting concerns: timeouts, bounded retries, fallbacks, caching, and cost caps.
+
+## Core stance
+
+Treat the LLM as an unreliable network dependency, not a local function call. Everything below follows from that.
+
+- **Every call gets a hard timeout and bounded retries.** Providers have outages, rate limits, and latency tails; a naked call can hang your whole request behind one slow upstream.
+- **Steps pass validated structured objects, not free text.** The output of step N is a contract you assert on before it becomes step N+1's input — a parse failure is caught at the seam, not three steps later.
+- **A router sits in front of every provider.** One model's 429/500/timeout fails over to another; no single provider is a single point of failure.
+- **Cache and tier before you tune prompts.** The cheapest, fastest, most reliable call is the one you never made. Prompt wording is the last lever, not the first.
+
+## Do you even need a pipeline?
+
+This skill is the orchestration *around* calls. If you only have one call, you are in the wrong place.
+
+| Situation | Go to |
+| --- | --- |
+| Make one prompt better, few-shot, system-prompt design | [../prompt-engineering/SKILL.md](../prompt-engineering/SKILL.md) |
+| One call must return a typed object validated against a schema | [../structured-extraction/SKILL.md](../structured-extraction/SKILL.md) |
+| The model decides its own next step / tool to call | [../building-agents/SKILL.md](../building-agents/SKILL.md) |
+| Chunk/embed/retrieve context to stuff into a prompt | [../rag/SKILL.md](../rag/SKILL.md) |
+| Pure spend ledger / attribution / dashboard | [../cost-tracking/SKILL.md](../cost-tracking/SKILL.md) |
+| **Fixed multi-step flow + reliability layer** | **here** |
+
+A pipeline is a *DAG you designed*. The moment the model picks its own next step, it is an agent — go build that instead.
+
+## Design the chain as a typed DAG
+
+Each step is a pure-ish function: `(typed input) -> (typed output via structured output)`. Chaining small single-purpose steps beats one mega-prompt — reported ~20% output-quality gain — because each step is debuggable, cacheable, and retryable in isolation.
+
+Rules:
+
+- **The structured output of step N is the input contract of step N+1.** Validate it (Pydantic / JSON Schema) at the seam. A schema-valid object that fails validation here never poisons the next call.
+- **Keep steps small and single-purpose.** "Extract entities" and "classify sentiment" are two steps, not one prompt doing both. Smaller steps route to cheaper models and cache better.
+- **Mark independent steps for parallel fan-out.** If step B and step C both only need step A's output, run them concurrently — see [../parallel/SKILL.md](../parallel/SKILL.md). Sequential only where there is a real data dependency.
+- **Tag each step idempotent or side-effecting.** Retries and replays must be safe; a step that writes to a DB or sends an email is not safe to blindly retry.
+
+```python
+# Bad: free text flows between steps; step 2 silently mis-parses step 1
+entities = client.responses.create(model="gpt-4o", input=f"Extract entities: {doc}").output_text
+summary  = client.responses.create(model="gpt-4o", input=f"Summarize for {entities}").output_text
+
+# Good: each step emits a validated object; the seam is a contract you assert on
+from pydantic import BaseModel
+
+class Entities(BaseModel):
+    people: list[str]
+    orgs: list[str]
+
+step1 = client.responses.parse(model="gpt-4o", input=f"Extract: {doc}",
+                               text_format=Entities, timeout=30)
+ents: Entities = step1.output_parsed          # parse fails HERE, not downstream
+summary = summarize(ents)                      # typed input, not a string blob
+```
+
+## Put a gateway/router in front
+
+Use a router so a failure on one deployment fails over to another, and so you can swap or load-balance models from config without touching call sites.
+
+**LiteLLM** is the de-facto open-source LLM gateway (current stable line **v1.83.3-stable**). It exposes a unified OpenAI-format `completion()` across 100+ providers, with built-in retry/fallback, cost tracking, and budget management — usable as a Python SDK or as a Proxy Server.
+
+Fallback semantics worth knowing: a request to an `order=1` deployment that fails (connection error, 404, 429, ...) auto-tries `order=2`, then `order=3`; each order level gets its own `num_retries` before escalating; exhausting orders falls through to configured fallbacks. There are specialized buckets — `content_policy_fallbacks` (ContentPolicyViolationError), `context_window_fallbacks` (ContextWindowExceededError), and `default_fallbacks`.
+
+```python
+from litellm import Router
+
+router = Router(
+    model_list=[
+        {"model_name": "smart",
+         "litellm_params": {"model": "anthropic/claude-sonnet-4-6", "timeout": 30}},
+        {"model_name": "smart-backup",
+         "litellm_params": {"model": "openai/gpt-4o", "timeout": 30}},
+    ],
+    fallbacks=[{"smart": ["smart-backup"]}],
+    context_window_fallbacks=[{"smart": ["smart-backup"]}],
+    num_retries=2,            # per order level, bounded
+    timeout=30,               # hard cap, never unbounded
+)
+resp = router.completion(model="smart",
+                         messages=[{"role": "user", "content": prompt}])
+```
+
+**Build vs buy:** raw SDK + a thin retry/timeout wrapper (fewest deps, fine for one provider) → LiteLLM SDK/proxy (widest provider coverage, fallbacks for free) → hosted gateway (Bifrost/Portkey, when you want it operated for you). Full config — all fallback buckets, redis cache params, budget/rate-limit settings, cost callbacks — is in [references/litellm-router.md](references/litellm-router.md).
+
+## Reliability mechanics
+
+- **Always set a timeout.** A 30–60s hard cap per call. Without it, one slow upstream hangs the request indefinitely.
+- **Bounded retries with exponential backoff + jitter.** LiteLLM defaults: backoff from `INITIAL_RETRY_DELAY` 0.2s up to `MAX_RETRY_DELAY` 10s, with jitter to avoid thundering herds. Never `while True`.
+- **Only retry idempotent steps.** Retrying a step that sent an email or charged a card double-fires. Gate retries behind the idempotency tag from the DAG design.
+- **Circuit-break and degrade gracefully.** When a provider is down and fallbacks are exhausted, return a partial result, a cached result, or a cheaper-model result — never hang and never 500 the user if a degraded answer exists.
+
+```python
+# Bad: naked call in a for-loop; no timeout, unbounded effect, no fallback
+for _ in range(10000):
+    try:
+        return client.chat.completions.create(model="gpt-4o", messages=msgs)
+    except Exception:
+        continue          # hammers a down provider, blows the budget, may never exit
+
+# Good: router does bounded retries + backoff + fallback; you degrade on exhaustion
+try:
+    return router.completion(model="smart", messages=msgs)   # timeout + num_retries set
+except Exception:
+    return cached_or_cheaper_answer(msgs)                     # graceful degradation
+```
+
+## Caching: two distinct layers
+
+| Layer | What it matches | Safety | Enable when |
+| --- | --- | --- | --- |
+| Prefix / prompt cache (provider-native) | Exact prefix of the prompt | Always safe (same input → same cached compute) | Always; put the stable prefix first |
+| Semantic cache (your gateway) | Embedding-similar prior query | Risky: weak embedder → false hits | Paraphrased FAQ-style queries, approximate answers OK |
+
+**Prefix cache** is transparent and free to enable. OpenAI caches automatically at ~50% off cached input tokens, no write penalty, no storage fee — first request full price, prefix hits half price. Anthropic is explicit (you mark cache breakpoints) and deeper: cache *read* = 0.1× base input (~90% off), 5-minute *write* = 1.25× base, 1-hour *write* = 2× base, delivering ~90% cost and ~85% latency reduction on long stable prefixes. For both, **put the stable content first** (system prompt, instructions, fixed context) and the variable content last so the prefix matches.
+
+**Semantic cache** matches an embedding-similar prior query and returns that prior response. The quality is dominated by the embedding model — a weak embedder produces **false cache hits: a confidently wrong answer for a similar-but-different question** (GPTCache is documented returning incorrect saved responses for similar prompts). So: strong embedder, tuned similarity threshold, and **never on correctness-critical paths**. Threshold tuning, embedding choice, TTL, and the multi-tier `semantic → prefix → inference` order are in [references/caching-layers.md](references/caching-layers.md).
+
+## Cost & latency control
+
+- **Model-tier routing, cheap-first.** Run the cheap tier, escalate only on low confidence or detected complexity. Anchor prices (Anthropic, 2026): Haiku 4.5 $1/$5 per M in/out, Sonnet 4.6 $3/$15, Opus 4.7 $5/$25 — flagship-for-everything is 5× the cost for zero quality gain on easy calls.
+- **Budget caps that ABORT, not just log.** Per-request and per-tenant caps that kill a runaway loop. A logged-but-uncapped budget still lets a bug spend $10k overnight.
+- **Token and latency budgets per step**, and stream output for perceived latency on user-facing calls.
+
+The *ledger* — attribution, per-team dashboards, monthly reporting — is not this skill; that is [../cost-tracking/SKILL.md](../cost-tracking/SKILL.md). This skill owns the *controls* (tiers, caching, caps that abort).
+
+## Observability hooks
+
+Log per step, every call: `model`, `tokens_in/out`, `cost`, `latency_ms`, `cache_hit`, `fallback_used`, `retry_count`. These are exactly the fields you debug a production incident from ("why did p99 spike?" → fallback_used + retry_count). Wire them into the tracing backbone in [../observability/SKILL.md](../observability/SKILL.md), and measure output *quality* with [../agent-eval/SKILL.md](../agent-eval/SKILL.md) — logging is not evaluation.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Naked call, no timeout | One hung provider stalls the whole request | Hard timeout on every call (30–60s) |
+| Unbounded `while True` retry | Thundering herd, blown budget, infinite hang | Bounded retries + exp backoff (0.2s→10s) + jitter |
+| Retrying a side-effecting step | Double-writes, double-charges | Idempotency tag; only retry pure steps |
+| Free text between steps | Step N+1 silently mis-parses | Validated structured output as the contract |
+| Semantic cache with a weak embedder | Confident WRONG answers from false hits | Strong embedder + tuned threshold, or prefix cache only |
+| Flagship model for everything | 5–25× the cost, no quality gain on easy calls | Tier routing, cheap-first, escalate |
+| No fallback configured | Provider outage = your outage | Router model group + fallbacks |
+| Treating schema-valid as correct | Perfectly-shaped wrong answers ship | Validate semantics + eval (agent-eval) |
+
+## Verify
+
+Run [scripts/verify.sh](scripts/verify.sh) `<file-or-dir>` against your pipeline/gateway code. It is offline and read-only, and checks statically: every completion/chat call site has an explicit timeout, retries are bounded (no `while True` retry loops), at least one fallback is configured when a router/model_list is present, no hardcoded `sk-`/provider key literals (must be env-sourced), and any YAML/JSON config parses and lists ≥2 model entries so a fallback target exists. It prints PASS/FAIL per check and exits non-zero on any FAIL; an empty or clean target exits 0.

package/skills/llm-pipeline/evals/README.md

@@ -0,0 +1,3 @@
+# Evals for llm-pipeline
+
+`cases.yaml` is read by the repo's skill-eval harness. The `should_trigger` and `should_not_trigger` sets check routing precision — that orchestration/reliability/caching/cost-control requests land here, while prompt-wording goes to `prompt-engineering`, single schema-bound calls to `structured-extraction`, retrieval to `rag`, autonomous decision loops to `building-agents`, and spend dashboards to `cost-tracking`. The `capability` case checks that the agent produces a reliability-complete pipeline design (typed contracts between steps, timeouts, bounded retries, router fallback, the right caching choice, tier routing with an aborting budget cap, and per-step observability). Run it through the repo's eval runner the same way as the other skills; all cases are static-routing and design-rubric checks, so no live API calls or keys are required.