@kentcdodds/friction-log

@kentcdodds/friction-log

Intent

Capture durable friction — recurring, clear-owner, reproducible contract gaps — and route each papercut to the right place:

• host: 'github' → GitHub issue labeled friction on the caller’s owner/repo (dedupe/reuse by title). Use repo: 'kody-hq/kody' when the platform repo is the intended target.
• host: 'kody' → wake Patch for that Kody package (no GitHub issue).

Separately, every day at 5am America/Denver the package lists open kody-hq/kody friction issues and may spawn one Cursor Cloud Agent when any are eligible.

Success for the daily hunt: an already-fixed or invalid issue is closed. An obvious low-or-medium-risk fix ships via the repo's /ship-pr skill. Anything else gets a recommended-fix comment plus the friction-skipped label, and stays skipped until that label is removed.

What it does

• Qualify — soft gates before create/file so one-off session confusion and “how do I use this once” reports get a clear skip path (principles, not a title deny-list)
• Create — require target: { host, repo }; GitHub file/reuse or Patch wake
• File — batch with one top-level target applied to all items; returns filed / reused / woke / skipped (dryRun supported)
• Scan — read-only eligibility scan of the platform friction queue (never spawns)
• Sweep — list open platform friction issues; spawn one Cloud Agent when eligible (dryRun: true previews without spawning)
• Daily job — 5am America/Denver wrapper used by the scheduler
• Pause / resume — kill switch for automatic spawns
• Status — operator snapshot
• Record-outcome — final report from the friction-log Cloud Agent

Qualification bar (soft skip)

Skip (do not throw) when any of: missing/invalid target; structured filing missing preliminaryInvestigation (and no body); missing reproducible gap (no howToReproduce, no body, structured fields too thin); looks transient/session-bound (heuristic: no howToReproduce, empty cost, short whatHappened); GitHub title empty after Friction: normalize. Prefer durable, recurring, clear owner, reproducible contract/API/docs gap.

Every structured papercut should carry a short preliminary investigation: what was already looked at, plus relevantFiles when any paths look relevant. Do not invent a root cause. Do not require a file list when none is known. Keep it short — not a second copy of a full issue thread. A raw body may include the same section inline.

Eligibility for the daily sweep remains rule-based (open friction without friction-skipped). At most one automatic Cloud Agent per Denver calendar day.

Prerequisites / setup

1. Depends on @kentcdodds/github (default bot account → secret github-botAccessToken), @kentcdodds/cursor (secret cursorApiKey), and @kentcdodds/grok-bot (Patch wake). Approve host/package access if prompted.
2. Keep the package daily job enabled unless you intentionally pause with ./pause. Do not disable live webhooks/jobs casually.
3. Agents must pass an explicit target on ./create / ./file — no silent default host, no aliases. Prefer those exports over gh so GitHub issues get the friction label.
4. Agents: see AGENTS.md for import paths and dry-run smoke.

Done when

• ./status shows enabled: true (or you intentionally paused)
• ./scan / ./sweep({ dryRun: true }) lists eligibility without spawning
• ./create({ dryRun: true, target: { host: 'github', repo: 'kody-hq/kody' }, … }) previews without posting
• A would-skip qualify case returns { ok: true, skipped: true, reason }
• ./create({ dryRun: true, target: { host: 'kody', repo: '@scope/leaf' }, … }) dry-runs Patch wake
• ./file({ dryRun: true, target, items: […] }) previews a batch
• Live daily sweep spawns at most one agent per Denver day when eligible