| name | gdd-migrate-context |
| description | Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration. |
| argument-hint | [--dry-run] |
| tools | Read, Write, Bash |
| user-invocable | true |
/gdd:migrate-context
Closes the pre-graph gap: before Phase 52 a project recorded its structured design knowledge as flat
.design/map/*.md mapper notes (token map, component taxonomy, motion map, a11y map, visual-hierarchy
map). Phase 52 introduced the typed DesignContext graph at .design/context-graph.json. This skill
carries a project across that boundary: it reads the old map notes, rebuilds the graph deterministically
from source, validates it, and surfaces anything it could not transform with confidence so a human can
confirm it. It never trusts a low-confidence guess silently.
Contracts: ../../reference/design-context-schema.md (the Node / Edge / Fragment / Graph shapes) and
../../reference/design-context-tag-vocab.md (the controlled tags[] vocabulary).
Invocation
| Command | Behavior |
|---|
/gdd:migrate-context | Run the full migration: read old maps, extract fragments, merge, validate, then report the low-confidence items for review. |
/gdd:migrate-context --dry-run | Preview only. Print the migration plan and what each step would write, change nothing on disk. |
Step 1 - Detect the pre-52 state
Read the project layout before touching anything.
- List
.design/map/*.md. These are the pre-52 mapper notes (for example token-map.md,
component-taxonomy.md, motion-map.md, a11y-map.md, visual-hierarchy.md). If the directory is
absent or empty, there is nothing to migrate: print No .design/map/*.md notes found; nothing to migrate. and stop.
- Check whether
.design/context-graph.json already exists. If it does, this is a re-run: keep the
existing graph as a backup reference and report that the migration will rebuild it. Do not delete it.
- In
--dry-run, print the file list and the planned outputs (.design/fragments/<mapper>.json per
mapper, then .design/context-graph.json) and stop before Step 2.
Step 2 - Rebuild fragments deterministically
The graph topology comes from the source tree, not from prose. Run each deterministic extractor over the
configured source roots (default src/; read source_roots from .design/STATE.md if present). Each
extractor is pure, dependency-free, and prints a schema-valid Fragment to stdout.
mkdir -p .design/fragments
for mapper in tokens components motion a11y visual-hierarchy; do
node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/extract-${mapper}.mjs" src/ \
> ".design/fragments/extract-${mapper}.json"
done
The extractors fill id / type / name / subtype / tags / complexity and every edge they can prove; they
leave each node summary empty for the summary pass. Use the old .design/map/*.md notes as the source
of the human-authored summary text and any tags the extractor could not infer: for each node whose name
matches a map entry, copy that note's one-line description into the node summary and add any vocabulary
tags it implies. This is the only place prose feeds the graph.
Step 3 - Merge into the canonical graph
Merge the fragments into the single graph. The merger dedupes nodes by id, unions tags, prefers a
non-stub summary over the empty stub, and keeps an edge only when both endpoints resolve to a node in some
fragment. Dropped dangling edges are reported on stderr as could-not-fix: lines.
node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/merge-fragments.mjs" \
.design/fragments --out .design/context-graph.json
Capture the stderr could-not-fix: lines. Each one is a transform the merge could not complete (a map
note referenced an entity the extractor never found in source). These are low-confidence items for Step 5,
not silent drops.
Step 4 - Validate
Validate the merged graph. The validator checks structure, referential integrity (no dangling edges),
unique ids, non-stub summaries (soft warning), and the controlled tag vocabulary (soft warning).
node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/validate-design-context.cjs" .design/context-graph.json
Exit 0 is clean, 1 is warnings only (stub summaries or unknown tags to tidy later), 2 is a hard
error (a dangling edge or duplicate id) that must be fixed before the graph is trusted. On exit 2, do
not present the graph as migrated: report the errors and stop so a human can resolve them.
Step 5 - Flag low-confidence transforms
Collect everything that needs human eyes and present it as one review list rather than applying it:
- every
could-not-fix: line from the merge (an unresolved or dropped edge);
- every node still carrying an empty
summary after Step 2 (a map note had no matching entity, or no
note existed);
- every validator
WARN (stub summary, tag outside the controlled vocabulary).
Print the list with a clear heading and ask the user to confirm or correct each item. Do not auto-resolve
a low-confidence transform: a wrong edge or a mislabeled node poisons every later graph query.
Step 6 - Deprecate the old map notes
The flat .design/map/*.md notes stay readable for one minor version so nothing breaks mid-upgrade. Add a
one-line deprecation banner to the top of each migrated map note (do not delete the file):
> Deprecated: superseded by the DesignContext graph (.design/context-graph.json) as of Phase 52.
> Read-only for one minor version; regenerate the graph with /gdd:migrate-context.
In --dry-run, describe this banner instead of writing it. Announce that the next minor version may remove
the .design/map/*.md notes, and that the graph is now the source of truth.
Do Not
- Do not trust a low-confidence transform silently. Every
could-not-fix: line and every stub goes on the
Step 5 review list.
- Do not delete
.design/map/*.md. Add the deprecation banner and keep the notes for one minor version.
- Do not hand-edit
.design/context-graph.json to force validation green. Fix the fragment or the source,
then re-merge.
- Do not edit the extractors, the merger, or the validator. This skill only calls them.
MIGRATE-CONTEXT COMPLETE
