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-.

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- and switch.

1. If on the expected migration branch (or any other chore/* /

feature/* branch the user explicitly confirms): silent continue.

1. 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- -> dev). The user opens that PR manually after Phase 7 completes.

Phase tags: migration does NOT set V-Model phase tags (/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 -- 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).

1. 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.

1. Files outside _devprocess/ and src/ are not touched.
2. 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.

1. 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).

1. 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.

1. _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.

1. _devprocess/analysis/ flattened: analysis/security/AUDIT-*

moves to analysis/ root, archive/ deleted (with the file list shown to the user first).

1. _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.

1. 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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pssah4
• Source: pssah4/digital-innovation-agents
• License: MIT
• Homepage: https://pssah4.github.io/digital-innovation-agents/

Install and usage instructions live in the source repository linked above.