The CONTEXT Framework™ for Developers

I am a senior developer reviewing a pull request from a mid-level team member. The PR adds a new payment processing module to our Node.js/TypeScript monorepo. The code works and tests pass, but there are patterns that will cause maintenance problems. We use the repository pattern, Zod for validation, and have strict error handling conventions.

Write 4 code review comments addressing: a try/catch that swallows errors silently, a Zod schema that does not validate edge cases, a function that mixes business logic with database calls, and a missing index on a query that will slow down at scale.

Be constructive, not critical. Explain why each change matters for the long term, not just what to change. Reference our team coding standards where relevant. Do not rewrite their code entirely — suggest specific, minimal changes. The developer is mid-level and learning our patterns, so frame feedback as coaching. Flag the silent error swallowing as the highest priority.

Supportive and educational. Like a mentor who wants the developer to understand the reasoning, not just follow instructions.

Comment style: 'This works for now, but here is what happens at scale: [explanation]. A small change that would help: [suggestion]. This matters because [reason].' Reference: our error handling guide at /docs/error-handling.md.

4 separate review comments. Each: Location (file:line), Priority (P1/P2/P3), Comment (60-80 words), Suggested Change (code snippet), and Why It Matters (1 sentence). Order by priority.

I am a backend developer debugging a production issue in our Python FastAPI application. Users intermittently get 500 errors when uploading files larger than 5MB. The error logs show 'Connection reset by peer' from our S3 client. It happens about 15% of the time, not consistently. We use boto3 with default configuration, and our infrastructure runs behind an AWS ALB with a 30-second idle timeout.

Diagnose the likely root cause, explain why it is intermittent, and provide a fix with code.

Consider the interaction between ALB timeout settings, S3 multipart upload thresholds, and boto3 default retry configuration. The intermittent nature suggests a timing/timeout issue, not a code logic bug. Check whether the boto3 default multipart threshold (8MB) might cause some files to use single-part upload while others use multipart. Include the specific boto3 configuration changes needed, not just general advice. The fix must not break uploads under 5MB.

Technical and precise. Like a senior engineer walking through the debugging process so the reader learns the methodology, not just the answer.

Diagnosis format: 'Hypothesis: [what I think is happening]. Evidence: [what supports this]. Test: [how to confirm]. Fix: [specific code change].' For the boto3 config, show the specific Config object with retry and timeout settings.

Structure: Diagnosis (hypothesis + evidence, 150 words), Root Cause Explanation (why it is intermittent, 100 words), The Fix (Python code with comments), Verification Steps (3 bullets on how to confirm the fix works), and Prevention (what monitoring to add). Total: 500-600 words including code.

I am a staff engineer at a fintech company with 40 developers across 6 teams. We currently use a monolithic Django application and are evaluating whether to extract the payments service into a separate microservice. The payments module handles 2,000 transactions per hour, has strict PCI compliance requirements, and is the most frequently changed module (45 PRs last quarter).

Write an Architecture Decision Record (ADR) evaluating whether to extract the payments microservice, with a clear recommendation.

Consider: team ownership boundaries (payments team is 6 people), deployment independence (payments deployments currently block the entire monolith), PCI compliance scope (a separate service could reduce the PCI audit surface), data consistency requirements (payments must be ACID-compliant with the orders table), and operational complexity (we do not have a service mesh or distributed tracing today). Be genuinely balanced — extraction has significant operational costs.

Technical, balanced, and decisive. The ADR should present both sides fairly but end with a clear recommendation and reasoning. Write for an audience of senior engineers and engineering directors.

ADR format: 'Status: Proposed. Context: [why this decision is needed now]. Decision Drivers: [numbered list]. Options Considered: [option + pros/cons]. Decision: [the recommendation]. Consequences: [what changes].' Reference the MADR (Markdown Any Decision Records) template.

Structure following MADR template: Title, Status, Context (150 words), Decision Drivers (5 bullets), Options (3 options, each with 3 pros and 3 cons), Decision (the recommendation with rationale, 100 words), Consequences (positive and negative, 4 bullets each). Total: 800-1,000 words.

I am a developer who just built an internal authentication middleware for our Express/TypeScript API. It handles JWT validation, role-based access control, and rate limiting. Three other teams will need to integrate with this middleware starting next week. None of them were involved in building it.

Write the developer documentation for the auth middleware so other teams can integrate it without asking me questions.

Assume the reader is a competent TypeScript developer but has never seen this codebase. Include the 3 most common integration patterns (protect a route, check a specific role, exempt a route from auth). Document every environment variable required. Include the error response format so frontend teams know what to handle. Flag the one gotcha that will definitely trip someone up (the middleware must be registered before the body parser).

Clear, practical, and scannable. Optimise for a developer who wants to integrate in 15 minutes, not read a textbook. Assume they will search for specific sections, not read top to bottom.

Integration example: 'import { requireAuth, requireRole } from "@internal/auth-middleware"; router.get("/users", requireAuth(), requireRole("admin"), handler);' — show the simplest working example first, then variations.

Structure: Overview (what it does, 50 words), Quick Start (copy-paste working example), Installation (npm install + env vars), API Reference (each exported function with params and return types), Integration Patterns (3 patterns with code), Error Responses (table of status codes and payloads), Gotchas (the body parser issue), and Troubleshooting (3 common issues). Total: 600-800 words plus code examples.

I am a developer writing tests for a pricing calculator function in our TypeScript e-commerce platform. The function calculates order totals with: percentage and fixed-amount discounts, stacking rules (max 2 discounts per order), tax calculation (varies by region), free shipping thresholds, and currency rounding. Current test coverage for this module is 34%.

Write a comprehensive test suite for the calculateOrderTotal function that covers the edge cases most likely to cause production bugs.

Focus on the edge cases that actually cause bugs in pricing: rounding errors with percentages (e.g., 33.33% of 10.00), discount stacking order (percentage then fixed vs. fixed then percentage gives different results), zero-quantity items, negative amounts from over-discounting, tax on discounted vs. original price, and currency precision (never display more than 2 decimal places). Do not write trivial tests like 'returns 0 for empty cart.' Use the Arrange-Act-Assert pattern.

Precise and thorough. Each test name should describe the scenario and expected behaviour. Comments should explain why each edge case matters, not what the test does.

Test style: 'describe("discount stacking", () => { it("applies percentage discount before fixed discount when both are present", () => { // Arrange: 100 item + 10% off + 5 fixed off // Act: calculate // Assert: should be 85 (100 * 0.9 - 5), not 85.50 (100 - 5 * 0.9) }); });'

Use Jest/Vitest syntax with TypeScript. Group tests into describe blocks by feature area (discounts, tax, shipping, rounding). Include at least 15 test cases with emphasis on edge cases. Each test: descriptive name, Arrange-Act-Assert pattern, and a comment explaining why this case matters. Include a table of test scenarios at the top as a comment.

I am a backend developer designing a new REST API for a project management tool. We need endpoints for managing tasks within projects. Tasks have: title, description, assignee, status (todo/in-progress/review/done), priority (low/medium/high/urgent), due date, tags, and comments. We follow JSON:API conventions, use cursor-based pagination, and our API is consumed by both a web app and a mobile app.

Design the complete REST API specification for the tasks resource, including all CRUD operations, filtering, and relationships.

Include bulk operations (assign multiple tasks, change status of multiple tasks) because the web app needs this for board views. Support filtering by status, assignee, priority, and due date range. The mobile app needs a lightweight response option that excludes comments and description to save bandwidth. Handle the case where a task is moved between projects. Include rate limiting headers in responses. Do not nest resources deeper than 2 levels.

Precise and standards-compliant. This spec will be handed to frontend developers and used to generate API documentation. Zero ambiguity.

Endpoint format: 'GET /api/v1/projects/:projectId/tasks?filter[status]=in-progress&filter[assignee]=user123&page[cursor]=abc123&fields=title,status,assignee' — show the full URL pattern with realistic query parameters.

Structure: Base URL and versioning, Authentication (bearer token), each endpoint with: HTTP method, URL pattern, request headers, request body (JSON example), response body (JSON example with JSON:API format), status codes (success + error cases), and rate limit headers. Cover: List tasks (with filtering + pagination), Get single task, Create task, Update task, Delete task, Bulk status update, Move task between projects, and Add comment. Total: 800-1,000 words plus JSON examples.

I am a senior developer responsible for a 5-year-old React class component that renders our main dashboard. The component is 1,800 lines long, manages 23 pieces of state, makes 7 API calls on mount, and has no tests. It is the most fragile file in the codebase — every sprint, at least one bug originates here. We cannot rewrite it all at once because it serves 10,000 daily active users.

Create a phased refactoring plan that modernises this component incrementally without breaking production.

Each phase must be deployable independently with zero user-facing changes. Start by extracting the easiest, most isolated pieces first to build confidence. Prioritise extracting the 7 API calls into custom hooks because they cause the most bugs. Do not convert to functional components until the state has been properly organised — doing both at once is too risky. Include a testing strategy that adds coverage before each refactor, not after. Account for the fact that other developers will be adding features to this file during the refactoring.

Pragmatic and risk-aware. This plan must convince a sceptical engineering manager that it will not break production. Acknowledge the risks at each phase and include rollback plans.

Phase format: 'Phase 2: Extract API hooks (5 days). Step 1: Add integration tests for current API call behaviour. Step 2: Create useProjectData() hook. Step 3: Replace the class method with the hook using a wrapper. Rollback: Revert the hook, class method still works. Risk: Medium — API timing could change. Mitigation: Feature flag on the hook.'

Structure: Current State Assessment (100 words + key metrics), Refactoring Principles (4 rules we will follow), Phase breakdown (5 phases), each with: name, duration estimate, steps (numbered), risk level, rollback plan, and definition of done. Include a Dependencies section (things that must not change during refactoring) and a Testing Strategy section. Total: 800-1,000 words.

I am the tech lead on a team migrating our PostgreSQL database from a single-tenant architecture to multi-tenant. We have 450 tables, 200GB of data, and 50 active customers. The application must remain online during the migration. We use Rails with ActiveRecord and have 12 developers who will need to adapt their queries. Current average query response time is 45ms.

Create a migration plan that adds tenant isolation to our database without downtime and without breaking existing queries.

Evaluate three approaches: schema-per-tenant, shared tables with tenant_id column, and Row Level Security (RLS) with tenant_id. Our largest customer has 60% of the data, which affects the schema-per-tenant option. Include the Rails ActiveRecord changes needed (default scopes, middleware to set current tenant). Address: how to backfill tenant_id on 450 tables without locking, how to handle cross-tenant queries for admin dashboards, and how to test that no data leaks between tenants. The migration must not increase average query time above 50ms.

Thorough, risk-aware, and implementation-focused. This is a plan for senior engineers to execute over 6-8 weeks. No hand-waving.

Migration step format: 'Step 3: Add tenant_id column to orders table. Migration: add_column :orders, :tenant_id, :uuid, null: true (nullable first to avoid lock). Backfill: UPDATE orders SET tenant_id = accounts.tenant_id FROM accounts WHERE orders.account_id = accounts.id — run in batches of 10,000. Validation: SELECT COUNT(*) FROM orders WHERE tenant_id IS NULL should equal 0. Then: change_column_null :orders, :tenant_id, false.'

Structure: Approach Decision (comparison table of 3 options with recommendation), Migration Phases (4 phases: schema changes, backfill, application changes, validation), each phase with: duration, specific steps, SQL examples, rollback procedure, and performance benchmarks. Include a Data Leak Testing section and a Rollback Master Plan. Total: 1,000-1,200 words plus code examples.

I am a developer submitting a PR that implements real-time notifications using WebSockets in our React/Node.js application. The PR touches 14 files across frontend and backend. It introduces a new WebSocket server, a React context provider for notification state, and modifies the existing notification REST endpoint to also push events via WebSocket. Two other developers will review this.

Write a PR description that helps reviewers understand the changes quickly and review efficiently.

Explain the architectural decision (why WebSockets instead of SSE or polling). Group the 14 file changes into logical sections so reviewers can review in the right order. Flag the 2 files that need the most careful review (the WebSocket connection manager and the notification context provider). Mention what is explicitly not included in this PR (notification preferences UI, which is a separate PR). Include the testing approach and how to test locally.

Clear, structured, and reviewer-friendly. Write for developers who are context-switching into this review from other work.

PR description format: '## What: [1 sentence]. ## Why: [2 sentences on the problem and approach]. ## How to Review: [ordered list of file groups]. ## Testing: [local testing steps]. ## Not Included: [what is deferred to future PRs].'

Structure: Title (under 72 chars, conventional commit format), What (1 sentence), Why (2-3 sentences), Architecture Decision (WebSocket vs SSE vs polling, 3 bullet comparison), How to Review (4 file groups in review order, with the 2 critical files flagged), Testing (4 steps to test locally including WebSocket connection verification), Not Included (3 bullets of deferred work), and Screenshots/GIF (describe what to include). Total: 400-500 words.

I am the on-call engineer who led the response to a 47-minute production outage last night. Our payment processing service went down at 23:14 UTC because a database connection pool was exhausted. The root cause was a new feature deployment at 22:45 that introduced a query with a missing index, which caused connection hold times to increase from 5ms to 4,200ms. 340 transactions failed during the outage. The team that deployed the feature did not know the query was problematic because it worked fine in staging (smaller dataset).

Write an incident postmortem that identifies root causes, captures lessons, and proposes preventive measures without blaming the team that deployed the change.

Apply the 'five whys' methodology to get past the surface cause (missing index) to the systemic issues (no query performance testing against production-sized data, no connection pool monitoring alerts, no automatic rollback on deployment). Be blameless — the postmortem should never identify individuals or teams by name. Include a timeline with UTC timestamps. Quantify the customer impact (340 failed transactions, estimated revenue impact). Distinguish between the immediate fix (added the index) and the systemic fixes (prevent this class of issue).

Factual, blameless, and improvement-focused. The postmortem should make everyone feel like the system failed, not a person. Serious about the impact but constructive about the path forward.

Timeline format: '22:45 UTC — Deployment of feature X completed successfully. 23:14 UTC — PagerDuty alert: payment-service error rate > 5%. 23:17 UTC — On-call engineer acknowledged, began investigation.' Action item format: 'Action: Add connection pool saturation alert at 80% threshold. Owner: [team, not individual]. Priority: P1. Due: [date].'

Structure: Incident Summary (50 words), Impact (customer-facing metrics), Timeline (minute-by-minute from deployment to resolution), Root Cause Analysis (five whys, 5 levels deep), What Went Well (3 bullets), What Went Poorly (3 bullets), Action Items (5 items, each with owner team, priority, and due date), and Lessons Learned (3 systemic observations). Total: 800-1,000 words.