{ "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": "e42dbb82-ade1-4b1e-8443-5429a93229b3", "key": "BRAG", "title": "Grounded support-document assistant", "field": "Applied AI", "summary": "Build a retrieval assistant whose answers respect source versions, access, and uncertainty.", "context": "A fictional internal support team needs answers from product guides. Some guides are outdated or restricted, and fluent unsupported answers would create operational mistakes.", "stack": [ "TypeScript", "PostgreSQL", "AiEvaluationProvider" ], "prerequisites": [ "Author a synthetic document collection with two tenants, conflicting versions, and a deterministic model double; no model account required." ], "developerValue": "Practice retrieval boundaries, citation validation, and deterministic evaluation.", "companyValue": "Create a reviewable assistant prototype with clear refusal, cost, and freshness behavior.", "delivery": "Deliver a local assistant using provider interfaces and scripted outputs; live model quality remains unmeasured.", "phases": [ { "id": "sources", "title": "Control sources", "goal": "Version documents and enforce retrieval scope." }, { "id": "answers", "title": "Constrain answers", "goal": "Validate citations, contradictions, and provider failures." }, { "id": "evaluate", "title": "Evaluate limits", "goal": "Measure scoped behavior without overstating model quality." } ], "tickets": [ { "id": "eda85d88-070e-4d1a-9db0-52f4cdff1baa", "key": "BRAG-101", "title": "Define versioned source records for the support collection", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "sources", "dependsOn": [], "scenario": "Two guides share a title but describe different product releases.", "acceptanceCriteria": [ "Assign immutable source-version identities.", "Record product version, scope, and supersession separately.", "Preserve old content when a revision is added." ], "implementationNotes": [ "Use synthetic document IDs, not fabricated Evidence IDs." ], "verification": [ "Retrieve both historical versions explicitly.", "Reject an attempt to overwrite a sealed source version." ], "deliverables": [ "Source metadata schema." ], "rollout": "Import a small synthetic collection first; append corrections instead of editing history.", "skills": [ "Data modeling" ], "fieldMix": [ { "field": "Data engineering", "percentage": 60 }, { "field": "Database engineering", "percentage": 40 } ], "patterns": [] }, { "id": "b30c1a82-7a6b-4a89-af3e-b133833fe455", "key": "BRAG-102", "title": "Apply tenant and document grants before retrieval ranking", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "sources", "dependsOn": [ "BRAG-101" ], "scenario": "A highly relevant private guide appears in another tenant's search results.", "acceptanceCriteria": [ "Scope candidate sources before scoring.", "Recheck grants before returning retrieved text.", "Ensure denied sources do not influence snippets or counts." ], "implementationNotes": [ "Authorization belongs in the retrieval service boundary." ], "verification": [ "Retrieve an authorized guide.", "Query an identical restricted guide from another tenant and verify no disclosure." ], "deliverables": [ "Scoped retriever." ], "rollout": "Fail closed on unknown grants; disable assistant responses if retrieval authorization fails.", "skills": [ "Authorization", "Retrieval" ], "fieldMix": [ { "field": "Security", "percentage": 60 }, { "field": "Applied AI", "percentage": 40 } ], "patterns": [] }, { "id": "9edd1497-7608-4e4f-a532-7ccdbe20dd6f", "key": "BRAG-103", "title": "Preserve source offsets when splitting documentation", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "sources", "dependsOn": [ "BRAG-101" ], "scenario": "Answer citations point to chunks that cannot be located in the original guide.", "acceptanceCriteria": [ "Retain source version and character ranges for each chunk.", "Keep headings with their relevant text within configured limits.", "Reject chunks whose ranges exceed the source." ], "implementationNotes": [ "Choose deterministic splitting; do not fabricate missing text." ], "verification": [ "Reconstruct cited text from saved offsets.", "Detect altered source content and invalid ranges." ], "deliverables": [ "Chunking pipeline." ], "rollout": "Rebuild indexes under a new version; retain the previous complete index for recovery.", "skills": [ "Text processing", "Provenance" ], "fieldMix": [ { "field": "Data engineering", "percentage": 60 }, { "field": "Applied AI", "percentage": 40 } ], "patterns": [] }, { "id": "ea322a0a-6f46-42fd-94b6-10590661a5b1", "key": "BRAG-104", "title": "Require structured answer output with verifiable citations", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "answers", "dependsOn": [ "BRAG-102", "BRAG-103" ], "scenario": "The model double returns a plausible answer with a nonexistent citation.", "acceptanceCriteria": [ "Validate the output schema and byte limit.", "Resolve every citation against authorized retrieved source versions.", "Reject unsupported citation identities rather than repairing them silently." ], "implementationNotes": [ "Access model behavior only through AiEvaluationProvider." ], "verification": [ "Accept a supported answer with valid ranges.", "Reject malformed output, nonexistent sources, and cross-tenant citations." ], "deliverables": [ "Answer validator." ], "rollout": "Keep invalid responses in a safe unavailable state; retain only sanitized failure metadata.", "skills": [ "Schema validation", "Grounding" ], "fieldMix": [ { "field": "Applied AI", "percentage": 70 }, { "field": "Security", "percentage": 30 } ], "patterns": [] }, { "id": "10b8a2cc-0242-4370-a8d5-b7def4fc406b", "key": "BRAG-105", "title": "Expose conflicting guide versions instead of choosing silently", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "answers", "dependsOn": [ "BRAG-104" ], "scenario": "Two authorized sources disagree about the retention setting and neither is marked superseded.", "acceptanceCriteria": [ "Represent the contradiction with both source references.", "Avoid presenting either value as settled.", "Ask for product-version context or return an explicit unresolved answer." ], "implementationNotes": [ "Do not infer authority from retrieval score alone." ], "verification": [ "Resolve a clearly superseded guide correctly.", "Keep equally current contradictory guides visibly unresolved." ], "deliverables": [ "Contradiction response behavior." ], "rollout": "Enable with conflict fixtures first; route unresolved advice to a support review workflow.", "skills": [ "Uncertainty handling", "Information retrieval" ], "fieldMix": [ { "field": "Applied AI", "percentage": 100 } ], "patterns": [] }, { "id": "b25784ec-75ba-4415-9257-cbd38089dfc6", "key": "BRAG-106", "title": "Treat instructions inside retrieved guides as untrusted content", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "answers", "dependsOn": [ "BRAG-104" ], "scenario": "A guide includes text telling the assistant to reveal other documents.", "acceptanceCriteria": [ "Keep retrieved text outside system instruction authority.", "Disallow tool calls or new retrieval scopes from document text.", "Reject answers citing content outside the authorized retrieval set." ], "implementationNotes": [ "Use bounded prompt-injection fixtures without real secrets." ], "verification": [ "Answer a benign guide question.", "Inject scope-changing instructions and verify access remains unchanged." ], "deliverables": [ "Adversarial retrieval checks." ], "rollout": "Block deployment if the boundary fails; keep source ingestion separate from execution authority.", "skills": [ "Prompt injection", "Trust boundaries" ], "fieldMix": [ { "field": "Applied AI", "percentage": 50 }, { "field": "Security", "percentage": 50 } ], "patterns": [] }, { "id": "29bb311e-c044-4a04-b23c-9bc1ae5a7223", "key": "BRAG-107", "title": "Bound assistant time and token reservations per request", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "answers", "dependsOn": [ "BRAG-104" ], "scenario": "Repeated retries can exceed the budget for a single support question.", "acceptanceCriteria": [ "Reserve a configured maximum budget before provider calls.", "Bound retries and total elapsed time.", "Release unused reservation after terminal completion." ], "implementationNotes": [ "Record provider, model, schema, timeout, cost, version, and trace metadata safely." ], "verification": [ "Complete a request within the reservation.", "Simulate timeout and ignored cancellation without unbounded retries." ], "deliverables": [ "Request budget controller." ], "rollout": "Default to deterministic provider mode; fail closed when reservation cannot be obtained.", "skills": [ "Cost controls", "Provider design" ], "fieldMix": [ { "field": "Applied AI", "percentage": 70 }, { "field": "Backend", "percentage": 30 } ], "patterns": [] }, { "id": "e0fa89eb-404e-4d8d-8027-085bcc7c1bbd", "key": "BRAG-108", "title": "Evaluate grounded answering separately from retrieval quality", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 360, "phaseId": "evaluate", "dependsOn": [ "BRAG-105", "BRAG-106", "BRAG-107" ], "scenario": "A single answer score hides whether failures came from missing documents or unsupported generation.", "acceptanceCriteria": [ "Create separate retrieval and citation-validity checks.", "Include answerable, absent, conflicting, and denied questions.", "Report deterministic-double results separately from unmeasured live-model behavior." ], "implementationNotes": [ "Use public synthetic expectations; do not embed hidden evaluator answers in product APIs." ], "verification": [ "Detect a missing retrieval result.", "Detect a fluent answer unsupported by retrieved text." ], "deliverables": [ "Evaluation report with failure categories." ], "rollout": "Require both boundaries before expanding the corpus; retain an explicit unmeasured label for live quality.", "skills": [ "Evaluation design", "Retrieval" ], "fieldMix": [ { "field": "Applied AI", "percentage": 60 }, { "field": "Quality engineering", "percentage": 40 } ], "patterns": [] }, { "id": "6ffea113-afb8-4065-9808-e44ae141b38d", "key": "BRAG-109", "title": "Prevent stale indexes from serving revoked source access", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "evaluate", "dependsOn": [ "BRAG-102", "BRAG-108" ], "scenario": "A document grant is revoked after its chunks have been cached.", "acceptanceCriteria": [ "Recheck current access on cached retrieval results.", "Evict or suppress revoked entries without serving stale text.", "Keep cache keys scoped to tenant and index version." ], "implementationNotes": [ "Cache entries cannot become access grants." ], "verification": [ "Serve an unchanged authorized cache entry.", "Revoke access and deny the next response even before cache expiry." ], "deliverables": [ "Revocation regression." ], "rollout": "Prioritize denial over cache availability; clear affected caches during recovery.", "skills": [ "Caching", "Authorization" ], "fieldMix": [ { "field": "Security", "percentage": 50 }, { "field": "Applied AI", "percentage": 30 }, { "field": "Distributed systems", "percentage": 20 } ], "patterns": [] }, { "id": "489c40f9-432d-4991-b95a-be235644c0fd", "key": "BRAG-110", "title": "Document the assistant's supported questions and limits", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "evaluate", "dependsOn": [ "BRAG-108", "BRAG-109" ], "scenario": "A prototype can sound ready for unrestricted customer support despite its small synthetic corpus.", "acceptanceCriteria": [ "List supported corpus and product versions.", "Explain unavailable and conflicting-source responses.", "State that deterministic validation does not measure live-model answer quality." ], "implementationNotes": [ "Avoid capability claims beyond observed local checks." ], "verification": [ "Follow one supported question to its source.", "Verify unsupported questions receive the documented response." ], "deliverables": [ "Operator and user-facing capability note." ], "rollout": "Ship the note with the prototype; revise it whenever corpus or provider behavior changes.", "skills": [ "Documentation", "AI product design" ], "fieldMix": [ { "field": "Applied AI", "percentage": 100 } ], "patterns": [] } ] } ] }