{ "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": "5ae7dc5a-eb3b-4e8b-8a2f-dffda17fb2de", "key": "PBATCH", "title": "Import a large supplier catalog without exhausting the worker", "summary": "Make a bounded catalog import stream, recover and report progress under explicit resource limits.", "context": "A fictional wholesaler imports supplier rows into a staging catalog. The current prototype reads the entire file into memory and restarts from zero after a failure. Build the prototype and generated CSV fixture locally before measuring improvements.", "stack": [ "TypeScript", "Node.js streams", "PostgreSQL", "CSV" ], "prerequisites": [ "Generate a deterministic 250,000-row synthetic CSV with quoted newlines, invalid records and a stated maximum record size.", "Create a disposable staging database and an import process constrained to 256 MiB; record runtime and available CPU." ], "developerValue": "Practice streaming, backpressure, allocation analysis and resumable work while retaining exact import semantics.", "companyValue": "Develop a repeatable import performance and recovery exercise that exposes memory, throughput and data-quality tradeoffs.", "delivery": "Ten tickets in three phases. All data and failures are locally generated; throughput targets are relative to the declared baseline and do not imply a production service-level guarantee.", "phases": [ { "id": "characterize", "title": "Define input and resource behavior", "goal": "Establish a representative file and honest end-to-end measurements." }, { "id": "stream", "title": "Bound the import pipeline", "goal": "Control buffering and write work without dropping or duplicating records." }, { "id": "operate", "title": "Recover and verify", "goal": "Resume safely, report useful progress and gate throughput improvements." } ], "field": "Performance engineering", "tickets": [ { "id": "c80696ed-e263-44af-b91f-17ea4c4cd20e", "key": "PBATCH-101", "title": "Generate a catalog file that includes difficult CSV boundaries", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 75, "phaseId": "characterize", "dependsOn": [], "scenario": "The demonstration file has one short record per line. It cannot expose parsers that split quoted descriptions or allocate one enormous record.", "acceptanceCriteria": [ "Generate 250,000 deterministic rows including quoted delimiters, embedded newlines, multibyte text and declared invalid cases.", "Publish expected accepted/rejected counts and a digest of normalized accepted records.", "Declare a maximum record size and include an intentionally oversized record in a separate failure fixture." ], "implementationNotes": [ "Use invented supplier identifiers and descriptions; fixture generation must not require a downloaded customer file." ], "verification": [ "Regenerate with the same seed and compare file digest and expected counts.", "Parse with a reference implementation and verify quoted newlines do not change record boundaries." ], "deliverables": [ "Fixture generator, manifest and expected normalized digest" ], "rollout": "Version the fixture before profiling; keep the oversized fixture separate so the normal baseline has a defined completion result.", "skills": [ "CSV contracts", "Synthetic data" ], "fieldMix": [ { "field": "Data engineering", "percentage": 50 }, { "field": "Quality engineering", "percentage": 30 }, { "field": "Performance engineering", "percentage": 20 } ], "patterns": [] }, { "id": "d60b7c84-d0c8-4007-be0a-feaa375640f8", "key": "PBATCH-102", "title": "Measure peak import memory across parsing, validation and writes", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "characterize", "dependsOn": [ "PBATCH-101" ], "scenario": "The worker exits near the end of an import, but the existing memory sample is taken only after garbage collection and misses the peak.", "acceptanceCriteria": [ "Record process RSS, managed heap, buffered-record count and stage throughput at a fixed documented sampling interval.", "Report peak values and exit outcome, including resource-limit termination.", "Separate input-read completion from database-commit completion in elapsed time." ], "implementationNotes": [ "Document sampling limitations and resource limits; do not report a killed run as a completed low-memory run." ], "verification": [ "Run the whole-file baseline and retain its peak or termination outcome.", "Inject a slow writer and verify the timeline shows buffered work accumulating before completion." ], "deliverables": [ "Resource timeline and baseline measurement command" ], "rollout": "Keep measurement output outside imported data; retain failed-run artifacts for the streaming comparison.", "skills": [ "Memory measurement", "Pipeline profiling" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 70 }, { "field": "Data engineering", "percentage": 30 } ], "patterns": [] }, { "id": "6e1eb2db-8f56-4d4d-8a71-cbe69bd221db", "key": "PBATCH-103", "title": "Attribute import time to parsing, validation and database waits", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "characterize", "dependsOn": [ "PBATCH-101", "PBATCH-102" ], "scenario": "A proposal to increase database concurrency assumes writes dominate, but expensive normalization may already saturate one CPU core.", "acceptanceCriteria": [ "Measure stage service time and time blocked on downstream capacity separately.", "Compare parse-only, parse-plus-validation and complete-import runs using the same input.", "Reconcile accepted and rejected records between stages and identify the supported bottleneck hypothesis." ], "implementationNotes": [ "Use bounded aggregate timing rather than one log entry per record, which would alter the measured workload." ], "verification": [ "Inject a known validation delay and show its contribution in the stage report.", "Inject writer delay instead and confirm it appears as downstream wait rather than parser CPU time." ], "deliverables": [ "Stage comparison report and aggregate instrumentation" ], "rollout": "Use the instrumentation in local benchmarks first; disable it independently if overhead makes comparisons unreliable.", "skills": [ "Bottleneck analysis", "Instrumentation" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 60 }, { "field": "Data engineering", "percentage": 40 } ], "patterns": [] }, { "id": "ad86adb6-2274-4dcd-9277-1388401c7a98", "key": "PBATCH-104", "title": "Stream records without buffering the rest of the catalog", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 240, "phaseId": "stream", "dependsOn": [ "PBATCH-101", "PBATCH-102", "PBATCH-103" ], "scenario": "Switching to a streaming file reader did not reduce memory because validation still accumulates every parsed row before writing starts.", "acceptanceCriteria": [ "Connect reading, parsing, validation and writing through bounded buffers with downstream backpressure.", "Reject an oversized record explicitly without allowing unbounded parser accumulation.", "Preserve normalized accepted-record digest and rejection reasons from the baseline fixture." ], "implementationNotes": [ "Express buffer bounds in records and bytes where record sizes vary; a stream API alone does not establish bounded memory." ], "verification": [ "Pause the writer and assert parser progress stops within the declared buffering bound.", "Split quoted multibyte records across small input chunks and compare complete results with the reference fixture." ], "deliverables": [ "Streaming pipeline, buffer invariants and peak-memory comparison" ], "rollout": "Keep the whole-file implementation only as a small-fixture reference; stop and retain the source file if the streaming result digest differs.", "skills": [ "Streaming", "Backpressure" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Data engineering", "percentage": 50 } ], "patterns": [] }, { "id": "613477c9-a754-4375-ab8d-2f6e21052b62", "key": "PBATCH-105", "title": "Batch staging writes without changing duplicate-SKU behavior", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "stream", "dependsOn": [ "PBATCH-104" ], "scenario": "Single-row inserts dominate after streaming is introduced. A bulk-insert experiment is faster but resolves duplicate supplier SKUs differently.", "acceptanceCriteria": [ "Document duplicate-SKU ordering and preserve it across batch boundaries.", "Cap batch rows and serialized bytes, with bounded transaction duration.", "Return deterministic accepted/rejected outcomes when one batch includes invalid or conflicting records." ], "implementationNotes": [ "Compare at least three bounded batch sizes on the fixed fixture; do not choose the largest solely from one fast run." ], "verification": [ "Place duplicate SKUs on either side of a batch boundary and compare normalized results with the reference behavior.", "Inject a write failure midway through a batch and verify the declared atomicity and retry outcome." ], "deliverables": [ "Batched writer, batch-size measurements and duplicate regressions" ], "rollout": "Canary in staging with batch size configurable; reducing it must preserve semantics and allow work to continue from a valid checkpoint.", "skills": [ "Batching", "Transaction semantics" ], "fieldMix": [ { "field": "Database engineering", "percentage": 50 }, { "field": "Data engineering", "percentage": 30 }, { "field": "Performance engineering", "percentage": 20 } ], "patterns": [] }, { "id": "3faa0be0-16a5-4755-bc9f-5e4367b6807e", "key": "PBATCH-106", "title": "Stop validation workers from creating an unbounded reorder queue", "type": "BUG", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 330, "phaseId": "stream", "dependsOn": [ "PBATCH-103", "PBATCH-104", "PBATCH-105" ], "scenario": "Parallel validation improves throughput until one slow record delays output. Later completed records accumulate while the writer waits for order.", "acceptanceCriteria": [ "Define a bounded in-flight window and preserve required source ordering without retaining unlimited completed work.", "Propagate cancellation and fatal validation failure through every active stage.", "Select worker concurrency from repeated measurements that include serialization and coordination overhead." ], "implementationNotes": [ "If the measured validation stage is not CPU-bound, document that result and retain a simpler bounded path instead of adding workers without benefit." ], "verification": [ "Delay the first record while later records complete and assert both in-flight and retained-result bounds.", "Fail one worker during the import and verify controlled shutdown, deterministic checkpoint state and no silent record loss." ], "deliverables": [ "Concurrency decision, bounded ordering implementation and fault tests" ], "rollout": "Keep a single-worker configuration available; drain or cancel active work before changing concurrency during a rehearsal.", "skills": [ "Parallel processing", "Ordering", "Memory bounds" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Data engineering", "percentage": 50 } ], "patterns": [] }, { "id": "9256487d-229e-4393-89f2-30a7e0ac9c62", "key": "PBATCH-107", "title": "Report import progress from committed records instead of bytes read", "type": "BUG", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "operate", "dependsOn": [ "PBATCH-104", "PBATCH-105" ], "scenario": "The UI reaches 100% while thousands of records are still queued for the database. Operators assume they can close the import.", "acceptanceCriteria": [ "Expose bytes consumed, records accepted/rejected, committed records and terminal state as separate counters.", "Mark completion only after all accepted records are committed and final reconciliation succeeds.", "Avoid a remaining-time promise when throughput is unstable; report an unknown estimate explicitly." ], "implementationNotes": [ "Keep progress updates throttled and monotonic within one attempt; resumed attempts must disclose their checkpoint origin." ], "verification": [ "Pause the final write and verify the import remains nonterminal despite input exhaustion.", "Inject rejection and retry cases and reconcile counters with the final staging contents." ], "deliverables": [ "Progress contract and end-of-input regression" ], "rollout": "Introduce the progress fields before changing the UI completion rule; retain committed counters if the display is reverted.", "skills": [ "Progress reporting", "State modeling" ], "fieldMix": [ { "field": "API design", "percentage": 40 }, { "field": "Data engineering", "percentage": 40 }, { "field": "Frontend", "percentage": 20 } ], "patterns": [] }, { "id": "10743c54-223f-4a0f-a4ea-9ddd53e0c09a", "key": "PBATCH-108", "title": "Resume an interrupted catalog import from a committed checkpoint", "type": "STORY", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 360, "phaseId": "operate", "dependsOn": [ "PBATCH-104", "PBATCH-105", "PBATCH-107" ], "scenario": "An import loses its process after several committed batches. Restarting from a byte offset inside a quoted multiline record corrupts the next batch.", "acceptanceCriteria": [ "Bind checkpoints to source digest, parser configuration and import identity.", "Checkpoint only a valid record boundary whose writes are committed, with an explicit idempotency rule for uncertain completion.", "Reject a changed source or configuration and preserve the previous import for inspection." ], "implementationNotes": [ "A raw newline is not a CSV record boundary. State whether resumption seeks to a validated boundary or replays and skips already committed record identities." ], "verification": [ "Terminate after commit but before checkpoint acknowledgement, resume and compare the final digest with an uninterrupted import.", "Change one source byte and attempt resumption; no additional staging writes may occur." ], "deliverables": [ "Checkpoint protocol, resume implementation and interruption matrix" ], "rollout": "Enable resumption only after the failure matrix passes; retain the source and last valid checkpoint when recovery is refused.", "skills": [ "Checkpointing", "Idempotency" ], "fieldMix": [ { "field": "Data engineering", "percentage": 50 }, { "field": "Database engineering", "percentage": 30 }, { "field": "Distributed systems", "percentage": 20 } ], "patterns": [] }, { "id": "1d4eda25-2403-4a60-ae0c-401a49e647dc", "key": "PBATCH-109", "title": "Prove temporary import resources disappear after cancellation", "type": "CHORE", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "operate", "dependsOn": [ "PBATCH-104", "PBATCH-106", "PBATCH-108" ], "scenario": "Cancelled imports leave temporary files and open connections. A subsequent run inherits resource pressure and appears slower for an unrelated reason.", "acceptanceCriteria": [ "Define ownership and cleanup for temporary files, file descriptors, workers and database connections.", "Cancel safely at read, validation and commit stages while preserving the last valid recovery checkpoint.", "Make repeated cancellation safe and keep the source fixture intact." ], "implementationNotes": [ "Check resource inventories before and after; avoid asserting cleanup from a completion message alone." ], "verification": [ "Cancel at each controlled stage and verify owned resources return to the declared baseline.", "Run cancellation twice, then resume or start a fresh import and confirm correct results without restarting the environment." ], "deliverables": [ "Cleanup implementation, resource inventory and cancellation regressions" ], "rollout": "Run cleanup rehearsal before accepting performance results; quarantine uncertain staging state for explicit recovery rather than deleting it silently.", "skills": [ "Resource lifecycle", "Cancellation" ], "fieldMix": [ { "field": "Site reliability", "percentage": 40 }, { "field": "Data engineering", "percentage": 30 }, { "field": "Performance engineering", "percentage": 30 } ], "patterns": [] }, { "id": "bcf0fe31-b169-442d-a494-4a20848247ec", "key": "PBATCH-110", "title": "Set a throughput gate that also enforces import memory and correctness", "type": "CHORE", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "operate", "dependsOn": [ "PBATCH-105", "PBATCH-106", "PBATCH-108", "PBATCH-109" ], "scenario": "The fastest batch configuration exceeds the worker memory budget and fails on interrupted runs. Throughput alone is selecting the wrong candidate.", "acceptanceCriteria": [ "Run three paired baseline/candidate comparisons with the same source, database state and resource limits.", "Require completion within the 256 MiB process budget, exact normalized digest and at least 20% higher median committed-record throughput than a completing baseline.", "If the whole-file baseline cannot complete, report that fact and compare throughput against a documented completing bounded baseline; never calculate improvement from a killed run." ], "implementationNotes": [ "Include reset and warmup procedures, peaks, repetitions and recovery observations in the report; the budgets are local exercise conditions." ], "verification": [ "Run normal and slow-writer fixtures and publish all memory peaks and completion outcomes.", "Repeat the commit/checkpoint interruption case with the chosen batch and concurrency settings, then verify final digest and resource cleanup." ], "deliverables": [ "Performance gate, raw measurements and chosen operating configuration" ], "rollout": "Promote only the configuration satisfying every gate in the synthetic environment; restore the prior bounded configuration if memory or recovery regresses.", "skills": [ "Performance budgets", "Data integrity" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 50 }, { "field": "Data engineering", "percentage": 30 }, { "field": "Quality engineering", "percentage": 20 } ], "patterns": [] } ] } ] }