| name | migrate-research |
| description | Autonomous research loop for Citum migration fidelity gaps and converter-focused Rust fixes. |
Migrate Research
Use this skill when multiple styles share a migration failure pattern or when a rich
input pass needs classification before changing citum_migrate.
Read first:
docs/policies/STYLE_WORKFLOW_DECISION_RULES.md
docs/guides/STYLE_WORKFLOW_EXECUTION.md
docs/specs/MIGRATE_RESEARCH_RICH_INPUTS.md
docs/guides/AGENT_SKILLS.md
docs/guides/JJ_AI_CHANGE_STACK.md when .jj is present and the research
pass needs an isolated local change
Use When
- The goal is converter improvement, not a style YAML patch.
- Several styles fail for the same reason.
- You need bounded evidence before deciding whether to fix migration, style, processor,
or adjudication.
Operating Rules
- Start with the smallest trustworthy evidence surface.
- State the target semantic class and implementation form before proposing a fix.
- Classify each cluster as
migration-artifact, style-defect, processor-defect,
or intentional divergence. For type- or field-population-shaped clusters,
run the conversion-layer pre-flight from the shared decision rules
(docs/policies/STYLE_WORKFLOW_DECISION_RULES.md) before classifying.
- Record the selected parent style when the target is a known wrapper.
- Preserve the config-wrapper contract for
profile + config-wrapper targets.
- Treat
journal + structural-wrapper as a valid endpoint; do not force thin-wrapper reduction.
- If a migration-side fix would require local templates or local
type-variants in a profile,
stop and reroute or escalate instead of breaking the profile contract.
- Stop when the cluster is clearly out of scope or converged.
- Keep the loop bounded to one cluster per pass.
Output
Report the chosen cluster, semantic class, implementation form, selected parent if any,
classification, before/after evidence, exact change made if any, and whether the pass
should continue, stop, or escalate.
Self-Improvement
When you reach a dead end not covered by the operating rules — a cluster pattern that
doesn't fit the four classifications, a stop condition missing from the guides, or a
migration artifact the evidence ladder doesn't anticipate — record the insight as a
concrete bullet here and include the file update in the same commit or PR. Future
research passes start with a richer surface.
- (2026-06-10) Corpus-level cluster selection: before opening a pass, run
node scripts/report-migrate-sqi.js --corpus random --seed 20260610 and pick
the cluster by reach from its fidelity headline + failure taxonomy, not from
the curated lab corpus alone. The random baseline and current cluster table
live in docs/architecture/audits/2026-06-10_MIGRATE_RANDOM_SAMPLE_BASELINE.md.
- (2026-06-10) A processor hard-fail on migrated output (e.g. a
type-variants
op matching no component) is always migration-artifact with an emit-time
validation fix in citum-migrate plus a regression test — the converter must
never emit YAML the processor rejects. No evidence ladder needed.
- (2026-06-10) Note-class run-on output (delimiters/affixes lost wholesale in
full-note citation templates) is one systemic cluster, not per-style defects;
do not open per-style passes for it.