linkedin-studio/docs/research-engine/brief-re-r3f.md

# Brief — RE-R3f: unattended AI discovery (`--headless`, slice e)

> **Slice:** RE-R3f (research-engine rung-2, R3 slice **(e)** in the operator's `(a)→(c)→(b)→(d)→(e)`
> sequence — the doc is numbered r3f by creation order, the concept is slice (e)). Closes the
> production gap named in `docs/research-engine-concepts.local.md` §5: RE-R3c/RE-R3e built a
> **deterministic** headless entry (`schedule`/`run-daily.sh`) that re-renders the brief on a
> schedule with no new discovery — a near-no-op without a prior human-run poll. RE-R3f makes the
> **actual discovery pass** — `/linkedin:trends`'s poll → score → capture → brief loop, including
> the `trend-spotter` agent's web research — safe to fire with no operator present.
> **Origin:** Maskinrommet production feedback, register row **MR-F5** — Sunday-morning discovery
> needs to run without the operator present. Elicited via `CLAUDE.local.md`'s feedback-intake
> protocol; validated against live plugin structure before any code/prose was touched.
> **The gate this slice opens:** `docs/research-engine-concepts.local.md` §5 recorded a 2026-06-24
> operator decision that slice (e) sits behind an **explicit re-evaluation gate against product
> maturity (v1.0.0)** — research is "rung-2." The plugin is at v0.8.0 (CLAUDE.md header); the gate
> had not been re-evaluated. Surfaced to the operator 2026-08-10 as a real conflict, not silently
> built around or silently deferred; the operator opened the gate explicitly (AskUserQuestion,
> "Open the gate now") after seeing the trade-off stated plainly.
> **Architectural decision — CONFIRMED (operator, AskUserQuestion 2026-08-10):** Desktop Scheduled
> Tasks (Claude Code's own first-party local scheduler) is the trigger mechanism, **not** a
> hand-rolled cron/launchd wrapper mirroring RE-R3c. A `-p`-mode `claude` invocation cannot be
> replicated by a shell script (it needs a full agent turn, incl. the `trend-spotter` subagent), and
> Claude Code's own headless docs state a hand-rolled `cron` + `claude -p` wrapper loses
> observability/session-resumption/error-recovery relative to the first-party mechanism. The recipe
> for the fallback (hand-rolled `claude -p`) path is documented for portability, but not built as
> repo code.

## 1. The gap — grounded in code and docs

- **`run-daily.sh` (RE-R3c) is deterministic-only by design** (`run-daily.sh:1-8`, `docs/
  research-engine/brief-re-r3c.md` C1): it re-renders the brief from the **current** store — no
  poll, no capture. Its own comment names the gap: *"The (e) slice will insert a pre-brief AI
  capture step here … before the `brief` call below."* Nothing has inserted it.
- **The attended pass blocks on operator input in two places.** `commands/trends.md` Step 1 asks
  the user for pillars when `${DATA}/profile/user-profile.md` is missing; Step 5 (Triage) calls
  `AskUserQuestion` up to 4× per batch. Fired unattended, either would hang or (in Claude Code's
  `dontAsk` permission mode, the correct mode for an unattended run) abort the run — `AskUserQuestion`
  is auto-denied unconditionally in that mode regardless of any `--allowedTools` entry (verified
  against Claude Code's `permission-modes` docs, 2026-08-10).
- **No documented recipe for firing a plugin command unattended existed in this repo.** RE-R3c's
  `schedule` CLI verb only ever targets the deterministic `brief` subcommand
  (`run-daily.sh:33`, `cli.ts` `schedule` branch) — it has no path to a full `claude` agent turn.
- **Exit-code trust was unstated.** Claude Code's headless docs are explicit that a `-p` run's
  process exit code reflects the CLI process, not the pass's semantic outcome (a tool denial or
  auth failure can still print to stdout without a non-zero exit). No existing doc in this repo
  told a scheduled caller what to check instead.

## 2. Scope — what is IN (RE-R3f)

### `commands/trends.md` (EDIT) — the `--headless` contract

- New flag `--headless`, documented in the Step 0 flags table + a new **Step 0.5** section stating
  the contract explicitly (so it reads as a rule, not something buried three steps down):
  - `--demand --headless` together → refused (one line, exit; never silently falls back to
    supply-side discovery).
  - Step 1 missing profile → print a one-line error and stop; never ask. The source-list fallback
    (shipped defaults) is unaffected — it already needs no operator input.
  - Step 5 (Triage) → skipped unconditionally. Every kept candidate stays `pending`; the next
    attended session (or the next morning brief) surfaces it for a human to resolve.
  - Steps 2–4 and 6 (poll, score, capture, render, `.last-run` marker) run exactly as attended —
    `--headless` changes who can be asked, never what gets persisted.
  - States plainly: ground success in the same artifacts Step 3 already verifies (`CLI status
    --json` capture delta, today's dated brief file) — never in this command's own exit code or
    prose.
- No frontmatter change (`allowed-tools` already lists `AskUserQuestion` for the attended path;
  leaving it is harmless belt-and-suspenders — `dontAsk` mode denies it unconditionally regardless
  of what a command's frontmatter requests).

### `scripts/trends/README.md` (EDIT) — the unattended-discovery section

- A new `## Unattended AI discovery — --headless (RE-R3f, slice e)` section, positioned after the
  existing RE-R3c section, explicit that this is a **different mechanism** (a full agent turn, not
  a bash/cron wrapper): Desktop Scheduled Tasks as the recommended trigger; the verified `claude -p`
  recipe (`--bare --plugin-dir … --permission-mode dontAsk --allowedTools "Read,Bash,Task,WebSearch,
  WebFetch" --output-format json`) as the documented fallback for a machine without Desktop
  Scheduled Tasks; the `ANTHROPIC_API_KEY` requirement under `--bare`; the background-subagent wait
  ceiling (`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, default 10 min) since the research subagent can
  run long; the artifact-grounded success check (never the exit code); the `total_cost_usd` cost
  visibility note from `--output-format json`.

### `CLAUDE.md` (EDIT) — command table

- `/linkedin:trends` row gains a `--headless` mention (one clause, no restructuring).

### `CHANGELOG.md` (EDIT)

- `[Unreleased]` entry: MR-F5 landed, gate opened, scope summary.

### Docs (this file + `plan-re-r3f.md`, NEW, tracked)

## 3. Non-goals — what is OUT (deferred)

- **A hand-rolled cron/launchd wrapper invoking `claude -p`** — OUT as repo code. The recipe is
  documented (README) for portability to a machine without Desktop Scheduled Tasks, but nothing in
  this repo shells out to `claude` itself; Desktop Scheduled Tasks is the built mechanism.
- **`schedule.ts` / `run-daily.sh` changes** — OUT. RE-R3c's deterministic brief-only wrapper is
  untouched and remains valid for a plain "re-render today's brief" use case distinct from
  discovery.
- **A cost cap / per-run candidate ceiling enforced in code** — OUT. `trend-spotter`'s existing
  guidance (Anti-Patterns: "max 2-3 trend posts per week") is advisory prose, not a mechanism;
  enforcing a hard cap on an unattended AI research run is a real design question, deferred rather
  than guessed at under this slice. `total_cost_usd` visibility (README) is the mitigant landed now.
- **`--demand --headless`** — explicitly refused, not built. The demand-sweep's judgment calls are
  a later slice's problem, if ever.
- **A new store field / schema bump** — none. `SCHEMA_VERSION` (4) / `BRIEF_SCHEMA_VERSION` (2)
  untouched — `--headless` changes command-level control flow only.
- **A new agent, a new CLI verb, a new source/test file** — none. RE-R3f is a prompt-contract EDIT
  plus documentation; there is no new TypeScript/bash to unit-test.

## 4. Boundaries / invariants (must hold)

- **`--headless` never changes what gets persisted**, only who can be asked. A headless run and an
  attended run that both clear Step 1 must capture/brief identically (Step 5's skip is the only
  behavioral divergence, and it is additive-safe: `pending` candidates are exactly what an attended
  triage would leave un-triaged if the operator picked "Leave" on all of them).
- **No silent degrade.** `--demand --headless` refuses rather than silently running supply-side
  discovery instead; a missing profile refuses rather than silently scoring against no pillars.
- **Success is artifact-grounded, never prose-grounded** — documented explicitly in both the
  command file and the README, because Claude Code's own docs establish the exit-code trap is real.
- **Domain-general** — no vendor/sector token in any edit (Section 17 de-niche stays green); the
  README's `claude -p` recipe names no user-specific path (the plugin-dir is a placeholder the
  operator fills at their own install).
- **Counts unchanged** — no new command (`/linkedin:trends` gains a flag, not a sibling command),
  no new agent, no new reference file. Recounted live at land.

## 5. Success criteria (verifiable — no test suite; this is a prompt/doc change)

- **SC1** — `commands/trends.md` documents `--headless` in the flags table AND a dedicated Step 0.5
  contract section; `grep -c '\-\-headless' commands/trends.md` ≥ 5 (table + Step 0.5 + the three
  step-level cross-references).
- **SC2** — Step 1's missing-profile branch explicitly forks on `--headless` (fail vs. ask); Step
  2D explicitly refuses `--demand --headless`; Step 5's header states the `--headless` skip
  condition inline (not only in Step 0.5) — each verified by direct read of the edited sections.
- **SC3** — `scripts/trends/README.md` documents the Desktop Scheduled Tasks recommendation, the
  fallback `claude -p` recipe with all four required flags (`--bare`, `--plugin-dir`,
  `--permission-mode dontAsk`, `--allowedTools`), the `ANTHROPIC_API_KEY` requirement, and the
  artifact-grounded success check — each present as literal text, verified by grep.
- **SC4** — `CLAUDE.md`'s `/linkedin:trends` row mentions `--headless`; `CHANGELOG.md` `[Unreleased]`
  names MR-F5.
- **SC5** — Section 17 de-niche guard stays green (no vendor/sector token introduced); command/
  agent/reference counts unchanged (recounted live).
- **SC6 (explicitly NOT claimed)** — an actual unattended end-to-end run. Per the
  `plugin-runtime-is-consumer-side` constraint, a plugin command does not resolve in this dev-repo
  session; the real Sunday-discovery proof happens consumer-side, after the operator updates +
  reloads + configures a Desktop Scheduled Task. This brief does not claim that proof; it claims the
  command-file contract and the documentation are correct and internally consistent.

## 6. Verification

**This session (dev-repo):** direct read-through of every edited section against SC1–SC5;
`bash scripts/test-runner.sh` for regression sanity (RE-R3f touches no source/test file the gate
tracks, so `FAIL=0` and every floor unchanged is the expectation, not a new floor); Section 17
de-niche green; counts recounted live.
**Consumer-side (deferred, not gated on this session):** update + reload the plugin, run
`/linkedin:trends --headless` once attended-but-silent (verify it does not prompt), then configure
a Desktop Scheduled Task and confirm a real unattended Sunday pass produces a capture delta + a
dated brief.

## 7. Open questions for the go-gate

Two decisions are **CONFIRMED** (operator, AskUserQuestion 2026-08-10): the gate is opened now
(production need outweighs waiting for v1.0.0); Desktop Scheduled Tasks is the mechanism, not a
hand-rolled wrapper (with the fallback recipe documented, not built). Residual decisions, baked to
the recommended default — confirm or redirect:
- **D1 — `--headless` default mode is long-form (inherits the command's own default)?** YES (rec).
  Unattended discovery is for the Sunday chronicle/newsletter pipeline per MR-F5's own framing; an
  operator wanting kortform passes `--mode kortform --headless` explicitly. Re-open only if the
  unattended default should differ from the attended default.
- **D2 — no hard cost/candidate cap enforced in code this slice?** YES (rec, per §3 non-goal) — cost
  visibility (`total_cost_usd`) is landed; a cap is a real question deferred rather than guessed.
  Re-open only if a cap should land now.
- **D3 — the fallback `claude -p` recipe is documented but not wrapped in a repo script?** YES
  (rec). Building an unused wrapper for a path the operator isn't using (Desktop Scheduled Tasks
  covers the real machine) would be speculative code. Re-open only if the fallback path is the one
  actually needed.