@todoist/doistbot-cli 0.0.0-stage → 1.0.16

package/sandbox/src/review/prompts/observability-standard.md

@@ -0,0 +1,169 @@
+# Standard: Observability
+
+| 📄 Document Type | Standard                                                                                                                                                             |
+| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎯 Status        | Approved                                                                                                                                                             |
+| 👤 Owner         | Luciano Facchinelli                                                                                                                                                  |
+| 📅 Last Reviewed | 2026-03-20                                                                                                                                                           |
+| 🗂️ References    | [Datadog Documentation](https://docs.datadoghq.com/), [Sentry Documentation](https://docs.sentry.io/), [OpenTelemetry Specification](https://opentelemetry.io/docs/) |
+| 📌 Version       | 1.0                                                                                                                                                                  |
+
+This document defines the standard approach for implementing observability in new projects at Doist. It is based on patterns and tools established across our production systems including Todoist, Twist, and Agentist.
+
+---
+
+## Overview
+
+Observability at Doist is built on three core pillars: **Logs**, **Metrics**, and **Traces**. We supplement these with **Error Tracking** to provide complete visibility into our systems.
+
+### Guiding Principles
+
+- **Consistency**: Use the same tools and patterns across all projects
+- **Structured Data**: Always use structured logging (JSON format)
+- **Correlation**: Ensure logs, metrics, and traces can be correlated via trace IDs
+- **Actionable Alerts**: Only alert on conditions that require human intervention or can be automated by leveraging LLMs
+- **Privacy First**: Never log PII or sensitive user data. Reuse existing sanitization patterns (see [Existing Implementations](#existing-pii-sanitization-implementations))
+
+---
+
+## Core Pillars
+
+### 1. Logging
+
+Structured logging is mandatory for all services. Logs should:
+
+- Use JSON format for machine parsability (single-line output is preferred where the log shipper supports it, but not strictly required)
+- Include correlation IDs for request tracing
+- Use appropriate log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- Do not include timestamps — these are added by the logging system
+- Avoid color codes, emojis, and decorative output
+- Never contain sensitive data (passwords, tokens, PII) — use existing sanitization libraries where available (see [Existing Implementations](#existing-pii-sanitization-implementations))
+
+### 2. Metrics
+
+Metrics provide quantitative measurements of system behavior:
+
+- **RED Metrics** (for services): Rate, Errors, Duration
+- **USE Metrics** (for resources): Utilization, Saturation, Errors
+- **Custom business metrics as needed**
+
+### 3. Traces
+
+Distributed tracing tracks requests across service boundaries:
+
+- All inter-service calls must propagate trace context
+- Use OpenTelemetry-compatible instrumentation like OpenTelemetry SDKs or Datadog APM libraries
+- Sample appropriately for high-traffic services
+
+> **Note**: For services running on AWS, the canonical trace entry point is the Application Load Balancer (ALB). The ALB automatically adds the `X-Amzn-Trace-Id` header to every incoming request, which your service should read and propagate to downstream calls. This header is compatible with OpenTelemetry. For services running on GCP, the canonical trace entry point will be defined in a future version of this standard.
+
+### 4. Error Tracking
+
+Dedicated error tracking provides detailed crash and exception analysis:
+
+- Capture stack traces with source maps
+- Group similar errors automatically
+- Track error frequency and affected users
+
+### 5. Real User Monitoring (RUM) _(optional)_
+
+Datadog RUM is available but carries significant cost and is not recommended for most applications. Prefer lighter-weight alternatives already in use at Doist:
+
+- **Web apps**: Use log-based metrics in Datadog (see [interaction-trace](https://github.com/Doist/interaction-trace) for reference)
+- **Landing pages**: Use [RequestMetrics](https://requestmetrics.com) for Core Web Vitals and performance tracking
+- **Mobile**: Evaluate tooling based on platform needs
+
+If adopted, RUM should cover page/screen load times, user interactions, and Core Web Vitals (web) or app performance (mobile).
+
+---
+
+## Tool Stack
+
+### Primary Tools
+
+| Purpose            | Tool                     | Usage                                      |
+| ------------------ | ------------------------ | ------------------------------------------ |
+| APM & Tracing      | **Datadog**              | Distributed tracing, APM, metrics          |
+| Error Tracking     | **Sentry**               | Exception monitoring, crash reporting      |
+| Metrics Collection | **Datadog + CloudWatch** | Infrastructure and application metrics     |
+| Log Aggregation    | **Datadog Logs**         | Centralized log management                 |
+| Feature Flags      | **Flagsmith**            | Feature flag management with observability |
+
+---
+
+## Configuration Standards
+
+### Naming Conventions
+
+- **Service Names**: lowercase, hyphen-separated (e.g., `todoist-api`, `twist-web`)
+- **Metric Names**: lowercase, dot-separated (e.g., `api.request.duration`)
+- **Log Fields**: snake_case (e.g., `user_id`, `request_id`)
+
+### Required Tags/Labels
+
+All metrics and traces must include:
+
+```
+service: <service-name>
+env: <environment>
+version: <app-version>
+```
+
+Use the following canonical values for `env`:
+
+| Environment | Tag value     |
+| ----------- | ------------- |
+| Production  | `production`  |
+| Staging     | `staging`     |
+| Development | `development` |
+
+---
+
+## Health Checks
+
+Health check requirements are defined in the Service Production Readiness standard, which is the canonical reference. Follow that standard for `/health` endpoint definitions, and startup grace periods.
+
+## Existing PII Sanitization Implementations
+
+Before writing custom data-scrubbing logic, check these existing implementations first — they cover the most common patterns and are already battle-tested in production.
+
+If you implement a new sanitizer or modify an existing one with improvements, please consider contributing it back to the original repository for reuse across projects.
+
+### Python — `ist_libs` (shared library)
+
+[`python/parts/logs/sanitizers.py`](https://github.com/Doist/ist_libs/blob/main/python/parts/logs/sanitizers.py) in `Doist/ist_libs`
+
+### TypeScript — `todoist-web`
+
+[`src/05-common/logger/utils.ts`](https://github.com/Doist/todoist-web/blob/main/src/05-common/logger/utils.ts) and [`sentry.ts`](https://github.com/Doist/todoist-web/blob/main/src/05-common/logger/sentry.ts) in `Doist/todoist-web`
+
+---
+
+## Common Metrics Reference
+
+Real metric names from existing Doist services to use as inspiration when naming metrics in new services.
+
+### Backend — `Doist/Todoist` (Datadog StatsD)
+
+- `todoist.sync_api.all_sync_lengths` (Distribution)
+- `todoist.sqs_workers.processing_duration` / `message_age_seconds` / `first_receive_latency_seconds` (Distributions)
+- `todoist.project_health.analysis.*` — `success`, `error`, `queued`, `rescheduled`, `abandoned`
+- `todoist.rate_limit.sync.<group>.activated`
+- `todoist.audit_log.change` (tagged with `table` / `column` / `action`)
+
+### Mobile — `Doist/todoist-ios` (Firebase GA4)
+
+- `task_added` / `task_completed`
+- `login` / `sign_up`
+- `screen_view` / `dialog_view`
+- `notification_opt_in` / `notification_opt_out`
+- `widget_add` / `widget_remove`
+
+---
+
+## References
+
+- [Datadog Documentation](https://docs.datadoghq.com/)
+- [Sentry Documentation](https://docs.sentry.io/)
+- [OpenTelemetry Specification](https://opentelemetry.io/docs/)
+- [Flagsmith Documentation](https://docs.flagsmith.com/)

package/sandbox/src/review/prompts/outline-map.json

@@ -0,0 +1,26 @@
+{
+    "workload-placement.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-workload-placement-"
+    },
+    "secrets-management.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-secrets-management-"
+    },
+    "ai-internal-tools.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-internal-ai-tools-"
+    },
+    "service-production-readiness.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-service-production-readiness-"
+    },
+    "observability-standard.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-observability-"
+    },
+    "backend-repository-standards.md": {
+        "id": "",
+        "url": "https://handbook.doist.com/doc/standard-backend-repositories-"
+    }
+}

package/sandbox/src/review/prompts/secrets-management.md

@@ -0,0 +1,286 @@
+# Standard: Secrets Management
+
+| 📄 Document Type | Standard                                                                                                                                                                                                                               |
+| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎯 Status        | Approved                                                                                                                                                                                                                               |
+| 👤 Owner         | Luciano Facchinelli                                                                                                                                                                                                                    |
+| 📅 Last Reviewed | 2026-03-06                                                                                                                                                                                                                             |
+| 🗂️ References    | [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/) [GitHub Actions OIDC with AWS](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) |
+| 📌 Version       | 1.0                                                                                                                                                                                                                                    |
+
+## Overview
+
+This document defines the standard approach for managing secrets across all environments at Doist. Secrets include API keys, database credentials, encryption keys, tokens, certificates, and any other sensitive configuration data that must not be exposed in source code or logs.
+
+### Principles
+
+1. **Never commit secrets to version control** - All secrets must be excluded from repositories
+2. **Least privilege access** - Services should only have access to the secrets they need
+3. **Environment isolation** - Production secrets must never be used in development or testing
+4. **Rotation capability** - Secrets should be stored in a way that allows rotation without code changes
+5. **Audit trail** - Access to production secrets should be logged and auditable
+
+### Scope
+
+This standard applies to:
+
+- Application configuration secrets
+- Database credentials
+- API keys and tokens (internal and third-party)
+- Encryption keys and certificates
+- Service-to-service authentication tokens
+
+---
+
+## Security Requirements
+
+### Prohibited Practices
+
+- Committing unencrypted secrets to version control (even in private repositories)
+- Logging secret values independently of their encoding
+- Passing secrets via command-line arguments (visible in process lists)
+- Storing production secrets in development environments
+- Sharing unencrypted secrets via unencrypted channels (email, Slack, Twist)
+- Using production secrets for testing
+
+### Required Practices
+
+- Use environment-specific secrets (dev, staging, prod)
+- Implement secret rotation procedures
+- Monitor for secret exposure (e.g., [GitHub secret scanning](https://github.com/Doist/scan-github-secrets/blob/main/README.md))
+- Use short-lived credentials where possible
+- Encrypt secrets in transit and at rest
+- Document secret dependencies for each service
+
+---
+
+## Production Environment
+
+All production secrets MUST be stored in a cloud-provider secret service. For AWS this is [AWS Secret Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html), for Google this is [Google Cloud secrets](https://docs.cloud.google.com/secret-manager/docs/overview).
+
+This provides:
+
+- Encryption at rest
+- Fine-grained access control
+- Automatic rotation capabilities
+    - For AWS Secret Manager, we can configure [automatic rotation for our secrets using AWS Lambda functions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_available-rotation-templates.html)
+    - For Google Cloud Secret Manager, we can [set up a rotation schedule and provide a Cloud Function to handle the rotation process](https://docs.cloud.google.com/secret-manager/docs/secret-rotation)
+- Audit logging
+
+Although we can have each of our secrets stored independently, in general we aim to bundle all of a service's secrets into a single JSON-structured secret. With this we can reduce complexity.
+
+The only exemption to this rule is database secrets.
+
+### Secret Naming Convention
+
+When we create secrets for our apps, we need to ensure they follow a logic structure that allows us to easily identify them and their purpose.
+
+**Examples:**
+
+#### AWS Secret Manager
+
+| Secret Path                     | Description                     |
+| ------------------------------- | ------------------------------- |
+| `prod/todoist/secrets`          | Main application secrets bundle |
+| `prod/todoist/rds-main`         | Primary database credentials    |
+| `prod/todoist/rds-shard01`      | Shard database credentials      |
+| `prod/todoist/apple-signin-key` | Apple Sign-In private key       |
+| `staging/todoist/secrets`       | Staging secrets bundle          |
+
+#### Google Cloud Secret Manager
+
+| Secret Path                     | Description                     |
+| ------------------------------- | ------------------------------- |
+| `prod-todoist-secrets`          | Main application secrets bundle |
+| `prod-todoist-rds-main`         | Primary database credentials    |
+| `prod-todoist-rds-shard01`      | Shard database credentials      |
+| `prod-todoist-apple-signin-key` | Apple Sign-In private key       |
+| `staging-todoist-secrets`       | Staging secrets bundle          |
+
+### Bundled Secrets Structure
+
+For bundled application secrets, group related secrets:
+
+```json
+{
+    "STRIPE_SECRET_KEY": "sk_live_...",
+    "STRIPE_WEBHOOK_SECRET": "whsec_...",
+    "COOKIE_SECRET_KEY": "base64-encoded-key",
+    "API_TOKEN_SIGNATURE_KEY": "base64-encoded-key"
+}
+```
+
+### Limits and tags
+
+When creating secrets, we need to be aware of the limits of the cloud provider secret manager:
+
+| Limit              | AWS Secrets Manager | Google Cloud Secret Manager |
+| ------------------ | ------------------- | --------------------------- |
+| Secret value size  | 64 KB per secret    | 64 KB per secret version    |
+| Secret name length | 512 characters      | 255 characters              |
+
+For tags, we should use them to add relevant information about the secret, such as the environment, the application it belongs to -or product-, and any other relevant information that can help us identify the secret and its purpose.
+
+For more information about our tagging strategy, please refer to the [Tagging policy](https://handbook.doist.com/doc/tagging-aws-resources-Fp1quAqmda?q=aws%20tag)
+
+### Accessing Secrets in Application Code
+
+Once our secrets are stored following our standard, the next step is to consume those secrets. For this there are 2 approaches:
+
+- Feed to our application as environment variables
+- Consumed from the application using the cloud provider SDK
+
+Each approach has its own pros and cons, and although consuming secrets as environment variables is the most straightforward process, it is also the most prone to expose those secrets.
+
+For instance, another process in our virtual machine or container could potentially see the content of the environment variable. Moreover, crash dumps, container metadata and logging frameworks tend to dump all environment variables values for debugging, which would inadvertently leak our secrets to the world.
+
+Consuming secrets from the application using cloud provider SDK allows us to avoid all of this, although requires more code lines to consume them.
+
+With all this information laid out, for production environments our recommended approach is to consume the secrets from the application using the cloud provider SDK.
+
+## Development Environment
+
+Unlike production environments, local or development environment secrets can be stored locally.
+It is important to ensure those files are not shared unencrypted and the secrets' values are not the same as production. This includes the permission level or access level they provide.
+
+Those secrets should be stored in a separate file (i.e `.env`) from our application and later consumed by it. This ensures no secret lives inside our application source code.
+
+For encryption of these secret files, we recommend the usage of [SOPS](https://github.com/getsops/sops). SOPS is an application that implements the mechanics to encrypt our secret file using an encryption key. With it, we can safely share our encrypted secret file over the internet to our colleagues and, in the event of someone leaking the secret file to the internet, it won't be possible to decrypt the secrets unless the bad actor has access to the decryption key.
+
+At Doist, all devs have automatic access to a shared encryption-decryption key that is used exclusively for development secrets. Please refer to the following guide to learn how to use SOPS with our shared key: [SOPS with Doist's shared key](https://handbook.doist.com/doc/sharing-development-secrets-nh7WApeEZR?q=SOPS)
+
+### Sharing Secrets Between Developers
+
+For secret sharing between developers — such as onboarding credentials, service accounts, or any secret that doesn't belong in a SOPS-encrypted file — use [Bitwarden](https://bitwarden.com/).
+
+Bitwarden is Doist's approved password manager. All developers have access to shared Bitwarden collections organized by team and project. When sharing secrets through Bitwarden:
+
+- **Use shared collections**, not individual sends, so secrets remain accessible to the team and not tied to one person
+- **Never duplicate production secrets** — Bitwarden is for development and internal credentials only
+- **Add descriptive names** to entries so others understand the secret's purpose and scope
+- **Remove entries that are no longer needed** to keep collections clean and reduce exposure
+
+As stated in the previous chapter, for secrets that need to live in a repository's `.env` file and be shared with the full team, use SOPS.
+
+Use Bitwarden for everything else — one-off sharing, service account passwords, and credentials that don't map to a specific repo.
+
+### Docker Build Secrets
+
+For build-time secrets (e.g., private package repositories), use [BuildKit secrets](https://docs.docker.com/reference/dockerfile#run---mounttypesecret):
+
+```dockerfile
+# Dockerfile
+# syntax = docker/dockerfile:1.3
+
+RUN --mount=type=secret,id=netrc,target=/root/.netrc \
+    pip install -r requirements.txt
+```
+
+Build command:
+
+```bash
+docker build --secret id=netrc,src=$HOME/.netrc -t myimage .
+```
+
+---
+
+## CI/CD Environment
+
+### GitHub Actions Secrets
+
+For CI/CD workflows, we store secrets in GitHub on each repository. This feature is available on the settings page of each repository, under `Security -> Secrets and Variables`
+
+CI/CD Secrets that should be shared across all repositories should be added at the GitHub organization level instead.
+
+Be aware that anyone can fork our public repositories and create pull requests against our main branch. By default GitHub Actions will not run on pull requests from forks, but if we enable it, we need to ensure that no secrets are exposed to those pull requests. For this reason, we should never use secrets in workflows that are triggered by pull requests from forks. Moreover, those forks could potentially be used to exfiltrate secrets if we are not careful enough.
+
+To solve this, we should configure our GitHub public repositories to not run GitHub Actions on pull requests from forks. This can be done in the repository settings, under `Actions -> General -> Approval for running fork pull request workflows from contributors`, by selecting the option `Require approval for all external contributors`.
+
+For more information about GitHub Actions Permissions configuration, please refer to the [About GitHub Actions permissions for your repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#about-github-actions-permissions-for-your-repository)
+
+## Secret Types and Handling
+
+### Classification
+
+| Type                       | Storage                      | Example            |
+| -------------------------- | ---------------------------- | ------------------ |
+| **Database credentials**   | Secrets Manager (individual) | RDS passwords      |
+| **API keys (internal)**    | Secrets Manager (bundled)    | Service tokens     |
+| **API keys (third-party)** | Secrets Manager (bundled)    | Stripe, Sendgrid   |
+| **Encryption keys**        | Secrets Manager or KMS       | Cookie signing     |
+| **Certificates**           | ACM or Secrets Manager       | TLS, Apple signing |
+| **Webhook secrets**        | Secrets Manager (bundled)    | Stripe webhooks    |
+
+---
+
+## Secret Rotation
+
+Rotation limits the blast radius of a compromised secret by reducing the window of time it remains valid. Even without a known breach, periodic rotation reduces risk from undetected exposure.
+
+### Rotation Strategy
+
+Not all secrets can or should be rotated the same way. Choose the approach based on the secret type:
+
+| Strategy                  | When to Use                                | Example                                                     |
+| ------------------------- | ------------------------------------------ | ----------------------------------------------------------- |
+| **Automatic (scheduled)** | Cloud-native secrets with provider support | Database credentials via AWS/GCP rotation lambdas/functions |
+| **Dual-key (overlap)**    | Secrets shared across multiple consumers   | API signing keys, webhook secrets                           |
+| **On-demand**             | Third-party keys with manual regeneration  | Stripe API keys, Sendgrid tokens                            |
+
+### Dual-Key Rotation
+
+For secrets consumed by multiple services or external parties, use a dual-key (overlap) approach to avoid downtime:
+
+1. Generate the new secret and store it alongside the current one
+2. Update consumers to accept **both** the old and new secret
+3. Roll out the new secret to all producers
+4. Once all traffic uses the new secret, remove the old one
+
+This is especially relevant for webhook verification secrets and API token signing keys, where the producer and consumer may deploy at different times.
+
+### Rotation Cadence
+
+| Secret Type             | Recommended Cadence                    | Notes                                       |
+| ----------------------- | -------------------------------------- | ------------------------------------------- |
+| Database credentials    | Annually                               | Use automatic rotation via Secrets Manager  |
+| Internal API keys       | Annually                               | Coordinate across dependent services        |
+| Third-party API keys    | On provider recommendation or annually | Some providers enforce their own schedule   |
+| Encryption/signing keys | Annually                               | Requires careful key versioning             |
+| Compromised secrets     | Immediately                            | See [Incident Response](#incident-response) |
+
+### Requirements
+
+- Rotation **must not** require code changes or redeployments. Secrets should be fetched at runtime, not baked into builds or container images.
+- Services consuming secrets via the cloud provider SDK (our recommended approach) should handle rotation transparently by re-fetching on a reasonable interval or on authentication failure.
+- Each secret in Secrets Manager should have a **rotation reminder** configured, even if automatic rotation is not yet enabled, so that the owning team receives a notification when rotation is due.
+- Rotation procedures for each service should be **documented and tested** before going to production. An untested rotation procedure is effectively no procedure at all.
+
+---
+
+## Incident Response
+
+If a secret is compromised:
+
+1. **Immediately rotate** the compromised secret
+2. **Incident response** team should be notified to investigate the breach. Please create an incident thread in our [Doist incident channel](https://twist.com/a/1585/ch/255325/) and follow the [Incident Response Checklist](https://twist.com/a/1585/ch/255325/t/2359936/).
+3. **Audit** access logs for unauthorized usage
+4. **Notify** the platform team
+5. **Review** and revoke any sessions or tokens that may have been compromised
+6. **Document** the incident and update procedures if needed
+
+---
+
+## Implementation Checklist
+
+Before deploying a service to production, verify that your secrets management aligns with this standard.
+The full set of production readiness requirements — including but not limited to secrets — will be covered in our [Production Readiness Standard](./production-readiness.md).
+That standard will define the baseline criteria every application or service must meet before being deployed to production, spanning areas such as observability, reliability, security, etc.
+
+---
+
+## References
+
+- [AWS Secrets Manager Documentation](https://docs.aws.amazon.com/secretsmanager/)
+- [GitHub Actions OIDC with AWS](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
+- [Pydantic Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+- [Docker BuildKit Secrets](https://docs.docker.com/build/building/secrets/)

package/sandbox/src/review/prompts/service-production-readiness.md

@@ -0,0 +1,122 @@
+# Standard: Service Production Readiness
+
+<!--
+past attempts:
+https://github.com/Doist/handbook/pull/81 (useful feedback)
+https://medium.com/google-cloud/production-guideline-9d5d10c8f1e
+
+https://github.com/Doist/platform-backlog/issues/283 (can close)
+-->
+
+| 📄 Document Type | Standard         |
+| :--------------- | :--------------- |
+| 🎯 Status        | Approved         |
+| 👤 Owner         | Artyom Pervukhin |
+| 📅 Last Reviewed | 2026-03-06       |
+| 🗂️ References    | —                |
+| 📌 Version       | 1.0              |
+
+This standard applies to all new services deployed at Doist.
+
+A _service_ is a server-side application that performs a defined function. Common types include:
+
+- Request-driven services (e.g., HTTP APIs).
+- Background or scheduled workers (queues, batch jobs, reports).
+
+## Health Checks
+
+Services that accept network traffic must expose health checks.
+
+- HTTP services should provide an endpoint (suggested path: `/health`) that returns `200 OK` HTTP status code when healthy (response body is not important).
+- TCP services are considered healthy when they accept connections.
+
+Health checks must reflect only the correctness of the deployed code.
+
+They should pass if and only if the current version can operate correctly compared to the previous version. If a deployment fails, automated rollback must restore a previously healthy version.
+
+Do **not** include external dependencies (e.g. database availability) in health checks. External outages must not prevent rollback. If database connectivity is checked during health checks, an external database outage could prevent automated rollback to a previously working version.
+
+A service should report healthy only after full initialization. If startup regularly exceeds one minute, the Platform team must configure the [`HealthCheckGracePeriodSeconds`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ecs-service.html#cfn-ecs-service-healthcheckgraceperiodseconds) property on the ECS service resource to prevent premature health check failures from triggering rollbacks during deployment.
+
+## Observability
+
+All services must produce structured, meaningful logs.
+
+- Prefer one JSON object per line.
+- Avoid color codes, emojis, and decorative output.
+- Do not include timestamps (added by the logging system).
+- Do not include sensitive or personal information in logs.
+
+Logs should support operational debugging and monitoring.
+
+See [the Observability standard for more details](https://handbook.doist.com/doc/standard-observability-vWRaOfitho).
+
+## Configuration Management
+
+Configuration must be provided via environment variables.
+
+- Command-line flags are acceptable for a small number of parameters.
+- Env files are allowed only if variables can be overridden by the environment.
+- Secrets must come from environment variables or read directly from a secrets management service (AWS Secrets Manager).
+
+See [the Secrets Management standard for more details](https://handbook.doist.com/doc/standard-secrets-management-wbKmIfrtgr).
+
+## State Persistence
+
+Services run in containerized environments with ephemeral local storage (AWS ECS Fargate is the default platform).
+
+Any state that must survive restarts must be stored externally, e.g.:
+
+- Redis/Valkey, Memcached
+- DynamoDB, MySQL
+- S3, EFS
+
+Local disk may be used only for temporary data.
+
+Durable state must be backed up. DynamoDB tables must have [point-in-time recovery](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Point-in-time-recovery.html) enabled and carry the account's `Backup` tag so the AWS Backup plan selects them. Caches, lock tables and short-lived session tables with a TTL are exempt.
+
+## Resource Limits
+
+Define expected CPU, memory, network, and local disk usage.
+
+Local development environments are often significantly more powerful than production instances. Profile and test accordingly.
+
+Estimate local disk requirements for temporary files. Fargate provides 20 GiB of ephemeral storage by default; contact the Platform team if more is needed.
+
+## Concurrency and Scaling
+
+Assume services will run with multiple parallel instances.
+
+- Do not rely on single-instance behavior.
+- Requests from the same client may reach different instances.
+- Shared state must be externalized.
+
+## Error Handling
+
+Services must handle non-happy-path scenarios:
+
+- Apply timeouts to all network calls.
+- Implement retries with backoff.
+- Support graceful degradation (e.g. returning cached or degraded responses when a downstream service is unavailable).
+- Use circuit breakers where appropriate (see [Martin Fowler's circuit breaker pattern](https://martinfowler.com/bliki/CircuitBreaker.html)).
+
+## Deployment Behavior
+
+Deployments use rolling updates: old and new versions run simultaneously.
+
+Design for version overlap:
+
+- Cache formats
+- Database schemas
+- Persisted data
+
+Multiple versions must coexist without causing errors. In practice, this means being flexible on the reading side: new versions must tolerate data written by old versions. Adding fields to cache formats, schemas, or persisted data is safe; removing or renaming fields requires a multi-step migration.
+
+## Building and Packaging
+
+Services must be built into container images.
+
+- Service code repository must include a Dockerfile.
+- All dependencies must be installed at build time.
+
+Services must not make unintended network calls at startup or runtime — for example, dependency update checks or telemetry to third-party build tools. Intentional integrations (e.g. Datadog, Sentry) are expected and not affected by this requirement.