Production readiness

<!-- Inlined into every SKILL.md via {{PREAMBLE_CORE}}. Keep ≤30 lines. -->

Preamble (Core)

Status protocol — end every session with one of: DONE (evidence provided) · DONE_WITH_CONCERNS (list each) · BLOCKED (state what blocks you) · NEEDS_CONTEXT (state what you need).

Auto-advance — pipeline: THINK → PLAN → REVIEW → BUILD → VERIFY → RELEASE. Only human gate is spec approval at THINK. On DONE at other stages, print [STAGE] DONE -> advancing to [NEXT-STAGE] and invoke the next skill. On any non-DONE status at any stage, STOP.

Output directory — all artifacts go in docs/superomni/<kind>/<kind>-[branch]-[session]-[date].md. See CLAUDE.md for the full directory map.

TACIT-DENSE — before high-tacit decisions, classify D1 (domain expertise) · D2 (user-facing UX) · D3 (team culture) · D4 (novel pattern). On hit, output TACIT-DENSE [D#]: [question] — My default: [recommendation]. See reference for actions.

Anti-sycophancy — take a position on every significant question. Name flaws directly. No filler ("that's interesting", "you might consider", "that could work").

Telemetry (local only) — at session end, log bin/analytics-log. Nothing leaves the machine.

See preamble-ref.md for detailed protocols.

Production Readiness Gate

Goal: Verify that code is ready for production deployment — beyond just passing tests.

The distinction between "code works" and "production ready":

• Code works = tests pass, acceptance criteria met (handled by verification)
• Production ready = code can be deployed safely, operated reliably, and debugged when it fails

Iron Law: Never Deploy Without This Checklist

"CI is green" is necessary but not sufficient for production. A broken deployment with no runbook, no alerts, and no rollback plan is worse than not deploying at all.

---

Phase 1: Goal Alignment

Before checking operational concerns, confirm the output actually achieves what the user originally asked for.

# Read acceptance criteria from spec
_SPEC=$(ls docs/superomni/specs/spec-*.md 2>/dev/null | sort | tail -1)
_PLAN=$(ls docs/superomni/plans/plan-*.md 2>/dev/null | sort | tail -1)
cat "$_SPEC" 2>/dev/null | grep -A 30 "Acceptance Criteria" | head -40 || \
  cat "$_PLAN" 2>/dev/null | grep -A 20 "Success Criteria" | head -30 || \
  echo "No docs/superomni/specs/spec-*.md or docs/superomni/plans/plan-*.md found — document what you are verifying against"

For each acceptance criterion found in docs/superomni/specs/spec-*.md:

Criterion	Status	Evidence
[criterion 1]	✓/✗	[proof: test output, screenshot, or code reference]
[criterion 2]	✓/✗	[proof]

Gate: ALL P0 acceptance criteria must be ✓ before proceeding.

If no docs/superomni/specs/spec-*.md exists:

• Document what user goal this change fulfills
• List the observable outcomes that prove the goal is met

---

Phase 2: Observability Check

Can you tell when it's broken in production?

• Logging — are key operations logged with appropriate level (info/warn/error)?
• No sensitive data in logs — no passwords, tokens, PII in log output?
• Error logging — are all caught exceptions logged with context?
• Metrics — are key performance indicators tracked (if applicable)?
• Distributed tracing — if microservices, are trace IDs propagated?

# Check for logging in changed files
git diff main...HEAD --name-only 2>/dev/null | while read f; do
  echo "=== $f ==="
  grep -n "log\.\|logger\.\|console\.\|print\(" "$f" 2>/dev/null | head -5
done | head -40

# Check for secrets in logs
git diff main...HEAD 2>/dev/null | grep "+" | \
  grep -iE "password|secret|token|api_key|credential" | \
  grep -v "^---\|^+++\|test\|spec\|mock" | head -10

---

Phase 3: Reliability Check

Does it fail gracefully?

• Health endpoint — is there a /health or equivalent endpoint that returns 200 when healthy?
• Graceful degradation — if a dependency is down, does the system degrade gracefully (not crash)?
• Timeouts — are all external calls wrapped with timeouts?
• Retry logic — are transient failures retried with backoff (if appropriate)?
• Circuit breaker — is there protection against cascading failures (if applicable)?
• Resource bounds — are there limits on memory, connections, queue depth?

# Check for timeout handling in changed files
git diff main...HEAD --name-only 2>/dev/null | while read f; do
  grep -n "timeout\|Timeout\|TIMEOUT" "$f" 2>/dev/null | head -3
done | head -20

For non-service changes (scripts, CLI tools, libraries): mark N/A for inapplicable items.

---

Phase 4: Operability Check

Can someone else run and fix this without the author?

• Rollback plan documented — how do you undo this deployment if it breaks something?
• Runbook exists — is there documentation on how to operate this feature (if new)?
• Alerts configured — will someone be paged if this breaks?
• On-call aware — does the on-call team know this is deploying today?
• Feature flag — if high risk, is this behind a feature flag that can be toggled off?
• Deployment window — is this being deployed at a safe time (not Friday afternoon)?

# Check for feature flag patterns
git diff main...HEAD 2>/dev/null | grep "+" | \
  grep -iE "feature_flag|feature\.enabled|flag\.|toggle\." | head -10

# Check for rollback instructions in docs
grep -r "rollback\|revert\|undo" . --include="*.md" -l 2>/dev/null | head -5

For low-risk changes (config, docs, tests): mark operability items N/A where not applicable.

---

Phase 5: Security Gate

Confirm security review has been done (or is not required).

• Security review run? (use code-review in security mode if not done)
• No new attack surface — no new endpoints, inputs, or permissions without review?
• Dependencies clean — no new CVEs in added dependencies?
• Secrets management — no hardcoded credentials, all secrets via env/vault?

Dispatch the planner-reviewer agent in security audit mode (dependency sub-mode) (OWASP A06) to scan all package manifests for CVEs, license issues, and stale packages. The agent returns a SECURITY AUDIT REPORT with the DEPENDENCIES section and an overall verdict. Any CHANGES_REQUIRED verdict is a deploy blocker.

# Quick secrets scan (dependency-auditor handles the full vulnerability scan)
git diff main...HEAD 2>/dev/null | grep "+" | \
  grep -vE "^---|\+\+\+|test|spec|mock|example" | \
  grep -iE "(password|secret|api_key|private_key)\s*[=:]\s*['\"][^'\"]{8,}" | head -10

---

Production Readiness Report

PRODUCTION READINESS REPORT
════════════════════════════════════════
Feature/Change:    [what is being deployed]
Branch/PR:         [identifier]
Date:              [YYYY-MM-DD]

GOAL ALIGNMENT
  Acceptance criteria:
    ✓/✗ [criterion 1] — [evidence]
    ✓/✗ [criterion 2] — [evidence]
  User goal achieved: YES | NO | PARTIAL

OBSERVABILITY
  Logging:          PASS | FAIL | N/A
  Error tracking:   PASS | FAIL | N/A
  Metrics:          PASS | FAIL | N/A
  Notes: [any gaps or concerns]

RELIABILITY
  Health check:     PASS | FAIL | N/A
  Graceful degrade: PASS | FAIL | N/A
  Timeouts:         PASS | FAIL | N/A
  Notes: [any gaps or concerns]

OPERABILITY
  Rollback plan:    DOCUMENTED | MISSING | N/A
  Runbook:          EXISTS | MISSING | N/A
  Alerts:           CONFIGURED | MISSING | N/A
  Feature flag:     YES | NO | N/A
  Notes: [any gaps or concerns]

SECURITY
  Audit status:     CLEAN | CONCERNS | SKIPPED
  Notes: [any concerns]

BLOCKERS (must resolve before deploy):
  - [blocker 1]

CONCERNS (deploy with awareness):
  - [concern 1]

VERDICT: READY | READY_WITH_CONCERNS | NOT_READY

Status: DONE | DONE_WITH_CONCERNS | BLOCKED
════════════════════════════════════════

When NOT_READY

If verdict is NOT_READY:

1. List all blockers with specific remediation steps
2. Assign an owner to each blocker
3. Re-run this checklist after blockers are resolved
4. Do NOT proceed to release until verdict is READY or READY_WITH_CONCERNS

Save Production Readiness Document

_PR_DATE=$(date +%Y%m%d-%H%M%S)
_PR_BRANCH=$(git branch --show-current 2>/dev/null | tr '/' '-' || echo "unknown")
_PR_FILE="production-readiness-${_PR_BRANCH}-${_PR_DATE}.md"
mkdir -p docs/superomni/production-readiness
echo "Production readiness report saved to docs/superomni/production-readiness/${_PR_FILE}"

Write the full PRODUCTION READINESS REPORT block to docs/superomni/production-readiness/production-readiness-[branch]-[session]-[date].md.