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

---
type: trekbrief
brief_version: "2.1"
created: 2026-05-31
task: "Command hardening pass — simulate every linkedin-studio command and harden it to its stated intention (intention-fidelity + prompt-quality), one command at a time, across ~8 journey-grouped sessions, before the GUI/M0 track"
slug: hardening
project_dir: docs/hardening/
research_topics: 0
research_status: skipped
auto_research: false
interview_turns: 1
source: interview
phase_signals:
  - phase: plan
    effort: high
    model: opus
  - phase: execute
    effort: high
    model: opus
  - phase: review
    effort: high
    model: opus
---

# Task: linkedin-studio command hardening

> Generated 2026-05-31 (operator-driven, one clarification turn — three forks
> locked via AskUserQuestion). This brief is the contract between requirements and
> planning. `/trekplan` reads it to produce the multi-session plan. Every decision
> in the plan must trace back to content here.
>
> **Predecessor of record:** the baseline-audit remediation (`docs/remediation/`)
> is **complete** (S1–S17, last commit `2633d32`, clean ALLOW). That phase fixed
> *structure, correctness, and honesty*. This phase is the next, distinct layer:
> does each command actually **deliver what it promises** when run?

## Intent

The remediation made every claim honest, wired every orphan agent, rebuilt the
lint, and reconciled the algorithm bar. What it did **not** do is exercise each
command's *workflow* end-to-end and judge the **quality of what it produces**
against the command's own stated intention. A command can be structurally correct
(right frontmatter, right agent wired, lint-green) and still under-deliver: a step
that under-determines the next move, a question that yields a weak answer, a prompt
that produces generic output, a missing graceful-degradation path.

This is a **hardening phase**: a deliberate, per-command pass that simulates a
realistic invocation, judges the result against intention + the 2026 algorithm
bar + the content-quality rules, and tightens the command definition where it
falls short. It is the last quality gate **before** the GUI/M0 track (the two
briefs `docs/linkedin-studio-ui-brief.md` + `docs/linkedin-studio-persona-brief.md`)
— hardening the engine before building a dashboard on top of it.

**Division of labour (explicit):** the operator tests the commands **live** over
the coming weeks (real inputs, real friction). This phase is the **complementary**
intention-fidelity pass from the definition side. The two converge through a
field-notes inbox (below): the operator's real-world findings outrank the
simulated ones and steer per-session priority.

## Goal

For every one of the 29 command surfaces, produce: (1) a recorded **intention**,
(2) a **simulated** run with a concrete persona, (3) an **evaluation** against four
axes, (4) a **hardened** command definition where gaps were found, (5) a green
**verification**. Leave the command set structurally identical (29/19/25/6) and the
plugin in a state where each command reliably delivers its description's promise.

## Non-Goals

- **No structural redesign.** No command merged, split, added, or removed; no new
  command; no journey re-tiering. 14a already proved zero redundancy; the surface
  count (29) and journey layer (v4.1.0) are fixed. *(Locked fork: "intention-fidelity
  + prompt-quality", not "structural".)*
- **No new features / capability accretion.** Hardening tightens existing
  intention; it does not add surfaces the audit/remediation deliberately scoped out
  (no auto-publish, no dwell measurement, no analytics-API integration, no new agents).
- **No GUI/M0 work.** The dashboard, the per-user data-dir migration (M0), and the
  provider register are the *next* track and require their own mandate + brief. This
  phase only hardens the command engine they will sit on.
- **No re-litigation of the algorithm bar.** `references/algorithm-signals-reference.md`
  is the single source of truth (settled in remediation). Hardening *applies* it; it
  does not re-research or re-open it. No `/trekresearch` is run.
- **No version/count churn per session.** Prompt/spec refinement is not a surface
  change; sessions do not bump the version or touch counts (S11–S16 refinement
  precedent). A single optional minor bump (v4.2.0 "command hardening pass") may be
  taken at phase end.

## Constraints

- **Opus on everything** (sub-agents + orchestration). Max-discipline default.
- **No hidden costs.** `/trekplan`, `/trekcontinue`, `/trekreview` and any Workflow
  fan-out are cost-warned in plain text before running; the operator's standing yes
  (2026-05-30) covers the routine `/trekcontinue`·`/trekreview` gate — run, don't block.
- **Gate before push (no WARN-override):** per session, `bash scripts/test-runner.sh`
  exit 0 + `node --test` green where touched + `/trekreview` **ALLOW** → commit (own
  files only, explicit staging, never `git add -u/-A`) → push to Forgejo. In-session
  fix of the session's *own* misses = completion; genuine pre-existing design findings
  → next session.
- **Three-doc rule** applies only if a hardening edit changes a feature/surface/count/
  version (most will not — they refine prompt text). Pure prompt-quality edits are
  `fix:`/`refactor:` and do not trigger the feat-gate.
- **Platform:** bash 3.2, Node-only hooks, no npm deps in hooks/scanners.
- **Untracked NOT-mine (never commit):** `docs/linkedin-studio-persona-brief.md`,
  `docs/linkedin-studio-ui-brief.md`, `docs/voyage-build/progress.json`. `*.local.md`
  + `.session-state.local.json` + `review.html` + STATE.md are gitignored.

## Preferences

- **Simulation = hybrid (locked fork).** Per command: role-play a realistic
  invocation (concrete persona + scenario, mock answers), produce/sketch the actual
  output the command would generate, **and** cold-read the spec against intention.
  Harden from both signals — catches "spec is broken" *and* "output is mediocre".
- **Personas:** drawn from the plugin's real ICP and state — a solo Norwegian/English
  AI-advisor creator (the author's own profile: ~1048 followers, "Validation" phase,
  5 expertise pillars), plus at least one **fresh adopter** (no voice samples, no
  analytics yet) to exercise progressive-onboarding + graceful-degradation paths. The
  `persona-brief` may be consulted (read-only) for richer personas; it is optional, not
  a hard dependency.
- **Session granularity (locked fork):** one journey per session where small
  (Start/Engage/Measure/Grow); split **Create** (8 commands incl. the 16-phase
  `newsletter`) across 2–3 sessions. ~8 sessions total.
- **Field-notes inbox:** before hardening a journey, check
  `docs/hardening/field-notes.local.md` for the operator's live-test findings on those
  commands and let them steer priority; the operator's real friction outranks the
  simulated friction.
- **Per-command log:** record intention → simulation (inputs + output sketch +
  friction) → evaluation (4 axes) → harden diff → verify, in `docs/hardening/log.md`,
  so the operator's parallel live-testing can cross-reference every change and its why.

## Non-Functional Requirements

- **No regression.** After each session: lint exits 0 with **unchanged counts**
  (Commands 29 · Agents 19 · Reference docs 25 · Skills 6); hooks `node --test` 98/98
  and analytics 116/116 stay green if those surfaces are touched; cross-references
  (router ↔ commands ↔ agents ↔ skills) stay consistent.
- **Determinism.** Every success criterion is falsifiable by a command or a recorded
  observation; the hardening log is the audit trail.
- **Independence.** The per-session `/trekreview` runs cold (independent reviewers),
  same as the remediation gate.

## Success Criteria

*Falsifiable per command and per phase.*

**Per command (the hardening unit):**
- **SC-A (intention recorded):** `docs/hardening/log.md` has, for the command, a
  one-paragraph intention distilled from its frontmatter `description` + journey role
  + the content-quality rules + the algorithm signals it must honor.
- **SC-B (simulated):** a concrete persona + scenario, the mock inputs, and the
  produced/sketched output are recorded, with a friction log of every ambiguity,
  dead-end, or under-determined step encountered walking the workflow as written.
- **SC-C (evaluated on 4 axes):** the simulated output + spec carry an explicit
  pass/gap verdict against (a) **intention fidelity** (does it deliver the
  description's promise?), (b) **algorithm bar** (`algorithm-signals-reference.md`),
  (c) **content-quality rules** (hook 110-140, length bands, no body links, no
  buzzwords, topic-relevance, topic-rotation), (d) **agent-wiring + graceful
  degradation** (right `subagent_type`; sensible fallback when an agent/tool/mcp/CLI
  is unavailable).
- **SC-D (hardened or deferred):** every gap is either fixed (diff recorded in the
  log) or explicitly deferred with a rationale — **no gap left unrecorded**.
- **SC-E (verified):** after hardening, `test-runner.sh` exits 0 with unchanged
  counts, `node --test` is green where touched, and a re-read/re-simulation confirms
  the previously-failing axis now passes.

**Per phase:**
- **SC-F (coverage):** all 29 command surfaces (27 atomic + the 2 front-doors
  `create`/`measure`) have a complete `log.md` entry through SC-A…SC-E.
- **SC-G (no structural drift):** `ls commands/*.md | wc -l` == 29 throughout; no
  merge/split/add/remove; the lint's count/version guards stay green; `grep` for any
  stale count returns 0.
- **SC-H (clean gate):** every session was pushed on `/trekreview` **ALLOW** (no
  WARN-override); the per-session `review.md` shows 0 open findings.
- **SC-I (operator findings honored):** where `field-notes.local.md` carries a live
  finding for a session's commands, it is addressed or explicitly triaged in that
  session's log.

## Hardening method (the per-command contract `/trekplan` must encode)

```
1. INTENT     distil the command's promise (description + journey role + quality
              rules + algorithm signals it must honor) → one paragraph
2. SIMULATE   pick a realistic persona + scenario; walk the workflow exactly as
              written; answer its questions; produce/sketch the real output; log
              every friction / ambiguity / dead-end / under-determined step
3. EVALUATE   judge output + spec on 4 axes: intention · algorithm bar · quality
              rules · agent-wiring + graceful degradation → pass/gap per axis
4. HARDEN     edit the command .md (surgical; agent/reference only if the intention
              requires it): fix dead-ends/contradictions/wrong-wiring + strengthen
              prompts/questions/steps so output hits the bar. NO structural redesign.
5. VERIFY     lint exit 0 + counts unchanged + node --test green where touched +
              re-simulation passes the failing axis; record before/after in log.md
```

## Proposed session decomposition (to be confirmed/refined by `/trekplan`)

| Session | Scope | Notes |
|---|---|---|
| **S1** | **Method calibration** on one command (`quick` — simplest, highest-volume) → show output + harden diff → lock the method. Then **Start**: `onboarding`, `first-post`, `setup` | de-risks the method before scaling |
| **S2** | **Create I** (atomic short-form): `post`, `react` (+ `quick` if not finished in S1) | |
| **S3** | **Create II** (visual/video): `carousel`, `video`, `multiplatform` | mcp-image / aspect-ratio / SRT graceful degradation in focus |
| **S4** | **Create III**: `batch`, `newsletter` | newsletter = orchestration only (16-phase; gate-agents already reviewed in remediation); may spill into its own session |
| **S5** | **Engage**: `firsthour`, `calendar`, `pipeline` | state-mutation + publish + first-hour plan paths |
| **S6** | **Measure**: `import`, `report`, `analyze`, `audit`, `ab-test` | analytics CLI graceful degradation + directional A/B framing |
| **S7** | **Grow**: `strategy`, `competitive`, `monetize`, `outreach`, `profile` | ~1K soft-gating + tracked-pipeline + SEO paths |
| **S8** | **Front-doors + router**: `create`, `measure`, `linkedin` | delegation/routing surfaces — verify they route correctly to the now-hardened commands |

## Research Plan

**None.** `/trekresearch` is deliberately skipped. The external 2026 bar
(algorithm signals, analytics/publish boundaries, coverage-gap specs) was fully
researched and triangulated in the remediation phase and is frozen in
`references/algorithm-signals-reference.md` (the single source of truth) +
`docs/remediation/research/01-03`. Hardening is an **internal intention-fidelity**
exercise: it *applies* that established bar, it does not extend it. If a simulation
surfaces a genuinely new external question, it is logged as an Open Question for the
operator — not researched mid-phase.

## Open Questions / Assumptions

- **[ASSUMPTION]** `/trekplan` orders work as the 8 sessions above, one (or part of a)
  journey per Voyage session, with `/trekreview` as the per-session release gate.
- **[ASSUMPTION]** `quick` is the S1 calibration command (operator did not object;
  overridable next session).
- **[ASSUMPTION]** No `/trekresearch` (operator proposed-and-agreed to skip — the
  bar is settled).
- **[ASSUMPTION]** Version stays v4.1.0 through the phase; an optional v4.2.0
  "command hardening pass" minor bump is a phase-end decision, not pre-committed.
- **[OPEN]** Whether `newsletter` (16-phase) needs its own dedicated session — decide
  during S4 once its orchestration simulation is scoped.
- **[OPEN]** Whether the operator wants the simulated outputs themselves preserved
  (full text) in the log, or only the friction/verdict summary (token cost vs.
  reviewability trade-off) — default: summary + output sketch, full output only when
  it's the evidence for a gap.

## Prior Attempts

The baseline-audit remediation (`docs/remediation/`, S1–S17, complete 2026-05-31,
commit `2633d32`) is the immediate predecessor. It closed every still-real audit
finding (correctness, honesty, orphan-agent wiring, dead lint, generalization) and
its S17 triage confirmed 0 still-real findings remain. No command has yet been
exercised end-to-end for **output quality against intention** — that gap is exactly
what this phase fills. The plugin is at v4.1.0, 29 commands / 19 agents, stable.

## Metadata

- **Created:** 2026-05-31
- **Interview turns:** 1 (three forks locked: simulation depth = hybrid; change
  appetite = intention-fidelity + prompt-quality; cadence = per-journey, large groups split)
- **Auto-research opted in:** no (bar already settled in remediation)
- **Source:** operator-driven foundation session; execution begins next session

---

## How to continue

```bash
# Plan (this session — lays the foundation):
/trekplan --project docs/hardening/

# Then, from next session onward, one journey-group per session:
/trekcontinue --project docs/hardening/     # S1: method calibration (quick) + Start
# … gate each: test-runner.sh + node --test + /trekreview ALLOW → commit (own files) → push
```

Driven per the operating model: the operator types **«Les STATE.md og følg
instruksjonene.»**; Claude invokes the `/trek*` skills itself. STATE.md points at the
next session; this brief is the contract `/trekplan` consumes now.