# Cleanup

> Review, refactor, document, and validate code changes in the current branch

- Skill: `pipecat-ai/cleanup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pipecat-ai/cleanup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pipecat-ai/cleanup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pipecat-ai (https://skillmd.com/u/pipecat-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/pipecat-ai/cleanup

---


# Code Cleanup Skill

The **Code Cleanup Skill** reviews, refactors, and documents code changes in your current branch, ensuring alignment with **Pipecat's architecture, coding standards, and example patterns**.
It focuses on **readability, correctness, performance, and consistency**, while avoiding breaking changes.

---

## Skill Overview

This skill analyzes all changes introduced in your branch and performs the following actions:

1. **Analyze Branch Changes**
   - Review uncommitted changes and outgoing commits
2. **Refactor for Readability**
   - Improve clarity, naming, structure, and modern Python usage
3. **Enhance Performance**
   - Identify safe, conservative optimization opportunities
4. **Add Documentation**
   - Apply Pipecat-style, Google-format docstrings
5. **Ensure Pattern Consistency**
   - Match existing Pipecat services, pipelines, and examples
6. **Validate Examples**
   - Ensure examples follow foundational patterns (e.g. `07-interruptible.py`)

---

## Usage

Invoke the skill using any of the following commands:

- "Clean up my branch code"
- "Refactor the changes in my branch"
- "Review and improve my branch code"
- `/cleanup`

---

## What This Skill Does

### 1. Analyze Branch Changes

The skill retrieves all uncommitted changes and outgoing commits to understand:

- New files added
- Modified files
- Code additions and deletions
- Overall scope and intent of changes

---

### 2. Code Refactoring

#### Readability Improvements

- Replace tuples with named classes or dataclasses
- Improve variable, method, and class naming
- Extract complex logic into well-named helper methods
- Add missing type hints
- Simplify nested or complex conditionals
- Replace deprecated methods and features
- Normalize formatting to match Pipecat style

#### Performance Enhancements

- Identify inefficient loops or repeated work
- Suggest appropriate data structures
- Optimize async workflows and I/O
- Remove redundant operations

> Performance changes are conservative and non-breaking.

---

### 3. Documentation

Documentation follows **Google-style docstrings**, consistent with Pipecat conventions.

#### Class Documentation

```python
class ExampleService:
    """Brief one-line description.

    Detailed explanation of the class purpose, responsibilities,
    and important behaviors.

    Supported features:

    - Feature 1
    - Feature 2
    - Feature 3
    """
```

#### Method Documentation

```python
def process_data(self, data: str, options: Optional[dict] = None) -> bool:
    """Process incoming data with optional configuration.

    Args:
        data: The input data to process.
        options: Optional configuration dictionary.

    Returns:
        True if processing succeeded, False otherwise.

    Raises:
        ValueError: If data is empty or invalid.
    """
```

#### Pydantic Model Parameters

```python
class InputParams(BaseModel):
    """Configuration parameters for the service.

    Parameters:
        timeout: Request timeout in seconds.
        retry_count: Number of retry attempts.
        enable_logging: Whether to enable debug logging.
    """

    timeout: Optional[float] = None
    retry_count: int = 3
    enable_logging: bool = False
```

---

### 4. Pattern Consistency Checks

#### Service Classes

- Correct inheritance (`TTSService`, `STTService`, `LLMService`)
- Consistent constructor signatures
- Frame emission patterns
- Metrics support:
  - `can_generate_metrics()`
  - TTFB and TTFA metrics
  - Usage metrics
- Alignment with similar existing services

#### Examples

Validated against `examples/07-interruptible.py`:

- Proper `create_transport()` usage
- Correct pipeline structure
- Task setup and observers
- Event handler registration
- Runner and bot entrypoint consistency

---

### 5. Specific Implementation Patterns

#### Service Implementation

```python
class ExampleTTSService(TTSService):
    def __init__(self, *, api_key: Optional[str] = None, **kwargs):
        super().__init__(**kwargs)
        self._api_key = api_key or os.getenv("SERVICE_API_KEY")

    def can_generate_metrics(self) -> bool:
        return True

    async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
        try:
            await self.start_ttfb_metrics()
            yield TTSStartedFrame()
            # ... processing ...
            frame = TTSAudioRawFrame(...)
            await self.process_ttfa_metrics(frame)
            yield frame
        finally:
            await self.stop_ttfb_metrics()
```

---

#### Example Structure Pattern

```python
transport_params = {
    "daily": lambda: DailyParams(...),
    "twilio": lambda: FastAPIWebsocketParams(...),
    "webrtc": lambda: TransportParams(...),
}


async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
    stt = DeepgramSTTService(...)
    tts = SomeTTSService(...)
    llm = OpenAILLMService(...)

    context = LLMContext(messages)
    user_aggregator, assistant_aggregator = LLMContextAggregatorPair(...)

    pipeline = Pipeline([...])
    worker = PipelineWorker(pipeline, params=..., observers=[...])

    runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)

    await runner.add_workers(worker)

    @transport.event_handler("on_client_connected")
    async def on_client_connected(transport, client):
        await worker.queue_frames([LLMRunFrame()])

    @transport.event_handler("on_client_disconnected")
    async def on_client_disconnected(transport, client):
        await runner.cancel()

    await runner.run()


async def bot(runner_args: RunnerArguments):
    """Main bot entry point compatible with Pipecat Cloud."""
    transport = await create_transport(runner_args, transport_params)
    await run_bot(transport, runner_args)
```

---

## Execution Flow

1. Fetch uncommitted and outgoing changes
2. Categorize files (services, examples, tests, utilities)
3. Analyze each file:
   - Readability
   - Performance
   - Documentation
   - Pattern consistency
4. Generate actionable recommendations
5. Apply Pipecat standards
6. Run `/prose-review branch` over the comments and docstrings written above, and fix
   anything it flags

---

## Examples

### Before: Tuple Usage

```python
def get_audio_info(self) -> Tuple[int, int]:
    return (48000, 1)
```

### After: Named Class

```python
class AudioInfo:
    """Audio configuration information.

    Parameters:
        sample_rate: Sample rate in Hz.
        num_channels: Number of audio channels.
    """

    sample_rate: int
    num_channels: int


def get_audio_info(self) -> AudioInfo:
    return AudioInfo(sample_rate=48000, num_channels=1)
```

---

### Before: Missing Documentation

```python
class NewTTSService(TTSService):
    def __init__(self, api_key: str, voice: str):
        self._api_key = api_key
        self._voice = voice
```

### After: Fully Documented

```python
class NewTTSService(TTSService):
    """Text-to-speech service using NewProvider API.

    Streams PCM audio and emits TTSAudioRawFrame frames compatible
    with Pipecat transports.

    Supported features:
    - Text-to-speech synthesis
    - Streaming PCM audio
    - Voice customization
    - TTFB and TTFA metrics
    """

    def __init__(self, *, api_key: str, voice: str, **kwargs):
        """Initialize the NewTTSService.

        Args:
            api_key: API key for authentication.
            voice: Voice identifier to use.
            **kwargs: Additional arguments passed to the parent service.
        """
        super().__init__(**kwargs)
        self._api_key = api_key
        self.set_voice(voice)
```

---

## Notes

- Non-breaking improvements only
- Backward compatibility preserved
- Conservative performance changes
- Google-style docstrings
- Pattern checks follow recent Pipecat code