nightytidy 0.3.7 → 0.3.9

package/src/prompts/steps/19-cost-resource-optimization.md

@@ -1,136 +1,136 @@
-# Cost & Resource Optimization
-
-Overnight audit to find every place the product wastes money — over-provisioned infra, unused services, redundant API calls, unbounded storage, and missing cost controls.
-
-**READ-ONLY for infrastructure.** Code-level fixes (redundant calls, missing caching, wasteful queries) go on branch `cost-optimization-[date]`. Run tests after every change.
-
----
-
-## Global Rules
-
-- Be specific: "$50-150/month based on [reasoning]", not "this could save money." State assumptions.
-- Distinguish **high-confidence savings** (unused resources, redundant calls) from **verify-with-metrics savings** (right-sizing, reserved instances).
-- Never recommend cost cuts that sacrifice reliability without calling out the tradeoff.
-- When you find waste, look for the same pattern elsewhere. Waste clusters.
-- Use web search to verify current pricing. Don't nickel-and-dime — focus on material waste.
-- You have all night. Be thorough.
-
----
-
-## Phase 1: Billable Service Inventory
-
-### Map every external service
-Search the entire codebase (source, config, IaC, Docker, CI/CD, `.env.example`, docs) for every billable service. For each, document: service name/provider, purpose (read the code), billing model, usage pattern (hot path vs. batch vs. rare), config location, SDK client initialization (shared vs. multiple instances), and tier/plan indicators.
-
-### Identify unused or underused services
-- Services in config but never called in code
-- Services only in dead/commented-out code or behind permanently-off feature flags
-- SDK initialized but only a fraction of capabilities used
-- Overlapping services (two email providers, two analytics platforms)
-- Dev/test services still configured in production
-
-### Identify missing cost controls
-For each service: rate limits? Budget caps? Usage alerts? Quota monitoring? Free-tier threshold awareness?
-
----
-
-## Phase 2: Infrastructure Resource Analysis
-
-### Infrastructure-as-Code (Terraform, CloudFormation, Pulumi, K8s, Docker Compose)
-
-Analyze every provisioned resource across these categories:
-
-- **Compute**: Instance sizing vs. workload, auto-scaling min/max, Lambda memory/timeout over-provisioning, container resource requests vs. actual needs, always-on resources that could be scheduled
-- **Database**: Instance size, unused read replicas (provisioned but not referenced in code), unnecessary Multi-AZ, provisioned IOPS vs. GP3, excessive backup retention, unbounded storage auto-scaling
-- **Storage**: Missing lifecycle policies, versioning without cleanup, no multipart upload abort policy, unbounded log buckets, CDN cache effectiveness
-- **Networking**: NAT Gateway costs ($0.045/GB), unnecessary cross-AZ/region transfer, unneeded load balancers, unattached Elastic IPs
-- **Cache/Search**: Instance sizing vs. dataset size, unused cache nodes, cluster mode vs. standalone, search index lifecycle management
-- **CDN**: Cache-control headers set correctly? Price class matches user geography?
-
-### Docker
-Base image bloat, missing multi-stage builds, dev dependencies in production images.
-
-### CI/CD
-Oversized runners for simple tasks, poor build caching, artifact retention policies, test execution efficiency, over-frequent scheduled pipelines.
-
----
-
-## Phase 3: Application-Level Cost Patterns
-
-### Redundant API calls
-Trace every external call: duplicate calls per request? Cacheable data re-fetched every time? Batch endpoints available but not used? Polling instead of webhooks? Data discarded and re-fetched instead of passed through?
-
-**Calculate**: calls_per_request × requests_per_day × cost_per_call = daily waste.
-
-### Database query cost
-Full table scans vs. indexed lookups, `SELECT *` fetching unneeded blobs, reads hitting primary instead of replicas, analytics on production DB, expensive aggregations recomputed per-request, N+1 queries, full-text search hitting DB when search index exists.
-
-### Storage patterns
-Unlimited upload sizes, permanently stored generated files that could expire, unclean temp files, logs on expensive tiers, blobs in DB instead of object storage.
-
-### Serverless patterns
-Unnecessary provisioned concurrency, long-running functions better suited to containers, memory over-allocation, function chaining costs, DynamoDB on-demand vs. provisioned mismatch, API Gateway where Lambda URLs suffice.
-
-### Third-party tier optimization
-Usage near tier thresholds? Premium features paid but unused? Cheaper alternatives for features actually used? Annual billing discounts missed? Non-prod on paid tiers unnecessarily?
-
-### Fix code-level waste (on branch)
-Cache repeated identical API calls, replace individual calls with batch calls, add `Cache-Control` headers, remove duplicate calls, add early returns before expensive operations, pass fetched data through call chains. Run tests, commit each batch.
-
----
-
-## Phase 4: Data Transfer & Egress
-
-Map data movement (client↔server, service↔service, server→third-party, DB→app). Then identify reduction opportunities: response compression (gzip/brotli), pagination on list endpoints, GraphQL depth limiting, CDN caching, production log verbosity, metrics cardinality.
-
----
-
-## Phase 5: Environment & Development Cost
-
-- Non-prod environments running production-scale infra? Always-on when used only business hours? Cleaned up after merge?
-- Paid tool seats for departed team members? Expensive tools used by one person billed to the whole team?
-
----
-
-## Phase 6: Cost Monitoring & Governance
-
-Assess: budget alerts, cost tagging strategy, per-feature cost attribution, anomaly detection, governance (can any dev provision expensive resources without review?), auto-scaling spending limits, third-party usage spike alerts. Recommend specific monitoring based on services found.
-
----
-
-## Output
-
-Save to `audit-reports/19_COST_OPTIMIZATION_REPORT_[run-number]_[date]_[time in user's local time].md`.
-
-### Report Structure
-
-1. **Executive Summary** — Total estimated monthly waste (range), confidence, top 5 savings, fixes implemented
-2. **Billable Service Inventory** — Table: Service | Provider | Purpose | Billing Model | Usage Pattern | Est. Monthly Cost | Issues
-3. **Infrastructure Analysis** — Tables per category (Compute, Database, Storage, Networking, Cache/Search, CDN, Containers, CI/CD) with current config, recommendation, estimated savings, confidence
-4. **Application-Level Waste** — Redundant API calls, DB cost patterns, storage patterns, serverless, third-party tier optimization
-5. **Data Transfer & Egress** — Patterns, volumes, recommendations
-6. **Non-Production Costs** — Environment inventory with parity/always-on/cleanup assessment
-7. **Code-Level Fixes Implemented** — File | Change | Impact | Tests Pass?
-8. **Cost Monitoring Assessment** — Visibility, tagging, alerts, governance gaps
-9. **Savings Roadmap** — Priority-ordered table: Opportunity | Est. Savings | Effort | Risk | Confidence | Details. Grouped into Immediate / This Month / This Quarter / Ongoing
-10. **Assumptions & Verification Needed** — Every estimate depending on unseen data, specific questions for the team
-
-### Chat Summary (always print in conversation)
-
-1. **Status** — One sentence: what you did, tests passing?
-2. **Key Findings** — Biggest savings with dollar estimates and confidence
-3. **Changes Made** — Code fixes applied (skip if none)
-4. **Recommendations** — Table if warranted: # | Recommendation | Est. Savings | Effort | Risk | Worth Doing? | Details. If total waste < $50/month, say so.
-5. **Verification Checklist** — Metrics/billing data the team should check
-6. **Report Location** — File path
-
----
-
-## Rules Summary
-
-- Branch for code changes only. Run tests after every change.
-- DO NOT modify infrastructure, cloud resources, env vars, or provisioning configs.
-- DO NOT downgrade tiers or remove resources — only recommend.
-- Always include dollar estimates with stated assumptions.
-- Never compromise reliability without explicit tradeoff disclosure.
-- When in doubt, document rather than change.
+# Cost & Resource Optimization
+
+Overnight audit to find every place the product wastes money — over-provisioned infra, unused services, redundant API calls, unbounded storage, and missing cost controls.
+
+**READ-ONLY for infrastructure.** Code-level fixes (redundant calls, missing caching, wasteful queries) go on branch `cost-optimization-[date]`. Run tests after every change.
+
+---
+
+## Global Rules
+
+- Be specific: "$50-150/month based on [reasoning]", not "this could save money." State assumptions.
+- Distinguish **high-confidence savings** (unused resources, redundant calls) from **verify-with-metrics savings** (right-sizing, reserved instances).
+- Never recommend cost cuts that sacrifice reliability without calling out the tradeoff.
+- When you find waste, look for the same pattern elsewhere. Waste clusters.
+- Use web search to verify current pricing. Don't nickel-and-dime — focus on material waste.
+- You have all night. Be thorough.
+
+---
+
+## Phase 1: Billable Service Inventory
+
+### Map every external service
+Search the entire codebase (source, config, IaC, Docker, CI/CD, `.env.example`, docs) for every billable service. For each, document: service name/provider, purpose (read the code), billing model, usage pattern (hot path vs. batch vs. rare), config location, SDK client initialization (shared vs. multiple instances), and tier/plan indicators.
+
+### Identify unused or underused services
+- Services in config but never called in code
+- Services only in dead/commented-out code or behind permanently-off feature flags
+- SDK initialized but only a fraction of capabilities used
+- Overlapping services (two email providers, two analytics platforms)
+- Dev/test services still configured in production
+
+### Identify missing cost controls
+For each service: rate limits? Budget caps? Usage alerts? Quota monitoring? Free-tier threshold awareness?
+
+---
+
+## Phase 2: Infrastructure Resource Analysis
+
+### Infrastructure-as-Code (Terraform, CloudFormation, Pulumi, K8s, Docker Compose)
+
+Analyze every provisioned resource across these categories:
+
+- **Compute**: Instance sizing vs. workload, auto-scaling min/max, Lambda memory/timeout over-provisioning, container resource requests vs. actual needs, always-on resources that could be scheduled
+- **Database**: Instance size, unused read replicas (provisioned but not referenced in code), unnecessary Multi-AZ, provisioned IOPS vs. GP3, excessive backup retention, unbounded storage auto-scaling
+- **Storage**: Missing lifecycle policies, versioning without cleanup, no multipart upload abort policy, unbounded log buckets, CDN cache effectiveness
+- **Networking**: NAT Gateway costs ($0.045/GB), unnecessary cross-AZ/region transfer, unneeded load balancers, unattached Elastic IPs
+- **Cache/Search**: Instance sizing vs. dataset size, unused cache nodes, cluster mode vs. standalone, search index lifecycle management
+- **CDN**: Cache-control headers set correctly? Price class matches user geography?
+
+### Docker
+Base image bloat, missing multi-stage builds, dev dependencies in production images.
+
+### CI/CD
+Oversized runners for simple tasks, poor build caching, artifact retention policies, test execution efficiency, over-frequent scheduled pipelines.
+
+---
+
+## Phase 3: Application-Level Cost Patterns
+
+### Redundant API calls
+Trace every external call: duplicate calls per request? Cacheable data re-fetched every time? Batch endpoints available but not used? Polling instead of webhooks? Data discarded and re-fetched instead of passed through?
+
+**Calculate**: calls_per_request × requests_per_day × cost_per_call = daily waste.
+
+### Database query cost
+Full table scans vs. indexed lookups, `SELECT *` fetching unneeded blobs, reads hitting primary instead of replicas, analytics on production DB, expensive aggregations recomputed per-request, N+1 queries, full-text search hitting DB when search index exists.
+
+### Storage patterns
+Unlimited upload sizes, permanently stored generated files that could expire, unclean temp files, logs on expensive tiers, blobs in DB instead of object storage.
+
+### Serverless patterns
+Unnecessary provisioned concurrency, long-running functions better suited to containers, memory over-allocation, function chaining costs, DynamoDB on-demand vs. provisioned mismatch, API Gateway where Lambda URLs suffice.
+
+### Third-party tier optimization
+Usage near tier thresholds? Premium features paid but unused? Cheaper alternatives for features actually used? Annual billing discounts missed? Non-prod on paid tiers unnecessarily?
+
+### Fix code-level waste (on branch)
+Cache repeated identical API calls, replace individual calls with batch calls, add `Cache-Control` headers, remove duplicate calls, add early returns before expensive operations, pass fetched data through call chains. Run tests, commit each batch.
+
+---
+
+## Phase 4: Data Transfer & Egress
+
+Map data movement (client↔server, service↔service, server→third-party, DB→app). Then identify reduction opportunities: response compression (gzip/brotli), pagination on list endpoints, GraphQL depth limiting, CDN caching, production log verbosity, metrics cardinality.
+
+---
+
+## Phase 5: Environment & Development Cost
+
+- Non-prod environments running production-scale infra? Always-on when used only business hours? Cleaned up after merge?
+- Paid tool seats for departed team members? Expensive tools used by one person billed to the whole team?
+
+---
+
+## Phase 6: Cost Monitoring & Governance
+
+Assess: budget alerts, cost tagging strategy, per-feature cost attribution, anomaly detection, governance (can any dev provision expensive resources without review?), auto-scaling spending limits, third-party usage spike alerts. Recommend specific monitoring based on services found.
+
+---
+
+## Output
+
+Save to `audit-reports/19_COST_OPTIMIZATION_REPORT_[run-number]_[date]_[time in user's local time].md`.
+
+### Report Structure
+
+1. **Executive Summary** — Total estimated monthly waste (range), confidence, top 5 savings, fixes implemented
+2. **Billable Service Inventory** — Table: Service | Provider | Purpose | Billing Model | Usage Pattern | Est. Monthly Cost | Issues
+3. **Infrastructure Analysis** — Tables per category (Compute, Database, Storage, Networking, Cache/Search, CDN, Containers, CI/CD) with current config, recommendation, estimated savings, confidence
+4. **Application-Level Waste** — Redundant API calls, DB cost patterns, storage patterns, serverless, third-party tier optimization
+5. **Data Transfer & Egress** — Patterns, volumes, recommendations
+6. **Non-Production Costs** — Environment inventory with parity/always-on/cleanup assessment
+7. **Code-Level Fixes Implemented** — File | Change | Impact | Tests Pass?
+8. **Cost Monitoring Assessment** — Visibility, tagging, alerts, governance gaps
+9. **Savings Roadmap** — Priority-ordered table: Opportunity | Est. Savings | Effort | Risk | Confidence | Details. Grouped into Immediate / This Month / This Quarter / Ongoing
+10. **Assumptions & Verification Needed** — Every estimate depending on unseen data, specific questions for the team
+
+### Chat Summary (always print in conversation)
+
+1. **Status** — One sentence: what you did, tests passing?
+2. **Key Findings** — Biggest savings with dollar estimates and confidence
+3. **Changes Made** — Code fixes applied (skip if none)
+4. **Recommendations** — Table if warranted: # | Recommendation | Est. Savings | Effort | Risk | Worth Doing? | Details. If total waste < $50/month, say so.
+5. **Verification Checklist** — Metrics/billing data the team should check
+6. **Report Location** — File path
+
+---
+
+## Rules Summary
+
+- Branch for code changes only. Run tests after every change.
+- DO NOT modify infrastructure, cloud resources, env vars, or provisioning configs.
+- DO NOT downgrade tiers or remove resources — only recommend.
+- Always include dollar estimates with stated assumptions.
+- Never compromise reliability without explicit tradeoff disclosure.
+- When in doubt, document rather than change.

package/src/prompts/steps/20-error-recovery.md

@@ -1,145 +1,145 @@
-You are running an overnight error recovery and resilience audit. Find where the system fails badly — crashes instead of recovering, hangs instead of timing out, corrupts data instead of rolling back — and fix the safe ones while documenting the rest.
-
-Branch: `resilience-[date]`
-
-## General Rules
-- Run tests after every change.
-- Commit messages: `fix: [what you did] in [module]`
-- DO NOT add new infrastructure dependencies. Use what exists or implement simple utilities.
-- DO NOT change business logic or user-facing behavior.
-- When adding timeouts, err generous — too-short causes false failures.
-- Only retry idempotent operations. If unsure, document instead.
-- Graceful shutdown must include a force-kill timeout to prevent hanging forever.
-- Be specific about failure modes. Not "this could fail" but "if Redis is unreachable for >5s, all authenticated endpoints hang until the 30s default timeout fires, exhausting the connection pool."
-- You have all night. Be thorough.
-
-## Phase 1: Timeout Audit
-
-**Step 1: Inventory every external call** — database queries, HTTP/API calls, cache ops, message queues, DNS, file storage (S3/GCS/NFS), email/SMS, WebSockets, gRPC/RPC.
-
-**Step 2: Check each call's timeout configuration**
-- Is there a timeout? Is it appropriate (a 30s default on a <100ms DB call is effectively none)?
-- Are connection timeout and read timeout configured separately?
-- What happens when the timeout fires — exception, null, retry, or silent hang?
-- Flag any calls with NO timeout (most dangerous).
-
-**Step 3: Fix missing/misconfigured timeouts**
-- Add timeouts to every unprotected external call. Sensible defaults:
-- Connection: 3-5s
-- Read: 100ms-2s for DB, 5-30s for external APIs, configurable for long-running ops
-- Make timeouts configurable via environment variables where they aren't already.
-
-## Phase 2: Retry Logic Audit
-
-**Step 1: Find all existing retry logic** — retry libraries, manual retry loops, queue/job retry config, webhook retry config.
-
-**Step 2: Evaluate each retry**
-- Is retry appropriate? Do NOT retry: non-idempotent ops without idempotency keys, client errors (4xx), auth errors, validation errors.
-- Has exponential backoff with jitter? (Fixed intervals cause thundering herd)
-- Has max retry limit and total timeout cap?
-- Are the right errors retried? (Network/503 yes, 400/404 no)
-- Is there logging on retry? Does the final error propagate meaningfully?
-
-**Step 3: Find operations that need retries but lack them** — transient-failure-prone external API calls, DB connection issues, queue publishes, notification sending.
-
-**Step 4: Add missing retries (safe operations only)**
-Only for idempotent ops expected to fail transiently, not on hot paths. Include exponential backoff with jitter, max 3 retries, transient-error-only filtering, and logged attempts with context.
-
-## Phase 3: Circuit Breaker & Fallback Assessment
-
-**Step 1: Identify circuit breaker needs** — For each external dependency: does failure cascade? Does the app return errors to ALL users, even those not needing that dependency? Does it hang?
-
-**Step 2: Identify fallback/degraded modes**
-Examples: cache down → direct DB queries; search down → basic LIKE queries; email down → queue for later; analytics down → continue without tracking; third-party API down → cached/stale data or "temporarily unavailable" UI.
-
-**Step 3: Document recommendations only** (do NOT implement overnight unless library already configured). For each: failure threshold, fallback behavior, recovery check, estimated effort.
-
-## Phase 4: Partial Failure & Data Consistency
-
-**Step 1: Find multi-step operations** with multiple side effects (e.g., create user + send email + create Stripe customer; process payment + update order + send confirmation + decrement inventory).
-
-**Step 2: Analyze failure modes** — What happens if step N fails after step N-1 succeeds? Is there a transaction? Are external side effects inside/outside it? Is there rollback/compensation logic? Audit trail?
-
-**Step 3: Fix safe issues**
-- Move external side effects OUTSIDE database transactions.
-- Add try/catch around non-critical side effects (notification failure should not fail the parent operation).
-- Log progress on critical multi-step operations for failure diagnosis.
-- Add idempotency guards for operations that might be retried after partial completion.
-
-## Phase 5: Graceful Shutdown
-
-**Step 1: Assess current behavior** — Does the app handle SIGTERM/SIGINT? On shutdown: does it kill in-flight requests, or drain them? Does it close DB/cache connections, drain queue consumers, flush logs/metrics? Is there a force-kill timeout?
-
-**Step 2: Implement/improve** — Add signal handlers if missing. Stop accepting new work → finish in-flight (with timeout) → close connections → drain queues → flush buffers → exit cleanly.
-
-## Phase 6: Dead Letter & Failure Queue Analysis
-
-If the app uses message queues or background jobs:
-
-**Step 1: Assess failure handling** — Are failed jobs retried with backoff? After max retries, where do they go? Is there a dead letter queue? Is it monitored? Can failed jobs be reprocessed? Are failure reasons logged with context?
-
-**Step 2: Assess queue health** — Unbounded growth risks? Max depth/age limits? Zombie jobs (started but never completed)? Stuck job detection?
-
-**Step 3: Fix what's safe** — Add DLQ config, failure logging, max retry limits, and error context to failed jobs.
-
-## Output
-
-Create `audit-reports/` in project root if needed. Save as `audit-reports/20_ERROR_RECOVERY_REPORT_[run-number]_[date]_[time in user's local time].md`, incrementing run number based on existing reports.
-
-### Report Structure
-
-1. **Executive Summary** — Resilience maturity (fragile / basic / moderate / resilient / robust). "What happens right now if [biggest dependency] goes down for 10 minutes?" Top 5 resilience gaps.
-
-2. **Timeout Audit** — Table: Operation | File | Timeout Before | Timeout After | Notes. List operations still missing timeouts and why.
-
-3. **Retry Logic** — Tables for: existing retries (Operation | Correct? | Issues | Fix), retries added (Operation | Strategy | Max Retries | Errors Retried), retries needed but not added (and why).
-
-4. **Circuit Breaker Recommendations** — Table: Dependency | Current Failure Mode | Recommended Config | Fallback | Effort.
-
-5. **Partial Failure Analysis** — Table: Operation | Steps | Failure Modes | Current Handling | Fixes Applied | Remaining Risk.
-
-6. **Graceful Shutdown** — Before/after state. Resource cleanup checklist: Resource | Cleaned Up on Shutdown?
-
-7. **Queue & Job Resilience** — Table: Queue/Job | Retry Config | Dead Letter? | Monitoring? | Fixes Applied.
-
-8. **Cascading Failure Risk Map** — Dependency graph, critical paths with no fallback, blast radius per dependency.
-
-9. **Recommendations** — Priority-ordered improvements, infrastructure needs, testing recommendations (chaos engineering, failure injection), incident response suggestions.
-
-## Chat Output Requirement
-
-In addition to writing the full report file, you MUST print a summary directly in the conversation when you finish. Do not make the user open the report to get the highlights. The chat summary should include:
-
-### 1. Status Line
-One sentence: what you did, how long it took, and whether all tests still pass.
-
-### 2. Key Findings
-The most important things discovered — bugs, risks, wins, or surprises. Each bullet should be specific and actionable, not vague. Lead with severity or impact.
-
-**Good:** "CRITICAL: No backup configuration found for the primary Postgres database — total data loss risk."
-**Bad:** "Found some issues with backups."
-
-### 3. Changes Made (if applicable)
-Bullet list of what was actually modified, added, or removed. Skip this section for read-only analysis runs.
-
-### 4. Recommendations
-
-If there are legitimately beneficial recommendations worth pursuing right now, present them in a table. Do **not** force recommendations — if the audit surfaced no actionable improvements, simply state that no recommendations are warranted at this time and move on.
-
-When recommendations exist, use this table format:
-
-| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
-|---|---|---|---|---|---|
-| *Sequential number* | *Short description (≤10 words)* | *What improves if addressed* | *Low / Medium / High / Critical* | *Yes / Probably / Only if time allows* | *1–3 sentences explaining the reasoning, context, or implementation guidance* |
-
-Order rows by risk descending (Critical → High → Medium → Low). Be honest in the "Worth Doing?" column — not everything flagged is worth the engineering time. If a recommendation is marginal, say so.
-
-### 5. Report Location
-State the full path to the detailed report file for deeper review.
-
----
-
-**Formatting rules for chat output:**
-- Use markdown headers, bold for severity labels, and bullet points for scannability.
-- Do not duplicate the full report contents — just the highlights and recommendations.
-- If you made zero findings in a phase, say so in one line rather than omitting it silently.
+You are running an overnight error recovery and resilience audit. Find where the system fails badly — crashes instead of recovering, hangs instead of timing out, corrupts data instead of rolling back — and fix the safe ones while documenting the rest.
+
+Branch: `resilience-[date]`
+
+## General Rules
+- Run tests after every change.
+- Commit messages: `fix: [what you did] in [module]`
+- DO NOT add new infrastructure dependencies. Use what exists or implement simple utilities.
+- DO NOT change business logic or user-facing behavior.
+- When adding timeouts, err generous — too-short causes false failures.
+- Only retry idempotent operations. If unsure, document instead.
+- Graceful shutdown must include a force-kill timeout to prevent hanging forever.
+- Be specific about failure modes. Not "this could fail" but "if Redis is unreachable for >5s, all authenticated endpoints hang until the 30s default timeout fires, exhausting the connection pool."
+- You have all night. Be thorough.
+
+## Phase 1: Timeout Audit
+
+**Step 1: Inventory every external call** — database queries, HTTP/API calls, cache ops, message queues, DNS, file storage (S3/GCS/NFS), email/SMS, WebSockets, gRPC/RPC.
+
+**Step 2: Check each call's timeout configuration**
+- Is there a timeout? Is it appropriate (a 30s default on a <100ms DB call is effectively none)?
+- Are connection timeout and read timeout configured separately?
+- What happens when the timeout fires — exception, null, retry, or silent hang?
+- Flag any calls with NO timeout (most dangerous).
+
+**Step 3: Fix missing/misconfigured timeouts**
+- Add timeouts to every unprotected external call. Sensible defaults:
+- Connection: 3-5s
+- Read: 100ms-2s for DB, 5-30s for external APIs, configurable for long-running ops
+- Make timeouts configurable via environment variables where they aren't already.
+
+## Phase 2: Retry Logic Audit
+
+**Step 1: Find all existing retry logic** — retry libraries, manual retry loops, queue/job retry config, webhook retry config.
+
+**Step 2: Evaluate each retry**
+- Is retry appropriate? Do NOT retry: non-idempotent ops without idempotency keys, client errors (4xx), auth errors, validation errors.
+- Has exponential backoff with jitter? (Fixed intervals cause thundering herd)
+- Has max retry limit and total timeout cap?
+- Are the right errors retried? (Network/503 yes, 400/404 no)
+- Is there logging on retry? Does the final error propagate meaningfully?
+
+**Step 3: Find operations that need retries but lack them** — transient-failure-prone external API calls, DB connection issues, queue publishes, notification sending.
+
+**Step 4: Add missing retries (safe operations only)**
+Only for idempotent ops expected to fail transiently, not on hot paths. Include exponential backoff with jitter, max 3 retries, transient-error-only filtering, and logged attempts with context.
+
+## Phase 3: Circuit Breaker & Fallback Assessment
+
+**Step 1: Identify circuit breaker needs** — For each external dependency: does failure cascade? Does the app return errors to ALL users, even those not needing that dependency? Does it hang?
+
+**Step 2: Identify fallback/degraded modes**
+Examples: cache down → direct DB queries; search down → basic LIKE queries; email down → queue for later; analytics down → continue without tracking; third-party API down → cached/stale data or "temporarily unavailable" UI.
+
+**Step 3: Document recommendations only** (do NOT implement overnight unless library already configured). For each: failure threshold, fallback behavior, recovery check, estimated effort.
+
+## Phase 4: Partial Failure & Data Consistency
+
+**Step 1: Find multi-step operations** with multiple side effects (e.g., create user + send email + create Stripe customer; process payment + update order + send confirmation + decrement inventory).
+
+**Step 2: Analyze failure modes** — What happens if step N fails after step N-1 succeeds? Is there a transaction? Are external side effects inside/outside it? Is there rollback/compensation logic? Audit trail?
+
+**Step 3: Fix safe issues**
+- Move external side effects OUTSIDE database transactions.
+- Add try/catch around non-critical side effects (notification failure should not fail the parent operation).
+- Log progress on critical multi-step operations for failure diagnosis.
+- Add idempotency guards for operations that might be retried after partial completion.
+
+## Phase 5: Graceful Shutdown
+
+**Step 1: Assess current behavior** — Does the app handle SIGTERM/SIGINT? On shutdown: does it kill in-flight requests, or drain them? Does it close DB/cache connections, drain queue consumers, flush logs/metrics? Is there a force-kill timeout?
+
+**Step 2: Implement/improve** — Add signal handlers if missing. Stop accepting new work → finish in-flight (with timeout) → close connections → drain queues → flush buffers → exit cleanly.
+
+## Phase 6: Dead Letter & Failure Queue Analysis
+
+If the app uses message queues or background jobs:
+
+**Step 1: Assess failure handling** — Are failed jobs retried with backoff? After max retries, where do they go? Is there a dead letter queue? Is it monitored? Can failed jobs be reprocessed? Are failure reasons logged with context?
+
+**Step 2: Assess queue health** — Unbounded growth risks? Max depth/age limits? Zombie jobs (started but never completed)? Stuck job detection?
+
+**Step 3: Fix what's safe** — Add DLQ config, failure logging, max retry limits, and error context to failed jobs.
+
+## Output
+
+Create `audit-reports/` in project root if needed. Save as `audit-reports/20_ERROR_RECOVERY_REPORT_[run-number]_[date]_[time in user's local time].md`, incrementing run number based on existing reports.
+
+### Report Structure
+
+1. **Executive Summary** — Resilience maturity (fragile / basic / moderate / resilient / robust). "What happens right now if [biggest dependency] goes down for 10 minutes?" Top 5 resilience gaps.
+
+2. **Timeout Audit** — Table: Operation | File | Timeout Before | Timeout After | Notes. List operations still missing timeouts and why.
+
+3. **Retry Logic** — Tables for: existing retries (Operation | Correct? | Issues | Fix), retries added (Operation | Strategy | Max Retries | Errors Retried), retries needed but not added (and why).
+
+4. **Circuit Breaker Recommendations** — Table: Dependency | Current Failure Mode | Recommended Config | Fallback | Effort.
+
+5. **Partial Failure Analysis** — Table: Operation | Steps | Failure Modes | Current Handling | Fixes Applied | Remaining Risk.
+
+6. **Graceful Shutdown** — Before/after state. Resource cleanup checklist: Resource | Cleaned Up on Shutdown?
+
+7. **Queue & Job Resilience** — Table: Queue/Job | Retry Config | Dead Letter? | Monitoring? | Fixes Applied.
+
+8. **Cascading Failure Risk Map** — Dependency graph, critical paths with no fallback, blast radius per dependency.
+
+9. **Recommendations** — Priority-ordered improvements, infrastructure needs, testing recommendations (chaos engineering, failure injection), incident response suggestions.
+
+## Chat Output Requirement
+
+In addition to writing the full report file, you MUST print a summary directly in the conversation when you finish. Do not make the user open the report to get the highlights. The chat summary should include:
+
+### 1. Status Line
+One sentence: what you did, how long it took, and whether all tests still pass.
+
+### 2. Key Findings
+The most important things discovered — bugs, risks, wins, or surprises. Each bullet should be specific and actionable, not vague. Lead with severity or impact.
+
+**Good:** "CRITICAL: No backup configuration found for the primary Postgres database — total data loss risk."
+**Bad:** "Found some issues with backups."
+
+### 3. Changes Made (if applicable)
+Bullet list of what was actually modified, added, or removed. Skip this section for read-only analysis runs.
+
+### 4. Recommendations
+
+If there are legitimately beneficial recommendations worth pursuing right now, present them in a table. Do **not** force recommendations — if the audit surfaced no actionable improvements, simply state that no recommendations are warranted at this time and move on.
+
+When recommendations exist, use this table format:
+
+| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
+|---|---|---|---|---|---|
+| *Sequential number* | *Short description (≤10 words)* | *What improves if addressed* | *Low / Medium / High / Critical* | *Yes / Probably / Only if time allows* | *1–3 sentences explaining the reasoning, context, or implementation guidance* |
+
+Order rows by risk descending (Critical → High → Medium → Low). Be honest in the "Worth Doing?" column — not everything flagged is worth the engineering time. If a recommendation is marginal, say so.
+
+### 5. Report Location
+State the full path to the detailed report file for deeper review.
+
+---
+
+**Formatting rules for chat output:**
+- Use markdown headers, bold for severity labels, and bullet points for scannability.
+- Do not duplicate the full report contents — just the highlights and recommendations.
+- If you made zero findings in a phase, say so in one line rather than omitting it silently.