-
-
The problem: a decision that lives in a forgotten comment.
-
A decision comment with Supersedes: the app records DL-3 and DL-2 is no longer in force.
-
The panel on a work item that goes against a decision in force, with a link to where it was decided.
-
The Rovo agent reports what the check-proposal action found.
Inspiration
A payments team decides, after two refunds were applied twice: PostgreSQL for all payment data, no MongoDB. Weeks later someone who missed that incident opens a work item to cache refund sessions in MongoDB. The decision exists. It is a comment on a ticket nobody remembers, and searching for it only works if you already know it is there.
What it does
- Record a decision with a comment. A Jira comment whose first line starts with
Decision:is recorded. Optional lines:Avoid:(terms later work is checked against),Scope: component=… / label=…,Supersedes: DL-n. The app replies with the id it recorded (DL-6). - Warn on the work item. The Decision Ledger panel on a work item shows each decision in force that the work item goes against, the term that matched, since when, and a link to the comment where it was decided.
- See the ledger. A Jira page lists every decision the viewer may see, newest first, with "in force" or "superseded by DL-n", and checks the hash chain on every load.
- Ask the Rovo agent. "Is DL-3 still in force?" or "Can PAY cache refund sessions in MongoDB?" The agent has two read-only actions, and its instructions say to report what they return.
- Load demo. One button adds a short history to a project you pick (a first decision to use MongoDB, the post-incident decision that supersedes it, and a later work item that goes against the new one), so a judge sees a warning within a minute of installing.
What code decides, and what the model does
Whether a comment is a decision, whether a decision is still in force, and whether a work item conflicts with it are decided by code, the same way every time. Matching is whole-word and case-insensitive (Mongo does not match MongoDB). It runs only inside the decision's project, and inside its scope if it has one. Supersedes only works on an existing decision, still in force, in the same project. The Rovo agent's instructions say to report the actions' results and not to judge conflicts itself. The app uses no LLM of its own.
Why the ledger can be trusted
Rows are only inserted; there is no update or delete path in the code. Each row stores the sha256 of its content plus the previous row's hash, and the page recomputes the chain on every load. The database enforces unique ids, unique source comments and unique hashes, so a repeated event cannot record the same comment twice.
Who sees what
Every visibility check runs as the person looking. The panel, the ledger page and both Rovo actions show a decision's text only if that person can open the work item it came from. This is checked per work item, because Jira issue security can hide single work items inside a visible project. Comments restricted to a group or role, and internal service-desk comments, are not recorded. The proposal check needs project access first and counts only decisions the person can see. The ledger stores no account ids: the source comment shows who wrote it.
How we built it
Atlassian Forge, all on Atlassian's platform (no outside servers):
avi:jira:commented:issuetrigger (ignoreSelf) records decisions.- Forge SQL holds the ledger (insert and select only).
jira:issuePanelandjira:globalPagein UI Kit.rovo:agentwith twoGETactions:explain-decisionandcheck-proposal.api.asUser()for every visibility check;asApp()only to post the reply and to create demo work items after checking, as the user, that they may create work items and comment in that project.- 14 tests, including property-based tests (fast-check) for the parser, the matcher and the hash chain.
Challenges
- Visibility. Three security reviews of my own code each found a way to see or infer decisions from work items the viewer cannot open: a comment in one project superseding another project's decision; the ledger page checking projects instead of single work items; the Rovo proposal check working as an oracle for a hidden project's Avoid terms. All three are fixed (commits 0059a42, 67c21b1, 4cba65f).
- Personal data. The first version stored the author's account id in rows that can never be deleted. It now stores none.
- Jira Product Discovery projects do not show issue panels in their idea view, so the demo loader leaves them out.
What it does not do
- Matching only knows the words in
Avoid. A proposal can go against a decision without using them; the panel and the agent say so. - The warning appears on the work item after creation, not on the create screen.
- The panel has to be added once from the work item's Apps menu.
- Not yet tried by a real team. Tested on one developer site (production install) and one Atlassian demo site (development install, for Rovo).
How it differs
Audit-log apps (e.g. Immutable Ledger for Jira, Codegeist 2025) record what happened. Decision Ledger records what a team decided, tracks which decisions are still in force and what replaced them, and checks new work against them where the work happens.
What's next
Register decisions from Confluence pages; a check on the create screen; real-team trial.
Built With
- atlassian-forge
- fast-check
- forge-sql
- javascript
- jira
- rovo
- ui-kit
- vitest