Quick Reference
| Need | Starting Direction |
|---|---|
| infrastructure provisioning | Terraform, OpenTofu, Pulumi, or cloud-native IaC |
| cluster or app deployment | GitOps first for steady-state, direct tooling for local iteration |
| CI/CD | protected pipelines plus workload identity and supply-chain controls — see supply-chain-security |
| observability | OpenTelemetry plus metrics, logs, traces, and SLO-based alerting |
| platform engineering | golden paths, policy-as-code, and self-service interfaces |
| incident operations | runbooks, severity model, escalation, and postmortems |
Workflow
- classify the dominant problem:
- provisioning
- deployment
- CI/CD
- observability
- platform engineering
- security hardening
- incident operations
- choose the smallest viable toolchain that matches the runtime and team skill
- load the relevant reference and template set
- use source and release links to check the target runtime's supported APIs, tool compatibility, and deprecations; for provenance, load supply-chain-security and assess the actual builder against the selected SLSA track
- separate evidence stages: static lint/plan, target-environment reconciliation, runtime health plus a representative service path, and rollback or roll-forward readiness
- finish with concrete operational outputs: plan, controls, owners, artifact or commit identity, environment, observation window, and untested failure modes
Decision Rules
| Situation | Rule |
|---|---|
| infrastructure change | IaC by default; reconcile an emergency manual change back into code before the next promotion |
| steady-state production reconciliation | GitOps (Argo CD / Flux) over push-based deploys |
| CI credentials | workload identity (OIDC) over long-lived secrets |
| alerting | page on actionable SLO burn rates or imminent capacity exhaustion; send diagnostic host metrics to dashboards |
| new environments | platform template + policy guard; no snowflakes |
| supply-chain integrity | SLSA build track + cosign keyless signing |
| drift | detect via reconciler or terraform plan in CI; never discover by accident |
Related Routing
- service-level retries, deadlines, and chaos engineering -> qa-resilience
- telemetry implementation details -> qa-observability
- backend service design -> software-backend
- system architecture -> software-architecture-design
- appsec-specific design -> software-security-appsec
- Git branch and PR workflow policy -> dev-git-workflow
- running a live incident, on-call, or postmortems -> ops-incident-response
- cloud, SaaS, or AI API spend -> ops-cost-optimization
- .NET builds on NUKE -> ops-nuke-cicd
Guardrails
| Domain | Do | Anti-pattern to avoid |
|---|---|---|
| Provisioning | all material changes in IaC; explicit promotion gates | clickops drift; untagged infrastructure |
| Delivery | protected pipelines; artifact provenance; rollback + smoke checks | pipelines without identity boundaries |
| Platform | golden paths before self-service; policy-as-code that reduces variation | tools shipped without adoption path or ownership |
| Observability | define SLOs first; join logs/traces/metrics on shared trace ID | alert fatigue from raw host-metric thresholds |
| Incidents | postmortems feed runbooks and platform changes | postmortems that stop at narrative |
| Cost | tagging + budget alerts at resource creation; monthly right-sizing | unmanaged snowflake environments; unreviewed reservations |
Navigation
Reference routing
| Load when… | Reference |
|---|---|
| supply-chain, SBOM, signing, SLSA | references/supply-chain-security.md |
| DORA's five metrics and team archetypes (Elite/High/Medium/Low tiers are retired), AI-adoption instability tax, general DevOps best practices | references/devops-best-practices.md |
| GitLab CI — parent/child pipelines, MR variable traps, env-export pattern | references/gitlab-ci-patterns.md |
| choosing a tool (IaC, GitOps, CI, policy, observability) | references/tool-landscape.md |
| golden paths, internal developer portal, platform maturity, when NOT to build an IDP, platform-vs-product boundary, measuring team cognitive load (Weis four-cluster model, Teamperature, leadership load), CI/IaC/GitOps adoption sequencing | references/platform-engineering-patterns.md |
| GitOps multi-env promotion, Argo CD / Flux patterns, automation lag and why continuous apply beats apply-on-change | references/gitops-workflows.md |
Terraform state isolation, why terraform workspace is wrong for environments, stage/prod/mgmt/global layout, secrets-in-state and backend choice |
references/terraform-state-architecture.md |
| stack sizing (monolithic → application-group → service → micro), blast radius, "is my stack a monolith?" | references/stack-sizing-patterns.md |
| IaC testing rungs and their blind spots, infrastructure test diamond vs pyramid, Swiss-cheese layering | references/infrastructure-testing-strategy.md |
| on-call, severity model, escalation, postmortems | references/sre-incident-management.md |
| day-2 operational runbooks, environment hygiene | references/operational-patterns.md |
| AIOps alert correlation, automated triage | references/aiops-patterns.md |
| Kalman canary, cost autoscaler, CI capacity stabiliser | references/control-theory-applied.md |
| capacity planning, saturation SLO, pipeline bottleneck hunt | references/queueing-theory-applied.md |
| CI/CD throughput recovery, constraint surfacing, spend reallocation | references/theory-of-constraints-applied.md |
| platform-team charter, algedonic escalation, PRR audit | references/cybernetics-vsm-applied.md |
| MTBF/MTTR, availability budgets, FMEA | references/reliability-theory-applied.md |
| CAP/PACELC, consensus, idempotency, quorums | references/distributed-systems-applied.md |
| source URLs and release trackers | data/sources.json |
When changing the source inventory, run python3 scripts/validate_sources.py --skip-network from this skill directory for schema and coverage only. Run the offline CLI regressions with python3 -m pytest scripts/test_validate_sources.py. URL reachability and source content require separate checks; a schema pass does not refresh evidence dates.
Templates
AWS / GCP / Azure
- assets/aws/template-aws-ops.md — AWS day-2 ops checklist
- assets/aws/template-aws-terraform.md — AWS Terraform module skeleton
- assets/aws/template-cost-optimization.md — AWS cost right-sizing and reservation review
- assets/gcp/template-gcp-ops.md — GCP day-2 ops checklist
- assets/gcp/template-gcp-terraform.md — GCP Terraform module skeleton
- assets/azure/template-azure-ops.md — Azure day-2 ops checklist
Kubernetes
- assets/kubernetes/template-kubernetes-ops.md — cluster day-2 ops, probe and rolling-update rules, HPA checklist
- assets/kubernetes/template-ha-dr.md — HA and disaster-recovery topology
- assets/kubernetes/template-platform-api.md — platform API contract for self-service
- assets/kubernetes/template-k8s-deploy.yaml — base Deployment manifest
Docker / Kafka
- assets/docker/template-docker-ops.md — image build and runtime hardening
- assets/kafka/template-kafka-ops.md — Kafka cluster operations
Terraform / IaC
- assets/terraform-iac/template-iac-terraform.md — root module structure
- assets/terraform-iac/template-module.md — reusable child module
- assets/terraform-iac/template-env-promotion.md — environment promotion workflow
CI/CD and GitOps
- assets/cicd-pipelines/template-ci-cd.md — generic CI/CD pipeline design
- assets/cicd-pipelines/template-github-actions.md — GitHub Actions workflow with OIDC
- assets/cicd-pipelines/template-gitops.md — GitOps promotion pipeline
- assets/cicd-pipelines/template-release-safety.md — release gates and rollback
Monitoring / Observability
- assets/monitoring-observability/template-slo.md — SLO definition sheet
- assets/monitoring-observability/template-alert-rules.md — burn-rate alert rules
- assets/monitoring-observability/template-observability-slo.md — full observability + SLO stack
- assets/monitoring-observability/template-loadtest-perf.md — load-test and performance baseline
Incident response
- assets/incident-response/template-postmortem.md — blameless postmortem
- assets/incident-response/template-runbook-starter.md — runbook starter
- assets/incident-response/template-incident-comm.md — stakeholder communications
- assets/incident-response/template-incident-response.md — full IR playbook
Security / Cost
- assets/security/template-security-hardening.md — hardening checklist
- assets/cost-governance/template-cost-governance.md — FinOps tagging and budget controls
Shared utilities
- ../software-clean-code-standard/references/config-validation.md
- ../software-clean-code-standard/references/resilience-utilities.md
- ../software-clean-code-standard/references/logging-utilities.md
- ../software-clean-code-standard/references/observability-utilities.md
Related Skills
- ../qa-resilience/SKILL.md
- ../data-sql-optimization/SKILL.md
- ../qa-observability/SKILL.md
- ../qa-debugging/SKILL.md
- ../software-security-appsec/SKILL.md
- ../software-backend/SKILL.md
- ../software-architecture-design/SKILL.md
- ../dev-api-design/SKILL.md
- ../dev-git-workflow/SKILL.md
- ../ai-mlops/SKILL.md
Learnings Loop
When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.