knowledge-sync

name	knowledge-sync
description	Sync ADO work items and ICM incidents to the persistent knowledge log. Invoked automatically by /review, /workitem, and /pac-cli-update when knowledge is stale.
user-invocable	true

Knowledge Sync — ADO Work Items + ICM Incidents

Reads ADO work items and ICM incidents for the PPBT area, extracts patterns and fixes, and appends them to a persistent knowledge log. Each run only fetches items newer than the last sync — knowledge accumulates over time rather than being overwritten.

Invoke as: /knowledge-sync

Also invoked automatically (inline) by /review, /workitem, and /pac-cli-update when the knowledge base is more than 7 days old. No manual scheduling needed.

---

How the knowledge base works

All persistent knowledge lives in two files in the memory directory:

• memory/ado-knowledge.md — append-only log of every work item and incident processed, grouped by run date. Never overwrite — only append new entries.
• memory/MEMORY.md — the live distilled summary: hard rules, patterns, and skill inventory. Update this with confirmed facts extracted from ado-knowledge.md.

The sync tracks progress via a ## Last sync header in ado-knowledge.md. Each run reads that date, queries only items changed after that date, appends new findings, then updates the header. On the very first run (no ado-knowledge.md exists), query the past 90 days as the bootstrap window.

---

Step 1 — Read last sync date

# Check if knowledge log exists and find last sync date
cat memory/ado-knowledge.md 2>/dev/null | grep "## Last sync" | tail -1

• If found: use that date as @since in WIQL queries below
• If not found: use @Today - 90 as @since (first-run bootstrap)

---

Step 2 — Configure ADO org (once per session)

az devops configure \
  --defaults organization=https://dev.azure.com/dynamicscrm project=OneCRM 2>&1

az devops configure --list 2>&1

If az login is needed (browser flow — no username/password):

az login --use-device-code

---

Step 3 — Query ADO for items changed since last sync

# Active items (all — re-read on every sync to catch state changes)
az boards query --wiql "
  SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType],
         [System.Tags], [Microsoft.VSTS.Common.Priority], [System.ChangedDate]
  FROM WorkItems
  WHERE [System.AreaPath] UNDER 'OneCRM\Client\UnifiedClient\AppLifeCycle\PPBT Extensions'
    AND [System.State] NOT IN ('Closed', 'Resolved', 'Done')
  ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.ChangedDate] DESC
" --output json 2>&1

# Items resolved/closed since last sync (only NEW ones)
az boards query --wiql "
  SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType],
         [System.Tags], [Microsoft.VSTS.Common.Resolution], [System.ChangedDate]
  FROM WorkItems
  WHERE [System.AreaPath] UNDER 'OneCRM\Client\UnifiedClient\AppLifeCycle\PPBT Extensions'
    AND [System.State] IN ('Closed', 'Resolved', 'Done')
    AND [System.ChangedDate] > '<last-sync-date>'
  ORDER BY [System.ChangedDate] DESC
" --output json 2>&1

For each returned item, fetch full detail (description, repro steps, resolution, comments). Cap at 30 full-detail fetches per run — summarise the rest by title + state only:

az boards work-item show --id <id> --output json 2>&1

---

Step 4 — Query ICM incidents

# Check if icm CLI is available
icm --version 2>&1 || echo "icm CLI not available — falling back to ADO cross-references"

# If available
icm query \
  --owning-service "Power Platform Build Tools" \
  --status "Active,Resolved" \
  --modified-after "<last-sync-date>" \
  --top 50 \
  --output json 2>&1

# Fallback: find IcM references in ADO work items
az boards query --wiql "
  SELECT [System.Id], [System.Title], [System.Description], [System.ChangedDate]
  FROM WorkItems
  WHERE [System.AreaPath] UNDER 'OneCRM\Client\UnifiedClient\AppLifeCycle\PPBT Extensions'
    AND [System.Description] CONTAINS 'IcM'
    AND [System.ChangedDate] > '<last-sync-date>'
  ORDER BY [System.ChangedDate] DESC
" --output json 2>&1

---

Step 5 — Classify findings

For each new item, assign one or more categories:

Category	Where it goes
Recurring bug / root cause	ado-knowledge.md log + skills/architecture/SKILL.md debug runbook
Known workaround	ado-knowledge.md log + skills/architecture/SKILL.md debug runbook
Architecture decision	ado-knowledge.md log + skills/architecture/SKILL.md layer notes
Dependency conflict / vuln pattern	ado-knowledge.md log + skills/fix-dependencies/SKILL.md hard rules
Task contract change (input name, GUID)	ado-knowledge.md log + skills/create-pr/SKILL.md review checklist
ICM mitigation / guidance	ado-knowledge.md log + skills/architecture/SKILL.md debug runbook

Only add facts explicitly stated in resolutions or ICM mitigations — no speculation.

---

Step 6 — Append to memory/ado-knowledge.md

Append a new dated section. Never delete or overwrite previous sections.

## Sync <YYYY-MM-DD>
**Last sync:** <YYYY-MM-DD>

### Active items (<N> total)
- <ID>: <title> [<priority>] [<type>]
- ...

### Newly resolved since last sync (<N> items)

#### <ID> — <title>
- **Type:** Bug / Task / Feature
- **Resolution:** <verbatim resolution text>
- **Root cause:** <extracted from description>
- **Fix:** <what was changed>
- **Category:** <from classification >


 :  — 


 

---

Step 7 — Update skills with new confirmed facts

Update only files where new facts apply. Skip files with no relevant new findings.

skills/architecture/SKILL.md

• Append to Debug Runbook by Symptom for any new recurring issue with a confirmed fix
• Update auth table or bundled dep notes if changed

skills/fix-dependencies/SKILL.md

• Add new package conflict patterns to Strategy A hard rules
• Add new formally risk-accepted vulnerabilities to the known accepted risks list

skills/create-pr/SKILL.md

• Add to review checklist any new breaking-change patterns from resolved work items

skills/workitem/SKILL.md

• Add recurring fix patterns so future similar work items resolve faster

memory/MEMORY.md

• Update the Key architecture facts and Dependency hard rules sections with any new confirmed facts
• Do NOT add speculation — only confirmed fixes from resolved items

---

Step 8 — Update last sync date

After all appends and skill updates are complete, update the ## Last sync line at the top of ado-knowledge.md:

# The sync date is updated by the append in Step 6 — confirm it is correct
grep "## Last sync" memory/ado-knowledge.md | tail -1

---

Final report

Print:

1. Sync window: <last-sync-date> → <today>
2. Items processed: N active, N newly resolved, N ICM incidents
3. New facts extracted: list each pattern/rule added
4. Skills updated: list each file and what section changed
5. Nothing changed: if no new items found since last sync, say so and exit cleanly