From dx-core
Generate technical documentation retroactively for completed stories — fetches ADO story, finds linked PRs, searches codebase, and produces wiki-ready docs without needing spec files. Posts to ADO Wiki or Confluence depending on provider config. Use when documentation was never generated during development.
npx claudepluginhub easingthemes/dx-aem-flow --plugin dx-coreThis skill is limited to using the following tools:
You generate technical documentation for stories that are already implemented. Unlike `/dx-doc-gen` (which reads spec files produced during development), this skill discovers everything from the ADO work item and linked PRs. Posts to ADO Wiki or Confluence depending on `tracker.provider`.
Guides project documentation structure, file organization, content requirements by project phase, and best practices for README.md, ARCHITECTURE.md, API docs, and more.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
You generate technical documentation for stories that are already implemented. Unlike /dx-doc-gen (which reads spec files produced during development), this skill discovers everything from the ADO work item and linked PRs. Posts to ADO Wiki or Confluence depending on tracker.provider.
Extract the numeric work item ID from the argument. Accept:
2357516https://dev.azure.com/{org}/{project}/_workitems/edit/2357516https://<org>.visualstudio.com/.../_workitems/edit/2357516If no argument, ask the user for it.
Read .ai/config.yaml for:
tracker.provider — ado (default) or jirascm.org, scm.project, scm.repo-idscm.wiki-id, scm.wiki-project, scm.wiki-doc-rootconfluence.space-key, confluence.doc-root (if provider = jira)mcp__ado__wit_get_work_item
project: <scm.project>
id: <work item ID>
expand: "relations"
Extract:
Sprint41 → Sprint 41)vstfs:///Git/PullRequestId/ URLs)Save sprint to memory for step 6.
If the work item is not found or is not a User Story/Bug, print the error and STOP.
From the relations, extract Pull Request artifact links. The URL format is:
vstfs:///Git/PullRequestId/{projectId}%2F{repoId}%2F{pullRequestId}
For each PR link, extract the pullRequestId and fetch:
mcp__ado__repo_get_pull_request_by_id
repositoryId: <scm.repo-id>
pullRequestId: <extracted PR ID>
Filter: Only keep PRs whose status is completed (discard abandoned, active, and all other non-completed statuses) and whose repository matches scm.repo-id (or any repo in repos: config). Discard PRs to unrelated repos.
For each relevant PR, collect:
If no PRs are linked, warn: No linked PRs found — documentation will be based on story content only. Continue with what's available.
Use the PR data and story content to search the codebase for changed files and patterns.
Strategy A — PR branch exists locally:
git log --oneline --name-only <target-branch>..<source-branch> 2>/dev/null
Strategy B — PR branch doesn't exist (most common for completed PRs): Extract keywords from the story title and PR descriptions. Search using:
Grep for component names, class names, or feature keywords from the title
Glob for file patterns if component names are identified
Focus on:
src/core/components/, src/brand/components/)src/core/themes/, src/brand/themes/)src/*/handlebars/)Strategy C — Cross-reference PR description: PR descriptions often list files or describe the approach. Parse the PR description for:
Collect a deduplicated list of relevant files grouped by area.
Create the spec directory if it doesn't exist:
DIR_NAME=$(bash .ai/lib/dx-common.sh find-spec-dir <work-item-id> 2>/dev/null || echo "")
if [ -z "$DIR_NAME" ]; then
# Create new spec dir using slugify from dx-req
DIR_NAME=$(bash .ai/lib/dx-common.sh slugify <id> "<title>")
mkdir -p ".ai/specs/${DIR_NAME}/docs"
fi
Save the sprint name to $SPEC_DIR/.sprint.
Check if this is an AEM project: read .ai/config.yaml for aem.author-url or aem.author-url-qa. If either exists → AEM project.
.ai/templates/wiki/wiki-page-aem.md.template — demo walkthrough structure.ai/templates/wiki/wiki-page.md.template — standard technical docFollow the template structure, adapted for retroactive documentation (PR links instead of branch, synthesize from PR descriptions instead of spec files).
AEM pages are the deliverable — this is what the customer wants to see. Every wiki page for an AEM project MUST include QA page URLs for both Author Edit and Preview modes.
Read QA URLs from .ai/config.yaml:
aem.author-url-qa — QA Author (e.g., https://qa-author.example.com)aem.publish-url-qa — QA Publisher (e.g., https://qa-publish.example.com)Determine affected components from the story, PR descriptions, and codebase search. Then:
For each component/page, provide:
| Environment | URL |
|---|---|
| QA Author (Edit) | <author-url-qa>/editor.html<page-path>.html |
| QA Author (Preview) | <author-url-qa><page-path>.html?wcmmode=disabled |
The Preview URL (wcmmode=disabled) shows the page as the end user sees it — this is the FE demo view.
If new components were created: Note that the component must be added to a QA page and configured for demo. If no existing QA page contains the component, flag this: ⚠️ Component <name> needs to be added to a QA page for demo.
If the component is only on production pages: Note: Component exists on production pages — no dedicated QA demo page. Still provide the production page paths if discoverable.
Key difference from /dx-doc-gen: No Architecture Decisions, API Changes, or Usage sections unless the PR descriptions explicitly contain that information. Keep it focused on what can be reliably discovered.
Do NOT list every changed file. Group by area (FE/BE/Config) with short descriptions. The Files Changed section should be a brief grouped summary, not a file-by-file changelog. The PR link has the full diff — the wiki page explains the what and why, not every file.
If the user asks to post to wiki, OR if PIPELINE_MODE=true:
Read tracker.provider from .ai/config.yaml (default: ado).
ado → follow Section 6a (ADO Wiki posting).jira → follow Section 6b (Confluence posting).Follow the same wiki posting logic as /dx-doc-gen (step 6a):
scm.wiki-id, scm.wiki-project, scm.wiki-doc-root)<wiki-doc-root>/<Sprint XX>/<id>-<slug>mcp__ado__wiki_list_pages) and check if any page name starts with <id>-. If found, reuse that existing path instead of the newly generated slug. The work item ID prefix is unique per story.mcp__ado__wiki_create_or_update_pageIf scm.wiki-id is not configured, save locally only.
Follow the same Confluence posting logic as /dx-doc-gen (step 6b):
Read confluence.space-key and confluence.doc-root from .ai/config.yaml.
If confluence.space-key is not configured, print: Confluence space key not configured — wiki page saved locally only. and STOP wiki posting.
Find the doc root parent page:
mcp__atlassian__confluence_search
cql: "title = '<confluence.doc-root>' AND space = '<confluence.space-key>'"
Extract page_id → DOC_ROOT_ID. If not found, print error and STOP.
mcp__atlassian__confluence_search
cql: "title = '<SPRINT>' AND ancestor = '<DOC_ROOT_ID>' AND space = '<confluence.space-key>'"
If not found, create it:
mcp__atlassian__confluence_create_page
space_key: "<confluence.space-key>"
title: "<SPRINT>"
body: "<h1><SPRINT></h1><p>Technical documentation for stories in <SPRINT>.</p>"
parent_id: "<DOC_ROOT_ID>"
Check if the doc page already exists under the sprint page.
Content format conversion (CRITICAL):
Skills generate markdown (same as for ADO wiki). Before posting to Confluence, test if the MCP server accepts markdown directly by making a test call. If the page renders correctly with raw markdown, use markdown. If it renders as raw text, convert markdown to basic Confluence storage format (XHTML):
# Heading → <h1>Heading</h1>**bold** → <strong>bold</strong>*italic* → <em>italic</em>- item → <ul><li>item</li></ul><ac:structured-macro ac:name="code"><ac:plain-text-body><![CDATA[...]]></ac:plain-text-body></ac:structured-macro><table><tr><th>...</th></tr><tr><td>...</td></tr></table>[text](url) → <a href="url">text</a>7a. If page doesn't exist — create:
mcp__atlassian__confluence_create_page
space_key: "<confluence.space-key>"
title: "<PAGE_TITLE>"
body: "<converted content>"
parent_id: "<SPRINT_PAGE_ID>"
7b. If page exists — update:
mcp__atlassian__confluence_update_page
page_id: "<existing page ID>"
title: "<PAGE_TITLE>"
body: "<converted content>"
version_number: <current version + 1>
Wiki page created/updated in Confluence: <space-key> > <SPRINT> > <PAGE_TITLE>## dx-doc-retro complete
**<Title>** (ADO #<id>)
- Sprint: <sprint name>
- PRs found: <count> (<pr-ids>)
- Files discovered: <count>
- Output: `<spec-dir>/docs/wiki-page.md`
- Mode: Local / Wiki (posted to <wiki path>)
### Discovery quality:
- Story content: <available/missing>
- PR descriptions: <rich/minimal/none>
- Codebase files: <N files found>
/dx-doc-retro 2357516 — Fetches the completed story from ADO, finds 2 linked completed PRs, extracts implementation details from PR descriptions, searches the codebase for changed component files, and generates docs/wiki-page.md with discovered context.
/dx-doc-retro https://dev.azure.com/myorg/MyProject/_workitems/edit/2357516 — Extracts the ID from the URL, follows the same flow. Discovers 15 relevant files grouped by Frontend/Styles/Templates/Config. Offers to save and optionally post to the ADO wiki.
/dx-doc-retro 2400000 (no linked PRs) — Fetches the story but finds no PR links in relations. Warns about reduced quality, generates documentation from story content + codebase search only, with a note about the limitation.
"No linked PRs found — documentation will be based on story content only" Cause: The story has no PR artifact links in ADO, or PRs were linked to a different work item. Fix: The skill continues with reduced context. For better results, manually link completed PRs to the story in ADO and re-run.
PR branch not found locally Cause: The PR is completed and the source branch was deleted (common after merge). This is the normal case for retroactive documentation. Fix: The skill falls back to Strategy B (keyword search from story title and PR descriptions) and Strategy C (parsing PR descriptions for file paths). No action needed.
Files discovered don't match the actual changes
Cause: The codebase search uses keywords from the story/PR, which may match unrelated files with similar names.
Fix: Review the generated docs/wiki-page.md and remove any incorrectly included files. The skill prioritizes PR descriptions as the most reliable source.
wiki-page-aem.md.template), non-AEM get the standard template.