Inspiration

Every software team makes dozens of decisions a month: which database, which queue, which vendor. They happen in Jira comments. Six months later someone asks "why did we pick this?" and nobody can find the answer. The thread is buried, or the person who argued for it has left. Teams re-open settled debates or quietly break assumptions they didn't know existed.

Architecture Decision Records solve this, but almost nobody keeps them up, because writing one is a chore separate from the discussion itself. We wanted decision records that write themselves from the conversation the team already had.

What it does

Decision Ledger records what a team decided, why, and what else it considered, then finds that reasoning again when anyone asks. It works in three places:

  • Rovo agent: on any Jira issue, ask the Decision Ledger agent to "record a decision from this issue". It reads the comments, drafts the decision, rationale, alternatives and tags, and waits for you to confirm before saving. Later, anyone can ask "why didn't we use SQS?" and the agent answers only from the ledger, citing the decision ID and linked issues. If nothing was recorded, it says so instead of guessing.
  • Jira UI: a Decisions panel on every issue, and a Decision Ledger page with stats, a status chart, search, filters and status changes. When a decision replaces an older one, both records point to each other, so nobody follows outdated advice.
  • MCP server: developers don't live in Jira. Decision Ledger exposes its tools over Atlassian's Forge MCP endpoint, so Claude Code, Cursor or any MCP client can look up and record decisions from the editor.

Every recorded decision also leaves a short comment on its linked Jira issues, so the issue points back to the reasoning.

How we built it

Decision Ledger is a single Forge app, built entirely on Atlassian's platform:

  • Six Forge actions (read issue discussion, record, find, get, list, update) power everything. The same actions back the rovo:agent and are exposed as tools in the rovo:mcp module, so Rovo and MCP clients share one implementation.
  • Decisions are stored in Forge Key-Value Storage, with an index per Jira issue for fast lookups. IDs (DL-1, DL-2…) are sequential per site.
  • Jira issues are read and commented on through the Jira REST API as the current user, so people only see issues they already have access to.
  • The issue panel and register page are built with UI Kit (@forge/react).
  • The ledger logic (IDs, search ranking, superseding) is plain JavaScript with unit tests.

Challenges we ran into

  • Rovo action limits: actions allow at most 10 inputs, and context is reserved by Rovo, which collided with our own field. We trimmed inputs and renamed it background.
  • Getting the agent to wait: an agent that saves records on its own is risky. We tuned the prompt and action descriptions so it always drafts first and records only after the user confirms.
  • Search without embeddings: search is keyword-based, scored across title, tags, decision text, alternatives and rationale, with a boost for issue keys and a penalty for superseded or rejected decisions.
  • MCP in Preview: exposing the tools required enabling them per site in Atlassian Administration and setting the app to sharing.

Accomplishments that we're proud of

  • One ledger, three surfaces: a decision recorded in Rovo shows up instantly in Claude Code, and the other way round.
  • The agent never invents reasons. Every answer cites a decision ID.
  • It's 100% Forge and eligible for Runs on Atlassian, so team data never leaves Atlassian.

What we learned

The hard part of decision records isn't storage. It's capturing them at the moment the decision is made. Letting an agent draft from the real discussion, with a human confirming, turns a chore into a ten-second step.

What's next

  • Per-project visibility that follows Jira project permissions
  • Confluence support: record decisions from pages and publish the register as a page
  • Teamwork Graph integration, linking decisions to pull requests, pages and people
  • Semantic search for larger ledgers
  • A Marketplace listing

Built With

Share this project:

Updates

Submission history