# Conventions

## Language & Dependencies

- Target the latest stable Go release.
- Prefer Go standard library; approved third-party packages allowed (see below).

### Approved Third-Party Packages

| Package | Use Case | Notes |
|---------|----------|-------|
| `gopkg.in/yaml.v3` | YAML parsing | Persona files, config |
| `github.com/google/go-cmp` | Test comparisons | `cmp.Diff` for readable diffs |

To add a new dependency:
1. Open a PR with justification (why stdlib is insufficient)
2. Package must be well-maintained, widely used, minimal transitive deps
3. Update this table when approved

## Error Handling

- Return errors; never panic.
- Wrap errors with context using `fmt.Errorf("context: %w", err)`.
- Check all error returns.

## Testing

- Test every exported function.
- Use `net/http/httptest` for HTTP mocking.
- Table-driven tests where multiple inputs share the same assertion logic.
- Integration tests use build tags (`//go:build integration`).

## Style

- Keep functions short and focused.
- Prefer early returns over deep nesting.
- Meaningful variable names — no single-letter names outside loop indices.
- Comments explain *why*, not *what*.

## Process

- `go test ./...` must pass before commit.
- `go vet ./...` must pass before commit.
- Keep commits atomic and well-described.