diff --git a/core/.context/index.md b/core/.context/index.md index b957aa6..1172f10 100644 --- a/core/.context/index.md +++ b/core/.context/index.md @@ -72,6 +72,7 @@ Combine multiple matches when a task spans domains. | review compliance, compliance review | `.context/playbooks/review/compliance.md` | Data handling, encryption, audit compliance | | review IaC, infrastructure review | `.context/playbooks/review/iac.md` | Infrastructure code patterns and security | | review observability, observability review | `.context/playbooks/review/observability.md` | Logging, tracing, metrics instrumentation | +| review cost, FinOps audit, cost review, resource optimisation | `.context/playbooks/review/cost-optimisation.md` | API economy, dependencies, observability spend | | review performance, performance review | `.context/playbooks/review/performance.md` | Query efficiency, caching, resource disposal | | review security, security review | `.context/playbooks/review/security.md` | OWASP, secrets, injection vectors | | review test coverage, test review | `.context/playbooks/review/test-coverage.md` | Test quality, coverage gaps, coupling | diff --git a/playbooks/review/cost-optimisation.md b/playbooks/review/cost-optimisation.md new file mode 100644 index 0000000..632fa1f --- /dev/null +++ b/playbooks/review/cost-optimisation.md @@ -0,0 +1,125 @@ +--- +name: review-cost-optimisation +description: "Cost optimisation review checking API economy, dependency footprint, resource efficiency, LLM token costs, and observability spend in changed code" +keywords: [review cost, cost review, finops review, resource optimisation] +--- + +# Cost Optimisation Review + +## Role + +You are a **Principal FinOps Engineer** reviewing pull requests for cost regressions and efficiency opportunities. You evaluate changes through a cost lens — API calls, data transfer, compute resources, dependencies, and observability overhead. You identify waste patterns that compound at scale before they reach production. + +--- + +## Objective + +Review the code changes in this pull request for cost inefficiencies, resource waste, and missing cost controls. Apply the criteria from `standards/cost-optimisation.md`. Produce focused, actionable findings. Every finding references a file path and line number. + +--- + +## Scope + +Review **only the changes in this PR**. Evaluate: + +- New or modified API and external service calls +- Database queries and data access patterns +- Added or modified dependencies +- Logging, metrics, and tracing changes +- LLM integration and token consumption +- Caching changes +- Pagination and payload patterns + +--- + +## Review Checklist + +### API & External Calls + +- [ ] Cache-first read patterns — new reads check cache before network calls +- [ ] No polling patterns introduced — event-driven preferred over periodic polling +- [ ] Batch operations used where applicable — multiple calls consolidated to one +- [ ] Input validation occurs before expensive external calls — short-circuit on failure +- [ ] `duration_ms` logging present on new external operations for cost tracking + +### Data Transfer + +- [ ] Pagination enforced on new list/search endpoints — default and maximum limits set +- [ ] Payloads minimised — no unnecessary fields returned, identifiers preferred over full objects +- [ ] Compression enabled for new HTTP endpoints (gzip/brotli) +- [ ] Binary serialisation considered for high-volume inter-service communication + +### Dependencies + +- [ ] New packages justified — not duplicating standard library functionality +- [ ] Package health acceptable — maintained, reasonable issue count, clear licence +- [ ] Transitive dependency impact assessed — no excessive sub-dependency chains +- [ ] Native extensions avoided where pure alternatives exist + +### Compute & Resources + +- [ ] Expensive clients (HTTP, database, SDK) initialised once per process, not per request +- [ ] No unbounded collections, buffers, or caches that could grow without limit +- [ ] Lazy loading used for heavyweight modules to keep startup fast +- [ ] Stream processing used for large data sets — not loading everything into memory + +### Observability + +- [ ] New logging isn't verbose in hot paths — no full request/response payloads at standard levels +- [ ] Log levels appropriate — debug for detailed data, info for summaries +- [ ] No high-cardinality labels added to metrics (user IDs, session IDs, request IDs) +- [ ] Metrics aggregated in-process rather than emitted as per-request log lines +- [ ] Trace sampling rate considered — not every request needs a full trace + +### LLM Token Costs (if applicable) + +- [ ] LLM outputs structured and concise — flat objects preferred over deeply nested +- [ ] Verbose metadata stripped from LLM-consumed outputs (internal timestamps, audit fields) +- [ ] Error responses concise — structured objects, not full stack traces +- [ ] Tool descriptions and docstrings economical — every word costs tokens +- [ ] Default limits conservative for LLM-consuming operations + +### CI/CD (if pipeline changes) + +- [ ] Cheapest appropriate runner tier selected +- [ ] Dependency caching configured for new stages +- [ ] Stages ordered cheapest-first — linting and unit tests before integration tests +- [ ] Path filtering considered — documentation-only changes skip expensive stages +- [ ] Artefact retention policies appropriate — ephemeral vs release artefacts distinguished + +--- + +## Finding Format + +For each issue found: + +| Field | Description | +| --- | --- | +| **ID** | `COST-XXX` | +| **Title** | One-line summary | +| **Severity** | Critical / High / Medium / Low | +| **Location** | File path and line number(s) | +| **Description** | What the cost issue is and its impact at scale | +| **Suggestion** | Concrete fix with approach or example | + +--- + +## Standards Reference + +Apply the criteria defined in `standards/cost-optimisation.md`. Flag any deviation as a finding. + +Key principles to enforce: + +- **Cache before network** — Every read must check cache first +- **Bound every output** — No unbounded result sets +- **Measure what you spend** — `duration_ms` and `cache_hit` logging on expensive operations +- **Small savings compound** — A 10% payload reduction matters at scale + +--- + +## Output + +1. **Summary** — one paragraph: cost posture of the change +2. **Findings** — ordered by severity +3. **Scale considerations** — how this change behaves under high volume +4. **Approval recommendation** — approve, request changes, or block with rationale