Activities - Envision the System

#	Name	Abbrev.	Guidance	Actions
Inception 7
1	Establish Conventions	ESM-1	Establish Conventions Objective Establish the foundational conventions and standards that will be used throughout the …	Read the 'ESM-1 Establish Conventions' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Establish Conventions ## Objective Establish the foundational conventions and standards that will be used throughout the entire UX design-to-development process. This includes the Screen ID naming convention for traceability and other important guidelines. --- ## Screen ID Convention (Traceability) All screens must follow a consistent naming pattern for end-to-end traceability. ### Format: `FOB-{ENTITY}-{OPERATION}-{VERSION}` Components: - `FOB` = Forward Operating Base (the web UI) - `{ENTITY}` = Uppercase entity name (PLAYBOOKS, WORKFLOWS, ACTIVITIES, etc.) - `{OPERATION}` = Screen operation type (see CRUDLF patterns below) - `{VERSION}` = Version number (usually `-1` for MVP) ### CRUDLF Operations Standard CRUD + List/Find pattern: - `LIST+FIND` - Entry point screen for entity (list view with search/filter) - `CREATE_{ENTITY}` - Creation form screen - `VIEW_{ENTITY}` - Detail/read-only view screen - `EDIT_{ENTITY}` - Edit form screen - `DELETE_{ENTITY}` - Deletion confirmation screen Examples: - `FOB-PLAYBOOKS-LIST+FIND-1` → Playbooks list with search/filter - `FOB-PLAYBOOKS-CREATE_PLAYBOOK-1` → Create new playbook form - `FOB-PLAYBOOKS-VIEW_PLAYBOOK-1` → View playbook details - `FOB-PLAYBOOKS-EDIT_PLAYBOOK-1` → Edit playbook form - `FOB-PLAYBOOKS-DELETE_PLAYBOOK-1` → Delete playbook confirmation - `FOB-WORKFLOWS-LIST+FIND-1` → Workflows list (within playbook) - `FOB-HOWTOS-CREATE_HOWTO-1` → Create howto form ### Traceability Chain Every Screen ID must appear in ALL of these artifacts: 1. User Journey (`docs/features/user_journey.md`) - Format: `#### Screen: FOB-{ENTITY}-{OPERATION}-{VERSION}` - Describes layout, actions, user flow 2. Screen Flow Diagram (`docs/ux/2_dialogue-maps/screen-flow.drawio`) - Box label: `FOB-{ENTITY}-{OPERATION}-{VERSION}` - Bold border for LIST+FIND entry points - Navigation arrows between screens 3. Feature File (`docs/features/act-X-{entity}/{entity}-{operation}.feature`) - Feature title: `Feature: FOB-{ENTITY}-{OPERATION}-{VERSION} {Description}` - Scenario IDs: `FOB-{ENTITY}-{OPERATION}-{NN}` (01, 02, 03...) - File naming: `{entity}-{operation}.feature` (kebab-case) 4. Template (`templates/{entity}/{operation}.html`) - HTML comment: `<!-- Screen: FOB-{ENTITY}-{OPERATION}-{VERSION} -->` - Hidden div: `<div data-testid="{entity}-{operation}-loaded" style="display: none;">{SCREEN_ID}</div>` - Enables grep discovery: `grep -r "FOB-PLAYBOOKS-LIST+FIND-1" .` 5. Tests (`tests/integration/test_{entity}_{operation}.py`) - Test names reference Screen ID - Docstrings include Screen ID ### Benefits ✅ Bidirectional Traceability: Navigate from code → design or design → code ✅ Quick Discovery: `grep -r "FOB-PLAYBOOKS-LIST+FIND-1" .` finds all related artifacts ✅ Consistency Validation: Verify all screens have complete documentation ✅ Onboarding: New developers can trace any screen to design intent ✅ Gap Detection: Missing Screen IDs indicate incomplete UX work --- ## Important Notes ### What NOT to Do - ❌ Do NOT create .MD files unless explicitly part of task definition, workflow, or rule - ❌ Do NOT skip the planning step - always show plan and get approval - ❌ Do NOT create massive documents or commits in one go - ❌ Do NOT declare features complete with failing tests - ❌ Do NOT mock in integration tests - ❌ Do NOT skip accessibility attributes or tooltips - ❌ Do NOT use vague naming or generic values in scenarios ### What TO Do - ✅ Follow plan-then-do at every step - ✅ Work incrementally - small vertical slices - ✅ Write tests before implementation - ✅ Maintain 100% test pass rate - ✅ Use existing patterns and conventions - ✅ Prioritize accessibility (ARIA, semantic HTML, keyboard navigation) - ✅ Ensure testability (`data-testid` on all interactive elements) - ✅ Validate diagrams visually with human eye - ✅ Add Font Awesome Pro icons and Bootstrap tooltips to all buttons - ✅ Check for existing GitHub issues before creating new ones - ✅ Commit after each major step with Angular convention --- ## Deliverables - ✅ Screen ID convention understood and documented - ✅ Traceability chain requirements clear - ✅ Important guidelines reviewed - ✅ Ready to proceed with User Journey definition
2	Define User Journey	ESM-2	Define User Journey Objective Establish the high-level user experience narrative with personas, user flows, and …	Read the 'ESM-2 Define User Journey' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Define User Journey ## Objective Establish the high-level user experience narrative with personas, user flows, and screen descriptions. ## Artifacts Created - `docs/features/user_journey.md` - Complete user journey narrative ## Process ### 1. Write User Journey Document - Define personas (e.g., Mike Chen, Maria Rodriguez) - Map out Acts (Act 0: Authentication → Act 9: PIPs, etc.) - Describe user goals, motivations, and context for each Act - Identify key screens and user flows - Document system architecture notes (FOB vs HB, MCP integration) - Follow narrative structure: Context → Screen → Actions → Results Template: ```markdown ### Act X: [ENTITY] - Complete CRUDLF Context: [User situation and needs] Pattern: [Entity] follows the standard CRUDLF pattern with LIST+FIND as the entry point. #### Screen: FOB-[ENTITY]-LIST+FIND-1 [User] clicks "[Entity]" in the main navigation. The [entity] list page appears: Layout: - Header: "[Entity]" with count badge (e.g., "[Entity] (3)") - Top Actions: - [Create New [Entity]] button (primary action, bold blue) - [Additional Action] button - Search & Filter Section: - Search box: "Find [entity]..." (searches [fields]) - Filters: [Filter1], [Filter2], [Filter3] - [Clear Filters] button - [Entity] Table with columns: - [Column1] \| [Column2] \| [Column3] \| Actions - Sort by any column - Row Actions (dropdown menu per [entity]): - [View] - Opens FOB-[ENTITY]-VIEW_[ENTITY] - [Edit] - Opens FOB-[ENTITY]-EDIT_[ENTITY] - [Delete] - Opens FOB-[ENTITY]-DELETE_[ENTITY] modal - [...More] - Additional actions - Empty State (if no [entity]): - Illustration: [Description] - "No [entity] yet" - "[Call to action message]" - [Action Buttons] - Pagination: Shows 20 per page with page controls Example Data: - "[Example 1]" \| [Data] \| [Data] \| [Status] - "[Example 2]" \| [Data] \| [Data] \| [Status] [User] sees [description of what user can do]. ``` ## How to Execute This Step ### 1. Plan Before Executing (plan-then-do) - Identify all affected documents, sections, and artifacts - Figure out what content you need and what's available to reference - Note what needs to be created from scratch - ALWAYS show the plan and ask for approval or refinements - Execute the plan, adjusting as necessary based on discoveries - After every major section, update the plan and explain next step ### 2. Work Incrementally (small-increments) - Work section-by-section (one Act at a time for user journey) - After every change: write → review → refine → evaluate - No massive documents created in one go - Build incrementally: personas → Act 0 → Act 1 → Act 2, etc. ## Deliverables - ✅ Complete user journey with all Acts documented - ✅ Each screen uses Screen ID format: `#### Screen: FOB-{ENTITY}-{OPERATION}-{VERSION}` - ✅ Screen IDs follow CRUDLF pattern: LIST+FIND, CREATE_{ENTITY}, VIEW_{ENTITY}, EDIT_{ENTITY}, DELETE_{ENTITY} - ✅ Entry point screens (LIST+FIND) clearly marked - ✅ Screen IDs are unique and traceable
3	Define Information Architecture	ESM-3	Define Information Architecture Objective Establish the design system foundation, layout patterns, and component standards. Artifacts …	Read the 'ESM-3 Define Information Architecture' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Define Information Architecture ## Objective Establish the design system foundation, layout patterns, and component standards. ## Artifacts Created - `docs/ux/IA_guidelines.md` - Information architecture and design system ## Process ### 1. Define Information Architecture - Document design system foundation (Bootstrap 5.3+ base) - Define design tokens (colors, spacing, typography, shadows, borders) - Establish layout patterns (2-column, 3-column, grid, forms) - Define navigation structure (top navbar, breadcrumbs, tabs) - Document component patterns (cards, buttons, forms, modals) - Specify accessibility requirements - Define icon system (Font Awesome Pro) Philosophy: Leverage Bootstrap's conventions, utilities, and component patterns as the first choice. Customize only when necessary for brand identity or specific user experience requirements. ### Key Sections to Document #### 1. Design Tokens - Color palette (primary, secondary, custom colors) - Spacing scale (Bootstrap multipliers) - Typography (font stacks, sizes, weights) - Shadows and borders #### 2. Layout Patterns - Dashboard grids - Form layouts - List/table views - Detail pages #### 3. Navigation Design - Top navigation structure - Breadcrumbs - Tab navigation - Active states and ARIA attributes #### 4. Component Patterns - Cards - Buttons (with Font Awesome icons and tooltips) - Forms and inputs - Modals and dialogs - Tables - Empty states #### 5. Page Header Pattern Document the canonical structure for every non-dashboard page: breadcrumb row, title + action cluster row, and (for detail pages) a metadata sub-row. Specify which information belongs in each row, how the action cluster is composed, and how it adapts between list, view, and edit contexts. #### 6. Baseline CRUDLF Page Templates Document the skeleton layout for each standard screen operation: List+Find, View, Edit, and Delete. For each, specify the column split, which organisms compose the main area, what the sidebar (if any) may contain, and whether the operation uses a full page or a modal. #### 7. Button Placement Rules Document as a decision table: for each context (list page header, form footer, detail page with destructive action, modal footer) — which corner holds the action cluster, and what is the left-to-right order of buttons within it. State the universal rules that apply across all contexts (e.g. primary always rightmost; destructive always leftmost in its cluster). #### 8. Feedback / Notification System Document the chosen mechanism for each feedback type: success, error, warning, info, and field validation. For each, specify the UI component used, its positioning, dismissal strategy (auto-dismiss with timing vs. manual), and how backend operations surface feedback to the frontend (e.g. response headers, HTMX events, Django messages framework). #### 9. Component State Catalogue For every interactive component, document all states: default, hover, focus, active, disabled, and loading. List the minimum set of components that must be covered. Specify the visual treatment (CSS class, style change, or animation) for each state and note any accessibility requirements (e.g. visible focus ring, aria-disabled). ## How to Execute This Step ### 1. Plan Before Executing - Identify all design system components needed - Reference existing Bootstrap documentation - Note Mimir-specific customizations - Show plan and get approval ### 2. Work Incrementally - Document one section at a time - After every section: write → review → refine - Build incrementally: tokens → layouts → navigation → components → page patterns → CRUDLF templates → button rules → feedback → states ## Deliverables - ✅ IA guidelines with design system specifications - ✅ Screen ID convention documented: Format, CRUDLF operations, examples - ✅ Navigation structure defined - ✅ Layout patterns documented - ✅ Component patterns with accessibility requirements - ✅ Icon system (Font Awesome Pro) documented - ✅ Bootstrap customization approach clear - ✅ Page header pattern documented (breadcrumb / title + action cluster / metadata sub-row) - ✅ Baseline CRUDLF templates documented (List+Find, View, Edit, Delete) - ✅ Button placement rules table documented - ✅ Feedback system documented (mechanism and dismissal strategy per feedback type) - ✅ Component state catalogue documented (all states for all required components)
4	Create Dialogue Maps	ESM-4	Create Dialogue Maps (Screen Flows) Objective Visualize screen-to-screen flows and entity relationships using Draw.io diagrams. …	Read the 'ESM-4 Create Dialogue Maps' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Create Dialogue Maps (Screen Flows) ## Objective Visualize screen-to-screen flows and entity relationships using Draw.io diagrams. ## Artifacts Created - `docs/ux/2_dialogue-maps/screen-flow.drawio` - Visual flow diagrams ## Process ### 1. Create Domain Model Diagram - Map core entities (Playbook, Workflow, Phase, Activity, Artifact, Role, Howto) - Show relationships between entities - Document cardinality and dependencies - Use color coding: - Blue (#4682B4): FOB screens - Green (#82b366): Homebase screens - Purple (#9673a6): MCP operations ### 2. Create MVP Flow Diagram - Create horizontal swimlanes per Act (ACT 0 → ACT 9) - Add screen boxes with Screen IDs (e.g., `FOB-PLAYBOOKS-LIST+FIND-1`) - Bold border for LIST+FIND entry points - Add navigation arrows showing screen-to-screen flow - Bold black arrows for main progression flow - Document screen states (loading, error, success) ### 3. Validate Diagram Visually - Human eye check: Does it look clear and understandable? - Fresh eyes test: Can someone unfamiliar understand immediately? - Arrow clarity test: Can you trace each flow path without confusion? - Primary user path is visually prominent and easy to follow ## Tools - Draw.io for diagram creation - Use tabs: "Domain Model" and "MVP Flow - Local FOB" ## Deliverables - ✅ Domain model diagram - ✅ Complete MVP flow with all Acts - ✅ Each screen box labeled with Screen ID: `FOB-{ENTITY}-{OPERATION}-{VERSION}` - ✅ LIST+FIND screens have bold borders (entry points) - ✅ Screen IDs match User Journey exactly - ✅ Navigation arrows show screen-to-screen flow - ✅ Grep-able: Can find screen in diagram by ID - ✅ Screen state documentation - ✅ Navigation flow clarity ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37).
5	Write Feature Files	ESM-5	APPEND TO GUIDANCE: Feature file location (layout) Write .feature files to docs/features/act-*/. That tree is …	Read the 'ESM-5 Write Feature Files' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## Feature file location (layout) Write `.feature` files to `docs/features/act-/`. That tree is the living BDD specification. After TFK-02 is in place, the same tree is also the AT runner path (`behave.ini` `paths = docs/features`) — there is no separate promote/copy into `tests/acceptance/` or `features/at/`. Tag not-yet-implemented scenarios `@wip` so CI can exclude them (`tags = ~@wip`) once behave is configured. --- ## TFK Integration: Step Library Consumption (optional, when TFK exists) ESM does not depend on TFK.* Workflow order is ESM → … → TFK. On a greenfield first pass, write clear, unconstrained Gherkin that expresses user goals. Do not block ESM-05 waiting for Step/Fixture Library Catalogs. When TFK already exists (bootstrap repos, later iterations, or after TFK-03/04 have run): 1. Prefer catalog phrases: Open the Step Library Catalog (TFK-03) and reuse existing step patterns (navigation, forms, tables, auth, assertions, dialogs). 2. Assemble from library: Compose scenarios from catalog building blocks so they become immediately executable once AT steps exist. 3. If a phrase is missing: Do not invent one-off step wording that will never be implemented. Either (a) write natural Gherkin and note a follow-up TFK-07 to add the phrase, or (b) if TFK-07 is available in this iteration, invoke it to extend the catalog. 4. Fixtures: Same rule for Fixture Library Catalog (TFK-04) — optional when present; otherwise describe data needs in scenario prose / examples tables. ### Why this split matters - Specification first (ESM): feature files are requirements, not a hostage of the test harness. - Automation second (TFK): TFK binds phrases to Django-client (AT) and Playwright (E2E) implementations. - No circular dependency: ESM-05 never lists TFK-03/04 artifacts as required inputs. ## Inputs (additional) - Step Library Catalog (Document, Optional) — produced by TFK-03 Build Step Library; use when available. - Fixture Library Catalog (Document, Optional) — produced by TFK-04 Build Fixture Library; use when available.
6	Create Mockups	ESM-6	Create Mockups (Prototyped Screens) Objective Build functional prototypes with representative mock data to validate UX …	Read the 'ESM-6 Create Mockups' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Create Mockups (Prototyped Screens) ## Objective Build functional prototypes with representative mock data to validate UX before full implementation. Mockups are design reference — not connected to live data or production runtime. ## Isolation Serve mockups only in local/preview environments. They must be unreachable in test and production (not found / not mounted). Do not mix mockup routes or screens into the production application surface. ## Mockup chrome (required on every screen) Every mockup inherits a single shared shell. Do not duplicate mockup chrome inside individual screens. Two signals are always present (except the full-bleed exception below): ### 1. Persistent mockup banner A fixed banner at the top of the viewport states that the screen is design reference only and is not connected to live data. - Defined once in the shared shell. - Never removed or hidden on individual mockup screens. - Production chrome (nav, page header) sits below it. ### 2. Shared screen inventory A single footer (or equivalent persistent index) lists every registered mockup screen. This is the canonical cross-link index for designers, reviewers, and agents jumping between prototypes. Rules: \| Rule \| Detail \| \|---\|---\| \| Single source \| Maintain inventory links in the shared shell only — never add a second per-page inventory block. \| \| Keep in sync \| When you add a mockup screen, add its inventory link in the same change. \| \| Page-specific hints \| Optional suffix text (reset notes, store keys, and similar) attaches to the shared inventory. Do not fork the inventory. \| \| Test hook \| The inventory root has a stable test id so agents and AT can find it. \| Representative detail/edit screens that are reachable from list rows do not need inventory links unless they are primary entry points. Full-bleed exception: A screen whose layout needs the full viewport height may hide the inventory. The banner stays visible. ## Process ### 1. Register every screen Every prototype in the Screen Flow is a registered mockup. Naming and routing follow the project's frontend conventions. The inventory in the shared shell is the canonical list — keep it in lockstep with registrations. ### 2. Use representative mock data Mock data is hardcoded fixtures. Mockup screens have no live datastore access and no production auth checks. Cover the states the IA requires: loading, empty, error, success. ### 3. Build screens from the shared shell Each screen extends the shared mockup shell (inherits banner + inventory). - Follow the IA Guidelines for layout, page headers, components, and test-id naming. - Visible title and subtitle use production copy — no Screen IDs and no “mockup” or storage jargon in the page header. - Screen traceability lives in metadata (screen-id slot → comment in the shell; test ids on containers and controls). - Mockup signaling is only the banner and the shared inventory. Interactive prototypes may append reset hints on the inventory, never in the page header. - Represent UI states; use semantic HTML, ARIA labels, and keyboard navigation. ### 4. Accessibility - Semantic structure (`nav`, `main`, `section`) - ARIA labels and roles on interactive elements - Keyboard navigation - Focus management for modals and alerts ## Deliverables - ✅ Shared mockup shell with persistent banner and single screen inventory - ✅ Every Screen Flow prototype registered and linked from that inventory (no per-page duplicate inventories) - ✅ Representative mock data; no live datastore; no production auth - ✅ Production-real page headers; Screen IDs only in metadata / test ids - ✅ All required UI states (empty, loaded, error, success) - ✅ Accessibility (ARIA, semantic HTML, keyboard nav) - ✅ Mockups available in local/preview only; unreachable in test and production ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - Screen Flow / Dialogue Map (Diagram, Required) — produced by Create Dialogue Maps (#38).
7	Feed into Implementation	ESM-7	Feed into Feature Implementation Workflow Objective Transition from UX design to full backend implementation. Process …	Read the 'ESM-7 Feed into Implementation' activity from playbook 'Junior Edda' (workflow 'Envision the System'). Follow its guidance when assisting me. # Feed into Feature Implementation Workflow ## Objective Transition from UX design to full backend implementation. ## Process ### 1. Handoff Checklist Ensure all UX artifacts are complete before implementation: Activity 1 → Activity 2: - [ ] Screen ID convention understood - [ ] Traceability requirements clear - [ ] Important guidelines reviewed Activity 2 → Activity 3: - [ ] User journey documented - [ ] All Acts defined with personas - [ ] Screen IDs assigned to all screens Activity 3 → Activity 4: - [ ] IA guidelines documented - [ ] Design system tokens defined - [ ] Navigation structure clear Activity 4 → Activity 5: - [ ] Domain model diagram complete - [ ] MVP flow diagram shows all screens - [ ] Screen states documented - [ ] Flow validated visually (human eye check) Activity 5 → Activity 6: - [ ] All CRUDLF feature files written - [ ] Scenarios follow BDD best practices - [ ] Navbar integration scenarios added - [ ] Error/edge cases covered Activity 6 → Activity 7: - [ ] All mockup templates created - [ ] Mock views functional - [ ] All UI states represented - [ ] Accessibility attributes present - [ ] `data-testid` attributes added - [ ] Design system compliance verified Activity 7 — UX complete: - [ ] All UX artifacts complete (Activities 1-6) - [ ] Feature files ready for implementation - [ ] Mockups ready for conversion to real views - [ ] Screen IDs documented across all artifacts ### 2. Traceability Verification Verify Screen ID appears in all 5 artifacts: 1. ✅ User Journey (section header) 2. ✅ Screen Flow Diagram (box label) 3. ✅ Feature File (feature title) 4. ✅ Template (HTML comment + hidden div) 5. ✅ Tests (test names + docstrings) Grep Test: `grep -r "FOB-{ENTITY}-{OPERATION}-{VERSION}" .` ## Deliverables - ✅ All UX artifacts complete (Activities 1-6) - ✅ Feature files ready for implementation - ✅ Mockups ready for implementation - ✅ Screen ID traceability complete - ✅ Handoff checklist verified ## Next Steps: Remaining Elaboration before Construction ESM is the first Inception workflow. Three more workflows must complete before building starts: \| Gate \| Artifact \| Workflow if missing \| \|------\|----------\|---------------------\| \| DTA \| `docs/architecture/SAO.md` \| DTA — Define Architecture \| \| DSP \| `CLAUDE.md` \| DSP — Deploy Software Process \| \| BSP \| `Makefile` + `requirements.txt` \| BSP — Bootstrap Project \| Run DTA next. DSP follows DTA (needs SAO.md). BSP follows DSP. When all four gates pass, see BSP-08 for the Construction Handoff and mode selection.

Activities in Envision the System