/flow-next-memory-migrate

name: flow-next-memory-migrate
description: Migrate legacy flat memory files (`.flow/memory/pitfalls.md`, `conventions.md`, `decisions.md`) into the categorized YAML schema. Triggers on /flow-next:memory-migrate, "migrate memory", "convert legacy memory", "lift pitfalls into categorized schema", "convert old memory format". Optional `mode:autofix` token in arguments runs without questions and accepts mechanical defaults for ambiguous classifications. Optional scope hint after the mode token narrows the migration to a specific legacy file (e.g. `pitfalls.md`).
user-invocable: false
allowed-tools: AskUserQuestion, Read, Bash, Grep, Glob, Write, Edit, Task

/flow-next:memory-migrate — agent-native legacy migration

Older flow-next versions stored memory as three flat markdown files: `.flow/memory/pitfalls.md`, `conventions.md`, `decisions.md`. Each was a sequence of `---`-delimited segments with ad-hoc headings and no schema. The categorized schema (track / category / module / tags / status frontmatter, one entry per file). Existing flat files persisted but became invisible to `memory list`, `memory search`, and `flow-next-audit` because there's no frontmatter to scope or stale-flag.

This skill IS the migration. The host agent (Claude Code / Codex / Droid) reads each legacy entry, applies the mechanical default `(track, category)` from the source filename, overrides only when the entry's content warrants, and writes a categorized entry via `flowctl memory add`. Optional autofix mode accepts every mechanical default and marks ambiguous entries as `needs-review` in the report.

There is no Python classifier subprocess, no `codex`/`copilot` dispatch, no fast-model probability scoring. The host agent is already an LLM with full repo context and does the work directly. flowctl provides only thin parsing + persistence plumbing (`memory list-legacy --json`, existing `memory add`).

**Read [workflow.md](workflow.md) for the full phase-by-phase execution. Read [phases.md](phases.md) for the (track, category) decision tree with mechanical baseline + override examples.**

Preamble

**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks (here and in `workflow.md`) use `$FLOWCTL`:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

**Inline skill (no `context: fork`)** — `AskUserQuestion` must stay reachable across phases. Subagents can't call blocking question tools (Claude Code issues #12890, #34592). Phase 1 (Classify) needs user choice on ambiguous entries in interactive mode; Phase 4 (Cleanup) needs consent before renaming originals. (sync-codex.sh rewrites this to a plain-text numbered prompt in the Codex mirror.)

Mode Detection

Parse `$ARGUMENTS` for the literal token `mode:autofix`. If present, strip it from the arguments — the remainder is the scope hint (a legacy filename like `pitfalls.md` to narrow the run, or empty to migrate all).

RAW_ARGS="$ARGUMENTS"
MODE="interactive"
if [[ "$RAW_ARGS" == *"mode:autofix"* ]]; then
  MODE="autofix"
  # Strip token, collapse whitespace, trim.
  SCOPE_HINT=$(printf "%s" "$RAW_ARGS" | sed 's/mode:autofix//' | tr -s ' ' | sed 's/^ //;s/ $//')
else
  SCOPE_HINT="$RAW_ARGS"
fi

| Mode | When | Behavior | |------|------|----------| | **Interactive** (default) | User is at the terminal | Ask via blocking-question tool when an entry's content suggests overriding the mechanical default; confirm Phase 4 cleanup; show triage summary before writes | | **Autofix** (`mode:autofix` in arguments) | Ralph or batch usage | No user questions. Apply mechanical defaults for every entry. Override only when the agent has high-confidence evidence from the entry body. Mark genuinely ambiguous entries as `needs-review` in the report. Default-decline Phase 4 cleanup. Print full report |

Autofix mode rules

• **No user questions.** Never call the blocking-question tool.
• **Process every legacy entry in scope.** No scope-narrowing question. If no scope hint was provided, migrate all three legacy files.
• **Mechanical default wins on borderline.** Override only when the entry body unambiguously points at a different `(track, category)` (e.g. an entry titled "race condition in worker pool" inside `pitfalls.md` clearly warrants `bug/runtime-errors` over the mechanical `bug/build-errors`).
• **Ambiguous → mechanical default + log as `needs-review`.** Genuine "could be A or B" cases take the mechanical default and surface in the report so the user can re-classify later.
• **Default-decline Phase 4 cleanup.** Originals stay in place. Surface the rename suggestion as a recommendation in the report.
• **Always print the full report.** The report is the sole deliverable — there is no user to ask follow-ups.

Interaction Principles (interactive mode only)

In autofix mode, skip user questions entirely and apply the rules above.

In interactive mode, follow these principles:

• Ask **one question at a time** via `AskUserQuestion` (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded). Fall back to numbered options in plain text only if the tool is unreachable or errors. Never silently skip the question.
• Prefer **multiple choice** when natural options exist.
• Lead with the **recommended option** (always the mechanical default unless the body warrants otherwise) and a one-sentence rationale.
• Do **not** ask the user to make decisions before the entry has been read — Phase 1 reads first, asks second.
• Group obvious mechanical-default migrations together for batched confirmation. Present overrides and ambiguous cases one at a time.

The goal is