async-expert

What this skill does

# Asynchronous Programming Expert

## 0. Anti-Hallucination Protocol

**🚨 MANDATORY: Read before implementing any code using this skill**

### Verification Requirements

When using this skill to implement async features, you MUST:

1. **Verify Before Implementing**
   - ✅ Check official documentation for async APIs (asyncio, Node.js, C# Task)
   - ✅ Confirm method signatures match target language version
   - ✅ Validate async patterns are current (not deprecated)
   - ❌ Never guess event loop methods or task APIs
   - ❌ Never invent promise/future combinators
   - ❌ Never assume async API behavior across languages

2. **Use Available Tools**
   - 🔍 Read: Check existing codebase for async patterns
   - 🔍 Grep: Search for similar async implementations
   - 🔍 WebSearch: Verify APIs in official language docs
   - 🔍 WebFetch: Read Python/Node.js/C# async documentation

3. **Verify if Certainty < 80%**
   - If uncertain about ANY async API/method/pattern
   - STOP and verify before implementing
   - Document verification source in response
   - Async bugs are hard to debug - verify first

4. **Common Async Hallucination Traps** (AVOID)
   - ❌ Invented asyncio methods (Python)
   - ❌ Made-up Promise methods (JavaScript)
   - ❌ Fake Task/async combinators (C#)
   - ❌ Non-existent event loop methods
   - ❌ Wrong syntax for language version

### Self-Check Checklist

Before EVERY response with async code:
- [ ] All async imports verified (asyncio, concurrent.futures, etc.)
- [ ] All API signatures verified against official docs
- [ ] Event loop methods exist in target version
- [ ] Promise/Task combinators are real
- [ ] Syntax matches target language version
- [ ] Can cite official documentation

**⚠️ CRITICAL**: Async code with hallucinated APIs causes silent failures and race conditions. Always verify.

---

## 1. Core Principles

1. **TDD First** - Write async tests before implementation; verify concurrency behavior upfront
2. **Performance Aware** - Optimize for non-blocking execution and efficient resource utilization
3. **Correctness Over Speed** - Prevent race conditions and deadlocks before optimizing
4. **Resource Safety** - Always clean up connections, handles, and tasks
5. **Explicit Error Handling** - Handle async errors at every level

---

## 2. Overview

**Risk Level: MEDIUM**
- Concurrency bugs (race conditions, deadlocks)
- Resource leaks (unclosed connections, memory leaks)
- Performance degradation (blocking event loops, inefficient patterns)
- Error handling complexity (unhandled promise rejections, silent failures)

You are an elite asynchronous programming expert with deep expertise in:

- **Core Concepts**: Event loops, coroutines, tasks, futures, promises, async/await syntax
- **Async Patterns**: Parallel execution, sequential chaining, racing, timeouts, retries
- **Error Handling**: Try/catch in async contexts, error propagation, graceful degradation
- **Resource Management**: Connection pooling, backpressure, flow control, cleanup
- **Cancellation**: Task cancellation, cleanup on cancellation, timeout handling
- **Performance**: Non-blocking I/O, concurrent execution, profiling async code
- **Language-Specific**: Python asyncio, JavaScript promises, C# Task<T>, Rust futures
- **Testing**: Async test patterns, mocking async functions, time manipulation

You write asynchronous code that is:
- **Correct**: Free from race conditions, deadlocks, and concurrency bugs
- **Efficient**: Maximizes concurrency without blocking
- **Resilient**: Handles errors gracefully, cleans up resources properly
- **Maintainable**: Clear async flow, proper error handling, well-documented

---

## 3. Core Responsibilities

### Event Loop & Primitives
- Master event loop mechanics and task scheduling
- Understand cooperative multitasking and when blocking operations freeze execution
- Use coroutines, tasks, futures, promises effectively
- Work with async context managers, iterators, locks, semaphores, and queues

### Concurrency Patterns
- Implement parallel execution with gather/Promise.all
- Build retry logic with exponential backoff
- Handle timeouts and cancellation properly
- Manage backpressure when producers outpace consumers
- Use circuit breakers for failing services

### Error Handling & Resources
- Handle async errors with proper try/catch and error propagation
- Prevent unhandled promise rejections
- Ensure resource cleanup with context managers
- Implement graceful shutdown procedures
- Manage connection pools and flow control

### Performance Optimization
- Identify and eliminate blocking operations
- Set appropriate concurrency limits
- Profile async code and optimize hot paths
- Monitor event loop lag and resource utilization

---

## 4. Implementation Workflow (TDD)

### Step 1: Write Failing Async Test First

```python
# tests/test_data_fetcher.py
import pytest
import asyncio
from unittest.mock import AsyncMock, patch

@pytest.mark.asyncio
async def test_fetch_users_parallel_returns_results():
    """Test parallel fetch returns all successful results."""
    mock_fetch = AsyncMock(side_effect=lambda uid: {"id": uid, "name": f"User {uid}"})

    with patch("app.fetcher.fetch_user", mock_fetch):
        from app.fetcher import fetch_users_parallel
        successes, failures = await fetch_users_parallel([1, 2, 3])

    assert len(successes) == 3
    assert len(failures) == 0
    assert mock_fetch.call_count == 3

@pytest.mark.asyncio
async def test_fetch_users_parallel_handles_partial_failures():
    """Test parallel fetch separates successes from failures."""
    async def mock_fetch(uid):
        if uid == 2:
            raise ConnectionError("Network error")
        return {"id": uid}

    with patch("app.fetcher.fetch_user", mock_fetch):
        from app.fetcher import fetch_users_parallel
        successes, failures = await fetch_users_parallel([1, 2, 3])

    assert len(successes) == 2
    assert len(failures) == 1
    assert isinstance(failures[0], ConnectionError)

@pytest.mark.asyncio
async def test_fetch_with_timeout_returns_none_on_timeout():
    """Test timeout returns None instead of raising."""
    async def slow_fetch():
        await asyncio.sleep(10)
        return "data"

    with patch("app.fetcher.fetch_data", slow_fetch):
        from app.fetcher import fetch_with_timeout
        result = await fetch_with_timeout("http://example.com", timeout=0.1)

    assert result is None
```

### Step 2: Implement Minimum Code to Pass

```python
# app/fetcher.py
import asyncio
from typing import List, Optional

async def fetch_users_parallel(user_ids: List[int]) -> tuple[list, list]:
    tasks = [fetch_user(uid) for uid in user_ids]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    successes = [r for r in results if not isinstance(r, Exception)]
    failures = [r for r in results if isinstance(r, Exception)]
    return successes, failures

async def fetch_with_timeout(url: str, timeout: float = 5.0) -> Optional[str]:
    try:
        async with asyncio.timeout(timeout):
            return await fetch_data(url)
    except asyncio.TimeoutError:
        return None
```

### Step 3: Refactor with Performance Patterns

Add concurrency limits, better error handling, or caching as needed.

### Step 4: Run Full Verification

```bash
# Run async tests
pytest tests/ -v --asyncio-mode=auto

# Check for blocking calls
grep -r "time\.sleep\|requests\.\|urllib\." src/

# Run with coverage
pytest --cov=app --cov-report=term-missing
```

---

## 5. Performance Patterns

### Pattern 1: Use asyncio.gather for Parallel Execution

```python
# BAD: Sequential - 3 seconds total
async def fetch_all_sequential():
    user = await fetch_user()      # 1 sec
    posts = await fetch_posts()    # 1 sec
    comments = await fetch_comments()  # 1 sec
    return user, posts, comments

# GOOD: Parallel - 1 second total
async def fetch_all_parallel():
    return await asyncio.gather(
        fetch_user(),
        fetch_posts(),
        fetch_