Inspiration

The most expensive sentence in a design doc is the one nobody re-checks.

"Checkout handles 1,000 orders a minute." "The vendor API never exceeds 200 ms." "Users never upload files over 10 MB."

Every engineering project starts with bets like these. Then the project gets built, and Jira fills up with bugs and incidents. Some of them quietly prove those bets wrong. But the bug lives in Jira, the claim lives in Confluence, and nothing connects them. The doc stays calm and confident while reality has already moved on, and the team finds out in a postmortem, the most expensive moment to learn it.

I wanted Confluence to notice, not just record.

Hindsight is built on three principles:

  • Evidence, not accusation. A Jira issue that merely mentions the same words is related evidence, never proof. Hindsight says "at risk" for that and "contradicted" only when the defined criteria are met or a person confirms it.
  • Numbers from code, judgement from AI. Every count, status, and issue key is computed by plain code. AI only reads and explains, and it can never change a number or a status.
  • A human decides. Hindsight drafts and proposes. A person signs off before anything changes, and only an administrator can accept a risk, with a written reason and an expiry.

Assumptions shouldn't fail in silence.


What it does

Hindsight gives every assumption in a Confluence design doc a tripwire: a Jira query, a threshold, and a time window, such as "bugs in project HSW from the last 14 days, trips at 3 or more." It gives software teams the context to ship with confidence before launch day instead of after it.

1. Tripwires on every assumption

  • Suggests assumptions from the page text, and a person confirms each one before it is saved
  • Tripwires come from templates or custom JQL, and the JQL is validated against Jira before it is saved.
  • Check now, and an hourly scheduled checker re-evaluates every tripwire in plain code with no AI call.

2. Five honest statuses

  • *Healthy, at risk, contradicted, unverified, stale, from an evidence-confidence model
  • People review each evidence issue, and the status follows the reviews.

3. One ticket per problem

  • When an assumption needs attention, Hindsight creates one Jira "Revisit assumption" ticket with the evidence, a plain-English impact note, and a suggested owner.
  • No duplicates, even if two checks overlap. If the ticket was resolved and the problem returns, a new one opens.

4. A plan a person approves

  • An evidence comment, the suggested owner, follow-up tasks, and a revised sentence for the doc
  • Nothing happens until a person ticks the steps and clicks Apply.

5. Is this release safe to ship?

  • Link assumptions to a release and get a verdict, ready, at risk, blocked, or unknown, from fixed rules, with the reasons
  • Only an administrator can knowingly accept a risk, with a written reason and an expiry.

6. Assumption Health Dashboard

  • Filters, search, links to the page and the ticket, release views, and an audit log of who changed what and when
  • Doc freshness: Has Jira work changed since the page was last edited?

7. One-click Demo mode

  • A design doc, Jira issues, and assumptions in about 15 seconds, so a judge needs zero setup

8. A Rovo agent you can trust

  • Ask, "Which assumptions are broken?" *"Is this release safe to ship?" or "What assumptions does this page make?"
  • Ask, "Explain why this one needs attention," and it judges each evidence issue, labelling that judgement as its own.
  • It saves nothing without an explicit yes, and it cannot close a ticket.

The trust model, in three layers

  1. Plain code decides: counts, statuses, owners, and release verdicts
  2. AI explains: reads the evidence, writes the go/no-go brief, and drafts the plan
  3. **A human approves every change and every accepted risk.

How I built it

  • Frontend: Forge UI Kit (React via @forge/react) with a Confluence page panel (confluence:contentBylineItem), a global page (`), and a settings page (confluence:globalSettings`)
  • Backend: Forge functions on Node.js 24 with a shared core of small, pure, testable functions: tripwire, assessment, checker, extraction, drift, and release rules
  • Storage: Forge key-value storage (@forge/kvs) for assumptions, settings, locks, and a capped audit log, plus a Jira issue property on each revisit ticket so a Rovo session on a Jira ticket sees what Confluence saved.
  • Scheduling: an hourly `scheduledTrigger check that re-checks every assumption with plain code
  • Atlassian APIs: Jira REST v3 (approximate count, search/jql, issue create, comments, assign, issue properties) and Confluence REST v2 (page body, version date, pages, footer comments)
  • Rovo: a rovo:agent with a strict prompt (never invent numbers, cite only issue keys and links that actions return, save nothing without a yes) and 14 actions, including list-assumptions, explain-assumption, get-page-content, save-assumption, release-readiness and propose-resolution
  • Trust and permissions: reads shown to people run as that person (asUser), while the scheduler and ticket creation run as the app (asApp). The dashboard hides assumptions on pages the viewer can't open. Settings, demo data, and risk acceptance are admin-only. Everything stays inside. Forge, with no external servers or API keys
  • Quality: 94 unit tests (node:test), forge lint clean, retries on rate limits and plain-English errors

Challenges I ran into

  • Forge storage is separate for the Jira and Confluence installations of one app. An Rovo session started from a Jira ticket; I couldn't see data saved from Confluence. I keep a small summary on the revisit ticket as a Jira issue property, so both sides agree.
  • Keyword matching is not proof. My first version called any matching issue a contradiction. I replaced it with an evidence-confidence model: related evidence is "at risk," and only if it meets criteria or a person's review makes it "contradicted."
  • Duplicate tickets under concurrency. "Check now," and the hourly run can overlap. A short lock, a search for an open ticket by title, and saving the ticket key straight away mean one problem: never getting two tickets. A test simulates five scheduled runs on one broken assumption and expects exactly one creation.
  • Rovo agents invent details when unconstrained, such as a made-up site address. My actions return real links, and the prompt forbids building any other
  • Rovo needs a Rovo-enabled site, so I tested the agent on a separate one.
  • Some UI Kit styling crashed the app silently. I bisected it and removed it.

Accomplishments that I'm proud of

  • A complete product, not a proof of concept: page panel, dashboard, settings, scheduler, Rovo agent, demo data, audit log, and docs
  • A trust model I can defend: numbers from code, a human decision before any change, admin-only risk acceptance
  • A demo that works in one click on a fresh site
  • Forge-native from end to end: no external servers, services, or API keys
  • 94 passing unit tests around the rules that must be exactly right

What I learned

  • Use AI where understanding is needed, such as reading a page or judging whether an issue is related, and plain code for everything that must be exactly right. That split is what makes an assistant people can trust.
  • Evidence needs a vocabulary. "Related," "at risk," and "contradicted" are different claims, and the product is more credible when it keeps them apart.
  • How Forge installations, storage, scopes, and Rovo actions fit together across Jira and Confluence

What's next for Hindsight

  • Suggest the tripwire for a sentence automatically, always with confirmation
  • Use Jira issues already linked to a page as its "area," so there is no query to write.
  • Validate Hindsight with real engineering teams, then add Teamwork Graph integration and a marketplace listing.

Built With

  • atlassian-forge
  • confluence
  • confluence-rest-api
  • eslint
  • forge-kvs
  • forge-resolver
  • forge-scheduled-triggers
  • forge-ui-kit
  • javascript
  • jira
  • jira-rest-api
  • jql
  • node-test
  • node.js
  • react
  • rovo
  • rovo-actions
  • rovo-agent
Share this project:

Updates

Submission history