# ops-review

Multi-lens review for operational infrastructure. Finds security issues, shell script bugs, and reliability problems in your Nix configs, shell scripts, Docker files, and CI/CD pipelines.

## Quick Start

**Claude Code / OpenCode:**
```
/ops-review bin/deploy.sh
```

The agent reviews your ops files and presents findings for approval before filing any issues.

## What It Reviews

| Artifact | Examples |
|----------|----------|
| Nix/NixOS | flake.nix, modules/*.nix, home-manager configs |
| Shell Scripts | bin/*.sh, setup_*.sh, deploy.sh |
| Containers | Dockerfile, docker-compose.yml |
| CI/CD | .github/workflows/*.yml, .gitea/workflows/*.yml |
| Services | systemd units, cron jobs |

## How It Works

**Linter-first hybrid**: Static tools catch syntax issues, LLM finds semantic problems.

```
shellcheck ──┐
statix    ───┼──► LLM interprets + finds logic bugs ──► Findings
hadolint  ───┘
```

## Available Lenses

### Phase 1: Core Safety (quick mode)
- **secrets** - Hardcoded credentials, SOPS issues
- **shell-safety** - set -euo pipefail, quoting, error handling
- **blast-radius** - Destructive ops, missing dry-run
- **privilege** - Unnecessary sudo, root containers

### Phase 2: Reliability
- **idempotency** - Safe re-run, atomic operations
- **supply-chain** - Unpinned versions, missing hashes
- **observability** - Silent failures, missing health checks

### Phase 3: Architecture
- **nix-hygiene** - Dead code, anti-patterns
- **resilience** - Timeouts, retries, resource limits
- **orchestration** - Execution order, prerequisites

## Usage Examples

```bash
# Review a single script
/ops-review deploy.sh

# Review a directory
/ops-review bin/

# Quick mode (Phase 1 only, fast)
/ops-review --quick bin/

# Review recent changes
/ops-review
```

## Example Output

```
## Review Summary: bin/deploy.sh

| Severity | Count |
|----------|-------|
| HIGH     | 2     |
| MED      | 3     |

### Top Issues

1. [SECRETS] HIGH bin/deploy.sh:45
   Issue: API token passed as CLI argument
   Suggest: Use environment variable instead

2. [BLAST-RADIUS] HIGH bin/deploy.sh:78
   Issue: rm -rf with variable that could be empty
   Suggest: Add guard: [ -n "$DIR" ] || exit 1

Would you like me to file any of these as beads issues?
```

## Prerequisites

For full functionality, install these linters:

```bash
# NixOS (add to configuration.nix or home-manager)
shellcheck
statix
deadnix
hadolint
```

The skill works without them but provides richer analysis with linter output.

## Configuration

No configuration required. The skill auto-detects file types and applies appropriate lenses.

## Integration

- **Issue Tracking**: Files findings as beads issues (`bd create`)
- **CI/CD**: Use `--quick` mode for pre-commit/pipeline gates

## See Also

- [code-review](../code-review/README.md) - Application code review
- [doc-review](../doc-review/README.md) - Documentation quality

## License

MIT
