{ "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": "47651627-f5f1-48b0-8215-e51588fd2312", "key": "READ", "title": "A document reader that keeps people oriented", "field": "Accessibility", "summary": "Improve navigation, text adaptation, annotations, and revision recovery in an internal document reader.", "context": "The fictional Plainview handbook reader serves versioned HTML documents with headings, tables, footnotes, and annotations. Scope is accessible HTML rendering from a structured model; OCR and arbitrary PDF remediation are excluded.", "stack": [ "React", "TypeScript", "CSS Modules", "Testing Library", "Playwright" ], "prerequisites": [ "Versioned synthetic documents with stable section IDs", "Annotation and document-access API contracts to stub" ], "developerValue": "Practice semantic structure, accessible navigation, safe annotations, and stable reading positions.", "companyValue": "Inspect how an engineer makes information usable while protecting document integrity and access boundaries.", "delivery": "Each ticket targets one reader behavior. Use synthetic documents and record assumptions about the source model.", "phases": [ { "id": "structure", "title": "Make content readable", "goal": "Preserve semantics and text preferences." }, { "id": "navigation", "title": "Keep the reader oriented", "goal": "Make search, contents, and bookmarks predictable." }, { "id": "interaction", "title": "Support richer reading", "goal": "Add annotations and long-document loading without breaking reading flow." }, { "id": "release", "title": "Verify access and recovery", "goal": "Check interruptions and document the release boundary." } ], "tickets": [ { "id": "38422679-6c18-4541-9253-4ce2dcc57ada", "key": "READ-101", "title": "Restore heading and table semantics in handbook chapters", "type": "BUG", "priority": "HIGH", "difficulty": "FOUNDATIONAL", "estimateMinutes": 75, "phaseId": "structure", "dependsOn": [], "scenario": "Every source block becomes a styled div. Readers cannot navigate by heading, and table cells expose no header relationships.", "acceptanceCriteria": [ "Headings preserve validated source hierarchy in semantic elements.", "Tables retain captions and source-model header associations.", "Unsupported blocks show a clear fallback rather than silently disappearing." ], "implementationNotes": [ "Validate the structured model; this ticket does not infer semantics from arbitrary visual formatting." ], "verification": [ "Navigate by headings and inspect a table with row and column headers.", "Supply an unsupported block and invalid hierarchy; content is not silently lost and validation identifies the issue." ], "deliverables": [ "Semantic block renderer and document-model fixtures" ], "rollout": "Enable for validated documents; retain the accessible source view when model validation fails.", "skills": [ "Semantic HTML", "Document models", "Accessibility" ], "fieldMix": [ { "field": "Accessibility", "percentage": 60 }, { "field": "Frontend", "percentage": 40 } ], "patterns": [] }, { "id": "e7fe2ef0-8ce0-41ac-92f7-1d9e92633a23", "key": "READ-102", "title": "Let readers adjust text without losing their place", "type": "STORY", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "structure", "dependsOn": [ "READ-101" ], "scenario": "Increasing font size resets the chapter to the top, while dark theme leaves footnotes unreadable. Add preferences that preserve position and cover every content type.", "acceptanceCriteria": [ "Font size, spacing, and theme apply to body, footnotes, tables, and annotations.", "Preference changes preserve the current section anchor.", "System theme is the initial default and invalid stored preferences recover safely." ], "implementationNotes": [ "Use semantic CSS variables and avoid fixed content heights." ], "verification": [ "Resize text midway through a chapter; the current section stays in view.", "Load corrupt preference data and test dark/system themes; content stays readable and defaults recover." ], "deliverables": [ "Reader preferences and theme/content fixture page" ], "rollout": "Release session-local preferences first; disable persistence if stored values break rendering.", "skills": [ "CSS variables", "User preferences", "Reading UX" ], "fieldMix": [ { "field": "Accessibility", "percentage": 50 }, { "field": "Frontend", "percentage": 50 } ], "patterns": [] }, { "id": "cbd3afdf-10c4-4b0b-bb96-5dcd7485b466", "key": "READ-103", "title": "Navigate search matches without breaking document text", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "navigation", "dependsOn": [ "READ-101" ], "scenario": "Highlighting rewrites innerHTML and removes links around matches. Keyboard users also cannot identify the current match.", "acceptanceCriteria": [ "Highlights preserve source text, links, and semantics.", "Next/previous exposes index and total without rereading the chapter.", "Clearing search restores normal reading at a sensible position." ], "implementationNotes": [ "Treat queries as literal text and use structured ranges; never interpolate search text into HTML." ], "verification": [ "Find a phrase spanning emphasis and follow the preserved link around a match.", "Search markup-like text and a no-match query; nothing executes and match navigation is correctly disabled." ], "deliverables": [ "Structured highlight layer and keyboard match-navigation tests" ], "rollout": "Enable for one renderer; disable highlighting separately while retaining plain results if semantics regress.", "skills": [ "Text ranges", "Keyboard navigation", "Safe rendering" ], "fieldMix": [ { "field": "Frontend", "percentage": 50 }, { "field": "Accessibility", "percentage": 30 }, { "field": "Security", "percentage": 20 } ], "patterns": [] }, { "id": "9a9a178b-edc4-4512-b3f9-ca8997a9059d", "key": "READ-104", "title": "Keep contents links and footnote returns oriented", "type": "BUG", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 105, "phaseId": "navigation", "dependsOn": [ "READ-101", "READ-102" ], "scenario": "Contents links scroll to sections but leave focus in the sidebar. Following a footnote returns to the document top.", "acceptanceCriteria": [ "Contents navigation updates the URL and focuses the destination heading without obscuring it.", "Footnotes offer a named return action to the originating reference.", "Back restores the preceding meaningful reading anchor." ], "implementationNotes": [ "Use stable source IDs and respect reduced motion for scrolling." ], "verification": [ "Navigate by contents, follow a footnote, and return using only the keyboard.", "Open a missing section link and use Back; show a useful fallback without trapping focus." ], "deliverables": [ "Anchor/focus coordinator and footnote walkthrough" ], "rollout": "Ship stable anchors before custom scrolling; disable scroll effects if focus and visual position diverge.", "skills": [ "Focus management", "Deep links", "Navigation" ], "fieldMix": [ { "field": "Accessibility", "percentage": 60 }, { "field": "Frontend", "percentage": 40 } ], "patterns": [] }, { "id": "33ee0c51-b7fb-40ee-a5a7-9493b10b8af7", "key": "READ-105", "title": "Recover bookmarks after a handbook correction", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "navigation", "dependsOn": [ "READ-103", "READ-104" ], "scenario": "A correction inserts two sections before a bookmark. Its raw character offset now opens an unrelated paragraph.", "acceptanceCriteria": [ "Bookmarks include version, stable section, and optional bounded text anchor.", "A newer version resolves the section or explicitly reports that the passage moved or disappeared.", "The permitted original version remains reachable without silently rewriting the bookmark." ], "implementationNotes": [ "Approximate text matching is not exact; disclose ambiguity and retain the original anchor." ], "verification": [ "Insert content before a stable section and reopen its bookmark; the intended section remains selected.", "Delete it and create two similar passages; show ambiguous recovery rather than silently choosing one." ], "deliverables": [ "Version-aware bookmark resolver and correction fixtures" ], "rollout": "Keep legacy bookmarks readable during migration; fall back to the permitted original version on uncertain resolution.", "skills": [ "Versioning", "Stable identity", "Recovery UX" ], "fieldMix": [ { "field": "Frontend", "percentage": 70 }, { "field": "Accessibility", "percentage": 30 } ], "patterns": [] }, { "id": "b61054ab-7157-466f-8ef1-2e1033a501c1", "key": "READ-106", "title": "Render annotations safely and expose their controls", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 135, "phaseId": "interaction", "dependsOn": [ "READ-103", "READ-104" ], "scenario": "Pasted annotation markup changes layout and introduces active links. Annotation actions are unnamed icons visible only on hover.", "acceptanceCriteria": [ "Annotations use plain text or an explicit constrained format that removes disallowed content.", "Edit, delete, and return-to-passage actions have accessible names and work without hover.", "Failed saves preserve a draft distinct from confirmed comments." ], "implementationNotes": [ "Keep document source immutable and treat annotation content as untrusted." ], "verification": [ "Create a normal annotation and navigate every action by keyboard.", "Paste script-like markup and a dangerous link, then reject save; no active content runs and the unsaved draft stays explicit." ], "deliverables": [ "Safe annotation renderer and keyboard/security regression cases" ], "rollout": "Enable plain text first; disable rich formatting on sanitization regression while preserving stored source text.", "skills": [ "Untrusted content", "Accessible controls", "Draft state" ], "fieldMix": [ { "field": "Security", "percentage": 40 }, { "field": "Accessibility", "percentage": 30 }, { "field": "Frontend", "percentage": 30 } ], "patterns": [] }, { "id": "5488dadd-410d-4c4d-8152-01f25cb4b44c", "key": "READ-107", "title": "Load long handbooks without losing reading order", "type": "TASK", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "interaction", "dependsOn": [ "READ-102", "READ-104" ], "scenario": "A 200-section handbook blocks interaction, but a virtual-list prototype removes headings while a screen reader navigates them.", "acceptanceCriteria": [ "Initial work is bounded through explicit section loading or an equally accessible documented strategy.", "Loaded sections stay in logical order and focused content is never removed.", "Section-load failure offers in-place retry without resetting the reading anchor." ], "implementationNotes": [ "Profile a reproducible fixture and state the environment; do not optimize by hiding required accessible content." ], "verification": [ "Profile initial load and navigate three loaded sections by keyboard and headings.", "Fail the next request while focus stays in the current section; retry without duplicates, reordered headings, or focus loss." ], "deliverables": [ "Incremental loading and before/after profile with reading-order checks" ], "rollout": "Enable for large documents; keep a full-document option when incremental reading is unsuitable.", "skills": [ "Performance", "Progressive loading", "Accessibility" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 40 }, { "field": "Accessibility", "percentage": 40 }, { "field": "Frontend", "percentage": 20 } ], "patterns": [] }, { "id": "5ec505e0-f2f6-4947-a32a-cb950e8cbe7c", "key": "READ-108", "title": "Keep annotation review stable through collaborator updates", "type": "STORY", "priority": "MEDIUM", "difficulty": "EXPERT", "estimateMinutes": 210, "phaseId": "interaction", "dependsOn": [ "READ-105", "READ-106", "READ-107" ], "scenario": "A colleague resolves a comment while another reader edits a reply. The panel reorders, steals focus, and sends the reply to the newly selected thread.", "acceptanceCriteria": [ "Editing binds to immutable thread identity and revision, not list position.", "Remote updates never silently retarget a draft or move current focus.", "Resolved/deleted-thread conflicts preserve the draft, announce once, and offer explicit permitted recovery." ], "implementationNotes": [ "Use fixture events; a full collaboration backend and automatic merging are excluded." ], "verification": [ "Insert a remote comment above the active thread while typing; the draft keeps its original thread.", "Resolve the active thread during reply acknowledgement; no reply lands elsewhere and the confirmed state stays coherent." ], "deliverables": [ "Revision-aware annotation model and concurrent-update tests" ], "rollout": "Pilot manual refresh before live events; pause remote panel updates if focus or binding becomes unstable.", "skills": [ "Concurrent UI", "Focus ownership", "Conflict recovery" ], "fieldMix": [ { "field": "Frontend", "percentage": 50 }, { "field": "Accessibility", "percentage": 30 }, { "field": "Real-time systems", "percentage": 20 } ], "patterns": [] }, { "id": "bcf45869-b625-4fb8-ad86-acd10b685264", "key": "READ-109", "title": "Handle access loss without an empty-reader trap", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 135, "phaseId": "release", "dependsOn": [ "READ-107", "READ-108" ], "scenario": "Access expires while a reader is on a late section. The next fetch clears the page and leaves focus on a removed annotation button.", "acceptanceCriteria": [ "Confirmed access loss stops fetches and clears protected rendered content.", "Focus moves to a named access-state heading with permitted navigation.", "Account changes cannot restore prior content through cached sections or Back." ], "implementationNotes": [ "Omit private authorization details and document account-scoped draft handling on access loss." ], "verification": [ "Remove access during a section fetch and verify a useful accessible access state.", "Switch account and navigate Back; protected cached content stays absent and stale fetches stop." ], "deliverables": [ "Access-loss boundary and account-switch browser tests" ], "rollout": "Verify before enabling protected handbooks; disable protected caching if invalidation cannot be guaranteed.", "skills": [ "Authorization UX", "Cache isolation", "Focus recovery" ], "fieldMix": [ { "field": "Security", "percentage": 40 }, { "field": "Accessibility", "percentage": 30 }, { "field": "Frontend", "percentage": 30 } ], "patterns": [] }, { "id": "af45c001-dcda-4701-9712-17c3208f6a3a", "key": "READ-110", "title": "Verify a complete reading-and-annotation session", "type": "CHORE", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 105, "phaseId": "release", "dependsOn": [ "READ-105", "READ-108", "READ-109" ], "scenario": "Component checks miss interactions among search, resizing, bookmarks, and drafts. Add a short reader acceptance script to the release checklist.", "acceptanceCriteria": [ "The script follows contents, changes text settings, searches, annotates, bookmarks, and reopens.", "Keyboard-only and one documented screen-reader pass record observed limitations.", "Version correction and denied annotation save are recovery branches." ], "implementationNotes": [ "Record the environment and observations; automated checks do not establish complete accessibility." ], "verification": [ "Run the ordinary synthetic session and verify final bookmark and annotation identities.", "Reject saving and replace the version; the draft stays explicit and ambiguous bookmarks require resolution." ], "deliverables": [ "Reader acceptance script and reproducible barrier notes" ], "rollout": "Use for navigation/annotation changes; pause the affected feature on identity loss or unrecoverable keyboard failure.", "skills": [ "Acceptance testing", "Accessibility", "Release handoff" ], "fieldMix": [ { "field": "Accessibility", "percentage": 60 }, { "field": "Quality engineering", "percentage": 40 } ], "patterns": [] } ] } ] }