dia-migration

DIA Migration

Convenience wrapper that brings an existing DIA repo to current conventions. Not a brownfield onboarding skill -- for that, use /reverse-engineering, which contains the same migration mechanics plus a full code-walk for missing artefacts.

Designed for two starting states:

• DIA v1 -> current: artefacts use the old patterns (FEATURE-NNNN, ADR-NNN, status in frontmatter, fixes under context/, archive/ folders, 20_bugs.md, numeric-prefixed context files).
• Older V-Model variant -> current: same DIA layout idea but inconsistent prefixes or per-cycle handoffs.

For brownfield without V-Model artefacts (code exists, no _devprocess/ directory): the answer is /reverse-engineering. That skill detects pre-existing partial artefacts, runs the same migration scripts as Phase -1.5, then walks the code to produce the missing artefacts. Do not start with /dia-migration for brownfield -- you would only get the migration step without the artefact-bootstrap from code.

The skill is idempotent. Running it on an already-current repo performs the consistency check and exits without changes.

MANDATORY Pre-Phase 0: Branch check (cross-cutting operation)

Migration is a cross-cutting maintenance operation, not a V-Model phase. It does not target a backlog item; it touches many artefacts across the repo. Therefore migration runs on a dedicated branch and does not set V-Model phase tags.

Branch convention: chore/dia-migration-<YYYY-MM-DD>.

Check at start (full rules: skills/project-conventions/references/team-workflow.md):

1. If on main / master / dev: refuse, AskUserQuestion to create chore/dia-migration-<YYYY-MM-DD> and switch.
2. If on the expected migration branch (or any other chore/* / feature/* branch the user explicitly confirms): silent continue.
3. If on a different branch: AskUserQuestion to switch to the migration branch (recommended) or stay (only when consciously bundling migration with other work, which is discouraged).

GitHub integration: migration does NOT create a per-item issue or draft PR. The migration commits go in as a single chore PR (chore/dia-migration-<date> -> dev). The user opens that PR manually after Phase 7 completes.

Phase tags: migration does NOT set V-Model phase tags (<id>/ba-done etc. are reserved for backlog items). It does write progress markers via per-phase commits with the message prefix chore(dia-migration): phase <N> -- <summary> so the history is reviewable.

State stored in .git/dia-active-skill so subsequent invocations of the migration loop stay silent if everything matches.

Shared tooling

This skill orchestrates the scripts under tools/migration/ in the DIA repo:

Script	Phase	Purpose
tools/migration/detect_state.py	0	Inventory the repo, classify v1/v2/mixed.
tools/migration/strip_frontmatter_status.py	2a	Remove status: / phase: from YAML frontmatter.
tools/migration/strip_body_status.py	2b	Remove body-level **Status:** / > **Status**: lines.
tools/migration/migrate_naming.py	3	Rename ID schemas (FEATURE-NNNN -> FEAT-EE-FF, etc.).
tools/migration/flatten_analysis.py	4	Flatten analysis/ to BA / EXPLORE / RESEARCH / AUDIT.
tools/migration/build_backlog.py	5	Regenerate BACKLOG.md from artefact scan.
tools/migration/migrate_skill_names.py	6	Rewrite /business-analyse -> /business-analysis,
/v-model-workflow -> /dia-guide.
tools/migration/migrate_status_vocabulary.py	5b	Rewrite BACKLOG status values to the GitHub-aligned vocabulary.

/reverse-engineering reuses the same scripts under Phase -1.5. Both skills share the canonical implementation; this one wraps it with a phase-by-phase confirmation loop, the other one runs them silently as part of the backwards walk.

Writing style

Every artifact this skill writes follows the rules in skills/project-conventions/SKILL.md under "Writing style for every artifact". No em dashes, no AI vocabulary, no negative parallelisms, sentence case in headings.

When to invoke

User says:

• "migrate this project to DIA v2"
• "upgrade my V-Model setup"
• "restructure the backlog"
• "clean up artifact frontmatter"
• "convert FEATURE-NNNN to FEAT-NN-NN"

Or: another skill (typically /dia-guide on first run against a non-conforming repo) calls /dia-migration to bring the structure in line before continuing.

Safety contract

The skill operates on a feature branch. It does not push, it does not touch source code, and it does not delete user-authored content without explicit confirmation. Concrete rules:

1. Branch check at start. Refuse to run on main, master, or dev. The user must create a migration branch first (git checkout -b feature/dia-migration is the typical name).
2. Source code under src/ (or the project's code root) is only edited to add src/ARCHITECTURE.map and optional src/{module}/README.md files. JSDoc headers in .ts/.js files are NOT auto-written. The skill proposes a list and asks.
3. Files outside _devprocess/ and src/ are not touched.
4. Deletes are listed before execution. archive/ folders, the legacy 20_bugs.md, and superseded handoff files are removed only after the user sees the list.
5. If git status is dirty at start, the skill stops and asks the user to commit or stash first. Mid-migration commits on a clean tree are encouraged so each phase is reversible.

Phases

The skill walks seven phases. Each phase is independently re-runnable. If a phase fails, the next one is not started.

Phase 0: Detection and plan

Inventory the repo and classify it. Outputs a one-page plan for user review.

• Detect project root convention: _devprocess/, docs/, or none.
• Scan for old vs. new patterns:
  • filename pattern FEATURE-NNNN (4-digit) -> v1
  • filename pattern FEAT-NN-NN -> v2
  • presence of _devprocess/context/fixes/ -> v1
  • presence of _devprocess/requirements/fixes/ -> v2
  • presence of _devprocess/context/20_bugs.md -> v1
  • presence of any archive/ directory under _devprocess/ -> v1
  • frontmatter status: or phase: fields -> v1
  • body-level **Status:** headers in artifacts -> v1
  • presence of _devprocess/requirements/epics/EPIC-*-ba.md (legacy mini-BA next to the EPIC) -> v1, must move to analysis/BA-EPIC-{nn}-{slug}.md in Phase 4
• Count each finding.
• Decide migration scope:
  • all v2 patterns, no findings -> exit with green report
  • mixed -> run all phases (each is idempotent)
  • brownfield (no _devprocess/ and no docs/) -> hand off to /reverse-engineering first, then continue here

The plan is saved as a Markdown report at _devprocess/context/HANDOFFS.md under a new entry dia-migration plan {date} and printed for the user.

Phase 1: Foundation

Create the layers that DIA v2 requires regardless of starting state.

1. _devprocess/rules/ with technical.md (always), design.md (only if the project has UI surface), domain.md (always). Seeded from skills/architecture/templates/RULES-*-TEMPLATE.md. If files already exist, leave them in place but check the line budget (max 500 lines total).
2. src/ARCHITECTURE.map seeded from skills/architecture/templates/ARCHITECTURE-MAP-TEMPLATE.md. If a map already exists, validate it; otherwise scan src/ for entry-point candidates (large files containing class, interface, Manager, Service, Registry, Pipeline in their names) and propose initial rows. The user confirms before writing.
3. _devprocess/requirements/{epics,features,fixes,improvements,handoff}/ directories. Move existing _devprocess/context/fixes/ to _devprocess/requirements/fixes/ and same for improvements/. Legacy EPIC-{nn}-ba.md files inside _devprocess/requirements/epics/ are moved to _devprocess/analysis/BA-EPIC-{nn}-{slug}.md (slug from the sibling EPIC file). The legacy mini-BA convention is dropped.
4. _devprocess/analysis/ flattened: analysis/security/AUDIT-* moves to analysis/ root, archive/ deleted (with the file list shown to the user first).
5. _devprocess/context/20_bugs.md deleted. The backlog regenerated in Phase 5 carries the FIX status.

Phase 2: Bulk frontmatter and body status cleanup

Every artifact under _devprocess/requirements/, architecture/, implementation/plans/, context/fixes/, context/improvements/ gets two passes:

1. Frontmatter pass: remove status:, phase:, last_updated:, last-updated:, lastUpdated: lines from the YAML frontmatter. Multi-line values are removed entirely.
2. Body header pass: in the first 25 lines after the frontmatter, remove lines matching **Status:** X, > **Status:** X, Status: Implemented, Status: Akzeptiert, etc. Also **Last Updated:** ... and German equivalents.

Run via tools/migration/strip_frontmatter_status.py and tools/migration/strip_body_status.py (both live under tools/migration/ in the DIA repo).

After this phase, the repo's status truth lives ONLY in the backlog.

Phase 3: Filename migration to DIA v2 ID schemas

Renames artifact files and updates all cross-references in .md-files plus src/ARCHITECTURE.map. Idempotent.

Old pattern	New pattern	Notes
EPIC-NNN-{slug}.md	EPIC-{nn}-{slug}.md	strip leading zero, fits in 2 digits
FEATURE-NNNN-{slug}.md	FEAT-{ee}-{ff}-{slug}.md	prefix change FEATURE -> FEAT, hyphen split
FEATURE-NNN-{slug}.md	FEAT-{ee}-{ff}-{slug}.md	legacy 3-digit (e.g. FEATURE-400) gets normalized
FIX-{eeff}-{nn}-{slug}.md	FIX-{ee}-{ff}-{nn}-{slug}.md	hyphen split for clarity
IMP-{eeff}-{nn}-{slug}.md	IMP-{ee}-{ff}-{nn}-{slug}.md	analog
ADR-NNN-{slug}.md	ADR-{nn}-{slug}.md	strip leading zero
PLAN-NNN-{slug}.md	PLAN-{nn}-{slug}.md	strip leading zero
BA-{slug}.md (project, no item ref)	BA-{PROJECT}.md	Singleton Project-BA, slug becomes project shortname
BA-NNN-{slug}.md (legacy item-BA)	BA-EPIC-{nn}-{slug}.md	Legacy generic BA-NNN promoted to Item-BA-Epic if it carries epic-level discovery; otherwise renamed to BA-{PROJECT}.md (asks user once)
EPIC-{nn}-ba.md (legacy mini)	BA-EPIC-{nn}-{slug}.md	move from requirements/epics/ to analysis/; slug carried over from sibling EPIC file
EXPLORE-NNN-{slug}.md	EXPLORE-{nn}-{slug}.md	strip leading zero
RESEARCH-NNN-{slug}.md	RESEARCH-{nn}-{slug}.md	strip leading zero
handoff files	architect-handoff-FEAT-{ee}-{ff}.md, plan-context-FEAT-{ee}-{ff}.md	per active feature stream

Run via tools/migration/migrate_naming.py. The script does two passes: first the file renames, then a global text replacement of references using the rename map. A second sweep catches body references to IDs that do not have a corresponding file (e.g. an EPIC-023 mentioned in prose but never created).

When the file count exceeds 99 in any class, the script suggests extending that class to 3-digit (e.g. EPIC-100). The user confirms before applying. Until then, 2-digit is the default.

The append-only _devprocess/context/HANDOFFS.md is exempt from the body sweep. Historical entries keep their original IDs as audit-trail records.

Phase 4: analysis/ flattening to four prefixes plus sources/

Reduces the analysis/ directory to four flat prefixes (BA-, EXPLORE-, RESEARCH-, AUDIT-) at the root, plus a single sources/ subfolder for user-provided source documents.

The BA prefix has five accepted shapes after the migration. All five sit flat in analysis/. None live next to the EPIC artefact:

• BA-{PROJECT}.md (singleton Project-BA)
• BA-EPIC-{nn}-{slug}.md (Item-BA per epic)
• BA-FEAT-{ee}-{ff}-{slug}.md (Item-BA per feature)
• BA-IMP-{ee}-{ff}-{nn}-{slug}.md (Item-BA per improvement, optional)
• BA-FIX-{ee}-{ff}-{nn}-{slug}.md (Item-BA per fix, optional)

Legacy mini-BAs at _devprocess/requirements/epics/EPIC-{nn}-ba.md move to analysis/BA-EPIC-{nn}-{slug}.md, with {slug} carried over from the sibling EPIC file. The EPIC-{nn}-ba.md file is removed after the move.

• CODEBASE-NNN, DESIGN-NNN, SECURITY-NNN, SPIKE-NNN, FINDING-, ROOT-CAUSE-, GAP-ANALYSE-, SOLUTION-PROPOSAL-, SCAFFOLD-, MOBILE-, STANDALONE-, TEMPLATE-, REVIEW-, ANALYSIS-, HANDOFF- -> renamed to RESEARCH-NN-{originalprefix-slug}, preserving the old prefix in the slug for traceability.
• analysis/security/AUDIT-*.md -> moved to analysis/AUDIT-*.md (flat).
• analysis/security/ and analysis/archive/ directories deleted (archive content has typically been replaced by the backlog).
• analysis/SOURCE-* (any extension) -> moved to analysis/sources/SOURCE-*. This is the only subfolder that survives the flatten because user-provided sources are not engineered artefacts and benefit from a clean separation.
• External content (blog posts, reddit posts) -> moved to _devprocess/articles/ if present.

Run via tools/migration/flatten_analysis.py.

Phase 5: Backlog regeneration

Build _devprocess/context/BACKLOG.md from scratch by scanning all artifacts. The new backlog is the single source of truth for status, phase, claim, and Refs.

• One row per Feature, Fix, Improvement, ADR, Plan.
• Epics are section headers, not rows.
• The Title column holds the bare title only, never an id prefix. A detail file whose H1 is # IMP-01-01-08: ensureColumn ... produces Title ensureColumn ..., not IMP-01-01-08: ensureColumn ... (the id already lives in the first column; flow.py would otherwise emit a doubled IMP-01-01-08: IMP-01-01-08: ... issue title). build_backlog.py strips the prefix for every type at one choke point; do not hand-write prefixed titles either.
• Status defaults from heuristics:
  • Features in epics 01-22 (or whatever ranges the user marks as "shipped") default to Done/Released.
  • Features in active epics default to Active/Building.
  • ADRs default to Accepted/Released for old ADRs and Accepted/Building for new ones (cutoff: numeric ID >= last_shipped_adr + 1, asked from the user once).
  • PLANs default to Draft/Building.
• The Refs column is populated from frontmatter epic:, adr-refs:, feature-refs:, related:, supersedes:, superseded-by:, ba-ref:.
• For every EPIC and FEAT artefact whose ID has a matching analysis/BA-EPIC-* or analysis/BA-FEAT-* file (after Phase 4), the script writes ba-ref: into the artefact frontmatter so the promotion link is restored.
• A pre-existing BACKLOG.md is overwritten only after the user confirms (the script saves the previous version under BACKLOG.md.preMigration for one-step rollback).

Run via tools/migration/build_backlog.py. The script is parameterized through a small YAML config that the user can edit before the run (epic cutoffs, status overrides for known exceptions).

Phase 5b: Status vocabulary alignment

After Phase 5 produces a fresh BACKLOG.md, this short phase brings the Status column from the legacy DIA vocabulary into the GitHub- aligned vocabulary so flow.py sync-status can mirror 1:1 without translation.

Mapping:

Old (DIA legacy)	New (GitHub-aligned)
Planned	Ready
Active	In Progress
Review	In Review
Done	Done
Waiting	Backlog
Deferred	Backlog

Run via tools/migration/migrate_status_vocabulary.py. The script edits only the Status column. Other columns and the Phase column (Released / Building / Planned / Candidates) stay untouched. The migration is idempotent: a second run reports zero changes.

After this phase, flow.py sync-status no longer needs the legacy mapping table; both BACKLOG.md and the GitHub project Status field share one vocabulary.

Phase 6: Cross-skill rename support

If the repo references the old skill names (/business-analyse, /v-model-workflow), this phase rewrites them to the current names (/business-analysis, /dia-guide). It also updates skill folder references in CLAUDE.md, README, and any inline scripts.

This phase is a no-op for repos that already use v2 skill names.

Phase 7: Consistency check

Runs /consistency-check mode A (syntactic) and reports findings. Auto-fix is applied for the safe drift types:

• Frontmatter status: or phase: fields lingering anywhere
• Backlog rows missing for an existing artifact (placeholder row inserted)
• Dashboard counts vs. computed totals
• Dead links inside _devprocess/

Findings that need human triage (orphan ADRs, ADR abstraction violations, true semantic conflicts) are listed in the final report and parked as BL-NNN rows in the backlog with Source = CONSISTENCY-CHECK.

If the consistency check passes, the skill writes a final entry to _devprocess/context/HANDOFFS.md:

## dia-migration {YYYY-MM-DD} -- migration complete

Phases run: 0 (detection), 1 (foundation), 2 (status cleanup),
3 (naming), 4 (analysis flatten), 5 (backlog), 6 (skill renames),
7 (consistency).

Counts after migration:
- Artifacts: {N}
- Backlog rows: {N}
- ADR catalog entries: {N}
- Status drift remaining: 0
- archive/ folders remaining: 0

Tools

The migration scripts live in the DIA repo at tools/migration/ and are shared with /reverse-engineering:

Script	Purpose
tools/migration/detect_state.py	Phase 0 detection. Returns a JSON report.
tools/migration/strip_frontmatter_status.py	Phase 2a. Removes status fields from YAML frontmatter.
tools/migration/strip_body_status.py	Phase 2b. Removes status headers from artifact bodies.
tools/migration/migrate_naming.py	Phase 3. Renames files and updates references.
tools/migration/flatten_analysis.py	Phase 4. Reduces analysis/ to four prefixes.
tools/migration/build_backlog.py	Phase 5. Regenerates the backlog from all artifacts.
tools/migration/migrate_status_vocabulary.py	Phase 5b. Maps Status values to the GitHub vocabulary.
tools/migration/migrate_skill_names.py	Phase 6. Updates /business-analyse and /v-model-workflow references.

All scripts:

• accept the project root as an argument (default: current working directory).
• print a summary at the end (files changed, refs updated).
• are idempotent. Running again finds zero changes if the repo is already clean.
• exit with non-zero code on any error so the skill can stop the pipeline.

Workflow when invoked

1. Pre-flight: confirm git branch is not main/dev/master and working tree is clean (or warn).
2. Phase 0: run detect_state.py, present the plan to the user, get confirmation. Stop if user declines.
3. Phase 1: foundation (rules, ARCHITECTURE.map seed, dirs). Confirm with user for the ARCHITECTURE.map seed (entry-point candidates).
4. Phase 2: status cleanup. Two scripts in sequence. Commit after.
5. Phase 3: naming migration. Show rename plan, ask user, then execute. Commit after.
6. Phase 4: analysis flattening. Show rename list, confirm, execute. Commit after.
7. Phase 5: backlog regeneration. Show backlog summary preview, confirm overwrite, execute. Commit after.
8. Phase 5b: status vocabulary alignment. Run tools/migration/migrate_status_vocabulary.py. Show counts per mapping. Commit after.
9. Phase 6: skill name updates. Idempotent, commit after.
10. Phase 7: consistency check. Run /consistency-check mode A with --fix. Final report.
11. Phase 8: parallel-branch id alignment check. After the migration commits land, scan other active branches for ids that would collide with the migrated state. Report only, do not modify other branches. See "Phase 8: Parallel-branch alignment" below.

Each phase ends with a commit message: chore(dia-migration): phase N -- {short summary}.

The user can interrupt between phases. Re-running /dia-migration picks up at the next dirty phase based on the detection output.

Phase 8: Parallel-branch alignment (advisory)

Migration touches many artefact ids. If other feature branches were in flight while the migration ran, those branches may carry ids that now collide with the migrated state on the migration branch.

The skill does not rewrite history on other branches. It only reports, so the maintainer decides per branch what to do (rebase, re-renumber via tools/renumber-for-merge.py, or abandon).

Steps:

1. Enumerate other branches:

   git for-each-ref --format='%(refname:short)' refs/heads/ \
     | grep -Ev '^(main|master|dev|chore/dia-migration-)'
   

2. For each branch, run a list-only collision check against the migration branch:

   git checkout <branch>
   python3 tools/renumber-for-merge.py \
     --target chore/dia-migration-<date> \
     --list-conflicts
   git checkout chore/dia-migration-<date>
   

3. Aggregate the JSON output into a final report block in _devprocess/context/HANDOFFS.md:

   ## dia-migration {YYYY-MM-DD} -- parallel-branch alignment
   Branches with id collisions vs migrated state:
   - feature/foo: epic 1, feat 2, fix 0, imp 0
   - feature/bar: epic 0, feat 1, fix 1, imp 0
   To align before merging, run on each branch:
     bash scripts/merge-to-dev.sh <branch> chore/dia-migration-<date>
   

4. The maintainer decides per branch. The skill itself does not switch branches for the user beyond the temporary checkouts in step 2 (which it always restores).

This phase is advisory. If no other branches exist, it is a no-op that prints "No parallel branches found".

Handoff Ritual

At the end of a successful run:

DIA migration complete on branch {branch}.

Summary:
- Phases executed: 7/7
- Files renamed: {N}
- References updated: {N}
- Status fields cleaned: {N}
- archive/ folders removed: {N}
- Backlog rows: {N}

Next steps:
1. Review the migration commits.
2. Merge the branch when satisfied.
3. /dia-guide picks up the project state from here.

Failure modes and rollback

If a phase fails:

1. The script writes its error to stderr and exits non-zero.
2. The skill stops without proceeding to the next phase.
3. The user can git reset --hard HEAD to undo the failed phase (the previous phases are already committed).
4. Re-running /dia-migration re-detects state and resumes at the first dirty phase.

For Phase 5 specifically (backlog overwrite), the previous backlog is preserved as BACKLOG.md.preMigration. To roll back the backlog rewrite without rolling back commits:

mv _devprocess/context/BACKLOG.md.preMigration \
   _devprocess/context/BACKLOG.md

Keywords

DIA migration, V-Model migration, repo migration, DIA v1, DIA v2, upgrade conventions, restructure backlog, status drift cleanup, filename migration, FEATURE to FEAT, EPIC numbering, ADR numbering, analysis flattening, archive cleanup, brownfield to V-Model.