| name | wiki-to-markdown |
| description | Konvertiert bildlastige ADO-Wiki-Seiten (z. B. CTRM Manual) Seite für Seite in saubere Markdown-Dateien. Echte UI-Screenshots bleiben als Bilder mit reichem Alt-Text und "Screenshot-Erläuterung". PowerPoint- und Flow-Diagramme werden zu Mermaid umgewandelt. Goldstandard: wiki-md/CTRM/ctrm-feature-process.md. Triggers: wiki to markdown, ADO Wiki Seite umwandeln, wiki-seite konvertieren, ctrm manual markdown, convert wiki page, wiki page zu markdown, convert_wiki_page.
|
Wiki → Markdown Skill
Konvertiert eine ADO-Wiki-Seite in eine strukturierte Markdown-Datei nach dem
Goldstandard wiki-md/CTRM/ctrm-feature-process.md.
Grafik-Klassifikation (Pflicht für jedes Bild)
Jedes Bild via view_image ansehen — dann nach dieser Tabelle entscheiden:
| Typ | Erkennung | Behandlung |
|---|
| UI-Screenshot | Echtes ADO-Formular, Felder, Buttons, Status-Dropdown | Bild behalten + Alt-Text + **Screenshot-Erläuterung:** + Aktivitäten-Tabelle |
| Annotierter Screenshot | UI-Screenshot mit Callout-Nummern ①②③ eingebettet | Bild behalten + JEDE Annotation ①..⑭ → Feld+Aktion im Alt-Text + Tabelle |
| State-Diagramm / einfacher Flow | Einzelne Linie von Zustand zu Zustand, KEIN Swimlane | Als Mermaid stateDiagram-v2 oder graph LR (ohne subgraph-Links) |
| Swimlane-Diagramm | Mehrere parallele Spuren nebeneinander (Rollen/Teams), mit Querverbindungen | Als HTML-Tabelle mit <td>, rowspan, inline CSS — KEIN Mermaid |
| Tabellen-Grafik | Tabelleninhalt als Bild (z. B. aus PowerPoint-Export) | Als Markdown-Tabelle rekonstruieren — kein Bild behalten |
| Informationsgrafik | Icons, Konzept-Überblick, rein symbolisch | Als Text/Liste rekonstruieren — kein Bild behalten |
Warum kein Mermaid für Swimlanes? ADO Wiki unterstützt offiziell keine Links to/from subgraph
und keinen flowchart-Typ. graph LR mit subgraph rendert korrumpiert (gestapelt statt horizontal).
HTML-Tabellen mit rowspan/colspan + inline CSS sind die einzige zuverlässige Darstellung für
Swimlane-Diagramme in ADO Wiki.
Mermaid-Orientierungsregel (Pflicht)
Mermaid-Diagramme müssen möglichst die Orientierung des Originals spiegeln:
| Original-Diagramm | Mermaid-Richtung | Syntax |
|---|
| Horizontal (links → rechts, Prozessfluss) | Landscape LR | stateDiagram-v2 mit direction LR oder graph LR |
| Vertikal (oben → unten, Hierarchie) | Portrait TD | graph TD oder stateDiagram-v2 (default) |
| Unklar / keine Vorlage | Landscape LR | Standard-Fallback: immer LR wählen |
Regel: Im Zweifel immer Landscape (LR) — Prozessdiagramme lesen sich horizontal
natürlicher und nutzen die Seitenbreite im ADO Wiki besser.
Für stateDiagram-v2 Landscape:
::: mermaid
stateDiagram-v2
direction LR
[*] --> Zustand1 : Trigger
Zustand1 --> Zustand2 : Bedingung
:::
Für graph Landscape:
::: mermaid
graph LR
A[Schritt 1] --> B[Schritt 2] --> C[Schritt 3]
:::
Swimlane → HTML-Tabelle (Muster)
Für Swimlane-Diagramme mit horizontalen Prozess-Spuren und einer vertikalen CAB/Gate-Spalte:
<table style="border-collapse:collapse;font-family:Segoe UI,Arial,sans-serif;font-size:12px;width:100%;">
<tr>
<td style="width:150px;font-weight:bold;padding:6px 10px;">Spur 1</td>
<td style="background:#7b2d8b;color:white;padding:6px 10px;">Schritt A</td>
<td style="background:#7b2d8b;color:white;padding:6px 10px;">Schritt B</td>
<td style="background:#2ecc71;color:white;padding:6px 10px;writing-mode:vertical-lr;
text-align:center;font-size:11px;" rowspan="N">Gate / CAB</td>
<td style="background:#7b2d8b;color:white;padding:6px 10px;">Schritt C</td>
</tr>
<tr>
<td style="font-weight:bold;padding:6px 10px;">Spur 2</td>
<td colspan="2" style="background:#999;color:white;padding:6px 10px;">Schritt 1-2</td>
<td style="background:#999;color:white;padding:6px 10px;">Schritt 3</td>
</tr>
</table>
Regeln für ADO-Wiki-HTML-Tabellen:
border-collapse:collapse ist Pflicht (sonst Doppelrahmen)writing-mode:vertical-lr für rotierten Text in rowspan-Spalten- Farben als Hex-Werte oder benannte Farben (kein
var(), kein CSS-Grid)
- Kein
<style>-Block — nur inline style="..."
6-Phasen-Workflow
Phase 0 — Setup
- ADO-Wiki-URL parsen →
org / project / wiki / pageId / slug extrahieren.
slug = kebab-case-lowercase aus Seitentitel (CTRM-PBI-Process → ctrm-pbi-process).- Ausgabepfade definieren:
- Markdown:
.temp/wiki-converted/<slug>.md
- Assets:
.temp/wiki-converted/assets/<slug>/NN-name.png
- Download-Temp:
.temp/wiki-import/<slug>/
- Ordner anlegen:
.temp/wiki-converted/assets/<slug>/ und .temp/wiki-import/<slug>/.
Hinweis: .temp/ ist gitignoriert — generierte Artefakte tauchen nicht im Repository auf.
Die Dateien sind für Review und als Quelle für das ADO-Wiki-Upload bestimmt.
Phase 1 — Seite laden
ado MCP → wiki_get_page (org, project, wikiId, pageId) → Roh-Markdown + Metadaten.- Alle
/.attachments/Filename-GUID.ext-Referenzen im Roh-Markdown sammeln.
- Seitenstruktur (H1, H2, H3) und Bild-Positionen kartieren.
Technische Details zu ADO-Toolaufruf und Attachment-URLs: extraction.md
Phase 2 — Bilder laden
- Jeden Attachment-Dateinamen nach
.temp/wiki-import/<slug>/ laden.
- Smoke-Test mit erstem Bild: Datei >0 Bytes? → ja: Batch fortsetzen; nein: Playwright-Fallback.
- Geladene Bilder nach
.temp/wiki-converted/assets/<slug>/NN-name.png kopieren.
Auth-Strategie (az rest + Access Token) und Playwright-SAML-Fallback: extraction.md
Phase 3 — Klassifizieren und verstehen
- Jedes Bild via
view_image ansehen und nach obiger Tabelle klassifizieren.
- ADO-Konzepte (Work-Item-Form, PBI-Workflow-States, Area Path, Iteration Path, DoR, DoD)
via
microsoft-docs MCP grounden — für fachlich präzise Alt-Texte.
- Pro UI-Screenshot: Alt-Text-Gerüst (5 Punkte, siehe unten) vorläufig notieren.
- Pro Diagramm: Knoten + Kanten + Labels für Mermaid erfassen.
Phase 4 — Markdown schreiben
Exakte Struktur nach output-template.md. Kurzübersicht:
- Sprache: Deutsch (Schweiz), kein ß, kein Gendern, Datum DD.MM.YYYY
- H1: Seitentitel
- Meta-Blockquote nach H1: Accountable-Zeile
- Intro-Absatz: Zweck (1–3 Sätze)
- Überblick-Diagramm: Prozessdiagramm →
Mermaid stateDiagram-v2 (mit direction LR) oder graph LR — immer Landscape, ausser das Original ist explizit vertikal
- Pro Sektion:
## Phase N — Titel (ggf. Meta-Blockquote wiederholen) — lokaler Pfad relativ zur .md-Datei**Screenshot-Erläuterung:** Legende- Aktivitäten-Tabelle
| Nr. | Pflicht | Aktivität |
- Hinweis-Blockquotes
Für das ADO-Wiki-Upload (Phase 4b) werden Bildpfade zu /.attachments/<GUID>.png umgeschrieben.
Phase 4b — ADO-Wiki-Upload (IMMER automatisch, ohne Rückfrage)
Ziel-Parent: /CTRM Manual migrated (pageId 28309, org swisslife, project CTRM, wikiId CTRM.wiki)
- ADO-Markdown aus
.temp/wiki-converted/<slug>.md herstellen:
```mermaid ... ``` → ::: mermaid ... :::- Lokale Bildpfade
assets/<slug>/NN-name.png → /.attachments/<originalGUID>.png
(Mapping: NN-name.png → GUID aus Phase 1 Attachment-Liste)
\n-Escapes in Mermaid-Node-Labels vereinfachen (ADO verarbeitet keine \n innerhalb von Labels)- Mermaid-Richtung prüfen:
direction LR bei stateDiagram-v2, graph LR bei Flowcharts — ausser das Original ist explizit vertikal
- Seiten-Pfad ableiten:
/CTRM Manual migrated/<Originaltitel der Wiki-Seite>
- Originaltitel = exakter Seitentitel aus dem ADO-Wiki (nicht URL-slug)
mcp_azure_devops__wiki_create_or_update_page aufrufen:
wikiIdentifier: CTRM.wikiproject: CTRMpath: /CTRM Manual migrated/<Originaltitel>content: ADO-Markdown
- Ergebnis-ID und URL im Report ausgeben.
Phase 5 — Validieren und Cleanup
| Check | Kriterium |
|---|
| Asset-Referenzen | Jedes  zeigt auf existierende Datei in .temp/wiki-converted/assets/<slug>/ |
| Alt-Text | Jedes Bild: Alt-Text ≥3 Sätze + **Screenshot-Erläuterung:** |
| Kein Bild für Diagramme | Kein Prozessdiagramm mehr als PNG vorhanden |
| Sprache | Kein ß, kein Gendern |
| Download-Temp | .temp/wiki-import/<slug>/ nach erfolgreichem Copy leeren |
| Report | Kurze Zusammenfassung: Bilder behalten / umgewandelt / gelöscht; Pfad zu .temp/wiki-converted/<slug>.md |
Alt-Text-Standard
In ![Alt-Text] — für AI und Accessibility (3–6 Sätze):
Schema (5 Punkte, alle relevant abarbeiten):
- Welcher Screen/Tool und aktueller Status (z. B. ADO Feature-Formular, Status «1 Funneling»)
- Räumliches Layout: was ist links/rechts/oben/unten sichtbar
- Jede Annotation ①②③ → konkreter Feldname + Aktion (① Titel eingeben, ② Self-assign)
- Sichtbare Seiten-Sektionen rechts/aussen namentlich aufführen
- Besondere UI-Elemente: hervorgehobene Box, Rahmenfarbe, Dropdown-Optionen, Checklisten
**Screenshot-Erläuterung:** — für Menschen (kompakt, unter dem Bild):
Kompakte Legende: Annotiert: ① Status setzen, ② Assigned to, ③ Save.
Nur wirklich relevante Annotationen; max. 2–3 Sätze.
Beide Elemente sind Pflicht für jeden UI-Screenshot.
Fehlerbehandlung
| Problem | Massnahme |
|---|
wiki_get_page → leer | pageId + path kombinieren; Playwright-Fallback |
| Attachment-Download 401/403 | az account get-access-token neu holen (Resource-ID in extraction.md) |
| Bild nicht klassifizierbar | Als UI-Screenshot behandeln (sicherer Fallback) |
| Mermaid-Syntax-Fehler | stateDiagram-v2 gegen flowchart LR tauschen; Node-Labels vereinfachen |
| Wiki-Seite hat keine klare Phasen-Struktur | H2/H3-Gliederung aus dem Roh-Markdown übernehmen; Aktivitäten-Tabellen ggf. weglassen |
