ai-playbook 1.0.0

package/roles/software-developer/logging/README.md

@@ -0,0 +1,105 @@
+# Logging and Observability
+
+This folder defines service-side logging and observability expectations for the
+software-developer role. Use it when a task changes runtime behavior, error
+handling, background jobs, API calls, data pipelines, model inference, or any
+production path that operators may need to diagnose later.
+
+## Goals
+
+- Make production behavior explainable without exposing sensitive data.
+- Help engineers find failures quickly across logs, metrics, and traces.
+- Keep logs structured, searchable, and consistent across services.
+- Capture business-relevant events without turning logs into analytics dumps.
+- Support incident response, audit needs, and regression analysis.
+
+## Signals
+
+| Signal | Use it for | Examples |
+| --- | --- | --- |
+| Logs | Discrete events and diagnostic context. | request accepted, validation failed, retry exhausted |
+| Metrics | Aggregated numeric behavior over time. | request count, error rate, queue depth, latency |
+| Traces | Causal path across services. | API request through gateway, worker, database, model call |
+| Alerts | Actionable symptoms needing human response. | high error rate, job stuck, SLO burn |
+| Audit events | Security- or compliance-relevant actions. | permission change, export started, token revoked |
+
+## Logging Contract
+
+Every production log event should include:
+
+- `timestamp`
+- `level`
+- `service`
+- `environment`
+- `event`
+- `message`
+- `request_id` or `correlation_id` when available
+
+Add domain fields only when they help diagnosis:
+
+- `user_id`, `tenant_id`, `organization_id`
+- `job_id`, `task_id`, `model_id`, `deployment_id`
+- `status_code`, `error_code`, `retry_count`
+- `duration_ms`, `queue_time_ms`, `tokens_in`, `tokens_out`
+
+Never log:
+
+- API keys, passwords, tokens, session cookies, or credentials.
+- Raw personally identifiable information unless explicitly approved.
+- Full prompts, documents, attachments, database rows, or payment data by default.
+- Secrets embedded in exception messages or request headers.
+
+## Log Levels
+
+| Level | Meaning | Typical use |
+| --- | --- | --- |
+| `debug` | Local or temporary diagnostic detail. | branch choice, raw dependency timing, feature-flag decision |
+| `info` | Normal lifecycle event. | request completed, job started, model response accepted |
+| `warn` | Unexpected but recoverable condition. | retry scheduled, fallback used, partial data skipped |
+| `error` | Failure affecting user, job, or system behavior. | request failed, persistence failed, external dependency unavailable |
+| `critical` | Severe failure requiring immediate attention. | data loss risk, widespread outage, safety control unavailable |
+
+Use `debug` sparingly in production. Prefer metrics for high-frequency facts and
+logs for events that explain state transitions or failures.
+
+## Event Naming
+
+Use stable, lowercase event names with dots:
+
+- `api.request.started`
+- `api.request.completed`
+- `worker.job.failed`
+- `model.inference.completed`
+- `auth.permission.denied`
+- `billing.invoice.exported`
+
+Event names are contracts. Do not rename them casually once dashboards, alerts,
+or runbooks depend on them.
+
+## Required Practices
+
+- Use structured logging when the runtime supports it.
+- Propagate correlation IDs across service boundaries.
+- Sanitize request, response, prompt, and exception data before logging.
+- Include error class, error code, and safe message for failures.
+- Record duration for external calls and slow internal operations.
+- Add metrics for rates, latency, saturation, and queue depth.
+- Add traces around cross-service calls, database calls, and model calls.
+- Link alerts to runbooks when the alert requires human action.
+
+## Review Questions
+
+- Can an on-call engineer identify what failed, where, and for whom?
+- Can the event be searched consistently across environments?
+- Does the log avoid secrets and unnecessary personal data?
+- Is a metric more appropriate than a log line?
+- Is this event high-volume enough to need sampling or aggregation?
+- Are dashboards or alerts updated when behavior changes?
+
+## Related Files
+
+- `checklists.md` for implementation and review gates.
+- `examples.md` for concrete logging, metrics, and tracing examples.
+- `roles/software-developer/frontend/logging-observability/` for browser-side observability.
+- `skills/security/` for privacy and secret-handling expectations.
+- `skills/performance/` for service-level measurement and SLO guidance.

package/roles/software-developer/logging/checklists.md

@@ -0,0 +1,48 @@
+# Logging and Observability Checklists
+
+Use these checklists when adding or changing production behavior, error handling,
+background processing, external calls, or operational monitoring.
+
+## Design
+
+- [ ] Identify the user, tenant, job, request, or resource identifiers needed for diagnosis.
+- [ ] Define stable event names before implementation.
+- [ ] Decide which facts belong in logs, metrics, traces, alerts, or audit events.
+- [ ] Define redaction rules for secrets, credentials, prompts, documents, and personal data.
+- [ ] Identify dashboards, runbooks, and alerts that must change with the behavior.
+
+## Implementation
+
+- [ ] Use the project's structured logging library or wrapper.
+- [ ] Include `service`, `environment`, `event`, `level`, and timestamp fields.
+- [ ] Propagate `request_id`, `correlation_id`, or `trace_id`.
+- [ ] Log lifecycle events at boundaries: accepted, completed, failed, retried, skipped.
+- [ ] Add safe error fields: `error_type`, `error_code`, and sanitized message.
+- [ ] Add durations for external dependencies, database calls, queues, and model calls.
+- [ ] Avoid high-cardinality metrics labels such as raw user emails or request paths with IDs.
+- [ ] Keep log volume controlled with sampling, aggregation, or lower levels where appropriate.
+
+## Privacy and Security
+
+- [ ] Confirm no secrets, tokens, cookies, credentials, or private keys are logged.
+- [ ] Confirm personally identifiable information is absent, hashed, or approved.
+- [ ] Confirm prompts, completions, uploaded files, and database records are redacted by default.
+- [ ] Confirm exception logging cannot leak request headers or raw payloads.
+- [ ] Confirm audit events are immutable or written to the approved audit sink when required.
+
+## Verification
+
+- [ ] Run unit tests for logging helpers, redaction, and error handling when applicable.
+- [ ] Exercise a success path and confirm expected logs/metrics are emitted.
+- [ ] Exercise at least one failure path and confirm the failure is diagnosable.
+- [ ] Verify correlation IDs connect logs, metrics, and traces across service boundaries.
+- [ ] Verify dashboards or queries can find the new event names.
+- [ ] Verify alerts are actionable and link to runbooks when human response is required.
+
+## Review
+
+- [ ] Log messages are concise and explain the operational meaning of the event.
+- [ ] Field names follow existing project conventions.
+- [ ] Event names are stable and documented where dashboards depend on them.
+- [ ] No debug-only or temporary log lines remain in production paths.
+- [ ] The change balances diagnostic value against cost, noise, and privacy risk.

package/roles/software-developer/logging/examples.md

@@ -0,0 +1,135 @@
+# Logging and Observability Examples
+
+These examples are intentionally framework-light. Adapt field names to the
+project logger, metrics client, and tracing library already in use.
+
+## Structured Request Log
+
+```python
+logger.info(
+    "API request completed",
+    extra={
+        "event": "api.request.completed",
+        "service": "orders-api",
+        "environment": settings.environment,
+        "request_id": request_id,
+        "user_id": safe_user_id,
+        "method": request.method,
+        "route": "/v1/orders/{order_id}",
+        "status_code": response.status_code,
+        "duration_ms": duration_ms,
+    },
+)
+```
+
+Use route templates instead of raw paths so metrics and logs do not explode with
+one value per resource ID.
+
+## Safe Error Log
+
+```python
+try:
+    result = await payment_client.capture(payment_id)
+except PaymentTimeout as exc:
+    logger.warning(
+        "Payment capture retry scheduled",
+        extra={
+            "event": "payment.capture.retry_scheduled",
+            "service": "billing-worker",
+            "environment": settings.environment,
+            "request_id": request_id,
+            "payment_id": payment_id,
+            "error_type": type(exc).__name__,
+            "error_code": "PAYMENT_TIMEOUT",
+            "retry_count": retry_count + 1,
+        },
+    )
+    raise RetryableJobError("payment capture timed out") from exc
+```
+
+Log the safe operational cause, not raw provider payloads or credentials.
+
+## Redaction Helper
+
+```python
+SENSITIVE_KEYS = {"authorization", "cookie", "password", "token", "api_key"}
+
+
+def redact_mapping(data: dict[str, object]) -> dict[str, object]:
+    redacted: dict[str, object] = {}
+    for key, value in data.items():
+        if key.lower() in SENSITIVE_KEYS:
+            redacted[key] = "[REDACTED]"
+        else:
+            redacted[key] = value
+    return redacted
+```
+
+Keep redaction helpers centralized so teams do not reimplement partial versions.
+
+## Metrics
+
+```python
+REQUESTS_TOTAL.labels(
+    service="orders-api",
+    route="/v1/orders/{order_id}",
+    method="GET",
+    status_class="2xx",
+).inc()
+
+REQUEST_DURATION_SECONDS.labels(
+    service="orders-api",
+    route="/v1/orders/{order_id}",
+    method="GET",
+).observe(duration_seconds)
+```
+
+Use low-cardinality labels. Avoid raw user IDs, emails, order IDs, prompts, or
+free-form error messages in metrics labels.
+
+## Trace Boundary
+
+```python
+with tracer.start_as_current_span("model.inference") as span:
+    span.set_attribute("model.id", model_id)
+    span.set_attribute("model.provider", provider_name)
+    span.set_attribute("request.id", request_id)
+
+    response = await model_client.generate(prompt=redacted_prompt)
+
+    span.set_attribute("model.tokens_in", response.usage.tokens_in)
+    span.set_attribute("model.tokens_out", response.usage.tokens_out)
+```
+
+Trace expensive or cross-service boundaries. Do not attach raw prompts,
+documents, or generated content unless a project policy explicitly allows it.
+
+## Audit Event
+
+```python
+audit_logger.info(
+    "User permission changed",
+    extra={
+        "event": "auth.permission.changed",
+        "actor_user_id": actor_user_id,
+        "target_user_id": target_user_id,
+        "organization_id": organization_id,
+        "permission": permission_name,
+        "action": "granted",
+        "request_id": request_id,
+    },
+)
+```
+
+Audit events should be stable, searchable, and written to the approved audit sink.
+
+## Anti-Examples
+
+```python
+logger.info(f"login payload: {request.json()}")
+logger.error(f"provider failed with headers={headers} token={token}")
+METRIC.labels(user_email=user.email, path=request.url.path).inc()
+```
+
+These patterns leak sensitive data, create high-cardinality metrics, or make
+production logs expensive and hard to search.

package/roles/software-developer/messaging/README.md

@@ -0,0 +1,24 @@
+# Messaging
+
+Use this packet for queues, streams, pub/sub systems, events, and asynchronous
+workflows.
+
+## Scope
+
+- Producers, consumers, topics, queues, event schemas, retries, and dead-letter queues.
+- Idempotency, ordering, deduplication, backpressure, and replay behavior.
+- Outbox, inbox, saga, and event-driven integration patterns.
+
+## Standards
+
+- Treat message schemas as contracts.
+- Make consumers idempotent because delivery may be duplicated.
+- Define retry, poison-message, and dead-letter behavior.
+- Include correlation IDs and causation IDs.
+- Monitor lag, failures, throughput, and dead-letter volume.
+
+## Related Files
+
+- `../microservices/` for distributed boundaries.
+- `../backend/` for worker/service implementation.
+- `../observability/` for lag and failure signals.

package/roles/software-developer/messaging/checklists.md

@@ -0,0 +1,21 @@
+# Messaging Checklists
+
+## Design
+
+- [ ] Define topic or queue ownership, message schema, and compatibility rules.
+- [ ] Decide ordering, delivery guarantee, retry, and dead-letter behavior.
+- [ ] Define idempotency key and deduplication strategy.
+- [ ] Document replay behavior and backfill safety.
+
+## Implementation
+
+- [ ] Validate message schema before processing.
+- [ ] Store processed message IDs when duplicate handling requires it.
+- [ ] Use transactional outbox or equivalent when publishing after database writes.
+- [ ] Emit metrics for lag, processing duration, success, failure, and dead-letter count.
+
+## Verification
+
+- [ ] Test duplicate, out-of-order, malformed, retried, and poison messages.
+- [ ] Test replay against representative data.
+- [ ] Verify failure diagnostics include correlation IDs.

package/roles/software-developer/messaging/examples.md

@@ -0,0 +1,26 @@
+# Messaging Examples
+
+## Idempotent Consumer
+
+```python
+async def handle_user_created(message: Message) -> None:
+    event = UserCreated.model_validate_json(message.body)
+    if await inbox.already_processed(event.event_id):
+        return
+
+    await projections.create_user_summary(event.user_id, event.tenant_id)
+    await inbox.mark_processed(event.event_id)
+```
+
+## Event Envelope
+
+```json
+{
+  "event_id": "evt_123",
+  "event_type": "user.created",
+  "schema_version": 1,
+  "correlation_id": "req_456",
+  "occurred_at": "2026-06-27T12:00:00Z",
+  "payload": {}
+}
+```

package/roles/software-developer/microservices/README.md

@@ -0,0 +1,25 @@
+# Microservices
+
+Use this packet when designing or changing distributed service boundaries,
+service-to-service communication, ownership, and runtime contracts.
+
+## Scope
+
+- Service boundaries, APIs, events, data ownership, deployment, and observability.
+- Resilience patterns such as timeouts, retries, circuit breakers, and bulkheads.
+- Compatibility, versioning, rollout, and incident isolation.
+
+## Standards
+
+- Services should own their data and expose stable contracts.
+- Avoid distributed transactions unless there is no simpler path.
+- Define timeouts, retries, idempotency, and fallback behavior for every remote call.
+- Keep cross-service changes backward compatible during rollout.
+- Add traces and metrics across service boundaries.
+
+## Related Files
+
+- `../api/`
+- `../messaging/`
+- `../backend/`
+- `../observability/`

package/roles/software-developer/microservices/checklists.md

@@ -0,0 +1,21 @@
+# Microservices Checklists
+
+## Design
+
+- [ ] Define service ownership, data ownership, and contract boundaries.
+- [ ] Identify synchronous and asynchronous dependencies.
+- [ ] Define failure behavior for each remote dependency.
+- [ ] Plan rollout, compatibility, and rollback.
+
+## Implementation
+
+- [ ] Set explicit connection, read, and total timeouts.
+- [ ] Use retries only for idempotent or safely deduplicated operations.
+- [ ] Propagate correlation and trace context.
+- [ ] Avoid leaking internal service errors through public contracts.
+
+## Verification
+
+- [ ] Test dependency timeout, failure, malformed response, and partial outage paths.
+- [ ] Verify metrics and traces show cross-service latency and errors.
+- [ ] Confirm old and new versions can coexist during deployment.

package/roles/software-developer/microservices/examples.md

@@ -0,0 +1,21 @@
+# Microservices Examples
+
+## Remote Call Policy
+
+```text
+Dependency: inventory-service
+Operation: reserve inventory
+Timeout: 800 ms total
+Retry: none, operation is not safe without idempotency key
+Fallback: fail order creation with retryable user-safe error
+Observability: trace span plus dependency latency metric
+```
+
+## Compatibility Rollout
+
+```text
+1. Provider adds optional response field.
+2. Consumer reads field when present.
+3. Provider starts writing required data.
+4. Consumer makes field required after all providers are upgraded.
+```

package/roles/software-developer/node/README.md

@@ -0,0 +1,25 @@
+# Node.js
+
+Use this packet for Node.js services, scripts, CLIs, workers, and runtime
+behavior.
+
+## Scope
+
+- Event loop behavior, async I/O, process lifecycle, package management, and runtime config.
+- HTTP servers, workers, queues, file operations, and background tasks.
+- Node-specific observability, error handling, and deployment concerns.
+
+## Standards
+
+- Avoid blocking the event loop in request paths.
+- Handle unhandled rejections and process shutdown gracefully.
+- Validate environment configuration at startup.
+- Keep package dependencies minimal and audited.
+- Use structured logs and correlation IDs.
+
+## Related Files
+
+- `../javascript/`
+- `../typescript/`
+- `../backend/`
+- `../observability/`

package/roles/software-developer/node/checklists.md

@@ -0,0 +1,15 @@
+# Node.js Checklists
+
+## Implementation
+
+- [ ] Validate required environment variables during startup.
+- [ ] Add request timeouts and body size limits.
+- [ ] Handle SIGTERM for graceful shutdown.
+- [ ] Avoid synchronous filesystem, crypto, or compression work in hot paths.
+- [ ] Lock package versions according to project policy.
+
+## Verification
+
+- [ ] Run lint, tests, and package audit where configured.
+- [ ] Test startup failure for missing config.
+- [ ] Test graceful shutdown with in-flight requests or jobs.

package/roles/software-developer/node/examples.md

@@ -0,0 +1,15 @@
+# Node.js Examples
+
+## Graceful Shutdown
+
+```javascript
+const server = app.listen(port);
+
+process.on('SIGTERM', () => {
+  logger.info({ event: 'process.shutdown.started' });
+  server.close(() => {
+    logger.info({ event: 'process.shutdown.completed' });
+    process.exit(0);
+  });
+});
+```

package/roles/software-developer/nosql/README.md

@@ -0,0 +1,24 @@
+# NoSQL
+
+Use this packet for document, key-value, wide-column, graph, and search-oriented
+datastores.
+
+## Scope
+
+- Access patterns, partition keys, document shape, secondary indexes, and consistency.
+- Denormalization, projections, TTLs, and schema evolution.
+- Hot partitions, query limits, and operational cost.
+
+## Standards
+
+- Model from access patterns, not only entity diagrams.
+- Make partition and sort keys explicit and reviewed.
+- Plan schema evolution and backfills for denormalized data.
+- Avoid unbounded scans in production paths.
+- Monitor capacity, throttling, latency, and hot keys.
+
+## Related Files
+
+- `../database/`
+- `../cache/`
+- `../performance/`

package/roles/software-developer/nosql/checklists.md

@@ -0,0 +1,21 @@
+# NoSQL Checklists
+
+## Design
+
+- [ ] List read and write access patterns.
+- [ ] Choose partition keys that avoid hot spots.
+- [ ] Define consistency requirements for each query.
+- [ ] Plan denormalized updates and repair jobs.
+
+## Implementation
+
+- [ ] Use conditional writes for concurrency-sensitive updates.
+- [ ] Keep document size and item cardinality within service limits.
+- [ ] Add TTLs only where expiry semantics are correct.
+- [ ] Avoid full collection scans in request paths.
+
+## Verification
+
+- [ ] Test hot-key, missing-item, duplicate-write, and stale-read cases.
+- [ ] Validate index usage or query plans.
+- [ ] Check cost and capacity impact.

package/roles/software-developer/nosql/examples.md

@@ -0,0 +1,20 @@
+# NoSQL Examples
+
+## Access Pattern Table
+
+```text
+Pattern: Load all active sessions for a user.
+Partition key: USER#{user_id}
+Sort key: SESSION#{created_at}
+Filter: status = active
+TTL: expires_at
+```
+
+## Conditional Write
+
+```python
+await table.put_item(
+    Item=item,
+    ConditionExpression="attribute_not_exists(pk)",
+)
+```

package/roles/software-developer/observability/README.md

@@ -0,0 +1,25 @@
+# Observability
+
+Use this packet when designing or changing the signals that explain production
+behavior: logs, metrics, traces, dashboards, alerts, and runbooks.
+
+## Scope
+
+- Service-level indicators, objectives, dashboards, tracing, metrics, and alerts.
+- Incident diagnosis, deployment verification, and operational readiness.
+- Signal quality, cost, cardinality, and retention.
+
+## Standards
+
+- Define what healthy means before choosing charts.
+- Measure rate, errors, duration, and saturation for critical paths.
+- Keep metric labels low-cardinality.
+- Link actionable alerts to runbooks.
+- Prefer symptoms over causes for paging alerts.
+
+## Related Files
+
+- `../logging/`
+- `../performance/`
+- `../microservices/`
+- `skills/performance/`

package/roles/software-developer/observability/checklists.md

@@ -0,0 +1,21 @@
+# Observability Checklists
+
+## Design
+
+- [ ] Define user-visible success and failure signals.
+- [ ] Identify service-level indicators and target objectives.
+- [ ] Decide logs, metrics, traces, dashboards, and alerts.
+- [ ] Define runbooks for alerts that require action.
+
+## Implementation
+
+- [ ] Add metrics for request count, error count, latency, and saturation.
+- [ ] Add traces across service, database, queue, and model boundaries.
+- [ ] Add structured logs for meaningful lifecycle events.
+- [ ] Keep labels bounded and avoid personal data.
+
+## Verification
+
+- [ ] Trigger success and failure paths and confirm signals appear.
+- [ ] Verify dashboards answer the main operational questions.
+- [ ] Verify alerts are actionable and not noisy.

package/roles/software-developer/observability/examples.md

@@ -0,0 +1,22 @@
+# Observability Examples
+
+## RED Metrics
+
+```text
+Rate: requests per second by service, route, method, status class
+Errors: failed requests by service, route, method, error code
+Duration: request latency histogram by service, route, method
+```
+
+## Alert Shape
+
+```yaml
+alert: HighErrorRate
+expr: rate(http_requests_total{status_class="5xx"}[5m])
+  / rate(http_requests_total[5m]) > 0.05
+for: 10m
+labels:
+  severity: page
+annotations:
+  runbook: docs/runbooks/high-error-rate.md
+```

package/roles/software-developer/performance/README.md

@@ -0,0 +1,26 @@
+# Performance
+
+Use this packet when work affects latency, throughput, memory, CPU, database
+load, network cost, startup time, or user-perceived responsiveness.
+
+## Scope
+
+- Measurement, profiling, optimization, capacity, and regression prevention.
+- Backend, database, cache, frontend, queue, and model-inference performance.
+- Load tests, benchmarks, SLOs, and production monitoring.
+
+## Standards
+
+- Measure before optimizing.
+- Optimize the bottleneck, not the most visible code.
+- Keep performance changes behaviorally safe and tested.
+- Track before-and-after evidence.
+- Avoid complexity unless the performance gain is necessary and proven.
+
+## Related Files
+
+- `../cache/`
+- `../database/`
+- `../observability/`
+- `../frontend/performance/`
+- `skills/performance/`

package/roles/software-developer/performance/checklists.md

@@ -0,0 +1,20 @@
+# Performance Checklists
+
+## Investigation
+
+- [ ] Define the target metric and acceptable threshold.
+- [ ] Capture baseline latency, throughput, CPU, memory, and dependency timing.
+- [ ] Identify the bottleneck with profiler, traces, query plans, or load tests.
+
+## Implementation
+
+- [ ] Make the smallest change that addresses the measured bottleneck.
+- [ ] Avoid changing behavior and performance in the same unreviewable diff.
+- [ ] Add metrics for the optimized path.
+- [ ] Document trade-offs such as freshness, memory, or complexity.
+
+## Verification
+
+- [ ] Compare before-and-after measurements.
+- [ ] Run regression tests for behavior.
+- [ ] Confirm no new bottleneck or resource spike appears.