{ "policy": { "version": 5, "patterns": { "version": 1, "method": "CURATED_PRACTICE_TOPIC", "notice": "Pattern topics identify design choices to practice. Read the ticket's acceptance criteria and justify the simplest suitable approach. Tags are not capability or ownership evidence; an untagged ticket has no curated pattern topic assigned." }, "fieldMix": { "version": 1, "method": "CURATED_ESTIMATE", "notice": "Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence." }, "contentStatus": "PRACTICE_BRIEF", "assessmentStatus": "NOT_QUALIFIED", "evidenceUse": "NONE", "aiPolicy": "AI tools are welcome during implementation. Record assumptions, review the result, and verify its behavior.", "notice": "Fictional engineering practice briefs. Starter repositories, fixtures, automated grading, and verified ownership are not included.", "outcomeEvidence": "Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.", "ownershipEvidence": "Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence." }, "patternTopics": [ { "id": "factory-method", "label": "Factory Method", "group": "Creational" }, { "id": "abstract-factory", "label": "Abstract Factory", "group": "Creational" }, { "id": "builder", "label": "Builder", "group": "Creational" }, { "id": "prototype", "label": "Prototype", "group": "Creational" }, { "id": "singleton", "label": "Singleton", "group": "Creational" }, { "id": "adapter", "label": "Adapter", "group": "Structural" }, { "id": "bridge", "label": "Bridge", "group": "Structural" }, { "id": "composite", "label": "Composite", "group": "Structural" }, { "id": "decorator", "label": "Decorator", "group": "Structural" }, { "id": "facade", "label": "Facade", "group": "Structural" }, { "id": "flyweight", "label": "Flyweight", "group": "Structural" }, { "id": "proxy", "label": "Proxy", "group": "Structural" }, { "id": "chain-of-responsibility", "label": "Chain of Responsibility", "group": "Behavioral" }, { "id": "command", "label": "Command", "group": "Behavioral" }, { "id": "interpreter", "label": "Interpreter", "group": "Behavioral" }, { "id": "iterator", "label": "Iterator", "group": "Behavioral" }, { "id": "mediator", "label": "Mediator", "group": "Behavioral" }, { "id": "memento", "label": "Memento", "group": "Behavioral" }, { "id": "observer", "label": "Observer", "group": "Behavioral" }, { "id": "state", "label": "State", "group": "Behavioral" }, { "id": "strategy", "label": "Strategy", "group": "Behavioral" }, { "id": "template-method", "label": "Template Method", "group": "Behavioral" }, { "id": "visitor", "label": "Visitor", "group": "Behavioral" }, { "id": "ports-and-adapters", "label": "Ports and Adapters", "group": "Architectural" }, { "id": "cqrs", "label": "CQRS", "group": "Architectural" }, { "id": "strangler-fig", "label": "Strangler Fig", "group": "Architectural" }, { "id": "saga", "label": "Saga", "group": "Distributed and reliability" }, { "id": "transactional-outbox", "label": "Transactional Outbox", "group": "Distributed and reliability" }, { "id": "circuit-breaker", "label": "Circuit Breaker", "group": "Distributed and reliability" }, { "id": "bulkhead", "label": "Bulkhead", "group": "Distributed and reliability" } ], "projects": [ { "id": "2e825222-0287-42c2-8b11-53751e8dc421", "key": "PLATENCY", "title": "Find the missing seconds in the quote API", "summary": "Explain and reduce quote latency under a mixed workload without weakening pricing correctness.", "context": "A fictional freight broker sees slow quote responses at dispatch handover. The service looks healthy in average-latency charts, yet a few long requests occupy every worker. Build a small synthetic quote service and controlled dependency stub before taking implementation tickets.", "stack": [ "TypeScript", "Node.js", "PostgreSQL", "OpenTelemetry", "k6" ], "prerequisites": [ "Create a local quote endpoint and a deterministic carrier-price stub; no repository or dataset is supplied.", "Use synthetic routes and a fixed workload manifest. Record runtime, machine resources and instrumentation settings." ], "developerValue": "Learn to distinguish queueing, dependency delay, CPU work and measurement mistakes using reproducible observations.", "companyValue": "Produce a reviewable diagnosis and guarded changes that could guide a team investigating customer-visible latency.", "delivery": "Ten tickets in three phases. Estimates assume the local service and generator already exist; all load runs stay in the owned local environment. Budgets are exercise requirements, not measured platform results.", "phases": [ { "id": "observe", "title": "Establish trustworthy measurements", "goal": "Define the traffic shape and separate time spent waiting from time spent working." }, { "id": "isolate", "title": "Remove demonstrated bottlenecks", "goal": "Change one constrained path at a time while checking exact quote outputs." }, { "id": "release", "title": "Protect the improvement", "goal": "Use tail-aware admission and a reversible release gate." } ], "field": "Performance engineering", "tickets": [ { "id": "0a2afd0d-53b7-4703-9809-5103abc53e6b", "key": "PLATENCY-101", "title": "Write down the traffic mix before comparing quote timings", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "observe", "dependsOn": [], "scenario": "The last benchmark sent one route repeatedly. Dispatch says the slow period contains mostly unique routes and a small number of expensive multi-stop quotes.", "acceptanceCriteria": [ "Create a seeded mix of 70% single-stop, 25% multi-stop and 5% invalid requests across 1,000 synthetic routes.", "Record concurrency, arrival rate, seed, payload sizes, runtime and resource limits in the run manifest.", "Count every attempted request, including validation failures and client timeouts, against the expected result class." ], "implementationNotes": [ "Keep the fixture bounded; random seeds must reproduce both request order and expected quote inputs." ], "verification": [ "Replay the same seed twice and compare request identities and expected outputs.", "Change the seed and confirm the traffic proportions stay within the declared rounding rule." ], "deliverables": [ "Workload manifest and deterministic request generator" ], "rollout": "Commit the baseline manifest separately; a workload change starts a new comparison series.", "skills": [ "Workload modeling", "Reproducibility" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [] }, { "id": "0d17d498-ff4c-4758-9150-256f1cd5dbc3", "key": "PLATENCY-102", "title": "Show quote latency percentiles alongside rejected and timed-out requests", "type": "STORY", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "observe", "dependsOn": [ "PLATENCY-101" ], "scenario": "The dashboard median improves when the slowest requests time out and disappear from successful-response measurements.", "acceptanceCriteria": [ "Report p50, p95 and p99 with sample counts for completed requests, and separate timeout, rejection and transport-error counts.", "State the observation window and histogram precision; do not average percentiles across workers.", "Keep route identifiers, customer IDs and quote payloads out of metric labels." ], "implementationNotes": [ "Use bounded result-class labels and merge histogram counts before computing aggregate percentiles." ], "verification": [ "Replay a fixture with known short, long and timed-out requests and reconcile all attempts.", "Compare merged-worker results with the same samples processed in one worker, within the declared histogram precision." ], "deliverables": [ "Latency dashboard definition and aggregation regression fixture" ], "rollout": "Run the new view beside the existing chart for the synthetic workload; keep raw counters if rendering is reverted.", "skills": [ "Metrics", "Latency distributions" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Site reliability", "percentage": 30 }, { "field": "Privacy engineering", "percentage": 20 } ], "patterns": [] }, { "id": "600e7dbd-d7ec-4981-b0b0-b838ac8639ed", "key": "PLATENCY-103", "title": "Separate quote queue time from carrier lookup time", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "observe", "dependsOn": [ "PLATENCY-101" ], "scenario": "A trace labels the entire request as carrier latency, but the stub returns quickly when called outside the API.", "acceptanceCriteria": [ "Record monotonic durations for admission wait, application work and carrier lookup with one request correlation identifier.", "Make the phase durations reconcile with total server duration within documented instrumentation overhead.", "Record cancellation and missing-span states explicitly instead of inventing zero-duration work." ], "implementationNotes": [ "Do not put route payloads or credentials into spans; use a bounded synthetic request identifier for this exercise." ], "verification": [ "Inject 100 ms of queue delay and verify it appears outside the carrier span.", "Cancel a queued request and confirm the trace distinguishes waiting from a lookup that never started." ], "deliverables": [ "Span boundaries and an annotated trace from the controlled stub" ], "rollout": "Enable sampling locally first; disable extra spans independently if instrumentation changes the measured workload.", "skills": [ "Tracing", "Queueing" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 60 }, { "field": "Site reliability", "percentage": 40 } ], "patterns": [] }, { "id": "00e1a598-b523-44a2-965d-f19546b29b1e", "key": "PLATENCY-104", "title": "Remove repeated tariff parsing from the quote hot path", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "isolate", "dependsOn": [ "PLATENCY-101", "PLATENCY-103" ], "scenario": "A CPU profile shows every quote parsing the same tariff document, including requests that use the same immutable tariff revision.", "acceptanceCriteria": [ "Parse once per tariff revision and cap retained revisions with an explicit eviction policy.", "Keep quote totals and rounding behavior identical to the uncached path for the seeded fixture.", "Reject a malformed new revision without replacing the last valid parsed tariff." ], "implementationNotes": [ "Measure before and after with the same revision distribution; do not cache request-specific discounts in the shared tariff object." ], "verification": [ "Compare every synthetic quote against the uncached implementation across two valid revisions.", "Alternate malformed and valid revisions, then force eviction and verify both bounded memory and correct reparsing." ], "deliverables": [ "Profile comparison, bounded parsed-tariff cache and regression tests" ], "rollout": "Gate parsed-tariff reuse behind a switch; reverting uses the original parser and discards only derived cache entries.", "skills": [ "CPU profiling", "Cache invalidation" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 70 }, { "field": "Backend", "percentage": 30 } ], "patterns": [] }, { "id": "06afe288-897d-40a0-9dd4-446c48dc4503", "key": "PLATENCY-105", "title": "Stop expired quotes from holding carrier connections", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "isolate", "dependsOn": [ "PLATENCY-102", "PLATENCY-103" ], "scenario": "A client disconnects after its deadline, but the carrier lookup continues and consumes one of the few available connections.", "acceptanceCriteria": [ "Propagate the remaining deadline through queue admission and the carrier client.", "Release the connection and remove queued work when the request is cancelled, including cancellation before dispatch.", "Return one bounded timeout outcome without automatically retrying a request whose caller has left." ], "implementationNotes": [ "Use the stub to control headers, body completion and connection close separately; wall-clock sleeps alone do not prove cleanup." ], "verification": [ "Cancel before dispatch, while waiting for headers and during a streamed response; count active work returning to baseline.", "Race normal completion against cancellation and confirm one response classification and no unhandled rejection." ], "deliverables": [ "Deadline propagation and deterministic cancellation tests" ], "rollout": "Canary the deadline path with active-connection counters; restore the previous client only after pending work drains.", "skills": [ "Cancellation", "Resource lifecycle" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 40 }, { "field": "Networking", "percentage": 30 }, { "field": "Backend", "percentage": 30 } ], "patterns": [] }, { "id": "b7c066b4-1ed2-4072-a170-257242fe4c1e", "key": "PLATENCY-106", "title": "Bound parallel carrier lookups without serializing every quote", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 240, "phaseId": "isolate", "dependsOn": [ "PLATENCY-101", "PLATENCY-105" ], "scenario": "Multi-stop quotes fan out immediately. A burst exhausts the carrier stub connection pool and slows unrelated single-stop traffic.", "acceptanceCriteria": [ "Apply a configurable global in-flight limit and a bounded admission queue.", "Remove cancelled entries promptly and define fairness so a large quote cannot monopolize all new slots.", "Preserve the required carrier results or return an explicit incomplete-quote outcome; never silently price from a partial result." ], "implementationNotes": [ "Compare limits using the fixed traffic mix and a stub with a declared service-time distribution." ], "verification": [ "Run single-stop and multi-stop requests together and verify the configured concurrency ceiling.", "Overfill the queue, cancel its head and inject a carrier failure; verify forward progress and no leaked permit." ], "deliverables": [ "Admission controller, mixed-traffic measurements and permit invariants" ], "rollout": "Start with the current safe connection limit; queue rejection is observable and the feature switch restores the previous dispatch path.", "skills": [ "Concurrency control", "Backpressure" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Backend", "percentage": 30 }, { "field": "Site reliability", "percentage": 20 } ], "patterns": [] }, { "id": "07d1b067-5c79-4e01-a56e-8bebd6ed1ee3", "key": "PLATENCY-107", "title": "Check whether quote serialization is blocking unrelated requests", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "isolate", "dependsOn": [ "PLATENCY-101", "PLATENCY-103" ], "scenario": "The largest multi-stop responses correlate with event-loop delay. The team has proposed adding workers before confirming where time is spent.", "acceptanceCriteria": [ "Capture CPU and event-loop delay measurements for small and maximum-size synthetic quote responses.", "Separate JSON serialization cost from database and dependency time in the experiment.", "Produce a decision note identifying the measured bottleneck, uncertainty and one bounded next change; report when the hypothesis is unsupported." ], "implementationNotes": [ "Use three repeated baseline runs after warmup on the same runtime and resource limits; save the measurement commands." ], "verification": [ "Repeat with a prebuilt response body to isolate serialization while retaining the same payload size.", "Run a small health request concurrently and compare its tail latency with and without the large-response workload." ], "deliverables": [ "Reproducible profiling report and supported next-step decision" ], "rollout": "This investigation changes no serving path; retain the baseline commands for the implementation review.", "skills": [ "Profiling", "Experimental design" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 70 }, { "field": "Backend", "percentage": 30 } ], "patterns": [] }, { "id": "ef36060e-64e7-4bdd-bc48-6e949a361070", "key": "PLATENCY-108", "title": "Choose an overload policy from the quote deadline budget", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 360, "phaseId": "release", "dependsOn": [ "PLATENCY-102", "PLATENCY-105", "PLATENCY-106" ], "scenario": "At overload, a larger queue increases completed work but most quotes arrive after the dispatch screen has already given up.", "acceptanceCriteria": [ "Compare at least two admission policies at 0.5, 1.0 and 1.5 times the measured sustainable arrival rate.", "Evaluate deadline success rate, rejection rate, p99 and queue depth together; document the selected tradeoff.", "Implement the selected bounded policy and retain exact pricing correctness for every admitted request." ], "implementationNotes": [ "Use an open-loop arrival schedule and account for generator saturation; define sustainable rate from the recorded local baseline, not a guessed production number." ], "verification": [ "Run three repetitions per load level after fixed warmup and publish spread, request counts and all timeout outcomes.", "Inject a carrier slowdown midway through a run and show queue depth remains bounded and recovery does not require restart." ], "deliverables": [ "Admission decision record, load results and overload recovery regression" ], "rollout": "Canary against the declared deadline-success guardrail; revert policy configuration if correctness or rejection behavior differs from the approved contract.", "skills": [ "Capacity planning", "Tail latency", "Load testing" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 60 }, { "field": "Site reliability", "percentage": 40 } ], "patterns": [] }, { "id": "77d79dd2-3bda-4eb2-9cdb-a5fa887cc121", "key": "PLATENCY-109", "title": "Make the quote benchmark fail when the generator cannot keep up", "type": "CHORE", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "release", "dependsOn": [ "PLATENCY-101", "PLATENCY-102" ], "scenario": "A promising result came from a generator sharing the API CPU quota. It slowed its own arrivals and reported a workload the service never received.", "acceptanceCriteria": [ "Record scheduled versus actual send time and count requests the generator could not issue.", "Invalidate comparisons when dispatch lag exceeds the manifest threshold or achieved load falls below the declared tolerance.", "Keep server and generator resource measurements distinguishable even when both run on one development machine." ], "implementationNotes": [ "Document the local topology and quota allocation; do not require a paid load-testing service." ], "verification": [ "Throttle the generator deliberately and verify the run is rejected as incomparable.", "Run a valid low-load fixture and reconcile planned, sent, completed and failed request totals." ], "deliverables": [ "Generator health gate and an intentionally invalid benchmark sample" ], "rollout": "Add the gate to the local benchmark command before accepting further performance comparisons.", "skills": [ "Benchmark validity", "Load generation" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [] }, { "id": "89dcf11d-aaff-4001-838f-3201ca47d6a3", "key": "PLATENCY-110", "title": "Gate quote changes on repeated tail-latency and correctness checks", "type": "CHORE", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "release", "dependsOn": [ "PLATENCY-104", "PLATENCY-106", "PLATENCY-108", "PLATENCY-109" ], "scenario": "The team can demonstrate one fast run, but it has no rule for accepting noisy results or reverting a change that prices correctly only at low concurrency.", "acceptanceCriteria": [ "Use the fixed workload and three paired runs after warmup; report all runs and median p99 with spread.", "For this exercise require unchanged fixture outputs, no higher timeout rate and at least 15% lower median p99 at the declared baseline arrival rate.", "Mark an unstable or generator-invalid result inconclusive and stop promotion; retain the prior configuration and a documented rollback command." ], "implementationNotes": [ "The 15% threshold is an exercise acceptance budget on the declared machine, not a universal performance promise." ], "verification": [ "Run the candidate and baseline in alternating order and retain raw histograms and output comparisons.", "Introduce a known pricing regression and a deliberately slow candidate separately; both must block the release gate for the relevant reason." ], "deliverables": [ "Repeatable release check, run artifacts and rollback rehearsal notes" ], "rollout": "Promote only within the synthetic environment after the gate passes; restore the previous configuration and repeat the same workload to verify recovery.", "skills": [ "Performance regression", "Release verification" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Quality engineering", "percentage": 30 }, { "field": "Site reliability", "percentage": 20 } ], "patterns": [] } ] } ] }