Inspiration

Company knowledge rarely lives in one place. A travel policy is written on an HR page, then re-summarized in an onboarding page, a finance FAQ, a knowledge base article, a request type description, and an issue template. Every copy is written in someone's own words, not linked to the source.

When the official source changes, nobody knows where the copies are. Employees and customers keep reading the old version, make decisions on the wrong number, and the policy owner spends weeks explaining again. Confluence macros and document-review apps only help if the author used the right link or workflow from the start. We built Ripple for the reality where copies are freely rewritten, scattered, and disconnected from their source.

What it does

Ripple is a Forge app that keeps an official fact (a policy, price, SLA, or procedure) the same everywhere it is restated. A page owner marks a page as the canonical source. Ripple finds the copies of that fact across Confluence (Jira Service Management and Jira are on our roadmap), flags each copy that is out of date, and prepares a minimal proposed edit for the person who owns that copy. Nothing is ever changed without the owner's approval.

  • Canonical source and facts. Ripple extracts candidate facts from the source page, and the owner confirms which of them are official.
  • Copy scan. Ripple searches Confluence for pages that restate each fact, and Forge LLM judges every candidate. The judge must return an exact quote that Ripple verifies exists in the page text. Copies are marked In sync, Out of date, Unsure, or Historical.
  • Change detection. When the source page is edited, Ripple shows the changed facts in a confirmation dialog. Nothing goes out until the owner confirms.
  • Owner-approved edits. Each affected copy gets a proposed edit that changes only the sentence containing the fact. The copy owner can approve, edit, reject, or mark "Not the same fact". An approved edit is saved as the approving user.
  • Routing and Jira tasks. Each copy owner gets one Jira issue per change, listing their pages and naming the team that owns the space. The issue moves to Done by itself when all of that owner's pages are handled.
  • Rollout and reminders. The source owner sees a rollout with a deadline, a Late badge on overdue owners, and a Remind owners button. A daily check also posts automatic reminders as Jira comments that mention the owner, when the deadline arrives and again when the updates are late.
  • Rovo agent. On sites with Rovo enabled, a Fact Keeper agent answers with the official value from the source page, lists where a fact is repeated and which copies are out of date (by space or owner, including "mine"), and points to the source page for proposing updates. It only uses sources the asking user can read, and it does not edit pages itself.

How Ripple differs from Tripwire and Hindsight (our other Codegeist entries): Tripwire asks "is this decision still valid?"; Ripple asks "does every copy of this fact still match the source?" Tripwire watches the assumptions behind decisions and opens Jira revisit tasks when outside data changes. Ripple watches official facts and their copies in other pages, and produces a proposed sentence revision routed to the page owner. Hindsight routes early signals before incidents in Jira and JSM to the right team and writes to Teamwork Graph through a connector. Ripple is about drift of restated facts, not incidents, and it only reads from Teamwork Graph.

How we built it

Ripple runs entirely on Forge. The UI is Custom UI (React): a Confluence byline item (confluence:contentBylineItem) on source and copy pages, a Jira issue panel on update tasks, and a settings page in Confluence administration (confluence:globalSettings) where a Jira admin picks the Jira project and can load or remove the Nimbus Labs demo data.

Teamwork Graph (our bonus category). Ripple consumes the Teamwork Graph API through requestTeamworkGraph with api.asUser() from @forge/api, using the curated query atlassianTeamsBySpace(spaceAri) to find the team that owns a space. The manifest requests exactly four Teamwork Graph scopes: read:graph:page:confluence, read:graph:space:confluence, read:graph:team:atlassian, and read:graph:user:atlassian.

Page owner. The owner comes from Confluence REST v2 (ownerId, then authorId), and display names come from the Confluence users bulk lookup, read as the viewing user.

Pipeline. Candidate search with CQL, fact extraction and judging with Forge LLM (@forge/llm, runs on Atlassian with no egress) in staged queue consumers, and Forge SQL for sources, facts, copies, proposals, changes, and the audit trail. A trigger on page updates starts change detection. Proposed edits replace the old value in the sentence directly when it can be matched exactly, and fall back to Forge LLM otherwise. Jira issues are the update tasks, and a daily scheduled trigger checks deadlines for reminders. The fact map is kept in Forge SQL, not written to the graph.

Challenges we ran into

The Teamwork Graph page owner lookup did not work for us. In two separate Confluence sites, confluencePageOwners returned an edge whose user node was null, which violates the schema's non-null type, on every selection we tried. confluencePageContributors was partially null. atlassianTeamsBySpace worked in both. We reported it here: https://community.developer.atlassian.com/t/teamwork-graph-confluencepageowners-always-returns-a-null-user-node-non-null-violation-contributors-partially-null-atlassianteamsbyspace-works/103766

So the page owner is read from Confluence REST, and Teamwork Graph supplies the owning team of the space. Teamwork Graph queries also only work from resolvers a user opens (asUser); from web triggers, scheduled triggers, and queues we got 401 NO_IMPERSONATION_SCOPES_DEFINED. Missing scopes return empty results rather than errors, so we check scopes first when a result is empty.

The other challenge is trust. One wrong suggested edit damages confidence more than ten missed copies, so every judgment needs a verified quote.

Accomplishments that we're proud of

  • The full loop works end to end: mark a source, confirm facts, scan copies, confirm a change, approve edits on the copy pages, and watch each owner's Jira issue close by itself.
  • Routing that combines the page owner from Confluence REST with the owning team from Teamwork Graph atlassianTeamsBySpace.
  • A documented, reproducible bug report for the owners query.
  • A clear design principle: Ripple never edits without approval, and every judgment carries a verified quote.

What we learned

Teamwork Graph is strongest for relationships such as spaces and teams today, and user resolution on Preview queries can lag behind. Reading owners from Confluence REST and teams from Teamwork Graph kept routing reliable. We also learned to keep the language precise: facts that have drifted, stale copies, and out of date pages are the problem, not opinions about what is true. Ripple treats the official source as correct.

What's next for Ripple

  • JSM knowledge base articles, request type descriptions, and Jira issue templates as copy locations.
  • Escalating overdue updates to space admins.
  • A content health dashboard.
  • Reading page owners and contributors from Teamwork Graph once the null user node is fixed.

Built With

Share this project:

Updates

Submission history