linkedin-studio/docs/hardening/plan.md

LinkedIn Studio — Command Hardening Plan v2 (interactive quality gate)

Supersedes the v1 autonomous plan (recoverable in git history: commit 2f90880). Motivated by the 2026-05-31 S2 fabrication incident: the v1 method (autonomous, prose-heavy 5-step per command, per-command Opus reviewer swarm, /trekreview gate) produced confident fabrications (Claude wrote SIMULATE/EVALUATE/HARDEN narratives — char counts, line numbers, before/after — for files it had not actually observed) and burned context without value (full-file re-reads + long logs + reviewer agents for what are usually 0–1-line edits). A large parallel tool-batch also destabilized the tool-result stream (out-of-order / duplicated / truncated returns). Nothing false shipped — the failed edits + empty greps + real reads caught it, and it was reverted — but the method had to change.

v2 is a slow, dialogic, human-in-the-loop gate: ONE command per session, the operator as the truth source, every mechanical claim tool-grounded.

Intent

Harden each of the 29 commands to its own intent — one command per session — with the operator in the loop. Last quality gate before GUI/M0. Brief: brief.md.

The locked interactive method (identical every session)

Per command, 8 steps. Claude STOPS and waits at each "agree" point — no autonomous run-ahead:

1. Agree intention — show the command's own description + its journey role; agree in one line.
2. Agree test-method — the class predicates (below) + what the simulation must prove.
3. Agree persona — who invokes + with what input.
4. Run the test — tool-grounded mechanical facts (each with file:line) + a GROUNDED persona simulation (a real invocation → concrete output, anchored to the shown file region).
5. Talk — the operator's judgment is the truth source.
6. Agree improvements — surgical, or "no change".
7. Implement — Edit → grep-confirm landed → show the confirmed diff.
8. Move on — run the end-of-session ritual; the next command is its own session.

Two guards (non-negotiable)

• Read-and-show BEFORE simulate — the simulation is anchored to observed text, shown to the operator.
• Every mechanical claim from a tool — char count, ✓/✗, line number: shown from a tool before stated.

Anti-drift through dialogue

The per-command dialogue IS the drift-reduction mechanism: Claude proposes at each agree-point (intention / test-method / persona / improvement) and waits for the operator to confirm or correct before proceeding. Frequent grounding checkpoints are what keep Claude from confabulating — never race past an agree-point.

Execution discipline (the S1+S2 incident lessons)

• ONE command per session. Never hold multiple command files in context at once.
• Never batch dependent tool calls in parallel. Read→Edit→grep→log is strictly sequential. Large parallel batches destabilize the tool-result stream.
• Guard greps: grep/grep -c exit non-zero on zero matches → append || echo NONE so a batch sibling isn't torn down.
• Never write a HARDEN/after claim before the edit is grep-confirmed landed.
• If the tool layer degrades (slow / truncated / empty / replayed returns): PAUSE and resume in a fresh session. Do not push through a degraded window.

Command classes & mechanical predicates (the testmethod per class)

• post-emitting — hook 110–140 present · length band present · no-body-link present · buzzword check present · topic→5 pillars present · every subagent_type: linkedin-studio:X resolves to agents/X.md.
• routing — every emitted /linkedin:Y resolves to commands/Y.md.
• guided/stateful — primary promised artifact actually produced · subagent targets resolve · graceful degradation present.
• analytics — graceful degradation present · saves/dwell honesty intact.

Synthetic test data (fixtures) — for data-dependent commands

Some commands cannot be meaningfully tested without input data — analytics (import, report, analyze, audit, ab-test) need a CSV/JSON; stateful commands (calendar, firsthour) need a queue/state. For these, step 2 (agree test-method) includes agreeing a small fictitious dataset that exercises the command's real path:

• Isolated + throwaway — built in a temp/scratch location (e.g. /tmp/… or a gitignored path), NEVER the real analytics/state dirs, NEVER committed.
• Minimal but realistic — just enough rows/fields to trigger the behavior under test (e.g. a 3–5-row CSV with the real column names; a 2-experiment ab-test file).
• Clearly fictitious — obviously-fake values, impossible to mistake for real data.
• Discarded after the test — the fixture proves the command works; it is not a deliverable.

Session queue (ONE command each)

S1 ✅ quick · onboarding · first-post · setup — DONE under v1; do NOT re-harden.

S2 post	S9 newsletter*	S16 analyze	S23 profile
S3 react	S10 headless-review	S17 audit	S24 create
S4 multiplatform	S11 pivot	S18 ab-test	S25 measure
S5 carousel	S12 firsthour	S19 strategy	S26 linkedin
S6 video	S13 calendar	S20 competitive	S27 ref-consistency A
S7 batch	S14 import	S21 monetize	S28 ref-consistency B
S8 pipeline	S15 report	S22 outreach	S29 terminology-scrub
			S30 magnitude-scrub

*S9 newsletter (16-phase) may split into S9a/S9b. Otherwise one command = one session.

S27/S28 — reference-consistency pass (added 2026-06-19, operator-approved; promotes open follow-up #1 to scheduled work). NOT full re-hardening of already-✅ commands — surgical SSOT-reconciliation of the documented divergences, same tool-grounded discipline (read-and-show → grep-confirm → re-grep final):

• S27 (A) — "penalty/penalizes" framing → SSOT ✅ DONE (2026-06-19, 10 edits/6 files; see log.md). The 3 cited lines (troubleshooting-guide.md:127, analyze.md:101, audit.md:60 — nr drifted ±1) + 7 same-class siblings (trend-spotter topic-relevance ×2, troubleshooting-guide :15, first-comment-strategy ×3, url-processing-templates :396) reconciled to "correlate with lower reach" / "topic relevance is a ranking input — off-topic gets lower reach". Bucket B (link-penalty lines in linkedin-formats.md) folded into S28; Bucket D (other unsourced magnitudes) promoted to S30.
• S28 (B) — format magnitudes → SSOT: commands/video.md:69 + references/linkedin-formats.md (the "30% zero-distribution" claim vs SSOT native-video framing) + the 6 link-penalty lines folded in from S27 Bucket B (linkedin-formats.md:52,:91,:194,:198,:200,:432) — reconcile link + format framing in one pass over that file.

S29 — terminology scrub: "thought leadership" → "LinkedIn Studio" / neutral (added 2026-06-19, operator-approved during S26). The phrase must not appear anywhere in the plugin (it is named LinkedIn Studio; see auto-memory no-thought-leadership-phrase). S26 fixed the 2 occurrences in commands/linkedin.md; ~85 lines across ~45 files remain (commands, agents, references — incl. the filename references/thought-leadership-angles.md — skills, plus historical CHANGELOG/docs). Open scoping questions for this pass: (a) user-facing surface only, or include historical CHANGELOG/docs too? (b) the thought-leadership-angles.md rename is its own sub-step — every pointer to the filename must update with it. Same tool-grounded discipline (read-and-show → grep-confirm → re-grep final); hardening-class.

S30 — magnitude scrub: unsourced reach-coefficients → SSOT (surfaced during S27, 2026-06-19). A different class from S27's link/topic-relevance framing: discrete percentage penalties with no primary source in the SSOT — −68% (5+ hashtags: linkedin-growth-playbook:166, ab-testing-framework:66), −25% (<1000 chars: linkedin-growth-playbook:224), −15-25% (topic-gap: glossary:235), −30-50% (engagement-bait: glossary:91), 55%/45% (AI-comment: engagement-coach:195, firsthour:112 — SSOT carries ~45% correlational engagement gap at medium confidence, not a 55% reach penalty), −25%/post (multiple posts/3h: post-feedback-monitor:330), poll-overuse (poll-strategy-guide:20,:205). Leave intact (officially confirmed, high confidence): engagement-pod + AI-slop "penalized" framing. Full grep catalog in log.md S27 entry, Bucket D. Same discipline; hardening-class.

Run after S26; order adjustable (S27 ✅ → S28 → S29 → S30). These edit already-hardened files surgically and are hardening-class (commit local, no push).

End-of-session ritual (every session — STATE.md handoff baked in)

1. bash scripts/test-runner.sh → Failed: 0 + counts 29/19/25/6.
2. Terse, tool-grounded log.md line for the command (ONLY after verify): PASS / edit + file:line.
3. Commit own file(s) only, LOCALLY (fix: for command edits; explicit git add <path>, never -u/-A). Do NOT push hardening work — see Push policy.
4. Overwrite STATE.md: mark this command ✅; point at the NEXT single command + its class; carry the method + discipline rules → ready for the next "Les STATE.md og følg instruksjonene".
5. (Optional) update Voyage .session-state.local.json next-label for /trekcontinue coherence.

Defaults (adjustable between sessions)

1. Log: keep, terse, tool-grounded, after-verify only.
2. Persona: ICP author default; fresh-adopter for onboarding/first-post/setup; deviate explicitly elsewhere.
3. Gate/commit: once per session = per command.

Push policy (operator rule, 2026-05-31)

Hardening work — "det vi GJØR": command edits + log.md entries — is committed locally only, never pushed. Only method / process / tooling improvements (this plan, a future checker, STATE conventions) may be pushed, and only on explicit operator OK ("eventuelle forbedringer").

Amendment policy

Improve the method/plan between sessions if a session surfaces a gap (operator-approved). This plan is a living contract, not frozen.