{ "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": "8e2589ff-c0f5-4704-8288-1dff41c049c8", "key": "BAPIBULK", "title": "Asynchronous bulk API contract", "field": "API design", "summary": "Design bulk record imports with explicit operation state, item errors, and recovery semantics.", "context": "A fictional catalog API needs to accept imports too large for one synchronous request. Partners need to distinguish accepted work, completed items, and recoverable failures.", "stack": [ "TypeScript", "OpenAPI", "PostgreSQL" ], "prerequisites": [ "Create a local API and worker double with synthetic catalog records and controlled interruption points." ], "developerValue": "Practice asynchronous resource contracts, partial outcomes, and idempotent operations.", "companyValue": "Provide predictable bulk integration behavior without ambiguous success or repeated effects.", "delivery": "Deliver local bulk endpoints, operation transitions, and public client examples.", "phases": [ { "id": "contract", "title": "Define operation resources", "goal": "Specify admission, identities, and lifecycle semantics." }, { "id": "process", "title": "Process bounded work", "goal": "Handle item outcomes, cancellation, and recovery." }, { "id": "client", "title": "Support clients", "goal": "Expose safe progress and lifecycle guidance." } ], "tickets": [ { "id": "fba83ad4-ac1d-490a-8e98-44314d90eb67", "key": "BAPIBULK-101", "title": "Define the difference between accepted and completed bulk work", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "contract", "dependsOn": [], "scenario": "The current endpoint returns success before any imported row has been validated.", "acceptanceCriteria": [ "Publish accepted, running, completed, and failed meanings.", "Define terminal partial-success representation.", "Keep transport acceptance separate from item validity." ], "implementationNotes": [ "Use explicit operation transition methods." ], "verification": [ "Represent an accepted unprocessed import.", "Show completed-with-errors without claiming every item succeeded." ], "deliverables": [ "Bulk operation schema." ], "rollout": "Review lifecycle vocabulary before adding endpoints.", "skills": [ "API modeling" ], "fieldMix": [ { "field": "API design", "percentage": 80 }, { "field": "Backend", "percentage": 20 } ], "patterns": [] }, { "id": "6df20f71-1f85-475e-9961-91b826121fe2", "key": "BAPIBULK-102", "title": "Bound bulk request size and record counts before admission", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "contract", "dependsOn": [ "BAPIBULK-101" ], "scenario": "A single import can exhaust parser memory before validation runs.", "acceptanceCriteria": [ "Enforce byte and item-count ceilings.", "Validate envelope schema before queueing work.", "Return structured errors without echoing the payload." ], "implementationNotes": [ "Use streamed or bounded parsing appropriate to the fixture." ], "verification": [ "Accept an import at the declared limit.", "Reject oversized and malformed requests before creating work." ], "deliverables": [ "Admission validator." ], "rollout": "Start with conservative limits and explicit client guidance.", "skills": [ "Resource bounds", "Validation" ], "fieldMix": [ { "field": "API design", "percentage": 40 }, { "field": "Security", "percentage": 30 }, { "field": "Performance engineering", "percentage": 30 } ], "patterns": [] }, { "id": "4c15e2d4-cf5e-421a-938d-a59ab8326202", "key": "BAPIBULK-103", "title": "Create bulk operations with tenant-scoped idempotency", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "contract", "dependsOn": [ "BAPIBULK-102" ], "scenario": "A timeout after admission causes the partner to submit the same catalog import again.", "acceptanceCriteria": [ "Bind key to tenant and canonical request digest.", "Return the existing operation on exact replay.", "Reject changed input under the same key." ], "implementationNotes": [ "Commit operation and dispatch intent atomically." ], "verification": [ "Replay a lost admission response.", "Race conflicting requests and preserve one operation identity." ], "deliverables": [ "Bulk admission command." ], "rollout": "Keep operation identity stable through retries.", "skills": [ "Idempotency", "Transactions" ], "fieldMix": [ { "field": "API design", "percentage": 40 }, { "field": "Database engineering", "percentage": 30 }, { "field": "Backend", "percentage": 30 } ], "patterns": [] }, { "id": "0223718a-bcd7-4976-9cc1-12de5720b3d1", "key": "BAPIBULK-104", "title": "Return per-item problems without exposing other tenant records", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "process", "dependsOn": [ "BAPIBULK-103" ], "scenario": "An item conflict response includes details about a catalog record owned by another tenant.", "acceptanceCriteria": [ "Authorize each item at the service boundary.", "Use stable item references and safe problem types.", "Avoid disclosing foreign record existence." ], "implementationNotes": [ "Item IDs supplied by clients are untrusted labels." ], "verification": [ "Import authorized updates and invalid items together.", "Attempt a cross-tenant item and verify safe denial." ], "deliverables": [ "Per-item outcome contract." ], "rollout": "Block imports with tenant-boundary regressions before expanding item types.", "skills": [ "Authorization", "Error design" ], "fieldMix": [ { "field": "Security", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "df3d070b-2848-4a7d-9a05-3233a7c8e34e", "key": "BAPIBULK-105", "title": "Checkpoint item progress without changing retry outcomes", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "process", "dependsOn": [ "BAPIBULK-104" ], "scenario": "A worker restart reapplies successful items and duplicates side effects.", "acceptanceCriteria": [ "Persist committed item outcomes with operation identity.", "Resume only incomplete items.", "Return the original result for exact processed-item replay." ], "implementationNotes": [ "Bound item batches and transaction duration." ], "verification": [ "Interrupt after a committed batch and resume.", "Retry a successful item and verify unchanged effects." ], "deliverables": [ "Resumable bulk processor." ], "rollout": "Retain checkpoints and immutable terminal item outcomes.", "skills": [ "Batch processing", "Idempotency" ], "fieldMix": [ { "field": "Data engineering", "percentage": 40 }, { "field": "Database engineering", "percentage": 30 }, { "field": "Distributed systems", "percentage": 30 } ], "patterns": [] }, { "id": "c587f1ed-4e7c-40fb-b375-1ca36a9cc536", "key": "BAPIBULK-106", "title": "Define cancellation after some items have committed", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "process", "dependsOn": [ "BAPIBULK-105" ], "scenario": "Clients assume cancelling an import undoes all previous item updates.", "acceptanceCriteria": [ "Document cancellation as stopping future work unless compensation exists.", "Preserve committed outcomes.", "Resolve cancellation-versus-completion races explicitly." ], "implementationNotes": [ "Do not silently roll back unrelated later changes." ], "verification": [ "Cancel after two items commit.", "Race cancellation with final completion and produce one terminal state." ], "deliverables": [ "Cancellation contract." ], "rollout": "Expose committed counts before accepting cancellation.", "skills": [ "State transitions", "API semantics" ], "fieldMix": [ { "field": "API design", "percentage": 60 }, { "field": "Distributed systems", "percentage": 40 } ], "patterns": [] }, { "id": "74c6ed43-3c83-4aea-8e98-39087d4550b0", "key": "BAPIBULK-107", "title": "Paginate bulk item outcomes with stable ordering", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "process", "dependsOn": [ "BAPIBULK-104", "BAPIBULK-105" ], "scenario": "Large result lists exceed response limits and change order while the client reads them.", "acceptanceCriteria": [ "Use stable operation-scoped ordering.", "Bound page sizes and cursor lifetime.", "Bind cursors to tenant, operation, and filter." ], "implementationNotes": [ "Do not place raw item payloads in cursors." ], "verification": [ "Read all outcomes without duplicates.", "Reject a cursor reused for another operation or tenant." ], "deliverables": [ "Outcome pagination endpoint." ], "rollout": "Keep terminal result pages immutable within retention.", "skills": [ "Pagination", "Authorization" ], "fieldMix": [ { "field": "API design", "percentage": 50 }, { "field": "Database engineering", "percentage": 30 }, { "field": "Security", "percentage": 20 } ], "patterns": [] }, { "id": "664e163e-e1f0-4c93-97eb-2ef910a8b2bb", "key": "BAPIBULK-108", "title": "Expose progress that does not imply unobserved completion", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "client", "dependsOn": [ "BAPIBULK-106", "BAPIBULK-107" ], "scenario": "The UI computes ninety-nine percent from queued jobs even when several items are unresolved.", "acceptanceCriteria": [ "Report accepted, committed, failed, and pending counts.", "Reconcile totals under declared semantics.", "Show unknown progress when observations are incomplete." ], "implementationNotes": [ "Avoid a fabricated precise completion estimate." ], "verification": [ "Display partial progress from known outcomes.", "Detect inconsistent counters and return an unavailable projection." ], "deliverables": [ "Safe progress projection." ], "rollout": "Use authoritative counters and stop polling on terminal states.", "skills": [ "API projections" ], "fieldMix": [ { "field": "API design", "percentage": 70 }, { "field": "Data engineering", "percentage": 30 } ], "patterns": [] }, { "id": "b261a0b0-97d5-498c-942a-1c99b06ba0a2", "key": "BAPIBULK-109", "title": "Choose atomic or partial bulk semantics for dependent items", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "client", "dependsOn": [ "BAPIBULK-104", "BAPIBULK-106", "BAPIBULK-108" ], "scenario": "Some imports contain parent and child catalog records, making arbitrary independent item processing unsafe.", "acceptanceCriteria": [ "Define the supported dependency boundary.", "Compare whole-request atomicity, ordered groups, and independent items.", "Document transaction, recovery, and client complexity tradeoffs." ], "implementationNotes": [ "Bound the decision to the synthetic catalog use case." ], "verification": [ "Import a valid parent-child group.", "Reject or explicitly report a missing-parent group under the chosen semantics." ], "deliverables": [ "Bulk semantics decision record." ], "rollout": "Start with the smallest supported grouping and reject unsupported dependency patterns.", "skills": [ "API architecture", "Tradeoffs" ], "fieldMix": [ { "field": "System design", "percentage": 40 }, { "field": "API design", "percentage": 40 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "0156b062-92c8-455f-aed0-ca3299954881", "key": "BAPIBULK-110", "title": "Publish a bulk client example covering timeout and partial failure", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "client", "dependsOn": [ "BAPIBULK-109" ], "scenario": "Partners have only a happy-path example that treats HTTP acceptance as completion.", "acceptanceCriteria": [ "Show admission retry with one idempotency key.", "Poll to a terminal operation state.", "Inspect item errors and retained committed results." ], "implementationNotes": [ "Use local mock data and no credentials." ], "verification": [ "Run a successful example.", "Run timeout, partial failure, and cancellation examples without duplicate submissions." ], "deliverables": [ "Executable bulk client guide." ], "rollout": "Version the example with the operation contract.", "skills": [ "SDK design", "Documentation" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 50 }, { "field": "API design", "percentage": 50 } ], "patterns": [] } ] } ] }