{ "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": "c53257d1-9494-4266-a422-aff06e782168", "key": "PDOC", "title": "Make a document editor predictable as operations grow", "field": "Frontend", "summary": "Build a bounded browser editor whose tree operations, history, subscriptions, and exports remain coherent under failures and repeated use.", "context": "A fictional support team edits reusable troubleshooting documents with paragraphs, links, and nested sections. The browser prototype has separate toolbar and keyboard handlers, an unreliable undo stack, and mutable shared formatting objects. Create a local editor and synthetic documents; no starter assets, rich-text engine, collaborative backend, or production service is supplied.", "stack": [ "TypeScript", "React", "Vitest", "Playwright" ], "prerequisites": [ "Browser events", "Immutable updates", "Accessible form controls" ], "developerValue": "Practice relating object and state patterns to real UI behavior, including undo semantics, bounded traversal, lifecycle cleanup, and memory tradeoffs.", "companyValue": "Review whether editor changes preserve user work, keep controls consistent, and reduce maintenance effort without concealing document corruption.", "delivery": "Ten tickets across document structure, interaction consistency, and safe evolution. Build the stated local fixtures and return an editor demo, operation tests, and a short design record.", "phases": [ { "id": "document", "title": "Establish document operations", "goal": "Make structure and editing commands consistent." }, { "id": "interaction", "title": "Coordinate interaction", "goal": "Keep history, controls, and subscriptions tied to one document state." }, { "id": "evolution", "title": "Exercise larger and changing documents", "goal": "Measure sharing and preserve compatibility under export and restoration." } ], "tickets": [ { "id": "acb1e99c-e059-424a-90c0-b6e640121822", "key": "PDOC-101", "title": "Give nested sections and paragraphs one structural contract", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 120, "phaseId": "document", "dependsOn": [], "scenario": "The outline view handles top-level paragraphs but crashes when a section contains another section. The current arrays do not distinguish leaves from containers or validate imported structure.", "acceptanceCriteria": [ "Represent paragraphs as leaves and sections as containers with stable node identities and explicit discriminated types.", "Render and count text nodes consistently through three nested section levels.", "Reject duplicate node identities, cycles in programmatic input, and depth above the declared maximum of twenty." ], "implementationNotes": [ "A Composite may use plain immutable data rather than classes. Keep document structure separate from React elements and DOM nodes." ], "verification": [ "Render empty, flat, and nested synthetic documents and compare outline counts.", "Feed a duplicate identity and a cyclic structure to validation and assert bounded rejection without rendering." ], "deliverables": [ "Document model, validator, and nested outline example" ], "rollout": "Enable the new model only after validating local sample documents; preserve an untouched input copy when migration rejects a document.", "skills": [ "Tree modeling", "Input validation", "Component composition" ], "fieldMix": [ { "field": "Frontend", "percentage": 80 }, { "field": "System design", "percentage": 20 } ], "patterns": [ { "pattern": "composite", "activity": "APPLY", "focus": "Give leaf paragraphs and nested section containers a consistent traversal contract without coupling the document tree to rendered UI elements." } ] }, { "id": "f62d3166-5845-46dc-9975-eec05d87a574", "key": "PDOC-102", "title": "Make Find next follow document order through collapsed sections", "type": "BUG", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 120, "phaseId": "document", "dependsOn": [ "PDOC-101" ], "scenario": "Find next walks visible DOM elements, so collapsing a section removes its paragraphs from search. Keyboard users cannot tell whether a result was skipped or the query ended.", "acceptanceCriteria": [ "Traverse paragraph text in document preorder, independent of collapsed presentation state.", "Find next visits each matching node once, wraps explicitly, and reports position and total through an accessible status message.", "An empty query yields no results; a removed node cannot remain the active match after document revision changes." ], "implementationNotes": [ "Use an Iterator or generator over a stable document snapshot; do not query the DOM to discover content." ], "verification": [ "Find a match inside a collapsed section and verify the section opens and focus moves to its paragraph control.", "Delete the active result and change the query to no matches; confirm stale focus targets and counts are cleared." ], "deliverables": [ "Snapshot traversal and keyboard search regression" ], "rollout": "Replace local search traversal while retaining the existing search control; fall back to document start when no prior result identity survives.", "skills": [ "Iterators", "Keyboard interaction", "State invalidation" ], "fieldMix": [ { "field": "Frontend", "percentage": 60 }, { "field": "Accessibility", "percentage": 40 } ], "patterns": [ { "pattern": "iterator", "activity": "APPLY", "focus": "Traverse the document model in a stable order so search behavior does not change when presentation hides a section." } ] }, { "id": "a6521057-dd7d-49ca-978e-a1038ae0473c", "key": "PDOC-103", "title": "Route toolbar and keyboard deletion through one command", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "document", "dependsOn": [ "PDOC-101" ], "scenario": "Toolbar deletion removes an entire selected section, but the keyboard shortcut deletes only its heading and leaves orphaned paragraphs. The two handlers also record different undo entries.", "acceptanceCriteria": [ "Both entry points issue one document command with target identity and expected document revision.", "Deleting a section removes its subtree atomically, updates selection to a documented surviving neighbor, and creates one history entry.", "Stale, missing, and protected-root targets return explicit failures with no document or history change." ], "implementationNotes": [ "Command execution belongs outside presentation event handlers; do not store DOM references in history." ], "verification": [ "Delete the same nested section through toolbar and keyboard and compare document, selection, and history results.", "Issue deletion against an old revision and the protected root; assert no partial update." ], "deliverables": [ "Shared delete command and entry-point parity tests" ], "rollout": "Move both handlers in one local change to prevent mixed semantics; retain saved synthetic documents for replay if the command is reverted.", "skills": [ "Command modeling", "Atomic state updates", "Interaction testing" ], "fieldMix": [ { "field": "Frontend", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [ { "pattern": "command", "activity": "APPLY", "focus": "Represent deletion as one validated document operation shared by toolbar, keyboard, and history so entry points cannot diverge." } ] }, { "id": "a95b295c-df6f-4b16-91ce-4689de6c5df7", "key": "PDOC-104", "title": "Restore selection together with content when undoing a deletion", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "interaction", "dependsOn": [ "PDOC-103" ], "scenario": "Undo restores paragraph text but leaves the caret pointing to the deleted node identity. A second edit then modifies the wrong paragraph. History currently keeps an editable reference to the live tree.", "acceptanceCriteria": [ "A history entry captures enough immutable document and selection state to restore one completed command consistently.", "Undo and redo restore content and logical selection, and a new edit after undo clears the redo branch.", "Retain at most fifty entries and disclose the boundary when older history is discarded; failed commands create no entry." ], "implementationNotes": [ "Compare a Memento snapshot with inverse commands for this bounded editor; do not serialize focusable elements or browser event objects." ], "verification": [ "Delete, undo, redo, undo, then type; verify the intended restored paragraph receives the edit.", "Mutate the live document after recording history and assert old entries remain unchanged; exercise the fifty-entry limit." ], "deliverables": [ "Bounded undo/redo history and selection restoration tests" ], "rollout": "Start a new local history session on the upgraded model; existing saved document content remains readable even when transient old history is discarded.", "skills": [ "Undo semantics", "Immutability", "Memory bounds" ], "fieldMix": [ { "field": "Frontend", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [ { "pattern": "memento", "activity": "COMPARE", "focus": "Evaluate immutable state snapshots against inverse commands for restoring both document content and logical selection within a bounded undo history." } ] }, { "id": "6868304d-900b-441b-9116-c72dbd15616a", "key": "PDOC-105", "title": "Stop closed editor tabs from receiving document updates", "type": "BUG", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "interaction", "dependsOn": [ "PDOC-103" ], "scenario": "Opening and closing the preview panel twenty times makes one edit trigger twenty-one outline refreshes. Subscriptions remain in the document store after the panel unmounts.", "acceptanceCriteria": [ "Each subscription has an idempotent unsubscribe operation tied to the subscribing component's lifetime.", "One committed document operation sends one versioned notification to each active subscriber, including when callbacks subscribe or unsubscribe during delivery.", "A failed subscriber does not stop delivery to other subscribers, and errors are reported without logging document content." ], "implementationNotes": [ "Keep the Observer surface small and define whether delivery is synchronous; avoid a global application event bus for this document-local need." ], "verification": [ "Mount and unmount the preview twenty times, edit once, and assert only active listeners run.", "Have one listener throw and another unsubscribe during delivery; verify remaining delivery and the next notification set." ], "deliverables": [ "Subscription lifecycle fix and repeated-mount regression" ], "rollout": "Replace document-local subscriptions together; reset transient listeners on reload without changing saved document data.", "skills": [ "Resource lifecycle", "Observer delivery", "Failure isolation" ], "fieldMix": [ { "field": "Frontend", "percentage": 60 }, { "field": "Performance engineering", "percentage": 40 } ], "patterns": [ { "pattern": "observer", "activity": "REFACTOR", "focus": "Repair subscription ownership and notification semantics so repeated panel mounts do not retain listeners or multiply document update work." } ] }, { "id": "4eb95e06-4e73-455a-b30e-14cebf2068d8", "key": "PDOC-106", "title": "Untangle the toolbar's direct calls into three side panels", "type": "CHORE", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "interaction", "dependsOn": [ "PDOC-103", "PDOC-105" ], "scenario": "Selecting a link makes the toolbar call the inspector, the inspector call the outline, and the outline call the toolbar again. A new panel added another circular dependency and occasional repeated selection updates.", "acceptanceCriteria": [ "Define one direction for selection intents and one authoritative logical selection state.", "Toolbar, inspector, and outline remain consistent without importing or invoking each other's component instances.", "Compare a document-scoped Mediator with reducer-driven state and callbacks; retain the simpler option that exposes event flow clearly." ], "implementationNotes": [ "Do not move every unrelated editor concern into a central god object; keep document commands and formatting rules separately testable." ], "verification": [ "Select a nested link from each panel and compare selection and enabled toolbar actions.", "Send the same selection intent twice and remove the selected node; assert bounded updates and a consistent empty selection." ], "deliverables": [ "Interaction dependency refactor and selection-flow decision record" ], "rollout": "Migrate the three selection participants together in the local editor; retain command behavior and shortcut bindings during the change.", "skills": [ "State ownership", "Dependency design", "UI architecture" ], "fieldMix": [ { "field": "Frontend", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [ { "pattern": "mediator", "activity": "COMPARE", "focus": "Compare a document-scoped coordinator with reducer state to remove circular panel calls without creating a central object that owns every editor feature." } ] }, { "id": "96b79ce6-223c-4957-a0cc-7fa4d58888cd", "key": "PDOC-107", "title": "Prevent edit actions while a replacement document is importing", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "interaction", "dependsOn": [ "PDOC-104", "PDOC-106" ], "scenario": "Import sets isLoading but leaves isEditable true. A user types while the asynchronous parser runs, then the parsed document replaces those edits without a warning.", "acceptanceCriteria": [ "Define explicit ready, importing, and import-failed states and legal transitions, including cancel and retry.", "Edit commands are rejected during replacement import, and controls expose their disabled reason accessibly.", "A failed or cancelled import preserves the prior document and selection; a late result from a cancelled attempt cannot replace them." ], "implementationNotes": [ "A tagged union and transition function can implement State semantics; separate state representation from parsing work." ], "verification": [ "Delay parsing, attempt a keyboard edit, and verify no hidden edit or unexpected replacement occurs.", "Cancel one import, start another, then resolve results in reverse order; only the current successful attempt may install a document." ], "deliverables": [ "Import state transitions and delayed-result interaction tests" ], "rollout": "Replace boolean flags with the explicit local state model; keep the last valid document available until a replacement commits.", "skills": [ "State machines", "Race handling", "Accessible feedback" ], "fieldMix": [ { "field": "Frontend", "percentage": 70 }, { "field": "Accessibility", "percentage": 30 } ], "patterns": [ { "pattern": "state", "activity": "APPLY", "focus": "Represent import lifecycle and command eligibility with explicit states so contradictory loading/editing flags cannot erase user work." } ] }, { "id": "74682930-3a00-4410-910f-5e2eda81baad", "key": "PDOC-108", "title": "Measure whether sharing text styles is worth the indirection", "type": "TASK", "priority": "LOW", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "evolution", "dependsOn": [ "PDOC-101", "PDOC-104" ], "scenario": "A generated 20,000-paragraph fixture repeats twelve formatting combinations. A proposed style pool reduces duplicate objects, but its mutable shared entries can change many paragraphs when one is edited.", "acceptanceCriteria": [ "Compare plain immutable style values with Flyweight style identities using the same declared fixture and measurement procedure.", "If pooling is retained, intrinsic styles are immutable and per-paragraph selection or editing state stays outside the pool.", "Report memory observations and edit/undo latency across five runs, including environment and variance; retain the simpler representation if benefits are inconclusive." ], "implementationNotes": [ "Measure the model separately from DOM rendering and keep the fixture size fixed; do not claim production performance from one browser snapshot." ], "verification": [ "Change one paragraph's style and undo it without changing any other paragraph.", "Attempt to mutate an interned style and verify prevention; repeat opening and closing documents to check that unused pools are released." ], "deliverables": [ "Reproducible comparison, isolation tests, and keep-or-remove decision" ], "rollout": "Keep style pooling behind a local representation switch until correctness and measurements support it; preserve a conversion back to plain values.", "skills": [ "Memory profiling", "Immutability", "Performance experiments" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 60 }, { "field": "Frontend", "percentage": 40 } ], "patterns": [ { "pattern": "flyweight", "activity": "COMPARE", "focus": "Measure immutable sharing of repeated formatting against plain values, while excluding mutable per-paragraph state from the shared objects." } ] }, { "id": "a8b4d579-8a38-466e-9cb2-b7592c3e8646", "key": "PDOC-109", "title": "Add text and outline export without teaching nodes about file formats", "type": "STORY", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "evolution", "dependsOn": [ "PDOC-101", "PDOC-102" ], "scenario": "Every new export format adds another method to paragraph and section objects. The team needs plain text and a structured outline, and expects document node types to change less often than export formats.", "acceptanceCriteria": [ "Both exporters handle every supported node type and preserve documented section order and paragraph boundaries.", "Keep export operations outside the document data model using a Visitor or exhaustive discriminated-union functions, with a written choice.", "An unknown node type fails with its identity and type instead of silently losing its content." ], "implementationNotes": [ "Treat link labels as text and serialize structured output through a serializer; exporting must not mutate document state or trigger network requests." ], "verification": [ "Export a nested fixture containing empty sections and links and compare explicit expected outputs.", "Introduce an unsupported node kind and assert both exporters fail visibly while leaving the input unchanged." ], "deliverables": [ "Two export operations, exhaustive handling tests, and variation tradeoff note" ], "rollout": "Add exports as local downloads after fixture comparison; disable one format independently if its contract changes.", "skills": [ "Tree operations", "Exhaustive handling", "Serialization" ], "fieldMix": [ { "field": "Frontend", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [ { "pattern": "visitor", "activity": "COMPARE", "focus": "Separate growing export operations from relatively stable node types, comparing a Visitor with exhaustive functions and their cost when a new node type arrives." } ] }, { "id": "27225e52-7e31-4ec9-993b-d82e8ac6cf4e", "key": "PDOC-110", "title": "Reject stale history after replacing the document", "type": "BUG", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 240, "phaseId": "evolution", "dependsOn": [ "PDOC-104", "PDOC-107", "PDOC-109" ], "scenario": "A delayed keyboard event queues Undo just before a successful import installs another document. The old history entry then restores part of the previous document into the replacement because both documents happen to contain node p1.", "acceptanceCriteria": [ "Bind commands and history entries to a document session identity as well as a revision.", "Replacement import commits document, logical selection, session identity, and history reset as one state transition.", "Stale queued commands and incompatible snapshots fail without modifying the active document; cancellation preserves the previous session and valid history." ], "implementationNotes": [ "Build a deterministic event-order harness rather than timing-dependent sleeps; this ticket does not require collaborative editing or remote persistence." ], "verification": [ "Interleave queued Undo, successful import, and duplicate node identities; assert the replacement never receives previous-session content.", "Fail and cancel imports at each transition boundary, then verify undo remains valid only for the preserved session." ], "deliverables": [ "Session-bound command/history contract and interleaving regression matrix" ], "rollout": "Introduce session identities at the local editor boundary and clear incompatible transient history once; preserve saved content separately for recovery.", "skills": [ "Concurrency modeling", "State transitions", "History integrity" ], "fieldMix": [ { "field": "Frontend", "percentage": 50 }, { "field": "System design", "percentage": 30 }, { "field": "Quality engineering", "percentage": 20 } ], "patterns": [ { "pattern": "command", "activity": "REFACTOR", "focus": "Bind queued editor operations to the session that created them so delayed commands cannot operate on a replacement document with reused node IDs." }, { "pattern": "memento", "activity": "REFACTOR", "focus": "Give history snapshots an explicit document-session boundary and install replacement content together with a coherent history reset." } ] } ] } ] }