tomevault-io Deploy-Health Craft
Codified at I86 Wave R close (drain7) to operationalise the I66 P5 + I68 P5/P7 precedent. The craft turns deploy verification from manual visual hunt into structured 4-step checklist + a growing Failure-N catalogue. Ratified by D-IH-86-CT.
When to use this skill
Read this skill at the start of any operator turn that touches a consumer repo tracked in REPOSITORY_REGISTRY.csv, before authoring a sibling-repo PR, and before closing any wave that includes sibling-repo work.
This skill assumes you have already read akos-deploy-health.mdc.
Core principles
Principle 1 — Always check deploy status FIRST
Before any other turn-work on a consumer repo, poll the hosting platform's MCP for the last 5 deployments. Three or more consecutive terminal-error states usually means a code regression that's blocking everyone, not a transient infra issue. Don't author new commits on top of broken deploys without acknowledging the breakage.
Platform → tool mapping:
- Vercel:
list_deployments(teamId, projectId, limit=5). - Render:
list_deploys(serviceId, limit=5). - Other (GitHub Pages, Cloudflare, AWS): document polling tool when added.
Principle 2 — Build log inspection on failure
If the most recent deploy is terminal-error, fetch + parse the build log:
- Vercel:
get_deployment_build_logs(teamId, idOrUrl, limit=400). - Render:
list_logs(serviceId, deployId, limit=400).
Look in the last ~30 events for the actual error trail. First events are typically clone + dep-install warnings (noise). See §"Failure-N catalogue" for known patterns.
Principle 3 — Multi-viewport visual smoke (after successful deploy)
Run the browser-use subagent against 5 standard viewports:
- 375 × 667 (iPhone SE) — narrowest mobile.
- 414 × 896 (iPhone 11/12/13/14/15) — wider mobile.
- 768 × 1024 (iPad portrait) — tablet.
- 1280 × 800 (desktop default) — most-common laptop.
- 1920 × 1080 (wide desktop) — large monitor.
Subagent prompt should explicitly enumerate:
- Pages or routes to load + key elements to verify.
- Locale switching where applicable.
- Console errors / 404s.
- Mobile-specific overflow / overlap / illegibility checks.
- Auth state (preview deployments may need session credentials).
Report format: HIGH / MEDIUM / LOW severity with actionable remediation per finding.
Principle 4 — Build-time optimisation gates
Operator's stated target: < 2 min per preview build for typical frontend repos. If exceeded, profile the build log timestamps + apply targeted optimisations:
- Observability source-map upload: non-blocking + skip on previews; production only.
- Stale build cache: ensure cache restored across deploys ("fresh dependency install" line = cache miss).
- Static prerender of dynamic routes: lazy-init singleton pattern (Failure 3 fix).
- Framework-level: Turbopack opt-in (Next.js 14+); Vite for SPAs; SWC over Babel.
Principle 5 — Failure-N catalogue is craft-shaped; add new patterns
The Failure-N catalogue in the parent rule grows with each incident. When a new failure mode is encountered:
- Reproduce it in the build log.
- Add a new
### Failure N — <one-line title>section to the parent rule body. - Each entry specifies: symptom + root cause + canonical fix + framework-applicability.
- Reference any reusable template files by path, not by full content.
- Update the relevant initiative's ChangeLog entry with a back-reference.
Speculative failure entries (e.g., "Failure 6 awaits P3 confirmation") are allowed; promote to "confirmed" on first observation in real CI.
Failure-N catalogue summary (per parent rule body)
| # | Title | Framework | Severity |
|---|---|---|---|
| 1 | Duplicate declare global { interface Window } |
TypeScript | HIGH |
| 2 | Observability SDK CLI fails build on transient API error | Any with source-map upload | MEDIUM |
| 3 | Static prerender fails on data-source-dependent route | Next.js / Remix / SvelteKit | HIGH |
| 4 | Mobile navbar overflow / no hamburger | Web frontends | MEDIUM |
| 5 | Sticky secondary header overlapping primary navbar | Web frontends | MEDIUM |
| 6 (speculative) | Visual-regression false positive on font subpixel | Playwright VR | LOW |
| 7 (speculative) | Render auto-deploy timeout on cold-start | Render workers | MEDIUM |
Full per-failure detail lives in the parent rule body §"Common build failures + canonical fixes".
Pre-flight checklist (every consumer-repo turn)
- Polled hosting platform MCP for last 5 deploys.
- No 3+ consecutive terminal-error states (or, if yes, acknowledged the blocker).
- If most-recent failed: build log fetched + last ~30 events inspected against Failure-N catalogue.
- After successful deploy: multi-viewport visual smoke triggered (via browser-use).
- Build-time profiled if > 2 min.
- Findings filed at HIGH / MEDIUM / LOW with actionable remediation.
- New failure modes added to parent rule + ChangeLog cross-referenced.
Anti-patterns
- AP1 — Skip the deploy status check. Authoring on top of broken deploys; rework + operator confusion.
- AP2 — Read whole build log linearly. Wastes time; the error is in the last 30 events.
- AP3 — Single-viewport smoke. Mobile overflow + sticky overlap go unnoticed; ship-blocking issues post-deploy.
- AP4 — Accept > 2 min build as normal. Sets bad baseline; future builds degrade further.
- AP5 — Don't catalogue new failures. Same pattern hits another agent later; rediscovery cost.
Cross-references
- Parent rule:
akos-deploy-health.mdc. - Repo registry:
REPOSITORY_REGISTRY.csv. - Sister rule:
akos-techops-discipline.mdc(TECHOPS mechanical layer). - Worked example: I68 P7 InfraMonitor module v0 + I66 P5 build-fix incident.
- Ratifying decision: D-IH-86-CT (this skill mint).
Source: FraysaXII/openclaw-akos — distributed by TomeVault.