detections/.cursor/skills/deploy/SKILL.md

---
name: deploy
description: |
  Comprehensive deployment skill covering status check, env setup, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts.
  7-step workflow: Status & env check, Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures, deployment scripts.
  Uses _docs/04_deploy/ structure.
  Trigger phrases:
  - "deploy", "deployment", "deployment strategy"
  - "CI/CD", "pipeline", "containerize"
  - "observability", "monitoring", "logging"
  - "dockerize", "docker compose"
category: ship
tags: [deployment, docker, ci-cd, observability, monitoring, containerization, scripts]
disable-model-invocation: true
---

# Deployment Planning

Plan and document the full deployment lifecycle: check deployment status and environment requirements, containerize the application, define CI/CD pipelines, configure environments, set up observability, document deployment procedures, and generate deployment scripts.

## Core Principles

- **Docker-first**: every component runs in a container; local dev, blackbox tests, and production all use Docker
- **Infrastructure as code**: all deployment configuration is version-controlled
- **Observability built-in**: logging, metrics, and tracing are part of the deployment plan, not afterthoughts
- **Environment parity**: dev, staging, and production environments mirror each other as closely as possible
- **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work
- **Ask, don't assume**: when infrastructure constraints or preferences are unclear, ask the user
- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code (except deployment scripts in Step 7)

## Context Resolution

Fixed paths:

- DOCUMENT_DIR: `_docs/02_document/`
- DEPLOY_DIR: `_docs/04_deploy/`
- REPORTS_DIR: `_docs/04_deploy/reports/`
- SCRIPTS_DIR: `scripts/`
- ARCHITECTURE: `_docs/02_document/architecture.md`
- COMPONENTS_DIR: `_docs/02_document/components/`

Announce the resolved paths to the user before proceeding.

## Input Specification

### Required Files

| File | Purpose | Required |
|------|---------|----------|
| `_docs/00_problem/problem.md` | Problem description and context | Greenfield only |
| `_docs/00_problem/restrictions.md` | Constraints and limitations | Greenfield only |
| `_docs/01_solution/solution.md` | Finalized solution | Greenfield only |
| `DOCUMENT_DIR/architecture.md` | Architecture (from plan or document skill) | Always |
| `DOCUMENT_DIR/components/` | Component specs | Always |

### Prerequisite Checks (BLOCKING)

1. `architecture.md` exists — **STOP if missing**, run `/plan` first
2. At least one component spec exists in `DOCUMENT_DIR/components/` — **STOP if missing**
3. Create DEPLOY_DIR, REPORTS_DIR, and SCRIPTS_DIR if they do not exist
4. If DEPLOY_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**

## Artifact Management

### Directory Structure

```
DEPLOY_DIR/
├── containerization.md
├── ci_cd_pipeline.md
├── environment_strategy.md
├── observability.md
├── deployment_procedures.md
├── deploy_scripts.md
└── reports/
    └── deploy_status_report.md

SCRIPTS_DIR/           (project root)
├── deploy.sh
├── pull-images.sh
├── start-services.sh
├── stop-services.sh
└── health-check.sh

.env                   (project root, git-ignored)
.env.example           (project root, committed)
```

### Save Timing

| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Status check & env setup complete | `reports/deploy_status_report.md` + `.env` + `.env.example` |
| Step 2 | Containerization plan complete | `containerization.md` |
| Step 3 | CI/CD pipeline defined | `ci_cd_pipeline.md` |
| Step 4 | Environment strategy documented | `environment_strategy.md` |
| Step 5 | Observability plan complete | `observability.md` |
| Step 6 | Deployment procedures documented | `deployment_procedures.md` |
| Step 7 | Deployment scripts created | `deploy_scripts.md` + scripts in `SCRIPTS_DIR/` |

### Resumability

If DEPLOY_DIR already contains artifacts:

1. List existing files and match to the save timing table
2. Identify the last completed step
3. Resume from the next incomplete step
4. Inform the user which steps are being skipped

## Progress Tracking

At the start of execution, create a TodoWrite with all steps (1 through 7). Update status as each step completes.

## Workflow

### Step 1: Deployment Status & Environment Setup

Read and follow `steps/01_status-env.md`.

---

### Step 2: Containerization

Read and follow `steps/02_containerization.md`.

---

### Step 3: CI/CD Pipeline

Read and follow `steps/03_ci-cd-pipeline.md`.

---

### Step 4: Environment Strategy

Read and follow `steps/04_environment-strategy.md`.

---

### Step 5: Observability

Read and follow `steps/05_observability.md`.

---

### Step 6: Deployment Procedures

Read and follow `steps/06_procedures.md`.

---

### Step 7: Deployment Scripts

Read and follow `steps/07_scripts.md`.

## Escalation Rules

| Situation | Action |
|-----------|--------|
| Unknown cloud provider or hosting | **ASK user** |
| Container registry not specified | **ASK user** |
| CI/CD platform preference unclear | **ASK user** — default to GitHub Actions |
| Secret manager not chosen | **ASK user** |
| Deployment pattern trade-offs | **ASK user** with recommendation |
| Missing architecture.md | **STOP** — run `/plan` first |
| Remote target machine details unknown | **ASK user** for SSH access, OS, and specs |

## Common Mistakes

- **Implementing during planning**: Steps 1–6 produce documents, not code (Step 7 is the exception — it creates scripts)
- **Hardcoding secrets**: never include real credentials in deployment documents or scripts
- **Ignoring blackbox test containerization**: the test environment must be containerized alongside the app
- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
- **Using `:latest` tags**: always pin base image versions
- **Forgetting observability**: logging, metrics, and tracing are deployment concerns, not post-deployment additions
- **Committing `.env`**: only `.env.example` goes to version control; `.env` must be in `.gitignore`
- **Non-portable scripts**: deployment scripts must work across environments; avoid hardcoded paths

## Methodology Quick Reference

```
┌────────────────────────────────────────────────────────────────┐
│            Deployment Planning (7-Step Method)                  │
├────────────────────────────────────────────────────────────────┤
│ PREREQ: architecture.md + component specs exist                │
│                                                                │
│ 1. Status & Env     → steps/01_status-env.md                   │
│                       → reports/deploy_status_report.md         │
│                       + .env + .env.example                    │
│    [BLOCKING: user confirms status & env vars]                 │
│ 2. Containerization → steps/02_containerization.md             │
│                       → containerization.md                    │
│    [BLOCKING: user confirms Docker plan]                       │
│ 3. CI/CD Pipeline   → steps/03_ci-cd-pipeline.md               │
│                       → ci_cd_pipeline.md                      │
│ 4. Environment      → steps/04_environment-strategy.md         │
│                       → environment_strategy.md                │
│ 5. Observability    → steps/05_observability.md                │
│                       → observability.md                       │
│ 6. Procedures       → steps/06_procedures.md                   │
│                       → deployment_procedures.md               │
│    [BLOCKING: user confirms deployment plan]                   │
│ 7. Scripts          → steps/07_scripts.md                      │
│                       → deploy_scripts.md + scripts/           │
├────────────────────────────────────────────────────────────────┤
│ Principles: Docker-first · IaC · Observability built-in        │
│             Environment parity · Save immediately              │
└────────────────────────────────────────────────────────────────┘
```