dotfiles/dot_claude/commands/cmem-to-linear.md

---
description: Extract actionable learnings from claude-mem into beads tasks and push them up to Linear for PM
---

# Sync claude-mem actionable learnings → beads → Linear

<!--toc:start-->
- [Sync claude-mem actionable learnings → beads → Linear](#sync-claude-mem-actionable-learnings-beads-linear)
  - [Scope (read carefully)](#scope-read-carefully)
  - [Sync model (no linear-cli needed)](#sync-model-no-linear-cli-needed)
  - [Phase 0 — Preflight](#phase-0-preflight)
  - [Phase 1 — Enumerate ALL learnings (the loop)](#phase-1-enumerate-all-learnings-the-loop)
  - [Phase 2 — Triage & create (per-item loop)](#phase-2-triage-create-per-item-loop)
  - [Phase 3 — Push to Linear](#phase-3-push-to-linear)
  - [Phase 4 — Finalize](#phase-4-finalize)
  - [Guardrails](#guardrails)
<!--toc:end-->

You are turning **actionable learnings** from **claude-mem** (the session memory store)
into **beads** (`bd`) tasks, then pushing the new ones up to **Linear** for PM. Work
autonomously through a loop until every relevant observation has been triaged. Do not
invent learnings — only persist what claude-mem actually returns.

## Scope (read carefully)

- **Record ONLY actionable learnings** — things to *do*: unfixed bugs, tech debt,
  follow-ups, TODOs, missing tests, planned refactors. Each becomes a `bd create` task.
- **Ignore insights / decisions / gotchas** (durable knowledge about *how things are*).
  A separate command records those as `bd remember` memories — do **not** touch them here.
  Leave them in claude-mem untouched.
- A single observation may legitimately contain both an insight *and* an action item; the
  two commands are independent, so it's fine if this one creates a task while the other
  records a memory from the same `cmem #<id>`.

## Sync model (no linear-cli needed)

Beads-first, push up, bidirectional thereafter:
1. Create tasks in beads (`bd create`).
2. Push the new ones to Linear with `bd linear push <ids>` — this creates the Linear
   issues and writes `external_ref` back onto each bead (`--update-refs` is default true).
3. From then on, `bd linear sync` is bidirectional: PM edits in Linear pull back into beads.

`linear-cli` is **not** used. All Linear interaction goes through native `bd linear`.

---

## Phase 0 — Preflight

1. Confirm beads is live: `bd ready` (and `bd doctor` if it errors).
2. Confirm Linear is wired up: `bd linear status`. If it errors / unconfigured, stop and
   tell the user to set `linear.api_key` + team (`bd linear teams` to find the team UUID).
   Note whether **multiple teams** are configured (`linear.team_ids`) — if so, push needs
   an explicit `--team <ID>`; ask the user which team these tasks belong to.
3. Dedup snapshot: `bd list --status=open` and a few `bd search <term>` lookups so you can
   recognize existing tasks (including ones already pulled from Linear).
4. Local progress file for resumability — NOT a beads issue:
   ```
   ./.claude-mem-sync/processed-actions.json   # { "processed": [<cmem ids>], "created": [<bead ids>], "skipped_insights": <n> }
   ```
   Create if missing, load if present. Ensure `.claude-mem-sync/` is in `.gitignore`.

---

## Phase 1 — Enumerate ALL learnings (the loop)

claude-mem search is query-based, so one call won't surface everything. Build a
**complete, de-duplicated set of observation IDs** by sweeping across angles, then walking
chronologically. Track seen IDs in a set; never process the same ID twice.

Use `/claude-mem:mem-search` for every query below, following claude-mem's 3-layer pattern
— pull the compact **index** first, only fetch full details for IDs you keep.

**1a. Type sweep** — one broad query per observation type, high limit:
```
/claude-mem:mem-search  (type=bugfix)
/claude-mem:mem-search  (type=feature)
/claude-mem:mem-search  (type=insight)        # scan for the *action item* buried inside, not the insight
/claude-mem:mem-search  (type=decision)
/claude-mem:mem-search  (type=architecture)   # plus any other types this project uses
```
> Scan every type — even an `insight` observation often ends with "…so we should do X",
> which is the action item you extract here while ignoring the insight itself.

**1b. Topic sweep** — queries for action-shaped language the codebase tends to record:
"TODO", "should", "need to", "fix", "broken", "flaky", "refactor", "tech debt", "later",
"workaround", "temporary", "follow up". Each adds new IDs to the set.

**1c. Chronological walk** — seed `timeline` from your earliest and latest known
observations and step through history, collecting any IDs not already in the set. Stop when
the timeline yields no new IDs in either direction.

Result: a deduplicated list of candidate observation IDs. Print the count.

---

## Phase 2 — Triage & create (per-item loop)

Process candidate IDs in batches. For each batch:

1. **Fetch details** once: `get_observations(ids=[...])` (batch IDs — never one-at-a-time).
2. For **each** observation, classify:

   - **Insight / decision / gotcha** (knowledge, nothing to *do*) → **IGNORE**. Increment
     `skipped_insights` and move on. It's the other command's job.

   - **Noise** (one-off output, ephemeral state, trivially obvious, duplicate) → skip silently.

   - **Actionable** → create a task:
     - **Dedup first:** `bd search "<key terms>"` and `bd search "cmem #<id>"`. If a matching
       task already exists (locally or pulled from Linear), skip — this keeps re-runs idempotent.
     - Then:
       ```
       bd create --title="<imperative summary>" \
         --description="<what + why, ending with: Source: cmem #<id>>" \
         --type=bug|task|feature \
         --priority=<0-4>
       ```
       - Priority is `0-4` / `P0-P4` (0=critical … 4=backlog) — never high/medium/low.
         bd maps this to Linear priority on push.
       - Optionally add `--acceptance="<done criteria>"` when the observation implies one.
       - If two items depend on each other: `bd dep add <issue> <depends-on>`.
     - Record the new bead id and the `cmem #<id>` in the progress file.

Repeat until the candidate set is exhausted.

---

## Phase 3 — Push to Linear

1. Review what's queued: `bd linear status` (shows issues pending push, i.e. no external_ref).
2. Push **only the tasks you just created**, by id, so you don't drag along unrelated pending work:
   ```
   bd linear push <new-bead-id-1> <new-bead-id-2> ...
   ```
   - Add `--team <ID>` if multiple teams are configured (from Phase 0).
   - Run `--dry-run` first if the user wants a preview.
   - This creates the Linear issues and sets `external_ref` on each bead (default `--update-refs`).
   - Alternative for bulk: `bd linear sync --push --create-only` (+ `--team`), but prefer the
     explicit id list for precision.
3. Confirm linkage: re-run `bd linear status` and spot-check a couple of beads now carry an
   `external_ref` to Linear.

> Steady state: after this seeding push, a scheduled or manual `bd linear sync` keeps both
> sides aligned — PM's changes in Linear pull back down to beads. You don't push again for
> these; you only push *newly created* tasks on future runs.

---

## Phase 4 — Finalize

1. Sync beads to its Dolt remote: `bd dolt push`.
2. **Session close protocol** — if any code/files changed (e.g. `.gitignore`):
   ```
   git status
   git add <files>
   git commit -m "chore: extract claude-mem action items into beads + Linear"
   git push
   ```

---

## Guardrails

- **Actionable only.** Never `bd remember` here. Insights are ignored and left in claude-mem
  for the insights command.
- **No linear-cli.** All Linear interaction is native `bd linear`.
- **Idempotent.** Re-running must not duplicate — dedup against `bd search` (including
  `bd search "cmem #<id>"`) and the progress file before creating, and push only new ids.
- **Cite the source.** Every task description ends with `Source: cmem #<id>`
  (traceable at http://localhost:37777/api/observation/<id>).
- **No `bd edit`** — it opens an editor and blocks. Use inline `--` flags on create/update.
- **Multiple teams → explicit `--team`** on push; ask the user if ambiguous.
- **Don't fabricate** — if a sweep returns nothing, say so and move on.
- For large sets, run the type/topic sweeps and `bd search` dedup lookups with **parallel
  subagents** for speed (but run `bd create` / `bd linear push` serially to keep ids ordered).

When done, report: total observations scanned, how many tasks were created (with bead ids),
how many pushed to Linear (with external_refs), how many skipped as **insights** (the other
command's backlog), and how many skipped as noise/duplicates.