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

description

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

• Sync claude-mem actionable learnings → beads → Linear
  • Scope (read carefully)
  • Sync model (no linear-cli needed)
  • Phase 0 — Preflight
  • Phase 1 — Enumerate ALL learnings (the loop)
  • Phase 2 — Triage & create (per-item loop)
  • Phase 3 — Push to Linear
  • Phase 4 — Finalize
  • Guardrails

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/).
• 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.