zhongwei/gh-xloxn69-agileflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
169a5fc5cd26989761ebe66e4f9eeaab94a83213
gh-xloxn69-agileflow/commands/blockers.md
Zhongwei Li 169a5fc5cd Initial commit
2025-11-30 09:07:10 +08:00

12 KiB
Raw Blame History

description, allowed-tools
description allowed-tools
blockers 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= — 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")

# 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)

# 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)

# 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)

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 
    # 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:

# 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)

# 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
Reference in New Issue View Git Blame Copy Permalink