{ "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": "2f93285f-6c1b-42ea-893f-ed7e6afc7778", "key": "BBILL", "title": "Payment-provider reconciliation adapter", "field": "Integrations", "summary": "Reconcile local order state with a simulated provider under duplicate and delayed delivery.", "context": "A fictional software vendor changes payment providers. Its application must tolerate unknown outcomes, signed callbacks, refunds, and inconsistent settlement reports.", "stack": [ "TypeScript", "PostgreSQL", "HTTP" ], "prerequisites": [ "Create a local payment-provider double and synthetic orders; use test-only signatures and execute no financial transactions." ], "developerValue": "Practice idempotent integrations, state reconciliation, and provider migration.", "companyValue": "Provide a reviewable adapter design that protects order consistency and recovery.", "delivery": "Deliver local provider contracts and reconciliation rehearsals; no live money or provider accounts.", "phases": [ { "id": "contract", "title": "Define provider semantics", "goal": "Model identities and state transitions." }, { "id": "connect", "title": "Handle asynchronous results", "goal": "Process callbacks and unknown outcomes safely." }, { "id": "reconcile", "title": "Recover discrepancies", "goal": "Reconcile records and rehearse migration." } ], "tickets": [ { "id": "91bd95c9-0297-4942-9673-fcbeae63477c", "key": "BBILL-101", "title": "Map provider payment states to explicit order transitions", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "contract", "dependsOn": [], "scenario": "Two provider status names are currently treated as equivalent even though only one confirms collection.", "acceptanceCriteria": [ "List provider states and allowed transitions.", "Represent pending and unknown separately.", "Reject impossible terminal reversals." ], "implementationNotes": [ "Keep provider status distinct from local order status." ], "verification": [ "Map successful and pending examples.", "Reject an unsupported state without marking an order paid." ], "deliverables": [ "State mapping contract." ], "rollout": "Review mapping before accepting callbacks.", "skills": [ "State modeling" ], "fieldMix": [ { "field": "Integrations", "percentage": 60 }, { "field": "Backend", "percentage": 40 } ], "patterns": [] }, { "id": "1270b2a7-898f-49ea-9704-338710dde496", "key": "BBILL-102", "title": "Bind payment creation retries to one local operation", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "contract", "dependsOn": [ "BBILL-101" ], "scenario": "A timeout prompts the application to create a second payment.", "acceptanceCriteria": [ "Persist operation identity before dispatch.", "Reuse identity for identical retries.", "Reject conflicting payload reuse." ], "implementationNotes": [ "Synthetic amounts use integer minor units." ], "verification": [ "Retry a timed-out accepted request.", "Reuse a key with another amount and verify rejection." ], "deliverables": [ "Idempotent payment command." ], "rollout": "Keep uncertain operations pending for reconciliation.", "skills": [ "Idempotency", "Transactions" ], "fieldMix": [ { "field": "Backend", "percentage": 50 }, { "field": "Integrations", "percentage": 30 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "8bd5242d-5c0f-459d-a014-5ce8dac7b167", "key": "BBILL-103", "title": "Verify callback signatures before trusting event fields", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "connect", "dependsOn": [ "BBILL-101" ], "scenario": "The adapter currently reads order IDs before validating callbacks.", "acceptanceCriteria": [ "Verify raw bytes with the configured test key.", "Enforce timestamp tolerance and key identity.", "Reject malformed or unsigned bodies before processing." ], "implementationNotes": [ "Never log signing secrets or full callback bodies." ], "verification": [ "Accept a valid signed fixture.", "Reject modified bytes and an expired timestamp." ], "deliverables": [ "Callback verification boundary." ], "rollout": "Reject unverifiable callbacks; retain safe failure counts.", "skills": [ "Webhook security" ], "fieldMix": [ { "field": "Security", "percentage": 70 }, { "field": "Integrations", "percentage": 30 } ], "patterns": [] }, { "id": "9e44b045-4470-4f50-82a3-66aa3d7dd3f1", "key": "BBILL-104", "title": "Apply duplicate and out-of-order payment callbacks idempotently", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "connect", "dependsOn": [ "BBILL-102", "BBILL-103" ], "scenario": "A delayed pending callback overwrites an already-confirmed payment.", "acceptanceCriteria": [ "Deduplicate provider event identity.", "Apply only allowed state transitions.", "Record ignored stale events for diagnosis." ], "implementationNotes": [ "Commit state and processed-event record atomically." ], "verification": [ "Replay a successful callback twice.", "Deliver pending after confirmed and preserve confirmation." ], "deliverables": [ "Callback transition handler." ], "rollout": "Adopt per synthetic merchant; pause on unresolved transition conflicts.", "skills": [ "Transactions", "Event ordering" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Distributed systems", "percentage": 40 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "f7d999cd-38e7-4637-a565-cec7346a2d67", "key": "BBILL-105", "title": "Reconcile unknown creation outcomes by operation identity", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "connect", "dependsOn": [ "BBILL-102", "BBILL-104" ], "scenario": "The provider accepted creation but the application lost the response.", "acceptanceCriteria": [ "Query the provider using the original operation identity.", "Adopt the matching remote payment once.", "Keep missing or mismatched results unresolved." ], "implementationNotes": [ "Bound query retries and elapsed reconciliation time." ], "verification": [ "Recover a matching accepted payment.", "Reject a remote result with different amount or currency." ], "deliverables": [ "Unknown-outcome reconciler." ], "rollout": "Stop new attempts for unresolved operations; retry reconciliation explicitly.", "skills": [ "Reconciliation" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Distributed systems", "percentage": 50 } ], "patterns": [] }, { "id": "7bcc58ca-b5bd-4a04-9952-22bd15accf25", "key": "BBILL-106", "title": "Represent partial refunds without rewriting original payment facts", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "connect", "dependsOn": [ "BBILL-104" ], "scenario": "A partial refund currently changes the original collected amount.", "acceptanceCriteria": [ "Append refund operations separately.", "Limit cumulative confirmed refunds to the collected amount.", "Distinguish requested, pending, and confirmed refund totals." ], "implementationNotes": [ "Run against the local double only." ], "verification": [ "Confirm two valid partial refunds.", "Race excess refunds and verify the invariant holds." ], "deliverables": [ "Refund state model." ], "rollout": "Enable after payment reconciliation; retain failed requests for investigation.", "skills": [ "Ledger modeling", "Concurrency" ], "fieldMix": [ { "field": "Database engineering", "percentage": 50 }, { "field": "Backend", "percentage": 30 }, { "field": "Integrations", "percentage": 20 } ], "patterns": [] }, { "id": "af1713a9-0d11-4ff5-8bf4-95379c5fb315", "key": "BBILL-107", "title": "Import settlement rows with source-file provenance", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "reconcile", "dependsOn": [ "BBILL-105", "BBILL-106" ], "scenario": "Repeated report uploads create duplicate reconciliation entries.", "acceptanceCriteria": [ "Bind imports to file digest and provider report identity.", "Deduplicate exact rows without losing source references.", "Reject conflicting duplicate settlement identities." ], "implementationNotes": [ "Use synthetic CSV and sanitize spreadsheet formula prefixes in exports." ], "verification": [ "Import the same report twice.", "Detect a changed amount under an existing settlement identity." ], "deliverables": [ "Settlement import pipeline." ], "rollout": "Stage reports before matching; preserve original synthetic report digests.", "skills": [ "Data ingestion", "Provenance" ], "fieldMix": [ { "field": "Data engineering", "percentage": 60 }, { "field": "Integrations", "percentage": 40 } ], "patterns": [] }, { "id": "3bdcf04e-19e3-4dc6-883c-dabbbdf4e22a", "key": "BBILL-108", "title": "Explain settlement discrepancies without automatic repair", "type": "STORY", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "reconcile", "dependsOn": [ "BBILL-107" ], "scenario": "Finance staff see only a mismatch count and cannot identify its cause.", "acceptanceCriteria": [ "Classify missing, amount, currency, and timing mismatches.", "Link each discrepancy to local and provider identities.", "Keep disputed records unchanged." ], "implementationNotes": [ "Do not infer fraud or automatically move funds." ], "verification": [ "Explain a timing difference and an amount mismatch.", "Verify unknown discrepancies remain unresolved." ], "deliverables": [ "Discrepancy report." ], "rollout": "Use reports for reviewed repair; keep reconciliation read-only by default.", "skills": [ "Diagnostics", "Reconciliation" ], "fieldMix": [ { "field": "Integrations", "percentage": 60 }, { "field": "Data engineering", "percentage": 40 } ], "patterns": [] }, { "id": "786f6a47-ed53-49ba-9084-48c574c69592", "key": "BBILL-109", "title": "Design a provider cutover with in-flight payment ownership", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 360, "phaseId": "reconcile", "dependsOn": [ "BBILL-105", "BBILL-108" ], "scenario": "Switching all traffic at once would send old payment lookups to the new provider.", "acceptanceCriteria": [ "Pin each operation to its original provider.", "Define new-operation routing and rollback conditions.", "Rehearse callbacks and refunds crossing the cutover boundary." ], "implementationNotes": [ "Compare adapter complexity and reconciliation burden explicitly." ], "verification": [ "Complete an old-provider payment after cutover.", "Roll back new routing without reassigning existing operations." ], "deliverables": [ "Cutover decision record and rehearsal." ], "rollout": "Change only new-operation routing; retain both adapters until old obligations finish.", "skills": [ "Migration design", "Distributed consistency" ], "fieldMix": [ { "field": "System design", "percentage": 50 }, { "field": "Integrations", "percentage": 30 }, { "field": "Distributed systems", "percentage": 20 } ], "patterns": [] }, { "id": "048d8f1b-3f1c-411d-890c-5a7241bfc64a", "key": "BBILL-110", "title": "Document a safe manual replay of a rejected callback", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "reconcile", "dependsOn": [ "BBILL-109" ], "scenario": "Support needs to retry a corrected callback without bypassing verification.", "acceptanceCriteria": [ "Require original event identity and verified source.", "Use the normal validation and idempotency path.", "Record replay operator and reason." ], "implementationNotes": [ "No direct database status edits." ], "verification": [ "Replay a previously failed valid event.", "Reject a replay with altered signed content." ], "deliverables": [ "Callback replay runbook." ], "rollout": "Keep replay scoped and audited; stop on conflicting operation facts.", "skills": [ "Runbooks", "Auditability" ], "fieldMix": [ { "field": "Site reliability", "percentage": 40 }, { "field": "Integrations", "percentage": 40 }, { "field": "Security", "percentage": 20 } ], "patterns": [] } ] } ] }