willowdev-code · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0 — 2026-10-15
+
+How it works and why, and repeatable changes.
+
+- `ado_search`: one search over work items (full text, with the field that matched), wiki pages and code (Git and
+  TFVC), grouped; without the search service work items fall back to titles, a missing part does not stop the rest.
+- `ado_file`: a file by TFVC path, Git path or only its name; X++ objects as their methods, `part` shows one method;
+  `history=true`: who changed it, when, through which pull request (also for squash and rebase flows) and for which work
+  items.
+- `ado_undo` and a local log of every change ADO Lens makes (`%LOCALAPPDATA%\ado-lens\audit`): field values back,
+  fields changed by someone else since are kept and named, comments deleted, links removed or added back, created items
+  set to their removed state; always previewed first.
+- `ado_health`: backlog hygiene of a team (no criteria, description, estimate or parent; stale; left in a finished
+  sprint; look-alike titles; done without code).
+- `ado_release_notes`: requirements and bugs finished in a sprint or between dates as markdown, grouped by feature.
+- Recipes (tool set `recipes`, `ado_recipe`, `adolens recipe`): saved steps with a WIQL query and changes, comments or
+  child items from a template, with parameters; every run previewed; `--yes` for Windows Task Scheduler.
+- `ado_update` and recipes take iteration `next`.
+- Skill `po-explain`: "how does X work" in business language with sources, code told apart from documentation.
+- Wiki search shows page paths with real hyphens.
+
 ## 0.3.0 — 2026-10-15
 
 Easy to install and to keep current, for people who are not developers.

diff --git a/README.md b/README.md
@@ -155,12 +155,13 @@ never a permission.
 | Tool set | Tools | po | dev | full |
 |---|---|:-:|:-:|:-:|
 | `core` | `ado_status`, `ado_settings`, `ado_upgrade`, `ado_fields` | ✓ | ✓ | ✓ |
-| `work` | `ado_work_item`, `ado_query`, `ado_create`, `ado_update`, `ado_comment`, `ado_link` | ✓ | ✓ | ✓ |
+| `work` | `ado_work_item`, `ado_query`, `ado_create`, `ado_update`, `ado_comment`, `ado_link`, `ado_search`, `ado_undo` | ✓ | ✓ | ✓ |
 | `pr` | `ado_pr`, `ado_pr_update` | – | ✓ | ✓ |
 | `pipelines` | `ado_pipeline`, `ado_pipeline_run` | – | ✓ | ✓ |
-| `boards` | `ado_sprint`, `ado_board`, `ado_backlog`, `ado_my_day` | ✓ | – | ✓ |
+| `boards` | `ado_sprint`, `ado_board`, `ado_backlog`, `ado_my_day`, `ado_health`, `ado_release_notes` | ✓ | – | ✓ |
 | `wiki` | `ado_wiki`, `ado_wiki_write` | ✓ | ✓ | ✓ |
-| `trace` | `ado_trace`, `ado_changes` | ✓ | ✓ | ✓ |
+| `trace` | `ado_trace`, `ado_changes`, `ado_file` | ✓ | ✓ | ✓ |
+| `recipes` | `ado_recipe` | ✓ | ✓ | ✓ |
 | `test`, `recipes` | planned | ✓ | (recipes) | ✓ |
 | `code` | planned | – | ✓ | ✓ |
 
@@ -192,6 +193,12 @@ What each MCP tool answers, when Claude should reach for it, and the CLI command
 | `ado_wiki` | the project wiki: page tree (`depth`), one page as markdown with its version and subpages, or search across the project's wikis with snippets; long pages are cut unless `detail=full` | "how does X work", finding documentation | `adolens wiki`, `adolens wiki "Team/Setup"`, `adolens wiki --search "dual write"` |
 | `ado_wiki_write` | `create` a page, `append` / `prepend` to it, or `replace` it with the version from the last full read — a page changed by someone else in the meantime is never overwritten; optional change comment | release notes, keeping docs current | `adolens wiki-write "Team/Release notes" --file notes.md --mode append` |
 | `ado_my_day` | since the previous working day (or `since`): where you were mentioned (all projects), your items and followed items changed by others, pull requests waiting for your review | the start of the day | `adolens myday --since 3d` |
+| `ado_search` | one search over work items (full text, with the field that matched), wiki pages and code (Git and TFVC, X++ objects named), grouped; a part that is not available (e.g. Code Search not installed) is reported and the rest still answers | "how does X work", "where is Y" | `adolens search "credit limit" --scope work;wiki` |
+| `ado_file` | a file by TFVC path, Git path + repo, or just its name (found through Code Search); X++ objects as their list of methods, `part` shows one method; `history=true`: who changed it, when, through which pull request and for which work items | "what does this object do", "why is it like this" | `adolens file CreditCheck.xml --part validate`, `adolens file CreditCheck.xml --history` |
+| `ado_health` | backlog hygiene of a team's open items (newest first): no acceptance criteria, description, estimate or parent, no change for 14+ days while in progress, left in a finished sprint, look-alike titles (series like "Sprint 202 / 203" excluded); items done in the last 30 days without any linked code | refinement, keeping the backlog clean | `adolens health --team "Demo Team"` |
+| `ado_release_notes` | markdown release notes: requirements and bugs finished in a sprint or between dates, requirements grouped under their feature | sprint review, a release page on the wiki | `adolens release-notes previous`, `adolens release-notes --since 14d` |
+| `ado_undo` | reverts the last change ADO Lens made: field values back (fields someone changed since are left and named), comment deleted, link removed or added back, a created item set to its removed state; always a preview first; `list=true` shows recent changes | "undo that", a mistaken mass change | `adolens undo --list`, `adolens undo` |
+| `ado_recipe` | saved repeatable changes: steps with a WIQL query (or ids) and what to do with each item - fields, state, iteration `next`, tags, a comment, a child item from a template (`{title}`, `{id}`); `{parameters}`; every run previewed, then confirmed | "close the sprint", "set up a new customer" | `adolens recipe run close-sprint --param sprint="Demo\Sprint 6"`, `--yes` for Task Scheduler |
 
 ### Writing rules built in
 
@@ -240,7 +247,7 @@ build.ps1                   compile; -Deploy replaces the installed binaries, -T
 pack.ps1                    release package (ZIP + SHA-256)
 release.ps1 release-notes.ps1   releases (see below); .github\ CI and Release workflows, issue forms
 install.ps1 uninstall.ps1   installation; get.ps1 is the one-line download and install
-skills\                     skills for Claude (po-verify, po-story, po-sprint)
+skills\                     skills for Claude (po-verify, po-story, po-sprint, po-explain)
 docs\PLAN.md                road map
 build\  dist\               output (keep nothing of your own there)
 ```
@@ -287,6 +294,7 @@ regular expression per line, `!word` for allowed words. Without a list the relea
 | `SetupFlowTests.cs` | release versions and packages for updates, the team's wiki table (round trip, hand-edited pages), detecting the flow from releases and branches, the team map on the wiki with its version, local map over the team's |
 | `PrPipelineTests.cs` | PR lists and details (votes, checks, human threads only), PR actions (vote, comment on a line with a mention, create), failed build errors and log lines, running pipelines by name, saving environments, guessing the flow |
 | `TraceTests.cs` | line diff (Myers, unified hunks), X++ per method with form data sources, object names from AOT paths, `ado_trace` across TFVC and Git (deployed stages YES / NOT YET, environment labels, merged branches, deleted builds, criteria changed after coding), `ado_changes` lists and file diffs |
+| `KnowledgeTests.cs` | search across work items, wiki and code (a missing part still answers), files found by name with X++ methods, file history with pull requests and work items, undo (values back, fields changed by others kept, comments deleted), backlog health, release notes, recipes (save, preview, run) |
 | `WikiTests.cs` | page tree, page with version, replace only with the current version (412 never overwrites), append, create over an existing page, search snippets |
 | `WorkItemTests.cs` | work item answers, required fields and allowed values before writing, transitions, preview and confirm of bulk updates, mentions, links, queries, HTML ⇄ markdown, PAT never sent to other hosts |
 

diff --git a/README.pl.md b/README.pl.md
@@ -157,12 +157,13 @@ Nigdy nie jest uprawnieniem.
 | Zestaw | Narzędzia | po | dev | full |
 |---|---|:-:|:-:|:-:|
 | `core` | `ado_status`, `ado_settings`, `ado_upgrade`, `ado_fields` | ✓ | ✓ | ✓ |
-| `work` | `ado_work_item`, `ado_query`, `ado_create`, `ado_update`, `ado_comment`, `ado_link` | ✓ | ✓ | ✓ |
+| `work` | `ado_work_item`, `ado_query`, `ado_create`, `ado_update`, `ado_comment`, `ado_link`, `ado_search`, `ado_undo` | ✓ | ✓ | ✓ |
 | `pr` | `ado_pr`, `ado_pr_update` | – | ✓ | ✓ |
 | `pipelines` | `ado_pipeline`, `ado_pipeline_run` | – | ✓ | ✓ |
-| `boards` | `ado_sprint`, `ado_board`, `ado_backlog`, `ado_my_day` | ✓ | – | ✓ |
+| `boards` | `ado_sprint`, `ado_board`, `ado_backlog`, `ado_my_day`, `ado_health`, `ado_release_notes` | ✓ | – | ✓ |
 | `wiki` | `ado_wiki`, `ado_wiki_write` | ✓ | ✓ | ✓ |
-| `trace` | `ado_trace`, `ado_changes` | ✓ | ✓ | ✓ |
+| `trace` | `ado_trace`, `ado_changes`, `ado_file` | ✓ | ✓ | ✓ |
+| `recipes` | `ado_recipe` | ✓ | ✓ | ✓ |
 | `test`, `recipes` | w planie | ✓ | (recipes) | ✓ |
 | `code` | w planie | – | ✓ | ✓ |
 
@@ -194,6 +195,12 @@ Na co odpowiada każde narzędzie MCP, kiedy Claude powinien po nie sięgnąć i
 | `ado_wiki` | wiki projektu: drzewo stron (`depth`), strona jako markdown z wersją i podstronami albo wyszukiwanie we wszystkich wiki projektu z fragmentami; długie strony są ucinane, chyba że `detail=full` | „jak działa X”, szukanie dokumentacji | `adolens wiki`, `adolens wiki "Team/Setup"`, `adolens wiki --search "dual write"` |
 | `ado_wiki_write` | `create` — nowa strona, `append` / `prepend` — dopisanie, `replace` — zastąpienie z wersją z ostatniego pełnego odczytu (strony zmienionej w międzyczasie przez kogoś innego nigdy nie nadpisze); opcjonalny komentarz zmiany | notatki wydania, aktualna dokumentacja | `adolens wiki-write "Team/Release notes" --file notes.md --mode append` |
 | `ado_my_day` | od poprzedniego dnia roboczego (albo `since`): gdzie cię oznaczono (wszystkie projekty), twoje i obserwowane elementy zmienione przez innych, pull requesty czekające na twój przegląd | początek dnia | `adolens myday --since 3d` |
+| `ado_search` | jedno wyszukiwanie po work itemach (pełny tekst, z polem, w którym znaleziono), stronach wiki i kodzie (Git i TFVC, z nazwami obiektów X++), pogrupowane; niedostępna część (np. brak Code Search) jest zgłaszana, reszta odpowiada | „jak działa X”, „gdzie jest Y” | `adolens search "limit kredytowy" --scope work;wiki` |
+| `ado_file` | plik po ścieżce TFVC, ścieżce Git + repo albo samej nazwie (szukanej przez Code Search); obiekty X++ jako lista metod, `part` pokazuje jedną metodę; `history=true`: kto zmieniał, kiedy, w którym pull requeście i dla jakich work itemów | „co robi ten obiekt”, „dlaczego tak działa” | `adolens file CreditCheck.xml --part validate`, `adolens file CreditCheck.xml --history` |
+| `ado_health` | higiena otwartych elementów zespołu (od najnowszych): brak kryteriów akceptacji, opisu, szacunku albo rodzica, w toku bez zmian od 14+ dni, zostawione w zakończonym sprincie, podobne tytuły (serie typu „Sprint 202 / 203” pominięte); elementy zakończone w ostatnich 30 dniach bez powiązanego kodu | refinement, porządek w backlogu | `adolens health --team "Demo Team"` |
+| `ado_release_notes` | notatki wydania w markdownie: wymagania i błędy zakończone w sprincie albo między datami, wymagania pogrupowane pod feature'ami | przegląd sprintu, strona wydania na wiki | `adolens release-notes previous`, `adolens release-notes --since 14d` |
+| `ado_undo` | cofa ostatnią zmianę zrobioną przez ADO Lens: przywraca wartości pól (pola zmienione w międzyczasie przez innych zostają i są wymienione), usuwa komentarz, usuwa lub przywraca link, utworzony element przestawia w stan usunięty; zawsze najpierw podgląd; `list=true` pokazuje ostatnie zmiany | „cofnij to”, pomyłka przy zmianie wsadowej | `adolens undo --list`, `adolens undo` |
+| `ado_recipe` | zapisane powtarzalne zmiany: kroki z zapytaniem WIQL (albo id) i tym, co zrobić z każdym elementem - pola, stan, iteracja `next`, tagi, komentarz, element podrzędny z szablonu (`{title}`, `{id}`); `{parametry}`; każde uruchomienie najpierw podgląd, potem potwierdzenie | „zamknij sprint”, „nowy klient” | `adolens recipe run close-sprint --param sprint="Demo\Sprint 6"`, `--yes` dla Harmonogramu zadań |
 
 ### Wbudowane zasady pisania
 
@@ -242,7 +249,7 @@ build.ps1                   kompilacja; -Deploy podmienia binaria w instalacji,
 pack.ps1                    paczka wydania (ZIP + SHA-256)
 release.ps1 release-notes.ps1   wydania (zob. niżej); .github\ workflowy CI i Release, formularze zgłoszeń
 install.ps1 uninstall.ps1   instalacja; get.ps1 to pobranie i instalacja jedną linijką
-skills\                     skille dla Claude'a (po-verify, po-story, po-sprint)
+skills\                     skille dla Claude'a (po-verify, po-story, po-sprint, po-explain)
 docs\PLAN.md                plan rozwoju
 build\  dist\               wyniki (nie trzymaj tu niczego własnego)
 ```
@@ -289,6 +296,7 @@ i publikuje go razem z `.sha256` i opisem z `CHANGELOG.md` (podgląd: `.\release
 | `SetupFlowTests.cs` | wersje i paczki wydań do aktualizacji, tabela zespołu na wiki (w obie strony, strony poprawiane ręcznie), wykrywanie przepływu z release'ów i gałęzi, mapa zespołu na wiki z wersją, mapa lokalna ponad zespołową |
 | `PrPipelineTests.cs` | listy i szczegóły PR-ów (głosy, kontrole, tylko wątki ludzi), akcje na PR (głos, komentarz na linii ze wzmianką, tworzenie), błędy nieudanego buildu i linie logu, uruchamianie pipeline'ów po nazwie, zapis środowisk, odgadywanie przepływu |
 | `TraceTests.cs` | diff linii (Myers, bloki unified), X++ per metoda ze źródłami danych formularza, nazwy obiektów ze ścieżek AOT, `ado_trace` w TFVC i Gicie (wdrożone etapy TAK / JESZCZE NIE, etykiety środowisk, scalone gałęzie, usunięte buildy, kryteria zmienione po rozpoczęciu prac), listy i diffy plików w `ado_changes` |
+| `KnowledgeTests.cs` | wyszukiwanie po work itemach, wiki i kodzie (brak jednej części nie psuje reszty), pliki po nazwie z metodami X++, historia pliku z pull requestami i work itemami, cofanie (wartości wracają, pola zmienione przez innych zostają, komentarze usuwane), higiena backlogu, notatki wydania, przepisy (zapis, podgląd, uruchomienie) |
 | `WikiTests.cs` | drzewo stron, strona z wersją, zastąpienie tylko z aktualną wersją (412 nigdy nie nadpisuje), dopisywanie, tworzenie na istniejącej stronie, fragmenty wyszukiwania |
 | `WorkItemTests.cs` | odpowiedzi o work itemach, pola wymagane i dozwolone wartości przed zapisem, przejścia stanów, podgląd i potwierdzanie zmian wsadowych, wzmianki, linki, zapytania, HTML ⇄ markdown, PAT nigdy do innych hostów |
 

diff --git a/skills/po-explain/SKILL.md b/skills/po-explain/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: po-explain
+description: Explains how a feature works and why it works that way, in business language, from work items, the wiki and the code in Azure DevOps. Use when someone asks "how does X work", "what happens when…", "why does the system do…", "where is this documented", or needs a feature described for users, testers or a new colleague. Needs the ado-lens MCP server.
+---
+
+# Explaining a feature
+
+The reader is a Product Owner or a business user: answer in plain language, in the language the user writes in.
+Technical names (objects, methods, files) only in brackets, or when asked for "details".
+
+## Steps
+
+1. `ado_search text=<feature in the user's words>` — work items, wiki pages and code at once. Try a second wording
+   (a synonym, the English or the local term) when the first finds little.
+2. Read the strongest sources, stop when the question is answered:
+   - wiki pages: `ado_wiki path=<page>`,
+   - work items: `ado_work_item ids=<ids>` — the requirement and its acceptance criteria say what was intended,
+   - code: `ado_file path=<file or name>` (X++ objects show their methods; `part=<method>` one method) — the code says
+     what really happens.
+3. "Why is it like this": `ado_file path=<file> history=true` — who changed it, when and for which work items; read the
+   work item behind the change that matters.
+4. With xpp-lens available (developer machine), its tools give callers and references; without it, stay with the above.
+
+## Answer
+
+Start with one or two sentences that answer the question. Then, as fits:
+- **How it works** — numbered steps "what happens when…", with an example ("an order for 120 pcs → …").
+- A small Mermaid diagram when there is a flow with decisions.
+- **Why** — the decision and its work item ("added in #4821 to stop orders over the credit limit").
+- **Sources** — links to the work items, wiki pages and files used.
+
+Always separate what the **code** does from what the **documentation** says; when they disagree, say so plainly —
+that is worth a work item or a wiki fix. Say "not found" rather than guess.
+
+## Afterwards
+
+Offer, do not do unasked:
+- a wiki page with the explanation (`ado_wiki_write`, ask where),
+- a work item when code and documentation disagree.
diff --git a/src/AdoLens/AdoLens.csproj b/src/AdoLens/AdoLens.csproj
@@ -21,7 +21,7 @@
     <AssemblyTitle>ADO Lens for Azure DevOps</AssemblyTitle>
     <Description>Azure DevOps (work items, boards, wiki, Git and TFVC, pipelines) served to AI assistants over MCP</Description>
     <Copyright>Copyright © 2026 WillowDev</Copyright>
-    <Version>0.3.0</Version>
+    <Version>0.4.0</Version>
   </PropertyGroup>
 
   <ItemGroup>