# Deployment Practical

> Deployment-first delivery — concrete architecture and IaC over theoretical advice. Use when deploying, provisioning infra, debugging first-apply failures, or when the user wants advice that works on the first attempt (not hand-wavy theory). Pair with Practical Focus toggle (architecture-first / deploy-ready).

- Skill: `sergeyitaly/deployment-practical` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sergeyitaly/deployment-practical`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sergeyitaly/deployment-practical/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: sergeyitaly (https://skillmd.com/u/sergeyitaly)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sergeyitaly/deployment-practical

---


# Deployment-practical

Shift from theoretical recommendations to **provisionable architecture** that survives a real first deploy.

## When to use

- User is deploying, planning infra, or fixing first-apply / first-run failures
- Advice so far was generic and did not work on first attempt
- Practical Focus is set to **architecture-first** or **deploy-ready**
- Questions about Azure, Terraform, CI/CD, containers, or release pipelines in **this** repo

## 1. Read before advising

Scan the repo for existing deployment truth (do not invent a greenfield stack):

| Look for | Why |
|---|---|
| `**/*.tf`, `backend.tf`, `modules/` | Terraform patterns, state backend, naming |
| `**/*.bicep`, `azure.yaml` | Azd/Bicep layout |
| `.gitlab-ci.yml`, `.gitlab/ci/*.yml` | Pipeline stages, manual gates, deploy jobs |
| `.github/workflows/*` | GH Actions deploy pattern |
| `Dockerfile*`, `docker-compose*` | Container build and runtime |
| `.azure/deployment-plan.md`, `infra/` | Project-specific deploy plan |
| `.claude/learning/runs.jsonl` | Known failures and fixes from past sessions |

Pick **one default approach** aligned with what the repo already uses. Only propose a different stack if the user explicitly asks to change it.

## 2. Architecture-first output

When explaining or designing, deliver:

1. **Topology** — resources, identities, networks, and data flow (names tied to this project)
2. **IaC placement** — which files/modules change; no orphan snippets
3. **Pipeline fit** — which CI stage runs plan vs apply vs deploy
4. **First-deploy blockers** — RBAC, quotas, Key Vault access, state backend, secrets, region SKUs
5. **Single recommended path** — not a menu of five options unless the user asked for comparison

Skip long theory unless it changes a concrete decision.

## 3. Deploy-ready checklist (first-try)

Before saying "ready to deploy" or "this should work":

1. **Prerequisites** — subscription, permissions, tools (`az`, `terraform`, `docker`), env vars
2. **Exact commands** — copy-pasteable, with working directory
3. **Validation** — at least one of: `terraform validate` + `plan`, `az deployment group validate`, `npm test`, `docker build`, CI preflight (`ci-preflight` skill)
4. **Smoke test** — how to confirm the deployment succeeded (URL, health endpoint, `az resource show`)
5. **Rollback** — `terraform destroy` scope, redeploy previous revision, or revert commit
6. **Admin handoff** — if RBAC blocks the executing identity, give the exact `az role assignment` or portal step

If validation cannot run in this environment, say what the user must run and do not claim success.

## 4. Common first-deploy failures

| Symptom | Likely cause | Fix pattern |
|---|---|---|
| 403 AuthorizationFailed | Executor lacks role; code is fine | `azure-rbac-diagnostics` — exact role + `az` command for admin |
| Terraform backend error | State/backend mismatch | Read `backend.tf`; match CI's init flags |
| Quota / SKU unavailable | Wrong region or limit | Check quota before apply; pick supported SKU |
| Secret not found | Key Vault RBAC or wrong name | List secret **names** only; verify MI access |
| CI plan OK, apply fails | Manual gate or prod credentials | Read pipeline rules; reproduce apply stage locally if safe |
| "Works locally" but not in cloud | Missing env, identity, or networking | Diff local vs deployed config from repo files |

Hand off to `ci-pipeline-debug`, `terraform-plan-review`, `azure-validate`, or `self-learning` when specialized.

## 5. Anti-patterns (do not do)

- Generic cloud architecture essays with no file paths
- "You could use Lambda/Functions/Container Apps…" without picking one for this repo
- Deploy steps without validation
- Assuming permissions the user's identity does not have
- Marking tasks done when only documentation was written

## 6. Record outcomes

After a deploy attempt, record pass/fail in `self-learning` so the next session does not repeat the same first-try failure.