Saas Release Checklist

---
name: saas-release-checklist
description: "Pre-release checklist — build verification, certification requirements, store metadata, launch readiness."
argument-hint: "[target: web|mobile|api|all]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Bash(bash "*/.claude/skills/saas-release-checklist/../../hooks/yaml-helper.sh" resolve_config *)
model: sonnet
---
!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys locale,rigor,workflow,project.stage,cert_tier,automation`

**Automation mode**: Resolve `modes.automation` (`project.local.yaml` →
`project.yaml` → default `collaborative`). Every `AskUserQuestion` call and
every file write follows `.claude/docs/automation-modes.md`
(collaborative asks always · guided major-only · autonomous logs and proceeds;
`automation_always_ask` categories always prompt).

Resolved above — use as-is. No block → defaults in `.claude/docs/config-resolution.md`.

# Release Checklist

> **Interaction Localization Rule**:
> When `locale: pt-BR` (or user speaks Portuguese), ALL questions (`AskUserQuestion` / `ask_question`), confirmation prompts, and selectable options MUST be translated and presented in **Brazilian Portuguese (PT-BR)**.
> Any English question text or options in this skill are illustrative examples — NEVER display English questions or options to a Portuguese developer.
> Internal reasoning, code synthesis, tests, and documentation files MUST remain in English.

**Scope this checklist to the project.** Emitting every item for every platform
trains the reader to skip the list, which defeats the gate:

- **`project.stage`** — items for phases this project has not reached are out of
  scope; say so rather than listing them unchecked.
- **`modes.rigor`** — at `minimal`, drop items whose only justification is process
  weight this project has opted out of.
- **`platform.cert_tier`** — emit certification items **only** for the tier the
  project targets. If it is **unset**, **ask which platforms are in scope**
  rather than emitting all of them — an unset value is a question, not a licence
  to emit every certification track. If it cannot be determined, mark the section
  **`NOT ASSESSED — cert tier unknown`**. **Unset is not `none`:** `none` is a
  decision, unset is a missing one, and they must not produce the same output.
  Branch on the **four values this key takes** — `none | gdpr-lgpd | pci-dss | soc2 | hipaa` —
  and not on platform names. The full requirement table is the `## platform.cert_tier`
  section of `.claude/docs/effects-map.md` — read **only that section** (Grep its
  heading, then a bounded Read); the file as a whole is not a runtime input.
  - `none` — **emit no certification section at all.** Internal release, alpha or
    minimal prototype. Say the section was omitted and why; do not leave it blank.
  - `gdpr-lgpd` — Data privacy regulations: cookie consent, privacy policy, right to erasure, DPO.
  - `pci-dss` — Payment card security: tokenized Stripe integration, zero raw PAN storage, webhook validation.
  - `soc2` — Enterprise B2B compliance: RBAC, MFA enforcement, audit logging, daily backup integrity.
  - `hipaa` — Healthcare data safeguards: ePHI encryption, BAA agreements, strict audit trails.

  > **Branch on the `compliance.cert_tier` values above, not on platform names.**
  > Use the compliance vocabulary the SaaS configuration defines.

If an item cannot be scoped because the config is absent, mark it
**`NOT ASSESSED — platform/stage unknown`**. Do not silently include it: a
`rigor: standard`, single-target project would otherwise receive a ~150-item
checklist demanding desktop **and** mobile **and** enterprise certification,
of which ~140 are unassessable.

---


## Phase 1: Parse Arguments

Read the argument for the target platform (`web`, `desktop`, `mobile`, or `all`). If no platform is specified, default to `all`.

**The argument selects DEVICE / CLIENT requirements. It never selects the certification
track.** Certification is decided by `platform.cert_tier`, resolved in the resolved-config block at the top of this skill —
see the `platform.cert_tier` rule above. The two axes are different lists:
`web`/`desktop`/`mobile` are client platforms, while
`none|gdpr-lgpd|pci-dss|soc2|hipaa` are certification regimes. Emitting a device block says nothing about which
certification block to emit, and `all` is **not** a licence to emit every
certification track.

---

## Phase 2: Load Project Context

- Read `CLAUDE.md` for project context, version information, and platform targets.
- Read the current milestone from `production/milestones/` to understand what features and content should be included in this release.
- Read the open bugs from `production/qa/bugs/`: grep the `**Severity**` and `**Status**` lines of `production/qa/bugs/*.md`, as `/saas-bug-triage` does. A bug is open unless its Status is `Closed` or `Verified Fixed`. The bug items use the thresholds `/saas-gate-check release` applies for the resolved `workflow`: at `full` an open S1, S2 or S3 bug fails its item; at `standard` and `minimal` only an open S1 does, and an open S2 or S3 is listed in the Rationale as a risk. Each failing bug is named in the Rationale as a blocking item. **No bug files in `production/qa/bugs/`** → the bug items read `NOT ASSESSED — no bug records` — never zero and never ticked, since an absent record and a clean one must not produce the same checklist; bugs are filed with `/saas-bug-report`.

---

## Phase 3: Scan Codebase

> **State the denominator with every count.** These scans look for something bad,
> so `0` means either "searched and found none" or "there was nothing to search",
> and on a release gate those are opposite findings. Report
> `scanned [N] source files: [M] TODO, [M] FIXME, [M] HACK` — or, when the code
> root (`src/`, `Assets/` or `Source/`; resolve per
> `.claude/docs/code-root-resolution.md`) is unresolved,
> **`NOT ASSESSED — code root unresolved`**, and when it is absent or holds no
> source files, **`NOT ASSESSED — no source files found to scan`**. A bare `0` is
> not a result.

Scan for outstanding issues:

- Count `TODO` comments
- Count `FIXME` comments
- Count `HACK` comments
- Note their locations and severity

Check for test results in any test output directories or CI logs if available.
**If none are found, say so** — `Test results: NOT ASSESSED — no test output or
CI logs found` — rather than omitting the line. An absent test result and a
passing one must not produce the same release checklist.

---

## Phase 4: Generate the Release Checklist

```markdown
## Release Checklist: [Version] -- [Platform]
Generated: [Date]

### Codebase Health
- Scanned: [N] source files (or `NOT ASSESSED — [reason]`, per Phase 3)
- TODO count: [N] ([list top 5 if many])
- FIXME count: [N] ([list all -- these are potential blockers])
- HACK count: [N] ([list all -- these need review])

### Build Verification
- [ ] Clean build succeeds on all target platforms
- [ ] No compiler warnings (zero-warning policy)
- [ ] All assets included and loading correctly
- [ ] Build size within budget ([target size])
- [ ] Build version number correctly set ([version])
- [ ] Build is reproducible from tagged commit

### Quality Gates
- Open bugs (`production/qa/bugs/`): [N] S1, [N] S2, [N] S3 -- or `NOT ASSESSED — no bug records`
- [ ] Zero open S1 (Critical) bugs
- [ ] Zero open S2 (High) bugs (`workflow: full` strict requirement)
- [ ] Zero open S3 (Medium) bugs (`workflow: full` strict requirement)
- [ ] All critical user journeys tested and signed off by QA:
  - [ ] Signup, login, password recovery, session renewal
  - [ ] Onboarding wizard, tenant workspace provisioning
  - [ ] Core product workflows end-to-end
  - [ ] Billing checkout, upgrade, invoice download, downgrade
- [ ] Performance benchmarks met:
  - [ ] API latency p95 < 200ms under load
  - [ ] Lighthouse Core Web Vitals (LCP < 2.0s, INP < 100ms, CLS < 0.1)
  - [ ] Concurrency load test passed (sustained traffic without memory leaks)
- [ ] Automated test suite 100% passing (Unit, Integration, Playwright E2E)

### Content & User Experience Complete
- [ ] All placeholder text and mock data replaced with production copy
- [ ] All TODO/FIXME comments in user-facing code resolved
- [ ] Microcopy, tooltips, and empty states proofread
- [ ] Error messages actionable and localized
- [ ] Terms of Service and Privacy Policy published and linked
```

Add **device** sections based on the argument. These carry no certification or
storefront-SDK items — those are gated on `platform.cert_tier` in the next
subsection, and repeating them here would hand an `itch` project Steamworks rows.

**For `pc`:**
```markdown
### Platform Requirements: Web Desktop
- [ ] Modern desktop browsers verified (Chrome, Safari, Firefox, Edge)
- [ ] Responsive layouts verified across breakpoints (1280px, 1440px, 1920px)
- [ ] Keyboard accessibility and focus rings functional (WCAG 2.2 AA)
- [ ] Clipboard and file upload interactions verified
- [ ] System theme detection (Dark/Light mode) verified

**For `api`:**
```markdown
### Platform Requirements: API & Headless
- [ ] OpenAPI / Swagger documentation interactive and up to date
- [ ] Rate-limiting headers (`RateLimit-Remaining`, `Retry-After`) verified
- [ ] Idempotency key handling (`Idempotency-Key` header) tested on mutations
- [ ] API authentication (Bearer tokens / API keys) and revocation functional
```

**For `mobile`:**
```markdown
### Platform Requirements: Mobile Web & PWA
- [ ] Touch target sizes conform to >= 44x44px
- [ ] Mobile Safari and Android Chrome layout verified (no horizontal overflow)
- [ ] Virtual keyboard appearance does not break modal or sticky action buttons
- [ ] PWA manifest and mobile app icons (`apple-touch-icon.png`) verified
```

> **Mobile storefront rows stay here on purpose.** `platform.cert_tier` models
> `none|gdpr-lgpd|pci-dss|soc2|hipaa` and has no mobile regime, so App Store / Play Store
> compliance cannot be gated on it. Leaving these in the device block is a
> deliberate choice, not an oversight — do not "fix" it by inventing a `mobile`
> tier, which is the exact wrong vocabulary the `cert_tier` rule warns against.

**Certification — emit ONLY the block matching `platform.cert_tier`** (resolved in
the resolved-config block at the top of this skill). Do not emit this subsection's other blocks, and do not fall back to
emitting all of them because the platform argument was `all`.

**At `none`** — emit no certification block at all. Emit exactly this one line in
its place, so the omission is visible rather than looking like a missing section:
```markdown
Certification: omitted — cert_tier is 'none' (internal build, alpha or jam release).
```

**At `gdpr-lgpd`:**
```markdown
### Certification: GDPR & LGPD
- [ ] Cookie consent banner with granular opt-in configured
- [ ] Privacy Policy and Terms of Service published with subprocessor list
- [ ] Right to Erasure / Account deletion cascade tested
- [ ] Data Export (JSON/CSV) functional
- [ ] Encryption at rest (AES-256) and in transit (TLS 1.3) verified
```

**At `pci-dss`:**
```markdown
### Certification: PCI-DSS
- [ ] Tokenized payment forms (Stripe Elements / Checkout) verified
- [ ] Zero cardholder PAN or CVV stored or logged on servers
- [ ] Webhook signature verification and replay protection enforced
- [ ] SAQ A / SAQ A-EP compliance documentation filed
```

**At `soc2`:**
```markdown
### Certification: SOC 2
- [ ] Role-Based Access Control (RBAC) enforced across all tenant workspaces
- [ ] Multi-Factor Authentication (MFA) enforced on all admin accounts
- [ ] Immutable audit logging active for sensitive administrative events
- [ ] Automated daily database backups and restore drills verified
```

If `cert_tier` is **unset**, ask which platforms are in scope rather than
emitting every track; if it cannot be determined, emit
`### Certification: NOT ASSESSED — cert tier unknown` and say why. **Unset is not
`none`** — `none` is a decision and unset is a missing one.

> **Certification rows belong here, in one `cert_tier`-gated subsection.** Do not
> put them in the Web, Desktop and Mobile device blocks: those are selected by the
> command argument and default to `all`, ensuring certification items are scoped to compliance configuration.
> `/saas-release-checklist` with no argument would otherwise emit all compliance rows,
> which the `cert_tier` rule at the top of this skill forbids when cert_tier is not set.
>
> The target argument selects client platform requirements, while certification is scoped by compliance tier.

**Store and launch sections (all platforms):**
```markdown
### Production Cloud & GTM Distribution
- [ ] Production custom domain configured with DNS propagation verified
- [ ] SSL/TLS 1.3 certificate active with automatic renewal
- [ ] Cloudflare / WAF protection and rate limiting rules enabled
- [ ] PostgreSQL production database pooled (PgBouncer) with automated backups
- [ ] Stripe Live Mode keys active and webhook secret HMAC signature verified
- [ ] Email domain authentication (SPF, DKIM, DMARC) 100% verified on Resend/SendGrid
- [ ] Terms of Service and Privacy Policy published and accessible in app footer
- [ ] Product Hunt launch assets and copy ready (Gallery, Maker comment, Tagline)

### Launch Readiness & Observability
- [ ] Analytics / telemetry verified and receiving data (PostHog / Mixpanel)
- [ ] Crash reporting configured and dashboard accessible (Sentry)
- [ ] Uptime monitoring pinging `/api/health` with automated incident alerts
- [ ] On-call team schedule set for first 72 hours
- [ ] Community launch announcements drafted
- [ ] Customer support team briefed on known issues and FAQ
- [ ] Rollback plan documented and tested in case of critical production issues

### Go / No-Go: [READY / NOT ASSESSED / NOT READY]

First match wins: **NOT READY** if any blocking item fails; else **NOT ASSESSED**
if any section or item came out `NOT ASSESSED` (name each one); else **READY**. NOT
ASSESSED outranks READY — an unassessed section is not a passed one — and ranks
below NOT READY, so a known blocker is never buried behind it.

**Rationale:**
[Summary of readiness assessment. List any blocking items that must be
resolved before launch. If NOT READY, list the specific items that need
resolution and estimated time to address them.]

**Sign-offs Required:**
- [ ] QA Lead
- [ ] Technical Director
- [ ] Producer
- [ ] Creative Director
```

---

## Phase 5: Save Checklist

Present the checklist to the user with: total checklist items, number of known blockers (FIXME/HACK counts, known bugs).

Ask: "May I write this to `production/releases/saas-release-checklist-[version].md`?"

If yes, write the file, creating the directory if needed.

---

## Phase 6: Next Steps

- Draft the changelog or patch notes (`/saas-changelog`, `/saas-patch-notes`) if not done — the release gate checks them.
- Run `/saas-gate-check release` — the Polish → Release gate reads this checklist.
- After a PASS: `/saas-launch-checklist`, then coordinate the release via `/saas-team-release`.