Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Doc Drift

Inspiration

Every team has Confluence pages that describe Jira work: plans, roadmaps, release notes, known-issue lists for support. They're accurate the day they're written. Then the work moves on in Jira: items get finished, closed as duplicates, dropped as won't do, or re-scoped. Nobody goes back to the page. Support quotes a workaround for a bug that was fixed, a roadmap still promises a feature that was cancelled, and new joiners learn a plan that no longer exists.

What it does

Doc Drift tells you when a page has drifted from the Jira work it describes.

  • Finds the work items a page mentions: Jira issue macros, links to work items, and plain keys of known projects (so "ISO-13485" or "UTF-8" aren't mistaken for work items).
  • Checks what happened after the page's last edit, from each work item's history:
    • Dropped: closed as Won't Do, Duplicate, Declined or similar. The page may still describe it as planned.
    • Now done: finished after the page was written.
    • Re-scoped: summary, description, fix version, due date or parent changed.
    • Not found: deleted, moved, or not visible.
  • Gives every page a verdict: Out of date, Needs review, Minor changes or Up to date, with who changed what and when.
  • Where you need it:
    • Under every page title (Confluence byline): the verdict and the list of changes, plus Ask for a review, which adds a footer comment listing exactly what changed, for the page owner.
    • Space report (space sidebar): every page in the space ranked by drift, with the details one click away.
    • In Jira, a "Pages about this work item" panel: the Confluence pages that mention this item, and which were written before its latest change. It uses Jira's "mentioned in" links, which also catch Jira macros that Confluence search doesn't index.
    • Rovo agent "Doc Gardener" and the same tools through MCP: "Which pages in this space are out of date?", "Is this page still accurate?", "Which docs mention WEB-12?"

How we built it

  • Forge, Runs on Atlassian: no egress, no remote backend, no external model. One app across Confluence and Jira:
    • confluence:spacePage, confluence:contentBylineItem and jira:issuePanel (UI Kit)
    • rovo:agent with three read-only actions, exposed through rovo:mcp
  • Confluence REST v2: space pages with storage-format bodies and version dates; footer comments for review requests.
  • Jira REST: key search, bulk changelog fetch, and issue remote links ("mentioned in" Confluence pages). Everything runs as the asking user, so people only see what they're allowed to see.
  • Pure, unit-tested core (src/drift.js): key extraction (macros, links, known-project text), drift classification from the change history after a timestamp, page verdicts, review notes and space summaries.

Challenges we ran into

  • Confluence search doesn't index keys inside Jira macros. Searching for "WEB-54" found nothing, although the page shows it. Jira's remote links ("mentioned in") had the answer, so the Jira panel uses them first and search second.
  • One missing work item breaks a whole JQL query. A page that mentions a deleted item made the batch search fail, so the search splits the batch and retries until it isolates the missing keys, which are then reported as "Not found".
  • False positives. "ISO-13485" looks like a work item key. Plain-text keys only count for projects that exist on the site.

Accomplishments that we're proud of

Open a roadmap page and see, under its title, that the German spelling feature it promises was closed as won't do last week, by whom, and then ask the owner for a review in one click.

What we learned

Docs don't rot randomly. They rot exactly when the work they describe changes, and Jira already records that moment. Comparing the two timestamps turns "our docs are probably outdated" into a precise to-do list.

What's next

  • Scheduled digest to page owners with their drifted pages.
  • Suggested edits: draft the corrected sentence with Rovo, for the owner to accept.
  • Drift from other sources: Compass components, Bitbucket releases.

Built With

Share this project:

Updates

Submission history