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

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

Amendment (2026-05-30) — Finish scope (S13–S17)

After the v4.0.0 remediation pushed (Phase 0–3 done; S12 review WARN, 2 findings open), the operator commissioned a finish pass to close every remaining hole to a clean ALLOW. Plan: docs/remediation/finish-plan.md. This amendment folds the new scope into the contract so the review gate measures it as in-scope (not Non-Goal violation).

Re-opened Non-Goals (superseded by operator decision 2026-05-30):

• "Not changing the /linkedin: command invocation surface"* — re-opened for S14 command rationalization (a deliberate keep/develop/merge/cut pass; merges/cuts only on explicit per-command operator approval).
• "Not adding a manual-entry feature for saves/dwell" — re-opened for saves only (S16). Dwell stays unmeasurable (internal-only); no dwell surface is built.

New Success Criteria (Finish):

• S13: replaceField (state-updater.mjs:14-18) inserts untrusted last_post_topic literally (replacement function); a $-bearing test pins the last_post_topic scalar; a structural $-safety lint (Section 12) fails on any string-replacement whose value derives from an untrusted parameter; /trekreview → ALLOW.
• S14: docs/remediation/command-rationalization.md records a per-command keep/develop/merge/cut recommendation for all commands; every merge/cut is operator- approved; the lint count-guard + all rosters + three-doc agree with ls commands/*.md.
• S15: /linkedin:onboarding produces a draft post inline (no Run /linkedin:first-post dead-end); /linkedin router is tiered (≤4 primary, ~1K-gated commands flagged "locked"); /linkedin:carousel copies the full deck (all slides + caption), not just the caption.
• S16: a manual saves value can be entered and surfaces in /linkedin:report without crashing; CSV-only data still works (backward-compatible); dwell remains explicitly unexportable.
• S17: every uncalibrated audit finding C13–C46 has a recorded disposition (docs/remediation/c13-c46-triage.md: still-real / already-fixed / outdated-drop); every still-real one is grep-verified closed.

Pending / out-of-band (not yet sequenced — operator will time it): two additional briefs the operator flagged — docs/linkedin-studio-persona-brief.md and docs/linkedin-studio-ui-brief.md. If their scope conflicts with S13–S17 (esp. the UI brief vs S15 router/onboarding/carousel UX), reconcile before executing the overlapping session; do not let the finish pass pre-empt a decision the operator hasn't made.

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):

# 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.