--- name: eco-review description: Use when reviewing code for environmental impact, auditing sustainability of infrastructure choices, or when user runs /eco-review. Scans for high-carbon cloud regions, inefficient API patterns, oversized containers, missing caching, and wasteful defaults. --- # eco-review Scan a project's infrastructure, code, and product design for sustainability issues. Matches findings against 27 known anti-patterns across infrastructure, code, product design, and architecture. Produces a ranked report with impact estimates, effort levels, and cited sources. ## Audit Process ### Step 1: Scan the Project Search the codebase for: - **Infrastructure files:** Terraform (`.tf`), CloudFormation (`template.yaml`/`.json`), Pulumi, Dockerfiles, docker-compose, CI configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`) - **Code patterns:** API endpoints, payload handling, compression middleware, caching headers, image tags, frontend bundle configs (webpack, vite, rollup), font files (`@font-face`, Google Fonts URLs), video/GIF tags, third-party script includes - **Database patterns:** ORM configuration (Prisma, Django ORM, ActiveRecord, TypeORM, Sequelize), query patterns, logging configuration - **Product design:** Default settings, notification systems, content loading patterns, data retention configs, background feature toggles - **Suppression file:** Check for `.eco-ignore` in the project root. Each line contains a pattern ID (e.g., `I7`, `C8`) with optional comment after `#`. Skip suppressed patterns in Steps 2-4. List them at the end of the report. ### Step 2: Match Against Patterns Compare findings against each pattern in the pattern set below. Record every match with the specific file and line where the anti-pattern appears. ### Step 3: Look Up Cloud Regions If cloud region configuration is found, look up the region in the carbon intensity reference in `data/carbon-intensity.md`. Note the grid carbon intensity and identify lower-carbon alternatives in the same provider. ### Step 4: Produce the Report Generate the output report using the format specified below. --- ## Output Format ``` ## Eco-Review: [Project Name] > **[Cø] Powered by CNaught** — carbon-aware code intelligence ### TL;DR 1. [problem] — [fix] ([effort]) 2. [problem] — [fix] ([effort]) 3. [problem] — [fix] ([effort]) ### Category Summary #### Infrastructure - ✓ [Good practice found] 1. **[Pattern ID]:** [Recommendation] ([effort]) 2. ... #### Code - ✓ [Good practice found] 1. **[Pattern ID]:** [Recommendation] ([effort]) 2. ... #### Product Design - ✓ [Good practice found] 1. **[Pattern ID]:** [Recommendation] ([effort]) 2. ... #### Architecture - ✓ [Good practice found] 1. **[Pattern ID]:** [Recommendation] ([effort]) 2. ... Numbers restart at 1 within each category. Include the pattern ID and effort label on each numbered item. This introduces the pattern ID prefixes (I = Infrastructure, C = Code, P = Product Design, A = Architecture) in context. ### Sustainability-Specific Findings These are issues you would only identify through a sustainability lens. **[Pattern ID]: [Description]** Found in: `[file:line]` Impact: [contextualized to this project — never copy verbatim from pattern definition] Sustainability impact: [Explain specifically how fixing this reduces energy, compute, storage, or emissions — e.g., "switching from us-east-1 to us-west-2 would reduce grid carbon intensity from 323 to 79 gCO2/kWh" or "eliminating idle compute for 80% of off-peak hours"] Effort: [Quick win / Next sprint / Roadmap] · Risk: [Low / Medium / High] [For Roadmap items, add a one-line empathy note: "This may not be practical because [reason] — consider for future planning."] Source: [citation from pattern] ### Engineering Co-Benefits Standard best practices that also reduce environmental impact. **[Pattern ID]: [Description]** Found in: `[file:line]` Impact: [contextualized to this project — never copy verbatim from pattern definition] Effort: [Quick win / Next sprint / Roadmap] · Risk: [Low / Medium / High] Source: [citation from pattern] ### Worth Checking [Bulleted list of patterns the audit could not verify from the codebase but suspects may apply. Keep brief — one line per item with the pattern ID and what to check. Omit this section if everything was verified.] ### Suppressed Patterns [Pattern IDs from .eco-ignore, if any. Omit this section if no .eco-ignore exists.] --- *Generated by [CNaught Carbonlog](https://github.com/CNaught-Inc/claude-code-plugins/tree/main/plugins/carbonlog)* ``` --- ## Pattern Set: Infrastructure ### I1: High-carbon cloud region - **Type:** Sustainability - **Anti-pattern:** Deploying to a high-carbon-intensity region without considering alternatives - **Look for:** `region` in `.tf`, `template.yaml`, `pulumi`, docker-compose, or cloud CLI configs; match value against High Carbon tier in `data/carbon-intensity.md` - **Recommendation:** Migrate to a lower-carbon region in the same provider. See carbon intensity table. - **Impact:** 2-10x reduction in carbon intensity depending on region pair - **Severity:** Medium - **Effort:** Roadmap — requires migration plan, latency testing, compliance review - **Technical risk:** Data residency/compliance violations, migration downtime, cross-region replication complexity - **Usability risk:** Higher latency for users near original region - **Skip if:** Region is already in the Green or Moderate tier; compliance/data residency mandates a specific region - **Tools:** `aws configure get region`, `terraform show | grep region` to identify current region - **Source:** Google Cloud Region Carbon Data, 2024 (https://cloud.google.com/sustainability/region-carbon) ### I2: Oversized container images - **Type:** Co-benefit - **Anti-pattern:** Docker images using full OS base (ubuntu, debian) or including build tools in production - **Look for:** `FROM` in Dockerfiles using `ubuntu`/`debian`/`centos`/`fedora` (not `alpine`/`distroless`/`slim`); build tools (`build-essential`, `gcc`, `make`) in final stage - **Recommendation:** Use alpine or distroless base images. Multi-stage builds to exclude build deps. - **Impact:** 50-90% reduction in image size, reducing transfer, storage, and cold start energy - **Severity:** Medium - **Effort:** Next sprint — Dockerfile refactor, test for compatibility - **Technical risk:** Missing system libraries in minimal images, debugging difficulty without shell tools - **Usability risk:** None - **Skip if:** Already using alpine, distroless, or slim base images; multi-stage build excludes build tools from final image - **Tools:** `dive ` for layer analysis - **Source:** Docker best practices (https://docs.docker.com/build/building/best-practices/) ### I3: Always-on compute for bursty workloads - **Type:** Sustainability - **Anti-pattern:** Running 24/7 instances for workloads with variable or low utilization - **Look for:** `aws_instance`, `google_compute_instance`, or `azurerm_virtual_machine` in IaC without autoscaling groups; always-on containers in docker-compose with no scaling config - **Recommendation:** Serverless (Lambda, Cloud Functions) or spot/preemptible instances for fault-tolerant work - **Impact:** Pay-per-use eliminates idle energy waste. Typical server utilization is 12-18%. - **Severity:** Medium - **Effort:** Roadmap — requires workload analysis, may need code changes - **Technical risk:** Cold start latency (100ms–10s), state management complexity, execution time limits - **Usability risk:** Noticeable delay on first request after idle period - **Skip if:** Workload is latency-critical with consistent high utilization (>60%); already using autoscaling or serverless - **Source:** NRDC Data Center Efficiency Assessment, 2014; AWS Well-Architected Sustainability Pillar ### I4: No build caching in CI/CD - **Type:** Co-benefit - **Anti-pattern:** CI pipeline rebuilds everything from scratch on every run - **Look for:** CI configs (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`) missing `cache:` or `actions/cache@` steps; Dockerfiles without `--mount=type=cache` - **Recommendation:** Cache dependencies, Docker layers, build artifacts between runs - **Impact:** 30-80% reduction in CI compute time (varies by project) - **Severity:** High - **Effort:** Quick win — CI config change - **Technical risk:** Stale cache causing flaky builds, cache invalidation bugs - **Usability risk:** None - **Skip if:** CI already caches dependencies and Docker layers; project has <1 min build time - **Tools:** `grep -r 'actions/cache\|cache:' .github/workflows/` to check for existing cache config - **Source:** GitHub Actions caching docs (https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) ### I5: Over-provisioned compute - **Type:** Co-benefit - **Anti-pattern:** Instance types much larger than workload requires - **Look for:** `instance_type` in IaC with `xlarge`/`2xlarge`/`4xlarge` sizes; `resources.requests` in Kubernetes with high CPU/memory limits relative to typical web workloads - **Recommendation:** Right-size based on actual utilization metrics. Start small, scale up. - **Impact:** Linear reduction in energy — half the cores = roughly half the power draw - **Severity:** Medium - **Effort:** Next sprint — requires monitoring data to right-size accurately - **Technical risk:** Under-provisioning causes performance degradation under load spikes - **Usability risk:** Slower response times during peak usage if sized too aggressively - **Skip if:** Utilization monitoring shows >60% average CPU usage; workload is compute-intensive (ML training, video encoding) - **Source:** AWS Well-Architected Sustainability Pillar (https://docs.aws.amazon.com/wellarchitected/latest/sustainability-pillar/sustainability-pillar.html) ### I6: Redundant CI runs - **Type:** Co-benefit - **Anti-pattern:** Running full test suite on every commit regardless of what changed - **Look for:** CI configs without `paths:` or `paths-ignore:` filters; `on: push` with no path constraints in GitHub Actions; missing `only:changes:` in GitLab CI - **Recommendation:** Path-based filtering, skip CI for docs-only changes, parallelise test shards - **Impact:** 20-60% reduction in CI minutes for monorepos (varies by change distribution) - **Severity:** High - **Effort:** Quick win — CI config change - **Technical risk:** Path filters may miss cross-cutting changes, allowing broken code through - **Usability risk:** None - **Skip if:** Single-package repo where all changes affect the build; CI already has path-based filtering - **Source:** GitLab CI rules documentation (https://docs.gitlab.com/ci/yaml/#rules) ### I7: x86 instances when ARM is viable - **Type:** Sustainability - **Anti-pattern:** Deploying on x86 (Intel/AMD) instances when the workload runs on ARM without modification - **Look for:** `instance_type` matching x86 families (`m[0-9]i`, `c[0-9]i`, `t[0-9].`, `r[0-9]i` on AWS); `machine_type` with `n2-`/`c2-` on GCP; absence of `arm64`/`graviton`/`cobalt`/`axion` in IaC - **Recommendation:** Use ARM-based instances (AWS Graviton, Azure Cobalt, GCP Axion) for compatible workloads. Check IaC for instance type families (e.g., `m6i` → `m7g` on AWS). - **Impact:** Up to 60% less energy per core. 20-40% cost savings on equivalent instance sizes. - **Severity:** Medium - **Effort:** Next sprint — requires testing application and dependencies on ARM, updating IaC - **Technical risk:** Native binary dependencies (e.g., compiled C extensions, some ML libraries) may lack ARM builds. Container images must be multi-arch or ARM-specific. - **Usability risk:** None - **Skip if:** Workload requires native x86 binaries (e.g., specific ML libraries, legacy compiled code); already using ARM/Graviton instances - **Source:** ARM Newsroom (https://newsroom.arm.com/); AWS Graviton documentation (https://aws.amazon.com/ec2/graviton/) --- ## Pattern Set: Code ### C1: Polling instead of event-driven - **Type:** Co-benefit - **Anti-pattern:** Clients polling an endpoint at fixed intervals for updates - **Look for:** `setInterval` or `setTimeout` with fetch/axios calls; repeated GET requests to the same endpoint in client code; absence of WebSocket/SSE/EventSource usage - **Recommendation:** Server-Sent Events (SSE), WebSockets, or webhooks - **Impact:** Eliminates redundant requests. A 5-second poll interval = 720 wasted requests/hour per client when nothing changes. - **Severity:** Medium - **Effort:** Next sprint — per-endpoint refactor - **Technical risk:** WebSocket connection management, reconnection logic, firewall/proxy issues - **Usability risk:** Missed updates if push connection drops silently - **Skip if:** Polling interval is >60 seconds; endpoint is used for one-time checks (not continuous updates); long-polling is already in use - **Tools:** Chrome DevTools Network panel to observe repeated identical requests - **Source:** GSF Green Software Patterns (https://patterns.greensoftware.foundation/) ### C2: Uncompressed text resources - **Type:** Co-benefit - **Anti-pattern:** Text resources (HTML, CSS, JS, JSON, API responses) served without compression - **Look for:** Express/Koa without `compression` middleware; nginx without `gzip on;`; CDN config without compression enabled; missing `Content-Encoding` headers in response config - **Recommendation:** Enable gzip or brotli compression at the server/CDN level for all text-based responses - **Impact:** 60-80% reduction in payload size for text-based responses. ~30% of websites serve uncompressed text resources, wasting ~500KB per median page load. - **Severity:** High - **Effort:** Quick win — server/middleware configuration - **Technical risk:** CPU overhead for compression on high-throughput endpoints, incompatibility with streaming responses - **Usability risk:** None - **Skip if:** Compression already enabled at CDN/reverse proxy level; all responses are binary (images, video); API only serves small payloads (<1KB) - **Tools:** `curl -sI -H 'Accept-Encoding: gzip' | grep -i content-encoding` to verify compression - **Source:** Web Almanac 2024, HTTP Archive (https://almanac.httparchive.org/) ### C3: Missing cache-control headers - **Type:** Co-benefit - **Anti-pattern:** Static assets served without cache-control headers - **Look for:** `express.static()` without `maxAge`/`setHeaders`; nginx `location` blocks for static files without `expires` or `add_header Cache-Control`; CDN config without caching rules - **Recommendation:** Set appropriate Cache-Control headers (immutable for hashed assets, max-age for others) - **Impact:** Eliminates redundant data transfer for repeat visitors. Static assets are typically 60-80% of page weight. - **Severity:** High - **Effort:** Quick win — server/CDN configuration - **Technical risk:** Stale content served after deploys if cache-busting strategy is wrong - **Usability risk:** Users see outdated content until cache expires - **Skip if:** Cache-Control headers already set; assets served through CDN with caching configured; all content is dynamic/personalized - **Tools:** `curl -sI | grep -i cache-control` to verify headers on static assets - **Source:** Web Almanac 2024, HTTP Archive ### C4: Unoptimized images - **Type:** Co-benefit - **Anti-pattern:** Serving PNG/JPEG when modern formats available, no responsive sizing, no lazy loading - **Look for:** `` tags with `.png`/`.jpg`/`.jpeg` without `srcset`; images missing `loading="lazy"`; no `` element with WebP/AVIF sources; image build pipeline without format conversion - **Recommendation:** WebP/AVIF format, srcset for responsive sizes, loading="lazy" for below-fold images - **Impact:** WebP is 25-35% smaller than JPEG at equivalent quality. AVIF is 40-50% smaller. - **Severity:** Medium - **Effort:** Next sprint — build pipeline and markup changes - **Technical risk:** Older browser incompatibility with WebP/AVIF, build pipeline complexity for multiple formats - **Usability risk:** Quality degradation if compression too aggressive, layout shift from lazy-loaded images - **Skip if:** Images already served as WebP/AVIF with srcset; image CDN (Cloudinary, imgix) handles format negotiation; only SVG/icon images used - **Tools:** `npx sharp-cli`, `npx @squoosh/cli` - **Source:** Google Developers Web Fundamentals; Web Almanac 2024 ### C5: Large frontend bundles - **Type:** Co-benefit - **Anti-pattern:** Shipping entire libraries when only parts are used, no code splitting - **Look for:** Webpack/Vite/Rollup config without `splitChunks`/`manualChunks`; `import` of full libraries (`import _ from 'lodash'` vs `import get from 'lodash/get'`); single entry point with no dynamic `import()` - **Recommendation:** Tree-shaking, code splitting, dynamic imports for route-based loading - **Impact:** Varies widely. Common savings: 30-60% bundle size reduction from tree-shaking alone. - **Severity:** Medium - **Effort:** Next sprint — build config and import changes - **Technical risk:** Code splitting adds loading states, race conditions with shared dependencies - **Usability risk:** Visible spinners/flashes for lazy-loaded chunks on slow connections - **Skip if:** Bundle is already <100KB gzipped; no frontend or server-rendered only; already using code splitting and tree-shaking - **Tools:** `npx webpack-bundle-analyzer`, `npx vite-bundle-visualizer` - **Source:** webpack/Vite documentation; Web Almanac 2024 ### C6: Verbose serialization at scale - **Type:** Co-benefit - **Anti-pattern:** Using JSON for high-volume internal service communication - **Look for:** Internal service-to-service calls using `JSON.stringify`/`JSON.parse` or `application/json`; gRPC `.proto` files absent in multi-service repos; high-throughput message queues with JSON payloads - **Recommendation:** Consider Protocol Buffers, MessagePack, or similar compact formats for internal APIs - **Impact:** 30-50% smaller payloads vs JSON. Most impactful for high-throughput internal services. - **Severity:** Low - **Effort:** Next sprint to Roadmap — requires schema definition, client/server changes - **Technical risk:** Schema versioning complexity, harder debugging (binary payloads not human-readable) - **Usability risk:** None (internal service change, not user-facing) - **Skip if:** Single-service architecture; internal traffic is low-volume (<100 req/s); JSON overhead is negligible compared to payload content - **Source:** Google Developers Protocol Buffers documentation ### C7: Dead code in frontend bundles - **Type:** Co-benefit - **Anti-pattern:** Shipping JavaScript that is never executed by users. Unused exports, abandoned feature code, and over-inclusive library imports remain in production bundles. - **Look for:** Bundle config without `sideEffects: false` in package.json; CommonJS `require()` instead of ESM `import`; large dependencies in `package.json` that could be replaced with lighter alternatives - **Recommendation:** Audit bundles with coverage tools (Chrome DevTools Coverage, `webpack-bundle-analyzer`). Remove unused exports, replace large libraries with lighter alternatives, use tree-shaking-friendly ESM imports. - **Impact:** 206KB median wasted JavaScript per mobile page load (44% of JS bytes unused). Reduces parse time, execution energy, and data transfer. - **Severity:** Medium - **Effort:** Next sprint — requires bundle analysis, dependency audit, and testing after removal - **Technical risk:** Removing code that appears unused but is dynamically referenced (e.g., via string-based imports or reflection). Side-effectful modules may break if tree-shaken. - **Usability risk:** None if properly tested - **Skip if:** No frontend bundle (server-rendered only); bundle already <50KB gzipped; tree-shaking and dead code elimination already configured - **Tools:** `npx webpack-bundle-analyzer`, `npx depcheck` - **Source:** Web Almanac 2024, HTTP Archive (https://almanac.httparchive.org/) ### C8: Excessive third-party scripts - **Type:** Co-benefit - **Anti-pattern:** Loading numerous third-party scripts (analytics, ads, trackers, social widgets) that bloat page weight, block rendering, and consume device energy - **Look for:** `