jira-realitycheck

RealityCheck: Silent Blocker Detector for Jira

Comment

RealityCheck: Silent Blocker Detector for Jira

Inspiration

In fast-moving teams, Jira issues often stall silently: assignees get overwhelmed, updates stop, and deadlines slip without anyone noticing until it’s too late. We wanted to build a simple, proactive tool that automatically detects these hidden risks — turning Jira’s raw data into clear, actionable insights so teams can spot problems early and keep projects on track.

What it does

RealityCheck analyzes Jira issues in real time and highlights potential risks:

  • Silent Blockers: Flags issues in "In Progress" with no comments for >3 days and a due date.

  • Reality Score (0–100):

    • −30 if silent blocker
    • −20 if overdue
    • −10 if assignee has >5 open issues
      Formula:
      $$ \text{Score} = 100 - 30 \cdot \mathbb{I}(\text{silent blocker}) - 20 \cdot \mathbb{I}(\text{overdue}) - 10 \cdot \mathbb{I}(\text{open issues} > 5) $$

  • Per-issue panel: Shows score, status badge (Safe / At Risk / Critical), and warnings.

  • Project dashboard: Simple overview of total issues, silent blockers, and critical items.

How we built it

  • Created with Atlassian Forge using the UI Kit template (forge create)
  • Added modules: jira:issuePanel for per-issue view and jira:projectPage for dashboard
  • Fetched data using @forge/bridge → requestJira to call Jira REST API v3
  • Implemented logic in Forge UI components with @forge/ui hooks (useState, useEffect, useProductContext)
  • Deployed serverlessly with forge deploy and installed via forge install --upgrade
  • Tested on a free Jira Cloud site with dummy Scrum project and custom test issues

Challenges we ran into

  • Permissions & scopes: API calls failed (403 Forbidden) until we added read:issue:jira, read:application-role:jira, etc., and upgraded the installation
  • UI Kit quirks: Hooks must come from @forge/ui (not react), or "React is not defined" crashes occur
  • Webpack polyfills: buffer module error fixed with npm install buffer + custom webpack.config.js
  • Debugging: Errors hidden behind "Loading..." in Jira — solved by adding visible error messages in the UI
  • Ad blocker interference: Atlassian telemetry blocked, but unrelated to app logic

Accomplishments that we're proud of

  • Built a fully functional MVP that deploys cleanly to any Jira Cloud site
  • Created a simple yet powerful scoring system that accurately flags real risks
  • Overcame multiple Forge-specific hurdles (scopes, hooks, polyfills) to make it work
  • Delivered a polished hackathon-ready product with both issue-level and project-level views

What we learned

  • Forge UI Kit is excellent for native Jira apps but requires strict adherence to its conventions (hooks from @forge/ui, correct resource paths)
  • Importance of visible error handling in production apps (Jira hides errors by default)
  • How to debug Forge bundler and network issues (verbose deploy, console logs)
  • Jira Cloud REST API is flexible but needs precise permissions for JQL and issue properties

What's next for RealityCheck

  • Make dashboard dynamic with real-time JQL queries
  • Allow configurable thresholds (e.g., days without update, max open issues)
  • Add notifications or email alerts for critical issues
  • Visualize assignee workload with charts
  • Support multiple projects or team-level insights

RealityCheck helps teams turn hidden Jira risks into visible opportunities to act early — we’re excited to keep improving it!

Built With

  • and-ran-jql-searches-for-open-issues-**node.js**-?-runtime-environment-(nodejs24.x)-configured-in-forge-**webpack**-?-bundling-(with-custom-`webpack.config.js`-for-`buffer`-polyfill)-**npm**-?-package-management-(dependencies:-`@forge/ui`
  • assignee-info
  • atlassian
  • badge
  • buffer`)-no-external-databases
  • built-with-**atlassian-forge**-?-core-platform-for-building-and-deploying-the-app-natively-inside-jira-cloud-**forge-ui-kit**-?-used-for-rendering-the-issue-panel-and-project-page-with-native-jira-components-(text
  • cloud
  • comments
  • due-dates
  • etc.)-**javascript-(es6+)**-?-primary-programming-language-**@forge/bridge**-?-for-making-authenticated-rest-api-calls-to-jira-from-the-frontend-**@forge/ui**-?-provided-react-like-hooks-(`usestate`
  • everything
  • forge
  • forge/bridge`
  • heading
  • inside
  • needed
  • or
  • runs
  • sectionmessage
  • serverlessly
  • servers
  • services
  • useeffect`
  • useproductcontext`)-and-ui-components-**jira-cloud-rest-api-v3**-?-fetched-issue-details
  • were
Share this project:

Updates