ktg-plugin-marketplace/plugins/linkedin-studio/docs/remediation/brief.md

---
type: trekbrief
brief_version: "2.1"
created: 2026-05-29
task: "Remediate linkedin-studio from the baseline audit — correctness, honesty, generalization, and the highest-leverage 2026 coverage gaps (full Phase 0–3 roadmap, phased)"
slug: remediation
project_dir: docs/remediation/
research_topics: 3
research_status: complete
auto_research: false
interview_turns: 3
source: interview
phase_signals:
  - phase: research
    effort: high
    model: opus
  - phase: plan
    effort: high
    model: opus
  - phase: execute
    effort: high
    model: opus
  - phase: review
    effort: high
    model: opus
---

# Task: linkedin-studio baseline-audit remediation

> Generated by `/trekbrief` on 2026-05-29.
> This brief is the contract between requirements and planning. `/trekplan`
> reads it to produce the implementation plan. Every decision in the plan must
> trace back to content in this brief.
>
> **Source of record:** `docs/critical-review-2026-05-29.local.md` (the baseline
> audit — Workflow `wf_8623b3ea-682`, 28 agents + Gemini Deep Research
> triangulation), including its **Operator correction (2026-05-29)** which is
> primary-source and supersedes the cold read. Section references below
> (§3, §3b, §4, §5, §7, §8, §9, §10) point into that file.

## Intent

The baseline audit was a cold, hostile read of the plugin repo with no operator
input. It found a set of **file-reproducible correctness and honesty defects**
that survive a second hostile pass: the analytics CLI crashes on first use on a
fresh clone (`ERR_MODULE_NOT_FOUND`); the algorithm "facts" contradict
themselves across files (a comment is "15x more reach" on one line and "5x" ten
lines later; carousel is "6.6%, highest of all formats" in two files and "1.92%"
in a third; the external-link penalty is "40-50%" in eight files and "25-40%" in
ten); the author's **real** voice profile ships committed and is read
unconditionally, so a fresh adopter who skips setup writes in the author's voice
and is told "Voice ✓ Done"; the only structural lint is dead and always fails
identically whether the plugin is healthy or gutted; the A/B output claims
statistical significance organic personal posts essentially never reach; the
analytics data model measures network-graph metrics while the strategy layer
tells the user to optimize saves/dwell it structurally cannot read; and 11 of 19
agents are never invoked by any command. On top of the correctness layer, the
plugin presents algorithm knowledge with a precision the evidence does not
support, and ships its flagship long-form engine as **bespoke disguised as
general** — hardcoded Norwegian, a maintainer-private absolute series path, and a
"skrivekontrakt §C2" that does not ship.

The operator's correction **refutes the audit's single hardest finding**: the
long-form pipeline HAS run end-to-end — two editions shipped via
`/linkedin:newsletter`, with artifacts living in a separate series repo
(`maskinrommet/serier`), so in-repo archaeology saw nothing. So this work is
**not** "prove the pipeline runs." It is: fix what is file-reproducibly broken,
make the plugin honest about what it knows and what it cannot do, and make it
usable by someone who is not the author. The stakes are trust — the operator
writes long-form regularly from now on, intends to share the plugin actively, and
will publish a Maskinrommet article about it. Every algorithm claim that ships
becomes a public claim, so correctness and honesty are load-bearing, not cosmetic.

## Goal

linkedin-studio passes a does-it-work bar on a fresh clone and is honest about
its boundaries, while keeping its differentiators. Concretely, the end state is:
the analytics CLI runs from any working directory on a fresh clone; the
structural lint reflects the real layout and fails on drift; there is **one**
source-anchored algorithm-signal statement that every command and agent cites,
with no intra-file or cross-file contradictions and no unsourced numeric
precision (the deployed-model name, the January-2026 date, and the −40-60% figure
are downgraded to exactly what current sources support); a generic placeholder
voice profile ships while the author's real one is gitignored; the plugin is
de-Norwegian-locked with a parameterized series path and documented default; the
plugin honestly discloses its boundaries (no self-serve analytics API for
personal profiles, no auto-publish, dwell is not exportable) up front; the
highest-leverage 2026 coverage gaps are closed with **wired, tracked** surfaces
(first-hour/reply loop, short-form de-AI gate, video 9:16 enforcement,
profile-SEO, newsletter distribution, outreach pipeline state); the long-form
stack is **kept** and trimmed for quality only where review-pass overlap is
**measured**, not assumed; and the 11 orphan agents are resolved case-by-case
(wired to a command or deleted). The README's "the version that ships is the
version that's actually been independently reviewed" claim is removed and
replaced with an honest framing. Delivered **phased** per §9: Phase 0
(correctness + honesty) → Phase 1 (usable by a non-author) → Phase 2 (coverage
gaps) → Phase 3 (long-form earn / redundancy measurement).

## Non-Goals

- **Not** rebuilding the plugin or rewriting the long-form engine. Fork-1 decision
  is **KEEP** the long-form stack; trim only where it measurably improves quality.
- **Not** proving the long-form pipeline runs end-to-end — refuted by the operator
  correction; it has shipped two editions. The audit's "never run" framing, the §2
  "Long-form stack: never executed" row, and teardown spine A's "accretion without
  dogfooding" premise are **dropped** and must not anchor any work.
- **Not** adding a manual-entry feature for saves/dwell. The saves/dwell decision
  is the **honesty-fix only** — downgrade the claims; do not build a measurement
  surface for them (operator decision, 2026-05-29).
- **Not** building LinkedIn auto-publish, an analytics-API integration, or any
  paid/remote service. Boundaries are to be **disclosed**, not engineered away.
- **Not** any enterprise feature (web dashboard, fleet policy, ticketing) — this is
  a solo project; those are fork-and-own.
- **Not** changing the `/linkedin:*` command invocation surface for short-form
  unless a fix requires it; the short-form feed engine is the part that works.
- **Not** writing the Maskinrommet article in this work — that is downstream of a
  clean, honest plugin.

## Constraints

- **Opus on everything** — all phases, all subagents, all loops (standing
  operator default; overrides any model-tiering table). Voyage = Opus always.
- **No hidden costs** — any `/trekplan` run or Workflow with many agents MUST be
  cost-warned with explicit operator yes before it runs. The operator is present.
- **Verification duty (the article will publish)** — every external claim that
  ships is verified against a current primary or credible source before it is
  written; gaps are marked "Not verified" or omitted, never filled with a guess;
  no sales language in technical text. Reproduce the audit's key external findings
  first-hand (§10 items 2–4), do not inherit them from the report.
- **Three-doc rule** — any feature change pushed to Forgejo updates all three doc
  levels in the same change: plugin `README.md`, plugin `CLAUDE.md`, root
  `README.md`.
- **Version sync** — on any version bump, grep the old version and update every
  reference (package/manifest, README badges, CHANGELOG, CLAUDE.md, SKILL.md,
  STATE.md counts).
- **Hook editing** — edit `hooks/hooks.template.json` + `hooks/prompts/*.md`, then
  run `python3 hooks/scripts/compile-hooks.py`; never edit `hooks.json` directly.
- **bash 3.2 + Node-only hooks** — all shell is bash-3.2-compatible; hooks are
  Node `.mjs`, cross-platform, zero npm dependencies.
- **Cross-repo `maskinrommet/`** — writing there requires an explicit instruction;
  this work touches only the plugin repo.
- **Audit report stays local** — `docs/critical-review-2026-05-29.local.md` is not
  committed until the article is out.

## Preferences

- Phased delivery following the §9 roadmap (Phase 0 → 1 → 2 → 3); one phase is a
  natural plan-step boundary, executed one Voyage session at a time.
- Per execution step, choose the engine deliberately: inline · `Agent` · `Workflow`
  (tightly-scoped fan-out for heavy steps only).
- Fix the **substrate first**: `references/algorithm-signals-reference.md` is the
  file the contradictions propagate from — correct it once and the agents/commands
  inherit the fix.
- Reframe "ritual vs craft" in the long-form critique as **trim-for-quality**, not
  justify-existence (the stack is exercised machinery).
- Honesty-reframe of the README "independently reviewed" claim happens **in this
  plan**, not as an out-of-band edit now (operator-confirmed).
- Generalize cleanly: parameterize the series path via env-var/config with a
  documented, non-private default; keep all voice profiles (author's and any
  adopter's) local-only and gitignored.

## Non-Functional Requirements

- **Zero new npm dependencies** in hooks/scanners/scripts (Node built-ins + `node:test`).
- **Fresh-clone clean** — analytics CLI and lint both succeed on a clone with no
  prior `npm install` state assumed (CLI surfaces the install step as first-class).
- **No PII in committed files** — the shipped voice profile contains no real name,
  avoid-list, or identifying vocabulary; ownership-neutral placeholder markers only.
- **Backward-compatible state** — any state-file change to
  `~/.claude/linkedin-studio.local.md` is additive; existing editions/queues keep working.
- **Cross-platform** — clipboard, hooks, and any new scripts run on macOS + Linux + WSL.

## Success Criteria

*Each is falsifiable by a command or a specific observation. Grouped by phase.*

**Phase 0 — correctness + honesty**

- Analytics CLI runs from any CWD on a fresh clone: from a directory other than
  the plugin root, `/linkedin:report`'s underlying CLI invocation exits 0 (no
  `ERR_MODULE_NOT_FOUND`) — verified by running the documented invocation after a
  clean checkout with the install step performed as instructed.
- One magnitude per algorithm effect: `grep -rn` for the comment multiplier,
  carousel engagement %, and link-penalty % across `references/` + `agents/` +
  `commands/` returns a **single** value (or one labelled range) per effect — no
  "15x vs 5x", no "6.6% vs 1.92%", no "40-50% vs 25-40%".
- `references/algorithm-signals-reference.md` carries a **per-claim source +
  confidence column**; every agent/command that states a signal cites it rather
  than restating a bare number.
- The "360Brew, January 2026" / "−40-60% before anyone sees it" claims are
  downgraded to sourced direction only: no asserted deployed-model name, no
  asserted Jan-2026 switch date, no unsourced reach figure (README + `commands/profile.md`).
- `assets/voice-samples/authentic-voice-samples.md` contains **no real PII**
  (no author name, no real avoid-list); a placeholder is detected by
  ownership-neutral markers; the real profile lives at a gitignored `*.local.md`;
  `setup.md` **overwrites** rather than merges.
- `scripts/test-runner.sh` exits **0** on the healthy repo, globs the real
  `agents/` layout, derives `EXPECTED_AGENTS` from `ls agents/` with a
  length-equality assertion, and **fails (non-zero)** when an agent file is
  added or removed without registration (provable by a temporary add/remove).
- `commands/ab-test.md` has **no** literal `Significant? Yes/No` column; confidence
  is capped at "directional" below ~50 samples per variant; the "20% significance
  rule" wording is gone.
- Saves/dwell claims are downgraded to honest wording **[refined by research/02]**:
  no report or strategy surface tells the user to optimize a signal the data model
  cannot populate. Accurate framing: saves ARE visible in native LinkedIn post
  analytics (since ~Sept 2025, count-only) but there is **no self-serve API** to pull
  them, so the tool does not auto-track them (point the user to the native number);
  dwell is internal-only for organic posts. The `report.md` "Saves (10x weight) …
  highest-impact" line is reframed accordingly.

**Phase 1 — usable by a non-author**

- The series root is read from an env-var/config with a **documented** default
  that is **not** a maintainer-private absolute path (`grep -rn '/Users/ktg'` over
  shipped — non-`*.local.*` — files returns 0 hits in long-form config/commands).
- The Norwegian-language review layer is gated/parameterized so it does not grade
  English prose against Norwegian rules for a non-Norwegian adopter (language is a
  configurable input, not a hardcoded lock).
- README + the relevant commands state the boundaries up front **[refined by
  research/02]**, each as plain prose, not buried and **dated ("as of 2026-05")**:
  (a) post-level analytics API for personal profiles EXISTS but is partner-gated
  (vetted Community Management API + verified org + Page) — not self-serve; CSV is the
  practical floor; (b) auto-publish to a personal profile IS technically possible
  self-serve (`w_member_social`) but is **deliberately not built** — a design + ToS
  choice, not an API impossibility (do NOT write "cannot auto-publish"); (c) dwell not
  exportable for organic posts. The calendar/queue/"publish" wording is reconciled so
  it never implies the tool auto-posts.
- Discoverability counts reconcile: the auto-activating router skill
  `skills/linkedin-studio/SKILL.md` no longer calls it the "thought leadership plugin",
  lists the **real** agent count, and routes to `newsletter`/`headless-review`/
  `pivot`/`react`; onboarding's "25 commands" and the pillar-count disagreement
  (`setup.md` 5 vs `onboarding.md` 3–5) are aligned to the real numbers.
- README contains **no** "the version that ships is the version that's actually
  been independently reviewed" string; an honest framing replaces it.

**Phase 2 — highest-leverage coverage gaps**

- A wired first-hour/reply surface exists, invoked by a command (not orphan prose),
  with tracked state: a target list + draft comments + a timestamped first-hour
  plan persisted in plugin state.
- A short-form de-AI / differentiation gate fires on short-form creation
  (post/quick/react/carousel/video) — provable by a hook/gate or an agent the
  command actually invokes (`grep -rl 'subagent_type: linkedin-studio:differentiation-checker' commands/` ≥ 1, or an equivalent wired gate).
- Each of the 11 orphan agents is **either** invoked by ≥1 command
  (`grep -rl 'subagent_type: linkedin-studio:<name>' commands/` ≥ 1) **or** deleted;
  the agent count in CLAUDE.md / README / SKILL.md equals `ls agents/*.md | wc -l`.
- Video gate is a **quality gate, not a reach-push [refined by research/03]**: MP4
  default (warn-only on MOV/AVI) + within-limits; **captions enforced/strongly
  recommended** (SRT or native auto-captions); aspect ratio is **guidance, not a hard
  gate — 4:5 / 1:1 preferred for broad distribution, 9:16 mobile-only opt-in** (the
  "4:5 deprioritized" self-contradiction is fixed toward "4:5 preferred"); **no
  "3-second hook" rule** (replaced by "front-load value for muted autoplay") and **no
  "video maximizes reach" copy** (per-video reach is declining; documents out-engage
  video).
- Profile, newsletter distribution, and outreach gain the §5 surfaces **[newsletter
  refined by research/03]** — each at least a wired command surface, not prose-only:
  profile-SEO fields; **honest** newsletter distribution (bypasses organic feed ranking
  via **one deduplicated** notification per subscriber per edition — NOT "triple
  notification"; one-time launch-blast + a **~1–2K follower floor**; realistic
  cold-start floors of 0–100 subs in months 1–3; disclose non-export / no-canonical /
  no-read-analytics / per-subscriber decay); outreach tracked contact/pipeline state.

**Phase 3 — long-form earn / redundancy measurement**

- `/linkedin:newsletter` shows a "multi-session, multi-gate, ~N-hour" expectation
  banner at the top.
- Long-form review-pass overlap is **measured** (a recorded comparison of what each
  reviewer/gate actually catches) and the redundancy is trimmed where the measurement
  does not justify it — with the measurement committed as evidence, not an assertion.
  The measurement source is an **in-repo fixture edition** by default; reading a
  shipped edition from `maskinrommet/serier` requires an explicit operator instruction
  per the cross-repo constraint, so the plan must not assume that read.

**Cross-cutting (every phase)**

- All three doc levels updated in the same change (plugin README, plugin CLAUDE.md,
  root README); `grep` for the prior version string returns 0 stale hits after any bump.
- The plugin's own lint (`scripts/test-runner.sh`, rebuilt) and any `node --test`
  suites pass on the final state.

## Research Plan

*The internal/file-level fixes (analytics-CLI crash, dead lint, voice-leak,
orphan-agent wiring, A/B significance, doc counts) need **no** external research —
they are reproducible from the repo. The fixes that touch **external claims** do:
the audit's external bar is explicitly "thin / re-check before publishing" (§10),
and the operator's verification duty (the article publishes) mandates first-hand
sourcing. Three topics, each feeding specific plan steps.*

### Topic 1: Canonical 2026 LinkedIn algorithm signal statement

- **Why this matters:** This is the substrate fix. Phase-0 steps that reconcile the
  contradictory stats (comment multiplier, carousel %, link penalty), reframe the
  first-comment advice, downgrade the "360Brew / Jan-2026 / −40-60%" premise, and
  widen the "golden hour" depend on knowing what current defensible sources actually
  support — magnitude, direction, and confidence per signal. The audit (§3/§3b) shows
  the existing numbers are a mix of vendor-blog estimates and self-contradiction; the
  reconciled statement every command/agent will cite cannot be authored without this.
- **Research question:** "What does the 2026 LinkedIn feed-ranking system actually
  reward — for the comment-vs-reaction weighting, document/carousel engagement rate,
  external-link reach effect and the current first-comment-workaround status, the
  early-engagement ('golden hour') window incl. delayed/evergreen reinjection, and
  the deployed ranking model's verifiable name and deployment date — with a primary
  or credible source and a confidence level for each claim?"
- **Suggested invocation:** `/trekresearch --project docs/remediation/ --external "What does the 2026 LinkedIn feed-ranking system actually reward — comment-vs-reaction weighting, document/carousel engagement rate, external-link reach effect and first-comment status, the early-engagement window incl. delayed reinjection, and the deployed ranking model's verifiable name and date — with a source and confidence per claim?"`
- **Required for plan steps:** Phase-0 "reconcile algorithm stats to one sourced
  statement", "reframe external-link penalty", "downgrade 360Brew premise"; the
  per-claim source/confidence column in `algorithm-signals-reference.md`.
- **Confidence needed:** high
- **Estimated cost:** deep — with contrarian + Gemini triangulation (the audit
  already shows vendor-blog noise and two passes disagreeing on the model name).
- **Scope hint:** external

### Topic 2: Personal-profile analytics + auto-publish boundaries (2026)

- **Why this matters:** Phase-1 "state the boundaries honestly" and Phase-2 "saves
  honesty-fix" need the current, verifiable status of three things the plugin makes
  architectural claims about: whether a personal profile can self-serve a Member Post
  Analytics API (§3b #11 marks the plugin's "individuals cannot → CSV only" premise
  as *outdated*, not merely a constraint), whether per-post saves are visible in the
  LinkedIn UI (the audit cites Sept-2025), and what auto-publish is/isn't possible for
  a personal profile via API. Wrong boundary statements would replace one false claim
  with another.
- **Research question:** "As of 2026, can a personal LinkedIn profile self-serve
  post-level analytics via an API (Member Post Analytics or partner platforms), are
  per-post saves visible in the native UI, and can a personal profile auto-publish
  posts via any API — and what are the exact access constraints for a solo user
  without partner/company-page access?"
- **Suggested invocation:** `/trekresearch --project docs/remediation/ --external "As of 2026, can a personal LinkedIn profile self-serve post-level analytics via an API, are per-post saves visible in the native UI, and can a personal profile auto-publish via any API — with the exact constraints for a solo user without partner/company-page access?"`
- **Required for plan steps:** Phase-1 "honest boundary statements in README +
  commands"; Phase-2 "saves/dwell honesty-fix wording"; the §5 scheduling-boundary
  disclosure.
- **Confidence needed:** high
- **Estimated cost:** standard — agent swarm.
- **Scope hint:** external

### Topic 3: Coverage-gap feature specs — video, de-AI signal, newsletter distribution

- **Why this matters:** Phase-2 builds new **wired** surfaces, so they need current
  specs, not prose. Three inputs: the hard requirements for short-form video that
  LinkedIn actually rewards in 2026 (aspect ratio, resolution, hook timing,
  caption/SRT), what concretely triggers the templated-AI / engagement-bait down-rank
  the de-AI gate must guard against, and the real newsletter-distribution mechanics
  (the triple-notification leverage, cadence discipline, realistic cold-start numbers)
  the long-form stack currently omits.
- **Research question:** "For LinkedIn in 2026, what are the hard short-form video
  requirements the algorithm rewards (aspect ratio, resolution, hook timing,
  captions), what specifically triggers the templated-AI / engagement-bait down-rank
  signal, and what are the newsletter-distribution mechanics (notification leverage,
  cadence, realistic cold-start subscriber numbers) a creator should follow?"
- **Suggested invocation:** `/trekresearch --project docs/remediation/ --external "For LinkedIn in 2026: hard short-form video requirements the algorithm rewards (aspect ratio, resolution, hook timing, captions); what triggers the templated-AI/engagement-bait down-rank; and newsletter-distribution mechanics (notification leverage, cadence, realistic cold-start numbers)?"`
- **Required for plan steps:** Phase-2 "video 9:16 enforcement", "short-form de-AI
  gate", "newsletter distribution surface".
- **Confidence needed:** medium
- **Estimated cost:** standard — agent swarm.
- **Scope hint:** external

## Open Questions / Assumptions

- **[ASSUMPTION]** The plan will order work as the §9 phases (0→1→2→3), one phase
  per Voyage session, with `/trekreview` as the final release gate. To be confirmed
  when `/trekplan` produces the step list.
- **[ASSUMPTION]** Orphan-agent case-by-case decisions (wire vs delete) are made
  **in the plan phase**, not now; the operator answered "case by case".
- **[ASSUMPTION]** Versioning shape (single major bump vs phased minor releases) is a
  plan-phase decision; not pre-committed here.
- **[OPEN — narrow, from the operator correction]** Whether the v3.1 headless
  cold-review layer (Step 6.5) co-ran in a *shipped* edition. Moot for the README
  (the "independently reviewed" claim is removed per fork-4), but worth noting so the
  honesty-reframe wording is accurate.
- **[ASSUMPTION]** Research Topic 1's "deep" cost (contrarian + Gemini) will be
  cost-warned before it runs, per the no-hidden-costs rule.

## Prior Attempts

The baseline audit itself is the prior work: a cold adversarial Workflow
(`wf_8623b3ea-682`, 28 agents) plus an independent Gemini Deep Research
triangulation pass, delivered as `docs/critical-review-2026-05-29.local.md`. After
delivery the operator supplied first-hand corrections that refuted the audit's
flagship "never run" finding and locked four scope decisions (keep long-form +
trim for quality; regular use confirmed; generalize the plugin; remove the README
"independently reviewed" claim). No remediation code has been written yet — this
brief is the first step of the fix. The plugin reached v3.1.0 via six versions in
~48 hours (the audit's "accretion" meta-finding), which is *why* the correctness
and honesty pass is needed before further feature accretion.

## Metadata

- **Created:** 2026-05-29
- **Interview turns:** 3 (scope boundary, orphan-agent disposition, saves/dwell disposition — the four headline forks were pre-locked by the operator correction)
- **Auto-research opted in:** no
- **Source:** trekbrief interview (driven by the locked operator corrections; no full re-interview per the operating model)

---

## How to continue

Manual (default):

```bash
# Run each research topic (order does not matter):
/trekresearch --project docs/remediation/ --external "What does the 2026 LinkedIn feed-ranking system actually reward — comment-vs-reaction weighting, document/carousel engagement rate, external-link reach effect and first-comment status, the early-engagement window incl. delayed reinjection, and the deployed ranking model's verifiable name and date — with a source and confidence per claim?"
/trekresearch --project docs/remediation/ --external "As of 2026, can a personal LinkedIn profile self-serve post-level analytics via an API, are per-post saves visible in the native UI, and can a personal profile auto-publish via any API — with the exact constraints for a solo user without partner/company-page access?"
/trekresearch --project docs/remediation/ --external "For LinkedIn in 2026: hard short-form video requirements the algorithm rewards (aspect ratio, resolution, hook timing, captions); what triggers the templated-AI/engagement-bait down-rank; and newsletter-distribution mechanics (notification leverage, cadence, realistic cold-start numbers)?"

# Then plan:
/trekplan --project docs/remediation/

# Then execute:
/trekexecute --project docs/remediation/
```

Auto (opt-in during `/trekbrief`): research and planning run automatically; only
execution is manual. **Not used here** — per the operating model, `/trekplan` is
invoked separately in the foreground after operator approval, with an explicit
cost warning.