linkedin-studio/commands/pivot.md

name	description	allowed-tools
linkedin:pivot	Re-open a long-form edition after a substantive late change (a "pivot") so the already-cleared quality gates re-run on the changed version before lock. Logs the pivot in edition-state, moves currentPhase back to the right earlier step, un-locks if needed, and marks which gates (fact-check, editorial, persona, headless) must re-pass. Includes the pivot-detection heuristic (>20% word-count change or >2 new sections). Use when the user says: "pivot", "I changed the angle", "I added a section", "re-open the edition", "the article changed after it was approved", "re-run the gates", "this needs re-review". Triggers on: "pivot", "linkedin pivot", "re-open edition", "added a section", "changed the angle", "pivot-reopen", "/linkedin:pivot".	Read Glob Grep Bash AskUserQuestion Write

LinkedIn Pivot — re-open a cleared edition for re-review

A pivot is a substantive change to a long-form draft made after a gate had already cleared it — a new argument anchor, a new section, a changed thesis. The problem this command solves: the pipeline's gates (fact-check Step 5, editorial Step 5.5, persona Step 6, headless Step 6.5) ran on the pre-pivot version, so the changed text was never validated. Without an explicit re-open, a pivoted edition can sail into lock carrying an unverified premise or an unread argument.

Why this exists (Del 4, Endring 9c). Del 4 was LOCK-ready on an early version (v8). Then a "Security Champions" pivot added a ~260-word section and a ~270-word role-description section — roughly +42 % length, two new sections, a new axis. The pipeline had no pivot-mode, so the whole post-lock chain had to be re-opened by hand. This command makes the re-open a named ritual, not a manual scramble.

Command anatomy

/linkedin:pivot
  --article  NN                  (required; the edition article that changed)
  --reason   "<one line>"        (required; e.g. "Security Champions-anker")
  --to-phase draft | consistency-quality   (optional; default from scope — see Step 2)

The pivot-detection heuristic

Compare the current draft against the version that last cleared Step 6 (persona-sweep-prelock). A pivot-reopen is suggested/required when either:

• word-count change > 20 %, or
• > 2 new sections (top-level headings added since the cleared version).

This heuristic is also checked as a lock precondition in Step 8 of /linkedin:newsletter: if the draft has drifted past these bounds since Step 6 cleared, the lock STOPS and points the operator here. (Length-band drift itself — soft/hard caps — is logged friction F1, not yet a gate.)

Worked example (acceptance test — Del 4 v8 → v11). At v8 the persona sweep had cleared a ~1 400-word draft. The Security Champions message pushed it to ~1 992 words (+42 %, > 20 %) and added 2 sections (a new anchor + a role-description) — at the boundary of the "> 2 new sections" rule and well past the 20 % rule. The heuristic fires: /linkedin:pivot --article 04 --reason "Security Champions-anker" would log the pivot, move currentPhase back to draft (structural change → full re-treatment), and require fact-check + editorial + persona + headless to re-pass on v11 before lock. That is exactly the re-sweep the manual Del 4 run had to improvise.

Step 1 — Load state + locate the article

1. Resolve the series root and read <serie>/linkedin/edition-state.json. Find articles.NN for the --article value. If it does not exist, stop and report.
2. Read the current draft <serie>/NN-utkast.md and note currentPhase and locked.

Step 2 — Measure the pivot scope

1. Current word count: cd <serie-mappe> && wc -w NN-utkast.md.
2. Baseline word count: the word count of the version that last cleared Step 6, recorded by newsletter Step 6 in articles.NN.personaSweep.resonance.wordCount. If that field is absent (older state), ask the operator for the cleared-version word count, or treat the pivot as structural by default.
3. Compute deltaPct = round((current - baseline) / baseline * 100) and count newSections = top-level headings now present that were not in the cleared version (a grep -c '^## ' delta is a reasonable proxy; confirm with the operator if ambiguous).
4. Classify scope (drives the default --to-phase):
   • Structural (deltaPct > 20 % OR newSections > 2, or a new axis/thesis) → default to-phase: draft so newsletter resumes at Step 4 (consistency-quality) — the changed prose is re-threaded, then fact-check (5) → editorial (5.5) → persona (6) → headless (6.5) re-run on it.
   • Moderate (new examples/claims, no new sections, deltaPct ≤ 20 %) → default to-phase: consistency-quality so newsletter resumes at Step 5 (fact-check) and the new claims get verified, then editorial (5.5) → persona (6) → headless (6.5) re-run.
   • The operator may override with explicit --to-phase.

Why these specific phases (the off-by-one trap). to-phase is written as currentPhase, which records the last completed phase; /linkedin:newsletter's resumption table (Step 0) then resumes at the step after it. So draft resumes at Step 4 and consistency-quality resumes at Step 5 (the fact-check). A pivot therefore never resets to factcheck-sweep — that would resume at Step 5.5 and skip the fact-check, violating this command's invariant that a pivot always invalidates the fact-check (Step 3, gatesToRerun).

Step 3 — Log the pivot + reset the phase (the ritual)

1. Append a pivot entry to articles.NN.pivots[]:

   {
     "timestamp": "<ISO-8601>",
     "reason": "<--reason>",
     "fromPhase": "<currentPhase before this command>",
     "toPhase": "<resolved to-phase>",
     "wordCountBefore": <baseline>,
     "wordCountAfter": <current>,
     "deltaPct": <deltaPct>,
     "newSections": <newSections>,
     "gatesToRerun": ["factcheck-sweep", "editorial-review", "persona-sweep-prelock", "headless-review"]
   }
   

   gatesToRerun always spans every gate from the reset phase through Step 6.5 — a pivot invalidates the fact-check, the editorial craft pass, the persona resonance verdict, AND the headless package, because all of them judged the pre-pivot text.
2. Reset currentPhase to the resolved toPhase, and set the article's phase to match.
3. Un-lock if needed. If articles.NN.locked was true, set locked: false and status: "in-progress" — a pivot means the edition is no longer locked. Surface this plainly (the prior POST.html is now stale and will be re-rendered at the next lock).
4. Invalidate the downstream verdicts so they cannot be mistaken for current: set personaSweep.resonance, editorialReview, and headlessReview.status back to a re-run state (e.g. headlessReview.status: "pending"), and note in each that they were invalidated by pivot <timestamp>. Leave the pivots[] log and factcheckLog history intact (history is durable).
5. Update updatedAt and write edition-state.json.

Step 4 — Point the next step

Write a precise next-step line to <serie>/STATE.md (overwrite, ONE-system):

PIVOT logged (<reason>, +<deltaPct>%, <newSections> new sections) →
currentPhase reset to <toPhase>. Resume /linkedin:newsletter; it will re-run
fact-check (5) → editorial (5.5) → persona (6) → headless (6.5) on the pivoted
version BEFORE lock. Headless package: /linkedin:headless-review --article NN.

Do not run the gates yourself — /linkedin:newsletter owns the pipeline and will resume deterministically from the reset currentPhase and re-run every gate in gatesToRerun before it permits lock.

Pivot logged.
- Article NN: <reason>
- Scope: <structural|moderate>  (Δ <deltaPct>%, <newSections> new sections)
- currentPhase: <fromPhase> → <toPhase>   locked: <true→false | unchanged>
- Gates to re-run before lock: fact-check (5) · editorial (5.5) · persona (6) · headless (6.5)
Next: resume /linkedin:newsletter (re-runs the gates) → then lock.

Reference Files

• ${CLAUDE_PLUGIN_ROOT}/commands/newsletter.md — the pipeline this re-opens; Step 8 lock-precondition runs the same heuristic; the resumption table replays from the reset currentPhase
• ${CLAUDE_PLUGIN_ROOT}/commands/headless-review.md — the cold review package that must re-pass on the pivoted version
• ${CLAUDE_PLUGIN_ROOT}/config/edition-state.template.json — articles.NN.pivots schema + the heuristic notes