@mohammadhprp/system-prompt 0.10.1

package/framework/skills/backend-best-practices/references/observability.md

@@ -0,0 +1,78 @@
+# Observability Reference
+
+Design logs, metrics, traces, health checks, dashboards, and alerts for production operations.
+
+## When to Use
+
+Use this when the task involves structured logging, metrics, distributed tracing, health checks, dashboards, alerting, service-level indicators, or incident readiness. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not use it for trivial text edits unless the edit changes engineering guidance.
+
+## Principles
+
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Structured logs should describe events with stable fields and no sensitive data.
+- Metrics should track rates, errors, durations, saturation, and business outcomes.
+- Traces should show cross-boundary latency and failure points.
+- Health checks should distinguish process liveness from dependency readiness.
+- Alerts should be actionable, tied to user impact, and include runbook guidance.
+- Dashboards should support both real-time triage and trend review.
+
+## Workflow
+
+1. Identify the operational signals needed: what questions will operators ask during normal operation and incidents?
+2. Add structured logs with stable field names, correlation IDs, and severity levels.
+3. Define metrics: rates (RPS), errors, durations (latency), saturation (CPU, memory, connections), and business outcomes.
+4. Add distributed tracing for requests that cross service boundaries.
+5. Implement health check endpoints that distinguish liveness (process alive) from readiness (able to serve traffic).
+6. Set up dashboards for triage (real-time) and trends (daily/weekly).
+7. Configure alerts that are actionable, documented with runbooks, and free of noise.
+8. Test observability: verify logs appear, metrics have values, traces propagate, alerts fire.
+
+## Rules
+
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/observability.md, references/standards/logging.md.
+
+## Deliverables
+
+- Structured logging schema with field names and severity levels.
+- Metrics definition: rates, errors, durations, saturation, business outcomes.
+- Distributed tracing configuration and propagation plan.
+- Health check implementation (liveness vs readiness).
+- Dashboard layouts and alert rules with runbook links.
+- Observability test plan.
+
+## Common Mistakes
+
+- Logging everything at the same level, making it impossible to distinguish critical from noise.
+- Creating dashboards that look impressive but cannot be used to diagnose an incident.
+- Setting alerts that page without a clear mitigation step.
+- Adding tracing to only some services, breaking the end-to-end trace.
+- Forgetting to log or metric business outcomes (orders placed, payments completed).
+
+## Failure Modes
+
+- An incident cannot be diagnosed because logs are too verbose or too sparse.
+- An alert fires but no one knows what to do because there is no runbook.
+- Metrics have high cardinality labels, causing monitoring infrastructure to fail.
+- Traces are sampled away for the exact request that failed.
+
+## Checklist
+
+- [ ] Logs are structured with consistent field names and correlation IDs.
+- [ ] Sensitive data is excluded from logs, metrics, and traces.
+- [ ] Metrics track rates, errors, durations, saturation, and business outcomes.
+- [ ] Health checks distinguish liveness from readiness.
+- [ ] Alerts are actionable and linked to a runbook.
+- [ ] Dashboards support both triage and trend analysis.
+- [ ] Tracing covers all services in the request path.

package/framework/skills/backend-best-practices/references/performance.md

@@ -0,0 +1,78 @@
+# Performance Reference
+
+Diagnose and improve CPU, memory, network, storage, caching, and query behavior using evidence.
+
+## When to Use
+
+Use this when the task involves CPU, memory, network, caching, query optimization, parallelism, profiling, benchmarking, latency, throughput, or resource cost. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not use it for trivial text edits unless the edit changes engineering guidance.
+
+## Principles
+
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Measure before optimizing and define the target metric: latency, throughput, cost, or capacity.
+- CPU work should be bounded and avoid repeated expensive computation.
+- Memory use should avoid unbounded aggregation, buffering, and cache growth.
+- Network calls need timeouts, batching where appropriate, and payload discipline.
+- Caching requires invalidation, freshness expectations, and failure behavior.
+- Parallelism must preserve correctness and respect downstream limits.
+- Benchmarks should reflect realistic data sizes and access patterns.
+
+## Workflow
+
+1. Define the performance target: latency p50/p95/p99, throughput RPS, resource budget.
+2. Measure the current state before proposing any change. Profile CPU, memory, I/O, network.
+3. Identify the bottleneck: slowest path, most allocated memory, most frequent call.
+4. Formulate a targeted optimization based on evidence, not intuition.
+5. Implement the smallest change that addresses the bottleneck.
+6. Re-measure to confirm improvement and verify no regressions in other paths.
+7. Add performance regression tests for critical paths.
+8. Document the optimization: baseline, result, tradeoffs (complexity, readability, maintainability).
+
+## Rules
+
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/performance.md.
+
+## Deliverables
+
+- Baseline measurement and profiling results.
+- Bottleneck identification with evidence.
+- Targeted optimization with before/after comparison.
+- Performance regression tests for critical paths.
+- Tradeoff documentation: complexity, readability, maintainability.
+
+## Common Mistakes
+
+- Optimizing without measuring first, leading to wasted effort on non-bottlenecks.
+- Adding caching without defining invalidation strategy, freshness requirements, or failure behavior.
+- Premature optimization that adds complexity for unproven gains.
+- Ignoring the performance impact of N+1 queries, unbounded data loading, and missing indexes.
+- Optimizing for throughput at the expense of p99 latency or vice versa without understanding the requirement.
+
+## Failure Modes
+
+- An optimization improves p50 but makes p99 worse (tail at scale).
+- A cache introduces stale data because invalidation was not designed.
+- A query optimization breaks on a different database version or data distribution.
+- A performance improvement reduces readability without sufficient documentation.
+
+## Checklist
+
+- [ ] A baseline measurement exists before the change.
+- [ ] The bottleneck is identified through profiling, not guessing.
+- [ ] Caching has defined invalidation, freshness, and failure behavior.
+- [ ] N+1 queries and unbounded data loading are resolved.
+- [ ] Performance regression tests cover critical paths.
+- [ ] Tradeoffs against readability, complexity, and maintainability are documented.
+- [ ] P50, P95, P99 latency targets are defined and measured.

package/framework/skills/backend-best-practices/references/refactoring.md

@@ -0,0 +1,77 @@
+# Refactoring Reference
+
+Improve code structure safely while preserving behavior through small verified steps.
+
+## When to Use
+
+Use this when the task involves removing duplication, simplifying code, reducing complexity, improving naming, preserving behavior, or making small incremental changes. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not use it for trivial text edits unless the edit changes engineering guidance.
+
+## Principles
+
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Preserve externally visible behavior unless a behavior change is explicitly requested.
+- Make one conceptual change at a time.
+- Remove duplication by extracting the stable idea, not by forcing unrelated code through one abstraction.
+- Improve names when they reduce cognitive load for future changes.
+- Characterization tests are useful before touching risky legacy behavior.
+- Stop refactoring when the code is simpler enough for the current goal.
+
+## Workflow
+
+1. Identify the improvement goal: reduce duplication, simplify logic, improve naming, extract module.
+2. Verify existing test coverage. If coverage is weak, add characterization tests first.
+3. Make one conceptual change at a time. Commit or stage after each safe step.
+4. Preserve external behavior: same inputs produce same outputs, same errors, same side effects.
+5. Run the full test suite after each change step.
+6. Compare before and after: verify the improvement did not introduce subtle behavioral differences.
+7. Remove dead code, commented code, and unused dependencies found during the refactor.
+8. Stop when the code is clear enough for the current maintenance needs - avoid over-refactoring.
+
+## Rules
+
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/naming.md, references/standards/testing.md.
+
+## Deliverables
+
+- Improved code with one conceptual change per step.
+- Passing test suite before and after each step.
+- Characterization tests for legacy code with weak coverage.
+- Before/after comparison confirming behavior preservation.
+- Removed dead code, commented code, and unused dependencies.
+
+## Common Mistakes
+
+- Refactoring and changing behavior in the same step.
+- Removing tests or code that seems unused but is actually relied upon implicitly.
+- Over-abstracting: creating interfaces, base classes, or indirection before a clear need exists.
+- Refactoring for performance without measuring the baseline.
+- Leaving the code in a half-refactored state.
+
+## Failure Modes
+
+- A refactor introduces a subtle behavior change that tests do not catch.
+- Over-refactoring produces a more complex design than the original.
+- A rename misses a reference, causing a production issue.
+- A shared abstraction created during refactoring becomes a coupling point that is hard to undo.
+
+## Checklist
+
+- [ ] Existing tests pass before and after each refactoring step.
+- [ ] One conceptual change is made at a time.
+- [ ] External behavior is preserved (same inputs, outputs, errors, side effects).
+- [ ] Dead code, commented code, and unused dependencies are removed.
+- [ ] Naming reflects business meaning after the refactor.
+- [ ] Refactored code is simpler, not more complex.
+- [ ] Characterization tests exist for legacy code with weak coverage.

package/framework/skills/backend-best-practices/references/security.md

@@ -0,0 +1,80 @@
+# Security Reference
+
+Apply practical security review across identity, access, secrets, data handling, and abuse resistance.
+
+## When to Use
+
+Use this when the task involves authentication, authorization, secrets, encryption, OWASP-style risks, injection, input validation, output encoding, rate limiting, abuse prevention, or least privilege. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not use it for trivial text edits unless the edit changes engineering guidance.
+
+## Principles
+
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Treat all input as untrusted, including internal calls, background jobs, files, and message payloads.
+- Enforce least privilege for users, services, tokens, storage, and operational access.
+- Secrets must never appear in source, logs, errors, metrics, traces, or examples.
+- Use encryption deliberately for data in transit and sensitive data at rest.
+- Prevent injection by separating commands from data and validating allowed shapes.
+- Output encoding and safe error responses prevent data disclosure.
+- Abuse controls such as rate limits should protect expensive and sensitive actions.
+
+## Workflow
+
+1. Identify data assets, entry points, and trust boundaries in the system.
+2. Review authentication: is identity verified at every entry point?
+3. Review authorization: is access checked against the resource, not assumed from the caller?
+4. Review input handling: are all inputs validated, sanitized, or parameterized at every boundary?
+5. Review secrets: are any credentials, tokens, or keys exposed in code, logs, configs, or errors?
+6. Review data protection: is encryption applied for data in transit and sensitive data at rest?
+7. Review abuse controls: rate limiting, payload limits, request throttling for expensive actions.
+8. Test security boundaries: attempt injection, forced browsing, privilege escalation.
+9. Document residual risks and recommended mitigations.
+
+## Rules
+
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/security.md.
+
+## Deliverables
+
+- Security review of authentication, authorization, and input handling.
+- Secrets exposure analysis.
+- Data protection review (in transit and at rest).
+- Abuse control assessment.
+- Residual risks and recommended mitigations.
+
+## Common Mistakes
+
+- Performing authorization checks only in the UI or frontend and not at the API boundary.
+- Storing secrets in source code, environment files committed to git, or inline configs.
+- Trusting input from internal services, background jobs, or message queues without validation.
+- Using weak or outdated cryptographic algorithms.
+- Ignoring rate limiting on authentication endpoints, allowing brute force.
+
+## Failure Modes
+
+- A vulnerability is introduced because input validation is missing on a new endpoint.
+- A secret is exposed in logs or error responses, causing a credential leak.
+- Authorization is checked on the first request but not re-verified for subsequent operations in a workflow.
+- A security review misses an issue because it focused on code and ignored infrastructure config.
+
+## Checklist
+
+- [ ] Authentication is enforced at every external entry point.
+- [ ] Authorization checks happen at the resource boundary, not just in the UI.
+- [ ] All inputs are validated, sanitized, or parameterized.
+- [ ] Secrets are never in source code, logs, errors, or example configs.
+- [ ] Encryption is applied for data in transit (TLS) and sensitive data at rest.
+- [ ] Rate limiting protects authentication and expensive endpoints.
+- [ ] Output encoding prevents injection in responses to other systems.
+- [ ] Dependencies are scanned for known vulnerabilities.

package/framework/skills/backend-best-practices/references/testing.md

@@ -0,0 +1,77 @@
+# Testing Reference
+
+Design deterministic unit, integration, contract, and end-to-end testing strategies.
+
+## When to Use
+
+Use this when the task involves unit, integration, contract, end-to-end, testability, mocking, deterministic behavior, or release confidence. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not use it for trivial text edits unless the edit changes engineering guidance.
+
+## Principles
+
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Unit tests prove local rules and edge cases quickly.
+- Integration tests prove persistence, transactions, serialization, and external boundaries.
+- Contract tests protect clients and providers from incompatible changes.
+- End-to-end tests should cover critical user journeys, not every branch.
+- Deterministic tests avoid time, order, randomness, and shared-state flakiness.
+- Mocks should model behavior and failure, not implementation trivia.
+
+## Workflow
+
+1. Identify what is being tested: a unit of logic, an integration boundary, a contract, or an end-to-end journey.
+2. Choose the narrowest test type that provides sufficient confidence for the risk level.
+3. Write the test starting with the expected behavior: given X, when Y, then Z.
+4. Cover normal paths, edge cases (empty, null, boundary values), and failure paths (timeouts, errors, invalid input).
+5. Keep tests deterministic: no dependence on time, random values, shared state, or external service availability.
+6. Use mocks at integration boundaries to model real behavior and realistic failures, not implementation details.
+7. Run the full test suite locally before pushing.
+8. Review test coverage: are there untested branches, error paths, or concurrent scenarios?
+
+## Rules
+
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/testing.md.
+
+## Deliverables
+
+- Test plan covering normal paths, edge cases, and failure paths.
+- Deterministic tests with given/when/then structure.
+- Mock strategy modeling boundary behavior.
+- Contract tests for public API boundaries.
+- Coverage analysis of untested branches and error paths.
+
+## Common Mistakes
+
+- Writing tests that mirror implementation details, breaking when the code is refactored.
+- Testing only the happy path and ignoring error handling and edge cases.
+- Using mocks that model framework internals instead of boundary behavior.
+- Creating flaky tests that depend on timing, ordering, or shared state.
+- Writing overly broad integration tests that are slow and brittle.
+
+## Failure Modes
+
+- A test passes in CI but fails locally (or vice versa) because of environment differences.
+- A refactor breaks many tests because they were coupled to implementation instead of behavior.
+- An integration test becomes a maintenance burden because it exercises too many paths at once.
+- False-positive tests give false confidence while real bugs exist in untested paths.
+
+## Checklist
+
+- [ ] Tests cover normal paths, edge cases, and failure paths.
+- [ ] Tests are deterministic: no flakiness from time, randomness, or shared state.
+- [ ] Mocks model boundary behavior, not implementation internals.
+- [ ] The test suite runs in CI and is fast enough for quick feedback.
+- [ ] Coverage includes error handling and concurrent scenarios where applicable.
+- [ ] Tests are readable: given/when/then structure with descriptive names.
+- [ ] Contract tests exist for public API boundaries.

package/framework/skills/backend-engineer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: backend-engineer
+description: Analyze backend requirements, risks, and implementation plans before coding.
+version: 0.1.0
+---
+# Purpose
+Analyze backend requirements, risks, and implementation plans before coding. This skill guides an AI agent to act with senior backend judgment: clarify the outcome, identify constraints, choose the least complex safe path, and make production impact visible.
+
+# When to Activate
+Use this skill when the task involves general backend planning, requirement analysis, problem breakdown, complexity estimates, risk evaluation, and simple solution selection. It is also useful when a request is vague, risky, touches production behavior, changes contracts, changes data, or needs a reviewable engineering plan. Do not activate it for trivial text edits unless the edit changes engineering guidance.
+
+# Principles
+- Correctness and data integrity come before speed of implementation.
+- Simplicity is a feature: fewer moving parts means fewer failure modes.
+- Existing contracts must remain compatible unless a breaking change is approved.
+- Every important decision should have a reason, an alternative considered, and an operational consequence.
+- Work should be testable, observable, deployable, and reversible.
+- Prefer explicit boundaries, clear names, and local reasoning over clever shared abstractions.
+- Security and privacy are design inputs, not final review steps.
+
+- Requirements analysis must identify users, workflows, data ownership, invariants, and constraints.
+- Break problems into contract, domain, persistence, operations, and delivery concerns.
+- Estimate complexity by counting boundaries, state transitions, migration steps, and failure modes.
+- Evaluate risks before implementation: data loss, authorization gaps, compatibility breaks, latency, and operational burden.
+- Choose the simplest solution that satisfies current known needs and can evolve safely.
+
+# Workflow
+1. Restate the user goal in concrete backend terms with explicit scope and non-goals.
+2. Identify actors, data entities, invariants, and failure modes.
+3. Identify external dependencies, integration points, and data flows.
+4. Inspect existing project patterns and conventions before proposing changes.
+5. Decide whether clarifying questions are needed. Ask only questions that materially affect design or risk.
+6. Produce a small plan: contract, data changes, behavior changes, tests, observability, deployment, rollback.
+7. Compare at least one simpler alternative when the proposed solution adds complexity.
+8. Verify with the narrowest meaningful tests, then broader checks when risk justifies them.
+9. Summarize tradeoffs, residual risks, and follow-up work.
+
+# Rules
+- Never assume hidden requirements, traffic scale, compliance needs, or data retention rules.
+- Do not introduce new infrastructure unless the current requirement cannot be met safely without it.
+- Do not hide breaking changes in refactors.
+- Do not weaken authorization, validation, transaction safety, or error handling to make implementation easier.
+- Keep public contracts, migrations, and operational changes explicit in the deliverable.
+- Reference related standards: references/standards/architecture.md, references/standards/testing.md.
+
+# Deliverables
+- A concise engineering plan or review summary.
+- Explicit assumptions and clarifying questions when needed.
+- Contract, data, test, observability, deployment, and rollback notes for production changes.
+- Concrete risks with mitigations.
+- A checklist showing completion evidence.
+
+# Common Mistakes
+- Starting with code before understanding invariants, data ownership, or failure modes.
+- Designing for imagined future scale while ignoring present correctness.
+- Treating validation, authorization, logging, and tests as optional polish.
+- Creating generic abstractions after seeing only one use case.
+- Optimizing without measurement or failing to define the target metric.
+- Writing documents that describe implementation but omit failure handling.
+
+# Failure Modes
+- A simple request becomes a broad rewrite because scope was not bounded.
+- A change works locally but cannot be safely deployed or rolled back.
+- Data becomes inconsistent because constraints or transactions were skipped.
+- Operators cannot diagnose incidents because logs and metrics are missing.
+- Reviewers cannot evaluate risk because decisions and assumptions are implicit.
+
+# Checklist
+- [ ] Goal, scope, and non-goals are clearly defined.
+- [ ] Simpler alternatives were considered and documented.
+- [ ] Data integrity and backward compatibility are protected.
+- [ ] Security and authorization impact is reviewed.
+- [ ] Tests cover normal paths, edge cases, and failure paths.
+- [ ] Logs, metrics, traces, or health signals are included when operationally relevant.
+- [ ] Deployment and rollback are understood and tested.
+- [ ] The deliverable explains reasoning and evidence, not just code.

package/framework/skills/backend-engineer/examples.md

@@ -0,0 +1,31 @@
+# Backend Engineer Examples
+
+## Example 1: User Settings API
+
+Implement an endpoint that reads and updates user notification preferences. Good agent behavior:
+
+- Identify actors (user, admin) and data ownership rules—user sees own settings, admin sees tenant-wide defaults.
+- Choose a caching strategy: cache by user_id with a short TTL; invalidate on write via cache-aside pattern.
+- Validate setting keys against an allowlist, reject unknown keys with a 422 error and a list of valid options.
+- Design the update to be partial (PATCH) so clients send only changed fields; merge with stored defaults.
+- Add a rate limit on writes to prevent abuse; reads can be higher but still bounded.
+
+## Example 2: Notification Service
+
+Design a service that sends email and push notifications when orders are placed. Good agent behavior:
+
+- Evaluate sync vs async delivery: accept the notification request synchronously but hand delivery off to a queue for resilience.
+- Implement a retry mechanism with exponential backoff for transient failures; dead-letter after 3 attempts.
+- Deduplicate by notification_id so the same event is not sent twice if the producer retries.
+- Template notifications server-side so copy changes don't require app releases.
+- Emit telemetry for each notification channel (sent, delivered, bounced, opened) to track provider health.
+
+## Example 3: Inventory Reservation
+
+Design inventory reservation for a checkout flow with a 15-minute payment window. Good agent behavior:
+
+- Reserve inventory atomically at checkout time; release the reservation if payment is not completed within the window.
+- Handle concurrent requests: use SELECT FOR UPDATE or optimistic locking to prevent overselling.
+- On payment failure, roll back the reservation immediately and asynchronously notify the warehouse.
+- Implement a background job that releases expired reservations every minute; log releases for audit.
+- Add metrics for reservation success, expiration, and contention rate to tune the timeout and capacity.