Curating Azure Deployment Learnings

Curating Azure Deployment Learnings

The feedback loop that keeps the diagnosing-azure-deployment-failures gotcha catalogue current. Capture lessons from real projects in learnings/, then promote recurring ones into the catalogue.

When to invoke

• A deployment problem was solved — capture it before it's forgotten
• Reviewing accumulated learnings/*.md for promotion candidates
• Triaging which learnings are project-specific vs broadly reusable

The pipeline

Project hits a problem in the field
   ↓
Solve it — file a learning in learnings/{date}_{project}.md
   ↓
Periodically review learnings/ — what shows up across multiple projects?
   ↓
Promote recurring ones to skills/diagnosing-azure-deployment-failures/references/gotchas.md
   ↓
Mark the learning entry "✅ Promoted in commit {sha}"

Learning file format

---
project: trg-directory-content-crawl
date: 2026-05-20
issues:
  - docker-hub-rate-limit
  - crawl4ai-pinning
severity: medium
promoted: false
---

# Session Learnings — TRG Directory Content Crawl

## Issue 1 — Docker Hub anonymous pulls hit rate limit in CI

### What happened
After 20+ successful deploys, the GitHub Actions runner started getting `toomanyrequests`
errors when pulling `unclecode/crawl4ai:latest`.

### Root cause
Docker Hub limits anonymous pulls to 100/6h per IP. GitHub-hosted runners share IPs,
so the project's pulls were rate-limited from other workflows on the same NAT IP.

### Fix applied
Pinned the image to `crawl4ai:0.8.6` and mirrored it into our ACR. Updated deploy.sh
and the Bicep template.

Files changed: `azure/deploy.sh:83`, `infra/modules/crawler.bicep:42`.

Status: ✅ Promoted as gotcha #31/#38 in commit abc1234.

The frontmatter is machine-readable; the body is for humans.

Severity rubric

Only high and medium are promotion candidates by default.

Scripts

capture-learning.sh

Interactive wrapper that creates a properly-formatted file:

bash skills/curating-azure-deployment-learnings/scripts/capture-learning.sh
# Prompts for: project slug, issue tags (comma-separated), severity, then opens the file in $EDITOR

review-learnings.sh

Scans learnings/*.md, groups by issue tag, and identifies promotion candidates:

bash skills/curating-azure-deployment-learnings/scripts/review-learnings.sh

# Output:
# Issue tag                       | Severity | Projects | Status
# --------------------------------|----------|----------|------------
# docker-hub-rate-limit           | medium   |        3 | PROMOTE
# crawl4ai-pinning                | medium   |        2 | PROMOTE
# fc1-cli-silent-fallback         | high     |        4 | already in gotchas
# trg-specific-cms-quirk          | low      |        1 | skip

promote-to-gotchas.sh

Given an issue tag, generates the markdown row to add to gotchas.md:

bash skills/curating-azure-deployment-learnings/scripts/promote-to-gotchas.sh docker-hub-rate-limit

# Output (paste into gotchas.md):
# | 38 | Docker Hub anonymous pull rate-limited in CI | 100 pulls/6h per IP | Pin tag + mirror to ACR/GHCR |

Promotion criteria

A learning is ready to promote when:

• It appears in ≥2 different projects, OR
• It's severity high (every project of that shape will hit it)
• AND the fix is reproducible — not "we restarted the runner"
• AND it's not already in the gotcha catalogue
• AND it's broadly applicable — not "this customer's CMS has a bug"

After promoting

1. Add the gotcha row to skills/diagnosing-azure-deployment-failures/references/gotchas.md
2. Update the quick symptom table in SKILL.md if symptoms match
3. Update each contributing learning's frontmatter: promoted: true and add commit SHA in the Status line
4. Commit with message: docs(gotchas): promote {issue-tag} from learnings

Anti-patterns

• Logging every minor papercut as a learning — only file when the fix is non-obvious and likely to recur
• Promoting one-project incidents — if it only happened once and you can't see why it would recur, the entry stays in learnings/ for context but doesn't go to gotchas
• Treating gotchas as commit messages — gotchas are about what to do when you hit symptom X, not what changed in commit Y. Keep entries action-oriented

Composes with

• diagnosing-azure-deployment-failures — destination for promoted learnings
• scaffolding-azure-bicep-infrastructure — many infrastructure learnings become Bicep template improvements too, not just gotchas