Inspiration

Software teams make binding technical choices in Jira issue text: which database to use, what is out of scope for v1, which framework or auth model to ship. Those lines are easy to scroll past. Weeks later, a new issue can quietly contradict them, and nobody has a reliable place to notice.

Atlassian already supports recording decisions by hand, for example with a Confluence DACI template. What we wanted was something that lives where the conversation already happens: in Jira, on the issue, with a human still in charge of what becomes official.

Decision Catch is our attempt to give software teams that context at the moment a later issue starts to drift.

What it does

Decision Catch is a Forge app for Jira Cloud. It does five things:

  1. Catch. It scans an issue's description and comments for candidate decisions, using deterministic heuristics: phrases such as "we decided to use," "going with," "won't use," or "out of scope." There is no paid LLM in the loop. The matches are explainable and can be dismissed when they are wrong.
  2. Approve. A Jira issue panel lists each candidate and lets a person approve or dismiss it. Approved decisions are shown as cards with the approver (Jira User component) and the date. Only approved decisions are stored, with the source issue, approver, and timestamp.
  3. Detect drift. When you open another issue, the app compares its text with the approved decisions in the project. If it finds a contradiction, the panel shows an active drift card with a warning border and a link back to the original decision. It catches alternative technologies (for example MongoDB vs PostgreSQL, Angular vs React, OAuth vs JWT) and scope violations (for example implementing something the team already marked out of scope). In a live demo on a fictional Payments API (PAY) project, the panel reported:
    • PAY-6 (migrate to MongoDB): Issue uses "mongodb" instead of decided "postgresql"
    • PAY-5 (merchant SSO): Issue implements "sso", but decision was to exclude it from scope and Issue uses "oauth" instead of decided "jwt"
    • PAY-7 (Angular prototype): Issue uses "angular" instead of decided "react"
  4. Resolve, and keep an audit trail. On an active drift card you can choose Mark as intentional change or Not a conflict, and optionally leave a note. The resolved card stays visible, with the reason, who resolved it, when, and the note. The app also posts a Jira comment that mentions the resolver, and adds the label decision-drift-resolved so the same action appears in the issue History tab.
  5. Ask in Rovo chat. A Rovo agent named Decision Catch can list approved decisions and check an issue for drift. This was verified live in Jira's Rovo chat: "Check PAY-6 for drift" returned the MongoDB vs PostgreSQL drift and the original decision from PAY-1; "List all decisions for project PAY" listed decisions with approver names and dates. The panel works without the agent.

A Jira admin page titled Decision Catch Settings explains what data the app stores and can clear stored decisions, drift resolutions, and dismissals after a confirmation step. That is how we reset the demo between runs.

How we built it

The app is a native Forge app on the Node.js 24.x runtime, installed on Jira Cloud.

  • UI. The issue panel and the admin page are Forge UI Kit views built with @forge/react v10 and React 18. The front end calls backend functions with invoke from @forge/bridge. Decisions and drift items are shown as cards with clean borders and rounded corners. Active drift cards use a warning border. Approvers and resolvers are rendered with the UI Kit User component.
  • Resolvers. A Forge resolver loads issue text, extracts candidates, reads and writes approved decisions, and runs drift checks when the panel opens. Backend Jira calls use @forge/api (asUser(), with an asApp() fallback).
  • Storage. Approved decisions, dismissals, and drift resolutions are stored with the Forge Storage API. There is no external database and no external egress. forge deploy reported the app as eligible for the Runs on Atlassian program. That is a technical property of the app (data stays on Atlassian infrastructure). It is not a Codegeist 2026 prize or bonus.
  • Jira trail. When a person resolves a drift, the resolver posts an ADF comment that mentions them and adds the decision-drift-resolved label, because Jira's History tab records field changes.
  • Triggers. Forge triggers listen for avi:jira:created:issue and avi:jira:updated:issue.
  • Rovo. The manifest includes a rovo:agent module named Decision Catch and three actions (list-decisions, check-drift, explain-changes) implemented in src/rovo.js. list-decisions and check-drift were verified in Jira's Rovo chat. explain-changes is implemented and covered by unit tests, but has not been tested live.
  • Jira data. Issue descriptions and comments from Jira REST v3 arrive as Atlassian Document Format, so the extractor first flattens ADF to text.
  • Scopes. read:jira-work, write:jira-work, read:jira-user, storage:app.
  • Tests. Extraction, drift, resolver, and Rovo logic is covered by Jest. On 20 November 2026, npm test on the public default branch (main, commit 8bb46e7) reported 147 tests passing, 4 suites. The tests run offline. The repository README's v3.0.2 changelog records the same count.

Core extraction and drift detection have no paid external APIs.

Challenges we ran into

Four problems from building and deploying the app shaped the final design.

Forge UI Kit did not match older examples. We were on @forge/react v10, and several patterns from earlier docs or samples did not apply. ButtonSet is not a component (the working equivalent is ButtonGroup). Badge is numeric, so text labels use Lozenge. Button labels are children, not a text prop. invoke comes from @forge/bridge, not from @forge/react. Getting those details wrong meant a panel that would not deploy or would not render.

Jira issue bodies are ADF, not plain text. REST v3 returns descriptions and comments as Atlassian Document Format objects. A first pass that treated the body as a string missed the actual decision text. We added an ADF-to-text walk so the heuristics see the same words a person sees in the comment.

Useful drift warnings needed careful false-positive work. Early matching treated postgres and postgresql as different technologies, and it could compare a database decision with something in another category, such as Redis. Mentions of a technology as a source ("switching from PostgreSQL to MongoDB") also needed to be handled so the warning names the new choice against the decided one. We tightened keyword extraction with whole-word matching, synonym handling, category checks, same-issue skip (a decision should not drift against the issue it came from), and scope-stopword filters. The PAY-5, PAY-6, and PAY-7 cases above are the result of that tuning, verified on a live site.

A resolution had to show up where Jira users already look. The History tab only records field changes, so marking a drift as resolved in app storage was not enough to appear there. We post a comment that mentions the resolver, and we add the decision-drift-resolved label so the same action is visible in Comments and in History. Separately, the first version of the Rovo agent did not reliably read the issue or project key from a chat prompt. We fixed how the actions receive that input, then verified check-drift and list-decisions live in Jira's Rovo chat.

Accomplishments that we're proud of

  • A working Forge issue panel on a live Jira Cloud site: extract a candidate, approve or dismiss it, and see approved decisions as cards with the approver and date.
  • Verified drift results on the fictional Payments API demo for PAY-5, PAY-6, and PAY-7, with the wording listed above. Active drift cards use a warning border.
  • Verified resolve flow: mark a drift as an intentional change or not a conflict, optionally leave a note, and see the resolved card stay visible with the reason, who, when, and the note. A Jira comment is posted, and the decision-drift-resolved label appears in History.
  • A Rovo agent, verified in Jira chat, that can check an issue for drift and list a project's decisions with approver names and dates.
  • An admin settings page that explains what is stored and can reset demo data after confirmation.
  • 147 Jest tests in 4 suites around extraction, drift, resolvers, and Rovo actions, including the live demo cases. Re-run on 20 November 2026 on main (8bb46e7); the tests run offline.
  • No external egress. The core path uses explainable heuristics, with a person approving every stored decision, and no paid model required.

We are not claiming production users, time saved, or testimonials. This is a hackathon app demonstrated with fictional demo data.

What we learned

  • Small UI Kit mismatches are enough to break a Forge panel, so the component set and the bridge API have to match the version you actually ship.
  • Anything that reads Jira Cloud content has to speak ADF, not only string fields.
  • A drift detector is only useful if it stays quiet on synonyms and on the originating issue, and specific when a later issue really chose a different technology or pulled something back into scope.
  • If a resolution should be auditable, it has to land in Jira's own comments and History, not only in app storage.
  • A Rovo action has to read the issue or project key from the shape of input Forge actually sends, or a prompt that looks clear to a person will still fail.

What's next for Decision Catch

  • Live-test the remaining Rovo action, explain-changes, before describing it as a demonstrated feature.
  • Keep the human approval step. If we add optional LLM-assisted extraction later, it should remain a candidate generator, not an automatic source of truth.
  • Possible later follow-ups, not in the current app: notifications when drift appears, and links out to ADRs in Confluence.

Built With

Share this project:

Updates

Submission history