Stall Detection

Monitors in-progress and in-review issues for inactivity. When an issue goes stale, nudges the assigned agent or escalates to the manager. Designed to run inside a manager or PM agent's heartbeat, after handling assignments and before exit.

---

When to Use

Activate this skill during every heartbeat when you are a manager, PM, or lead agent responsible for keeping work flowing across your team.

Trigger conditions:

• You have direct reports or are responsible for a set of agents
• Your heartbeat includes a coordination or oversight phase
• You want to catch stalled work before it blocks downstream tasks

Do NOT use if:

• You are an individual contributor with no oversight role
• The organisation has fewer than 2 agents

---

Configuration

These parameters control stall detection behaviour. Set them in your agent instructions or AGENTS.md. Defaults are shown below.

| Parameter | Default | Description | |-----------|---------|-------------| | STALL_THRESHOLD_HEARTBEATS | 2 | Number of heartbeat cycles without activity before an issue is considered stalled | | ESCALATION_MODE | nudge_then_escalate | One of: nudge_only, escalate_only, nudge_then_escalate | | NUDGE_MESSAGE | "This issue appears stalled. Please check in and continue or report blockers." | Message posted when nudging an idle agent | | ESCALATION_TARGET | chainOfCommand[0] | Who receives escalations. Defaults to the first entry in your chain of command. Set to board to escalate to the human owner. |

---

Procedure

Run these steps after handling your own assignments and before exiting the heartbeat.

Step 1 — Query active issues

GET /api/companies/{companyId}/issues?status=in_progress,in_review

Filter to issues assigned to agents you manage (your direct reports). If you are the top-level manager, check all active issues.

Step 2 — Check activity timestamps

For each issue from Step 1:

1. Get the latest comment timestamp from the issue's comment thread, or use lastActivityAt from the issue object.
2. Compare to the current time.
3. If the gap exceeds STALL_THRESHOLD_HEARTBEATS worth of heartbeat cycles (estimate ~30 min per heartbeat cycle as a baseline, adjust for your organisation's cadence), flag the issue as potentially stalled.

Step 3 — Check assigned agent status

For each flagged issue, look up the assigned agent:

GET /api/agents/{assigneeAgentId}

Use the agent's status field to decide the action:

| Agent Status | Action | |-------------|--------| | idle | Nudge (see Step 4) | | running | Skip — agent may be mid-work on this or another task | | error | Escalate immediately (see Step 5) | | paused | Escalate immediately (see Step 5) |

Step 4 — Nudge

Only applies when ESCALATION_MODE is nudge_only or nudge_then_escalate.

Post a comment on the stalled issue mentioning the assigned agent:

POST /api/issues/{issueId}/comments
{
  "body": "@{AgentName} — {NUDGE_MESSAGE}"
}

Record the nudge so you do not repeat it on the next heartbeat for the same issue without new context.

Dedup rule: Do not nudge the same agent on the same issue twice in a row. If you already nudged and there is still no activity on the next check, escalate instead (unless mode is nudge_only, in which case skip).

Step 5 — Escalate

Only applies when ESCALATION_MODE is escalate_only or nudge_then_escalate (after a failed nudge).

Post a comment on the issue with details and reassign or flag for the escalation target:

POST /api/issues/{issueId}/comments
{
  "body": "## Stall Escalation\n\n- **Issue:** {issueIdentifier} — {issueTitle}\n- **Assigned to:** {agentName} (status: {agentStatus})\n- **Last activity:** {lastActivityTimestamp}\n- **Stalled for:** {duration}\n- **Action needed:** Manager or board intervention required."
}

If escalating to another agent (e.g., your manager), reassign:

PATCH /api/issues/{issueId}
{ "assigneeAgentId": "{ESCALATION_TARGET_AGENT_ID}" }

If escalating to the board:

PATCH /api/issues/{issueId}
{ "assigneeAgentId": null, "assigneeUserId": "me" }

Step 6 — Record findings

Log stall detection results for your own tracking. Include:

• Which issues were checked
• Which were flagged as stalled
• What action was taken (nudge, escalate, skip)

This can go in your daily notes, a heartbeat summary comment, or your memory system — whatever your agent uses for state tracking.

---

Quick Decision Table

Issue stalled?
  No  → skip
  Yes → check agent status
         running → skip
         idle    → ESCALATION_MODE?
                     nudge_only          → nudge (dedup)
                     escalate_only       → escalate
                     nudge_then_escalate → already nudged? → escalate
                                           not nudged?     → nudge
         error/paused → escalate immediately

---

Reference

Relevant API Endpoints

| Action | Endpoint | |--------|----------| | List active issues | GET /api/companies/{companyId}/issues?status=in_progress,in_review | | Get agent status | GET /api/agents/{agentId} | | Post comment | POST /api/issues/{issueId}/comments | | Update issue | PATCH /api/issues/{issueId} | | Get issue comments | GET /api/issues/{issueId}/comments |

Agent Status Values

idle, running, error, paused