/
๐Ÿ“˜ How to Use Stuck Issues Guard

๐Ÿ“˜ How to Use Stuck Issues Guard

๐Ÿงญ Overview

Stuck Issues Guard is a Jira Cloud app that automatically detects issues that may be stuck, idle, blocked, or at risk โ€” based on configurable guardrails.

It continuously evaluates issues using workflow status history, activity timestamps, and transition patterns. When a guardrail condition is violated, the app can:

  • Add a comment

  • Mention the assignee or project lead

  • Apply or remove labels

  • Write an audit record

  • Display a visible marker on the issue

It works automatically every hour and can also be triggered manually using Check Project Now.

๐Ÿš€ Getting Started

1๏ธโƒฃ Enable a Guardrail

Open Project Settings โ†’ Stuck Issues Guard.

You will see two main tabs:

  • Templates โ€” preconfigured guardrails

  • Guardrails โ€” detailed configuration view

From the Templates tab, you can enable ready-made guardrails such as:

  • Stuck in To Do

  • Blocked Too Long

  • In Progress Idle

  • Review Ping-Pong

  • Reopened Loop

  • Due Date Risk

Click Enable Template to activate one.

2๏ธโƒฃ Configure Threshold & Scope

Each guardrail allows you to configure:

  • โฑ Threshold (hours)

  • ๐ŸŽฏ Issue Types (optional)

  • ๐Ÿ”Ž Exclude JQL (optional)

  • ๐Ÿ”” Notification target (Assignee / Project Lead)

  • ๐Ÿ’ฌ Comment on activation

  • ๐Ÿท Label behavior

  • ๐Ÿ“Š Audit logging

After saving, the app automatically re-evaluates the project.

3๏ธโƒฃ Run a Manual Scan

Click Check Project Now to:

  • Re-evaluate all enabled guardrails

  • Recalculate violations

  • Update labels and issue markers

  • Clean up disabled guardrail artifacts

Manual scans always reconcile the full project scope.

๐Ÿ“‹ Available Guardrail Types

๐Ÿงฉ Stuck in To Do

Triggers when an issue stays in a To Do-type status longer than the configured threshold.

Recognized status aliases include:

  • To Do

  • Backlog

  • Ready

  • Pending

  • Not Started

  • Grooming

  • Draft

โ›” Blocked Too Long

Triggers when an issue remains in a Blocked-type status beyond the threshold.

Recognized blocked aliases include:

  • Blocked

  • On Hold

  • Waiting for Client

  • Needs Info

  • Paused

  • Dependency

  • Escalated

๐Ÿ›  In Progress Idle

Triggers when an issue in In Progress-type status has no activity for the configured number of hours.

Activity includes:

  • Status transitions

  • Field updates

  • Comments

๐Ÿ”„ Review Ping-Pong

Triggers when an issue transitions repeatedly between:

  • In Review โ†” In Progress

If transitions exceed the configured maximum within the threshold window, the guardrail activates.

๐Ÿ” Reopened Loop

Triggers when an issue enters a Reopened-type status too many times within the threshold window.

๐Ÿ“… Due Date Risk

Triggers when:

  • Due date is within the configured time window

  • Issue is not in Done

๐Ÿ“Š Issue Panel

Open any issue and locate the Stuck Issues Guard panel.

It shows:

  • โœ… Healthy โ€” no active risks

  • โš  Active Risks โ€” guardrail violations

  • โธ Guardrails Disabled โ€” if project-level disabled

For each active risk, youโ€™ll see:

  • Reason

  • Threshold

  • Exceeded by (hours or transitions)

  • Trigger timestamp

  • Suggested actions

A history section shows previous activations and resolutions.

๐Ÿท Labels & Card Marker

When activated, the app can:

  • Add a canonical template label

  • Remove it automatically when resolved

  • Maintain label consistency

  • Update a custom issue field:

    Stuck Issues Guard

The field displays a marker like:

FG: STUCK TODO, BLOCKED TOO LONG

Markers automatically update as guardrail states change.

๐Ÿ“ Comments & Notifications

If configured, the app posts a structured comment:

  • Guardrail name

  • Reason

  • Threshold

  • Current status

  • Optional @mention (Assignee or Project Lead)

Cooldown logic prevents repeated spam notifications within the configured cooldown period.

๐Ÿ“Š Audit Tab

The Audit tab provides:

  • Trigger history

  • Resolution history

  • Actions taken

  • Scan origin (manual / scheduled)

  • Time filters (7d / 30d)

  • Guardrail filters

  • Issue search

Each event records:

  • Issue key

  • Guardrail

  • Reason

  • Actions taken

  • Timestamp

๐Ÿ”„ How It Works

The app uses Jira REST APIs:

  • /rest/api/3/search/jql

  • /rest/api/3/issue/{key}

  • /rest/api/3/issue/{key}/changelog

  • /rest/api/3/project/{key}

Evaluation Process

  1. Build JQL from guardrail scope

  2. Fetch candidate issues

  3. Load changelog when needed

  4. Evaluate violation logic

  5. Compare with previous state

  6. Apply actions if state changes

  7. Sync labels and issue marker

  8. Write audit record

Scheduled evaluation runs hourly.

Manual scan runs in batched mode with execution limits to stay within Forge runtime constraints.

๐Ÿงน Automatic Cleanup

When a guardrail is disabled:

  • All issue states are removed

  • Managed labels are cleaned up

  • Marker field is updated

  • Audit remains intact

Resolved states are retained for 30 days before cleanup.

๐Ÿ›ก Permissions & Data

The app reads:

  • Issue key, status, labels, assignee

  • Due date

  • Updated & created timestamps

  • Changelog transitions

  • Project lead info

The app writes (if enabled):

  • Issue comments

  • Labels

  • Custom issue field value

  • Audit records (stored in app storage)

No data is stored outside Forge storage.

๐Ÿ’ก Best Practices

  • Keep status names consistent and intuitive

  • Use threshold values aligned with team SLAs

  • Enable audit logging for retrospectives

  • Use manual scan after large workflow changes

  • Configure cooldown to avoid noise