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:
- Topology — resources, identities, networks, and data flow (names tied to this project)
- IaC placement — which files/modules change; no orphan snippets
- Pipeline fit — which CI stage runs plan vs apply vs deploy
- First-deploy blockers — RBAC, quotas, Key Vault access, state backend, secrets, region SKUs
- 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":
- Prerequisites — subscription, permissions, tools (
az, terraform, docker), env vars
- Exact commands — copy-pasteable, with working directory
- Validation — at least one of:
terraform validate + plan, az deployment group validate, npm test, docker build, CI preflight (ci-preflight skill)
- Smoke test — how to confirm the deployment succeeded (URL, health endpoint,
az resource show)
- Rollback —
terraform destroy scope, redeploy previous revision, or revert commit
- 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.
1---2name: deployment-practical3description: 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).4---56# Deployment-practical78Shift from theoretical recommendations to **provisionable architecture** that survives a real first deploy.910## When to use1112- User is deploying, planning infra, or fixing first-apply / first-run failures13- Advice so far was generic and did not work on first attempt14- Practical Focus is set to **architecture-first** or **deploy-ready**15- Questions about Azure, Terraform, CI/CD, containers, or release pipelines in **this** repo1617## 1. Read before advising1819Scan the repo for existing deployment truth (do not invent a greenfield stack):2021| Look for | Why |22|---|---|23| `**/*.tf`, `backend.tf`, `modules/` | Terraform patterns, state backend, naming |24| `**/*.bicep`, `azure.yaml` | Azd/Bicep layout |25| `.gitlab-ci.yml`, `.gitlab/ci/*.yml` | Pipeline stages, manual gates, deploy jobs |26| `.github/workflows/*` | GH Actions deploy pattern |27| `Dockerfile*`, `docker-compose*` | Container build and runtime |28| `.azure/deployment-plan.md`, `infra/` | Project-specific deploy plan |29| `.claude/learning/runs.jsonl` | Known failures and fixes from past sessions |3031Pick **one default approach** aligned with what the repo already uses. Only propose a different stack if the user explicitly asks to change it.3233## 2. Architecture-first output3435When explaining or designing, deliver:36371. **Topology** — resources, identities, networks, and data flow (names tied to this project)382. **IaC placement** — which files/modules change; no orphan snippets393. **Pipeline fit** — which CI stage runs plan vs apply vs deploy404. **First-deploy blockers** — RBAC, quotas, Key Vault access, state backend, secrets, region SKUs415. **Single recommended path** — not a menu of five options unless the user asked for comparison4243Skip long theory unless it changes a concrete decision.4445## 3. Deploy-ready checklist (first-try)4647Before saying "ready to deploy" or "this should work":48491. **Prerequisites** — subscription, permissions, tools (`az`, `terraform`, `docker`), env vars502. **Exact commands** — copy-pasteable, with working directory513. **Validation** — at least one of: `terraform validate` + `plan`, `az deployment group validate`, `npm test`, `docker build`, CI preflight (`ci-preflight` skill)524. **Smoke test** — how to confirm the deployment succeeded (URL, health endpoint, `az resource show`)535. **Rollback** — `terraform destroy` scope, redeploy previous revision, or revert commit546. **Admin handoff** — if RBAC blocks the executing identity, give the exact `az role assignment` or portal step5556If validation cannot run in this environment, say what the user must run and do not claim success.5758## 4. Common first-deploy failures5960| Symptom | Likely cause | Fix pattern |61|---|---|---|62| 403 AuthorizationFailed | Executor lacks role; code is fine | `azure-rbac-diagnostics` — exact role + `az` command for admin |63| Terraform backend error | State/backend mismatch | Read `backend.tf`; match CI's init flags |64| Quota / SKU unavailable | Wrong region or limit | Check quota before apply; pick supported SKU |65| Secret not found | Key Vault RBAC or wrong name | List secret **names** only; verify MI access |66| CI plan OK, apply fails | Manual gate or prod credentials | Read pipeline rules; reproduce apply stage locally if safe |67| "Works locally" but not in cloud | Missing env, identity, or networking | Diff local vs deployed config from repo files |6869Hand off to `ci-pipeline-debug`, `terraform-plan-review`, `azure-validate`, or `self-learning` when specialized.7071## 5. Anti-patterns (do not do)7273- Generic cloud architecture essays with no file paths74- "You could use Lambda/Functions/Container Apps…" without picking one for this repo75- Deploy steps without validation76- Assuming permissions the user's identity does not have77- Marking tasks done when only documentation was written7879## 6. Record outcomes8081After a deploy attempt, record pass/fail in `self-learning` so the next session does not repeat the same first-try failure.
sergeyitaly