---
name: spark-code-review
description: Review SPARK Python and Go code for readability, safety, and consistency with project conventions. Use when examining changes under core/, agents/, or scraper.go.
---

# SPARK Code Review Skill

## Review focus

- **Correctness**: Look for potential logic bugs, unhandled edge cases, and incorrect assumptions about external services.
- **Security**: Pay attention to how external data (HTTP responses, scan outputs, scraped content) is parsed and used; avoid unsafe eval, shell injection, or leaking sensitive data into logs.
- **Resilience**: Ensure retries, timeouts, and error paths are handled in a way that does not break the pipeline.
- **Style & consistency**: Align with the Python & SPARK Coding Style rules and keep naming, structure, and patterns consistent across agents.

## Checklist for Python changes

When reviewing changes in `core/` or `agents/`:

1. **Interfaces**
   - Do new functions and classes have clear, typed signatures?
   - Does any new agent integrate properly with `PipelineContext` and `AgentResult`?
2. **Async behavior**
   - Are `async` functions free from blocking calls?
   - Are `asyncio.gather` calls using `return_exceptions=True` when partial failures are acceptable?
3. **Error handling**
   - Are exceptions caught where appropriate and converted into clear error messages instead of crashes?
   - Are errors from external tools (e.g., Wapiti, web scrapers) surfaced in a way that is helpful in reports?
4. **Logging**
   - Do log messages provide enough context (which company/domain, which stage) without leaking secrets?

## Review output format

When providing review feedback:

- Group comments under headings: `Correctness`, `Security`, `Resilience`, `Style`.
- Mark severity with labels like **[must-fix]**, **[nice-to-have]**.
- When possible, propose small concrete code changes or refactors instead of only high-level comments.