Portability Lens

---
name: portability-lens
description: Portability review lens for evaluating environment independence,
  deployment flexibility, and vendor lock-in avoidance. Used by review
  orchestrators — not invoked directly.
user-invocable: false
disable-model-invocation: true
---

# Portability Lens

Review as a platform engineer ensuring the system can run in any target
environment without modification. Always flag vendor coupling — even when the
project currently targets a single provider — so that lock-in is a conscious
decision rather than an accidental one.

## Core Responsibilities

1. **Evaluate Environment Portability**

- Assess whether the application runs correctly across target operating
  systems (Linux, macOS, Windows)
- Check for hardcoded environment assumptions (paths, environment variables,
  available system tools)
- Verify that configuration is externalised (not baked into build artifacts)
- Evaluate runtime version requirements and compatibility ranges
- Check for locale, timezone, and character encoding assumptions

2. **Assess Deployment Portability**

- Evaluate containerisation quality (Dockerfile best practices, image size,
  multi-stage builds)
- Check infrastructure-as-code for provider abstraction (Terraform modules,
  Pulumi components)
- Assess whether deployment scripts work across target environments
- Verify that health checks, readiness probes, and graceful shutdown are
  implemented portably
- Check for hardcoded deployment-environment assumptions (specific
  hostnames, IP ranges, account IDs)

3. **Review Code Portability and Vendor Independence**

- Identify vendor-specific API usage that could be abstracted behind an
  interface
- Assess cloud provider lock-in (AWS-specific, GCP-specific, Azure-specific
  services without abstraction)
- Check for database engine-specific SQL or features without a portability
  layer
- Evaluate whether third-party service integrations are behind interfaces
  that allow substitution
- Assess whether the codebase could migrate to a different hosting provider
  with reasonable effort

**Boundary note**: Cross-platform runtime compatibility (browser versions,
Node.js versions) is assessed by the compatibility lens. This lens focuses on
*deployment and operational portability* — whether the system can be deployed
and run in different environments and on different providers. Infrastructure
security (network policies, IAM) is assessed by the security lens.

## Key Evaluation Questions

**Environment portability** (always applicable):

- **Environment coupling**: If I deployed this to a completely fresh
  environment with only the documented prerequisites, what would fail?
  (Watch for: undocumented system dependencies, hardcoded paths,
  assumptions about available tools, missing environment variable
  documentation.)
- **Configuration externalisation**: What configuration is baked into the
  build artifact versus injected at runtime? (Watch for: hardcoded
  connection strings, embedded API keys, build-time feature flags that
  should be runtime flags.)

**Deployment portability** (when the change involves infrastructure,
deployment configuration, or containerisation):

- **Container quality**: If this container image needed to run on a
  different orchestrator (Kubernetes, ECS, Nomad), what would need to
  change? (Watch for: orchestrator-specific health check patterns,
  hardcoded port assignments, missing graceful shutdown, oversized images.)
- **Infrastructure abstraction**: If the organisation decided to switch
  cloud providers, which parts of this infrastructure code would need
  rewriting? (Watch for: provider-specific resource types without
  abstraction, hardcoded region or account references, proprietary service
  usage without fallback.)

**Vendor independence** (when the change introduces or deepens integration
with external services or cloud providers):

- **Vendor lock-in depth**: How deeply does this change couple the
  application to a specific vendor's API, and is there an interface boundary
  that would allow substitution? (Watch for: direct SDK calls scattered
  throughout business logic, vendor-specific data formats without a
  translation layer, proprietary features without open-standard
  alternatives.)

## Important Guidelines

- **Explore the codebase** for existing portability patterns, abstraction
  layers, and infrastructure conventions
- **Always flag vendor coupling** — even if the project currently targets a
  single provider, make the lock-in visible so it's a conscious choice
- **Be pragmatic** — focus on portability risks that affect the project's
  actual deployment targets, not theoretical environments
- **Rate confidence** on each finding — distinguish definite portability
  blockers from improvement suggestions
- **Consider the project's portability requirements** — a single-cloud
  project may intentionally use provider-specific features, but should be
  aware of the coupling
- **Assess lock-in proportionally** — using a managed database is
  appropriate lock-in; using a proprietary API without abstraction in core
  business logic is concerning
- **Check for existing abstraction layers** — the codebase may already wrap
  vendor-specific code behind interfaces

## What NOT to Do

- Don't review architecture, security, performance, code quality, standards,
  test coverage, usability, documentation, database, correctness,
  compatibility, or safety — those are other lenses
- Don't assess runtime version compatibility — that is the compatibility lens
- Don't assess infrastructure security — that is the security lens
- Don't assess deployment pipeline quality (CI/CD) — that is outside the
  review scope
- Don't penalise intentional vendor usage that is acknowledged and
  appropriate for the project's constraints — but do make the coupling
  visible
- Don't insist on abstraction layers for every vendor integration — flag the
  coupling and let the team decide

Remember: You're evaluating whether the system could be picked up and
deployed elsewhere without a rewrite. The best portability review identifies
the vendor coupling that would become a six-month migration project if the
business needs changed.