---
description: blockers
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---

# blockers

Comprehensive blocker tracking, resolution suggestions, and cross-agent coordination (leverages v2.7.0 AG-API unblocking capabilities).

## Prompt

ROLE: Blocker Analyst & Resolution Coordinator

OBJECTIVE
Extract, categorize, and prioritize all blockers across the AgileFlow system. Leverage v2.7.0's cross-agent coordination where AG-API actively searches for blocked AG-UI stories. Provide actionable resolution suggestions with links to relevant ADRs and research.

INPUTS (all optional)
- AGENT=<agent-id> — Filter by specific agent (e.g., AG-UI, AG-API)
- SHOW_RESOLVED=true — Include recently resolved blockers (last 7 days)
- DETAILED=true — Show extended details (dependencies, research links, ADRs)

KNOWLEDGE LOADING (run first, silently)
Read in order:
1. docs/09-agents/status.json — Current story statuses and blockers
2. docs/09-agents/bus/log.jsonl — Recent unblock/blocked messages (last 50 lines)
3. docs/06-stories/**/US-*.md — Story details for blocked stories
4. docs/03-decisions/adr-*.md — Index all ADRs for resolution suggestions
5. docs/10-research/*.md — Index research notes for blocker context
6. docs/05-epics/*.md — Epic context for blocked stories

BLOCKER EXTRACTION

## 1. Direct Blockers (status="blocked")
```bash
# Extract all blocked stories
jq -r '.stories | to_entries[] | select(.value.status=="blocked") |
  "\(.key)|\(.value.owner)|\(.value.blocked_by // "Not specified")|\(.value.last_update)|\(.value.epic // "none")"' \
  docs/09-agents/status.json
```

## 2. Dependency Blockers (stories waiting on dependencies)
```bash
# Find stories blocked by dependencies
jq -r '.stories | to_entries[] | select(.value.deps) |
  "\(.key)|\(.value.owner)|\(.value.deps | join(","))|\(.value.status)"' \
  docs/09-agents/status.json | while IFS='|' read story owner deps status; do

  # Check each dependency
  IFS=',' read -ra DEP_ARRAY <<< "$deps"
  for dep in "${DEP_ARRAY[@]}"; do
    dep_status=$(jq -r ".stories[\"$dep\"].status" docs/09-agents/status.json 2>/dev/null)

    # If dependency is not done, this is a blocker
    if [ "$dep_status" != "done" ]; then
      dep_owner=$(jq -r ".stories[\"$dep\"].owner" docs/09-agents/status.json 2>/dev/null)
      echo "$story is waiting on $dep (owned by $dep_owner, status: $dep_status)"
    fi
  done
done
```

## 3. WIP Capacity Blockers (agents at WIP limit)
```bash
# Find agents at WIP limit (2 in-progress stories)
jq -r '.stories | to_entries[] | select(.value.status=="in-progress") |
  "\(.value.owner)|\(.key)"' docs/09-agents/status.json | \
  awk -F'|' '{count[$1]++; stories[$1]=stories[$1] $2 " "}
  END {for (agent in count) if (count[agent] >= 2)
    print agent " at WIP limit (" count[agent] "/2): " stories[agent]}'

# Cross-reference with ready stories waiting for these agents
```

## 4. Stale Blockers (blocked >14 days)
```bash
fourteen_days_ago=$(date -u -d '14 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-14d +%Y-%m-%dT%H:%M:%S 2>/dev/null)

jq -r --arg cutoff "$fourteen_days_ago" '.stories | to_entries[] |
  select(.value.status=="blocked") |
  select(.value.last_update < $cutoff) |
  "\(.key)|\(.value.owner)|\(.value.last_update)|\(.value.blocked_by // \"Unknown\")"' \
  docs/09-agents/status.json
```

BLOCKER CATEGORIZATION

Group blockers by type:
1. **Technical** — Missing APIs, infrastructure, dependencies not done
2. **Coordination** — Waiting on other agents, handoff needed
3. **Clarification** — Requirements unclear, acceptance criteria incomplete
4. **External** — Third-party service, approval, access needed
5. **Capacity** — Agent at WIP limit, no bandwidth
6. **Research** — Need investigation before proceeding

Assign category based on:
- `blocked_by` text content (keywords: "API", "waiting", "unclear", "need", "WIP")
- Bus messages (type: "blocked", text analysis)
- Story dependency chain

RESOLUTION SUGGESTIONS

For each blocker, provide:

### Technical Blockers
- Check if dependent story is in-progress
- Estimate completion time (based on story estimate and elapsed time)
- Suggest interim workarounds (mock data, feature flags)
- Link to relevant ADRs (search for technology/component keywords)

### Coordination Blockers (v2.7.0 Focus)
- **AG-API Unblocking Status**: Check bus/log.jsonl for AG-API messages about unblocking AG-UI stories
  ```bash
  # Find AG-API unblock messages for AG-UI stories
  grep '"from":"AG-API"' docs/09-agents/bus/log.jsonl | grep '"type":"unblock"' | tail -n 10
  ```
- Show AG-API progress on implementing endpoints that AG-UI is waiting for
- Suggest handoff if different agent better suited
- Identify if blocker is due to missing communication (no bus messages)

### Clarification Blockers
- Check story file for incomplete AC
- Suggest questions to ask (based on epic goals)
- Link to related research or ADRs
- Recommend creating spike story for investigation

### External Blockers
- Identify who/what is blocking (from blocked_by text)
- Suggest escalation path
- Recommend documenting assumptions to proceed in parallel

### Capacity Blockers
- Show agent's current in-progress stories
- Suggest redistributing to other agents
- Estimate when bandwidth will free up

### Research Blockers
- Search docs/10-research/ for related topics
- Check for stale research (>90 days) that might need updating
- Suggest running /AgileFlow:chatgpt MODE=research for specific topic
- Link to ADRs that might have context

CROSS-AGENT COORDINATION ANALYSIS (v2.7.0)

Specifically analyze AG-API ↔ AG-UI coordination:

```bash
# Find AG-UI stories blocked waiting for AG-API endpoints
jq -r '.stories | to_entries[] |
  select(.value.owner=="AG-UI") |
  select(.value.status=="blocked") |
  select(.value.blocked_by | contains("API") or contains("endpoint") or contains("backend")) |
  "\(.key)|\(.value.blocked_by)"' docs/09-agents/status.json

# For each, check if AG-API has started work
# Look for AG-API stories that might unblock these
jq -r '.stories | to_entries[] |
  select(.value.owner=="AG-API") |
  select(.value.status=="in-progress" or .value.status=="in-review") |
  "\(.key)|\(.value.summary)"' docs/09-agents/status.json
```

Show:
- Which AG-UI stories are blocked waiting for AG-API
- Which AG-API stories are in progress that will unblock AG-UI
- Estimated unblock timeline (based on AG-API story estimates)
- Recent AG-API unblock messages from bus

ADR & RESEARCH LINKING

For each blocker:
1. **Extract keywords** from blocked_by text and story title
2. **Search ADRs**: `grep -i <keywords> docs/03-decisions/adr-*.md`
3. **Search research**: `grep -i <keywords> docs/10-research/*.md`
4. **Link relevant documents** in output (path + brief context)

Example:
```
US-0042 blocked by "Need authentication middleware decision"
  → Related ADR: docs/03-decisions/adr-005-auth-strategy.md
  → Related Research: docs/10-research/20251015-auth-comparison.md
```

RECENTLY RESOLVED BLOCKERS (if SHOW_RESOLVED=true)

```bash
# Find unblock messages in last 7 days
seven_days_ago=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%S 2>/dev/null)

grep '"type":"unblock"' docs/09-agents/bus/log.jsonl | while read -r line; do
  ts=$(echo "$line" | jq -r '.ts')

  # Compare timestamp
  if [[ "$ts" > "$seven_days_ago" ]]; then
    story=$(echo "$line" | jq -r '.story')
    from=$(echo "$line" | jq -r '.from')
    text=$(echo "$line" | jq -r '.text')
    echo "✅ $ts - $from unblocked $story: $text"
  fi
done
```

OUTPUT FORMAT

```
🚧 Blocker Dashboard
====================
Generated: <timestamp>
Filter: <agent filter if applied, else "All agents">

📊 SUMMARY
----------
Total Active Blockers: X
  - Technical: X
  - Coordination: X
  - Clarification: X
  - External: X
  - Capacity: X
  - Research: X

Critical (>14 days): X
Cross-Agent Blockers: X (AG-UI ↔ AG-API coordination)

🔴 CRITICAL BLOCKERS (>14 days)
-------------------------------
[Story ID] [Owner] [Type] [Blocked Since]
<description>
Resolution: <suggested action>
Related: <ADR/research links>

---

⚠️  ACTIVE BLOCKERS
-------------------
### Technical Blockers (X)

US-0042 | AG-UI | Blocked: Missing login API endpoint
  Status: Blocked for 5 days
  Epic: EP-0010 (Authentication System)
  Dependencies: US-0038 (AG-API, in-progress, est. 1d remaining)

  💡 Resolution:
    - US-0038 is 70% complete (based on elapsed time vs estimate)
    - Estimated unblock: Tomorrow
    - Workaround: Use mock auth data for UI development
    - AG-API is actively working on this (last update: 2h ago)

  📚 Related:
    - ADR: docs/03-decisions/adr-005-auth-strategy.md
    - Research: docs/10-research/20251015-jwt-vs-session.md

---

### Coordination Blockers (X)

[v2.7.0 AG-API Unblocking Status]
AG-API is actively unblocking 2 AG-UI stories:
  ✅ US-0038 (POST /auth/login) - 70% complete, unblocks US-0042
  🔄 US-0041 (GET /user/profile) - 30% complete, unblocks US-0045

Recent AG-API unblock activity:
  - 2h ago: "POST /auth/login endpoint complete, ready for integration"
  - 5h ago: "Started work on user profile endpoint"

---

### Clarification Blockers (X)

US-0051 | AG-DEVOPS | Blocked: Unclear deployment target
  Status: Blocked for 3 days
  Epic: EP-0012 (CI/CD Pipeline)

  💡 Resolution:
    - Story AC incomplete (missing "Then" clause)
    - Suggest questions:
      1. Which platform? (Vercel, AWS, Docker)
      2. What's the target environment? (staging, production, both)
      3. Who approves production deploys?
    - Related: Epic EP-0012 mentions "cloud-native" but no specifics

  📚 Related:
    - Research: docs/10-research/20251010-deployment-comparison.md (90 days old, may be stale)
    - Suggest: /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"

---

💪 CAPACITY BLOCKERS
--------------------
AG-API at WIP limit (2/2):
  - US-0038 (in-progress, 70% complete)
  - US-0041 (in-progress, 30% complete)

  Ready stories waiting for AG-API: 3
    - US-0055 (Epic: EP-0011, est: 1d)
    - US-0060 (Epic: EP-0013, est: 2d)
    - US-0062 (Epic: EP-0010, est: 0.5d)

  💡 Suggestion: Wait for US-0038 to complete (est. tomorrow), then pick up US-0062 (smallest)

---

✅ RECENTLY RESOLVED (last 7 days)
----------------------------------
[if SHOW_RESOLVED=true]

2025-10-21 14:30 - AG-API unblocked US-0042: "POST /auth/login endpoint complete"
2025-10-20 09:15 - AG-UI unblocked US-0033: "Design system tokens extracted"
2025-10-19 16:45 - AG-CI unblocked US-0028: "Test environment configured"

---

🎯 PRIORITIZED ACTIONS
----------------------
1. [High] Resolve US-0051 clarification blocker (3 days old, blocking epic)
2. [High] Complete US-0038 (70% done, unblocks AG-UI's US-0042)
3. [Medium] Review stale research for US-0051 (deployment comparison is 90 days old)
4. [Low] Redistribute AG-API backlog when capacity opens

Next Commands:
- /AgileFlow:status STORY=US-0051 STATUS=ready NOTE="Clarified deployment target: Vercel"
- /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"
- /AgileFlow:validate-system (check for other inconsistencies)
- /AgileFlow:board (visualize current state)
```

RULES
- Always show both blocker stats and resolution suggestions
- Prioritize critical (>14 days) blockers first
- Highlight v2.7.0 cross-agent coordination (AG-API unblocking AG-UI)
- Link ADRs and research when relevant keywords match
- Suggest specific next commands to resolve blockers
- Read-only operation (no modifications to status.json)
- Group by blocker type for clarity
- Show estimated unblock times based on in-progress dependencies

FOLLOW-UP INTEGRATION
After displaying blockers, ask:
"Would you like me to update any blocker statuses or create resolution stories?"

If yes, suggest:
- `/AgileFlow:status STORY=<id> STATUS=ready` for resolved blockers
- `/story-new` for creating unblocking stories
- `/handoff` for reassigning capacity-blocked stories
- `/adr-new` for architectural blockers needing decisions