review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Infrastructure Review

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/infra:review [target] [--env=<env>] [--cloud=<cloud>] [--round=<n>]`

## Desired Outcome

A review a team can act on: an ownership map, findings ranked by severity, each written as
**path:line → what → impact → fix → source**, plus a mandatory multi-cloud section and a mandatory
environment-parity section — and the things that genuinely cannot be judged from outside listed as
open questions rather than guessed at.

## Decision Criteria

| Situation | Do this |
|-----------|---------|
| The environment is unknown | Ask before writing findings. The same code gets a different verdict per environment (§ Per-Environment Standards) |
| The finding concerns `local` or `production` | Both are outside the observed implementation. Ground the finding in this skill's conventions or in official documentation — **never in the bundle's authority** |
| The repository and the bundle differ | The repository is what exists. The bundle is a snapshot of specific commits; do not assert "it should look like this" without reading the code |
| The topic is outside the bundle | Say so, then WebFetch official documentation or record it as an open question |
| A finding has no proposed fix | It is not finished. Do not emit findings without fixes |

## Prerequisites

| File | Required/Recommended | Source |
|------|---------------------|--------|
| `knowledge/okf-k8s-tf/` | **Required** | Vendored bundle (@rules/okf-k8s-tf-bundle.md) |
| The review target (repository / MR diff / design document, with revision) | **Required** | The user |
| Previous round's review report | Recommended | `$OUT/reviews/review-<target>-r<n-1>.md` |

When invoked from `/infra:start`, environment, cloud, target path, `$OKF` and the freshness list
arrive already settled. **Do not re-ask them.**

The freshness list names the bundle documents past `stale_after` or awaiting re-verification
(from `tools/update-okf-bundle.sh status --bundle=k8s-tf` when invoked directly). A finding
grounded in a listed document says the document awaits re-verification and why, so it is not
read as settled — and when the finding turns on what the document says about a version or a
deprecation, check the official source before assigning its severity.

## Steps

1. **Fix the target and its scope** — whole repository / a specific MR diff / a design document.
2. **Confirm the target environment.** Always devote one section to environment parity; the
   standards differ per environment.
3. **Confirm the target clouds.** Always devote one section to multi-cloud.
4. **Build the ownership map first.** Without knowing who applies what, the remaining findings
   cannot be prioritized [architecture/platform-architecture.md].
5. **Work through the checks below**, opening the relevant bundle document before each.
6. **Assign severity**, remembering it moves with the environment.
7. **Emit with `templates/infra/review-report.md`.**
8. Round 2 and later: open with a reconciliation against the previous round — resolved / still
   open / new. Determine the round number from the existing files unless `--round=<n>` says
   otherwise.

## The Three Checks That Come First

Check these in order; anything found here is written before every other finding.

1. **Ownership overlap** — is any resource managed by two or more of Terraform / Argo CD / CI /
   manual operation? [architecture/platform-architecture.md]
2. **Broken artifact identity** — do build / scan / sign / verify / deploy all reference the same
   image digest, with no re-resolution from a tag in between? [delivery/docker-cosign.md]
3. **Secret exposure** — any plaintext secret in Git / values / tfvars / plan artifacts / CI logs /
   Docker layers? [foundation/terraform.md, delivery/docker-cosign.md]

## Checks by Area

Walk every item of `architecture/design-build-checklist.md`. Below is that list plus the points
worth digging into.

### Requirements and boundaries
- [ ] Are availability / RTO / RPO / performance / retention / budget / regulatory and residency
      constraints expressed as numbers?
- [ ] Are test / staging / production separated by purpose, data, access and change approval?
- [ ] Are failure boundaries defined (namespace, cloud account/subscription/project, state)?

### IaC [foundation/terraform.md]
- [ ] Terraform / provider / module / chart versions pinned, lock file committed
- [ ] Remote state encrypted, access-controlled, locked, versioned/backed up
- [ ] CI runs `fmt` / `validate` / plan / static analysis; apply restricted to protected refs
- [ ] Plan and apply use different roles; OIDC rather than long-lived access keys
- [ ] Procedures exist for destroy / import / state move / provider upgrade
- [ ] Sharing between states limited to a minimal set of outputs
- [ ] `-target` not baked into normal operation
- [ ] Modules have not become giant lowest-common-denominator conditionals (over-abstraction)

### Kubernetes [foundation/kubernetes.md]
- [ ] Requests / limits, probes, PDBs, multiple replicas, topology spread
- [ ] RBAC and workload identity least-privileged per namespace / ServiceAccount
- [ ] Use of `cluster-admin`, wildcard verbs/resources, default ServiceAccount tokens
- [ ] Pod Security, NetworkPolicy (starting from default deny), staged admission policy
- [ ] No secrets in Git or plaintext values; a decided reload path after rotation
- [ ] Upgrade / rollback including CRDs, and version-skew verification

### Delivery [delivery/*.md]
- [ ] CI templates and job images pinned by commit / tag / digest (not `main` / `latest`)
- [ ] Runners separated by trust boundary; nothing unrelated on a privileged DinD runner
- [ ] Staging / production changed through Git declarations; CI not hitting the cluster directly
- [ ] Failure conditions decided for GitOps prune / selfHeal / auto-sync / sync waves
- [ ] Security jobs allowed to fail are not acting as the real gate
- [ ] Cosign verify **explicitly specifies** issuer and certificate identity, rather than merely
      confirming a signature exists [delivery/docker-cosign.md]

### Secrets [secrets/*.md]
- [ ] Vault in HA (three or more nodes, zone-spread, PDB, anti-affinity), not dev/standalone
- [ ] Auto-unseal KMS permissions, availability, deletion protection, rotation
- [ ] Vault policies deny-by-default, avoiding wildcards
- [ ] Root token revoked after initial setup
- [ ] Several audit devices, with defined behaviour when logging stops
- [ ] ESO's Vault policy limited to read/list on the paths it needs
- [ ] `ClusterSecretStore` not shared without restriction
- [ ] `dataFrom` / templates not copying broad value sets into Kubernetes Secrets
- [ ] Restore, not just snapshotting, actually tested

### Observability [operations/observability.md]
- [ ] SLI / SLO / recording rules / alerts / dashboards / runbooks tied together per service
- [ ] Symptom-based alerts, plus dead-man / availability alerting on the monitoring stack itself

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect