Inception - Junior Edda

Description

Inception phase establishes the product vision, UX specification, and software architecture before any code is written. Workflow execution sequence: (1) ESM - Envision the System: produces user journey, screen flows, feature files, and mockups. (2) DTA - Define Technical Architecture: consumes ESM artifacts to produce the System Architecture Overview (SAO.md). DTA must complete before DSP can begin since DSP requires the tech stack from SAO.md. NOTE: DSP (Define Software Process) has been moved to the Elaboration phase because it depends on DTA output. Both ESM and DTA must be complete before transitioning to Elaboration.

Activities in this Phase

Order	Name	Actions
Envision the System
#1	Establish Conventions	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	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	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	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	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	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	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.
Define Architecture
#1	Analyze ESM Artifacts	Read the 'DTA-1 Analyze ESM Artifacts' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Analyze ESM Artifacts ## Objective Extract capability requirements per architectural domain from the ESM output artifacts (user journey, screen flows, .feature files, IA guidelines). This structured requirements list feeds all subsequent DTA activities (DTA-02 through DTA-17). --- ## Process ### 1. Read User Journey - Extract domain entities (e.g., User, Playbook, Workflow, Activity, Skill) - Identify interaction patterns (CRUD, search, import/export, real-time updates) - Note personas and roles that imply auth/authorization requirements - Flag integration points (external systems, APIs, data sources) ### 2. Read Screen Flows - Identify UI complexity per screen type: - Simple: static content, read-only views - Moderate: forms, tables, filters, pagination - Complex: graphs, drag-and-drop, real-time, rich text editors - Count screen types to estimate frontend effort - Note navigation patterns (breadcrumbs, tabs, modals, wizards) ### 3. Read Feature Files (.feature) - Extract required capabilities from scenario steps: - CRUD operations per entity - Search and filter requirements - Authentication and authorization scenarios - Error handling and edge cases - Data validation rules - Map scenarios to capability domains (GUI_FORM, API_CRUD, AUTH_SESSION, etc.) ### 4. Read IA Guidelines - Extract design system requirements (component library, theming) - Note accessibility requirements (ARIA, keyboard navigation) - Identify responsive/multi-device needs ### 5. Compile Requirements per Domain Produce a structured list mapping ESM findings to the 16 architectural domains: ``` Domain: Application Blocks (DTA-02) - 5 bounded contexts identified: Auth, Methodology, Planning, MCP, Web UI - Dependency: Methodology → Planning (planning reads methodology) Domain: Integration & API Design (DTA-03) - MCP stdio interface required (read-only) - Web UI HTTP interface required (full CRUD) - No external 3rd party integrations identified Domain: Code Organization (DTA-04) - Monorepo structure implied (single Django project) - 3 layers visible: models, services, views Domain: Data Architecture (DTA-05) - 6 entities with relationships (graph-like) - Version tracking required - Import/export functionality needed ... (continue for all 16 domains) ``` --- ## Deliverables - ✅ Domain entities extracted from user journey - ✅ UI complexity assessed from screen flows - ✅ Capability domains mapped from .feature files - ✅ Structured requirements list produced for all 16 architectural domains - ✅ Ready to proceed with DTA-02 through DTA-17 ## 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).
#2	Define Application Blocks	Read the 'DTA-2 Define Application Blocks' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Application Blocks ## Objective Identify bounded contexts, domain packages, module boundaries, and dependency rules. Choose the foundational architectural pattern (MVC, event-driven, modular monolith, microservices, etc.). --- ## Internal Process Every domain activity follows this structure: 1. Identify needs — what does ESM require for this domain? 2. Scan Skills — query Playbook Skills by `capability_domain` for this domain 3. Propose options — 2-3 approaches with Skill coverage, cost, risk 4. Record decision — user picks, rationale documented --- ## Decisions to Make ### 1. Bounded Contexts / Domain Packages - Review ESM entities and their relationships - Group entities into cohesive domain packages - Define which entities belong together (high cohesion) vs. which are separate concerns (loose coupling) - Example groupings: - `auth/` — User, Session, Permissions - `methodology/` — Playbook, Workflow, Activity, Skill - `planning/` — WorkPlan, Task, Estimation - `mcp/` — MCP protocol, tools, stdio interface ### 2. Module Boundaries & Dependency Rules - Define what can import what (dependency direction) - Identify shared kernel vs. independent modules - Example rules: - `planning` → depends on `methodology` (reads playbook structure) - `mcp` → depends on `methodology` (exposes methodology as tools) - `auth` → independent (no methodology dependency) - No circular dependencies allowed ### 3. Foundational Architectural Pattern Choose one: - MVC / MTV — Model-Template-View (Django default). Best for: server-rendered web apps with moderate complexity. - Event-Driven — Publish/subscribe, event sourcing. Best for: highly decoupled systems, real-time requirements. - Modular Monolith — Single deployable unit with strict module boundaries. Best for: starting simple with clear growth path. - Microservices — Independent deployable services. Best for: large teams, independent scaling needs. - Batch Processing — Scheduled jobs processing data in bulk. Best for: data pipelines, ETL. - Hybrid — Combine patterns (e.g., MVC for web + event-driven for async). ### 3a. UI Architecture Patterns (if system has a web/desktop UI) Define the presentation layer architecture: Rendering model: - Server-rendered — HTML generated on server (Django templates, Jinja2). Best for: testability, SEO, minimal JS. - SPA — Single Page Application (React, Vue, Svelte). Best for: rich interactivity, complex state. - Hybrid — Server-rendered with progressive enhancement (HTMX, Alpine.js, Turbo). Best for: server-side simplicity with dynamic UX. Layout pattern: - Single-panel — One main content area. Best for: simple CRUD, mobile-first. - Multi-panel — Split layout (navigation + content + detail). Best for: explorer-style UIs, dashboards. - Wizard/stepper — Sequential steps. Best for: complex forms, onboarding. Component interaction model: - Full page reload — Traditional links/forms. Simplest, most testable. - Partial updates — Server returns HTML fragments, client swaps them (HTMX, Turbo Frames). Testable with standard server-side tests. - Client-side state — JS manages state, talks to API (React+Redux, Vue+Pinia). Requires browser-based testing. Visualization approach (if applicable): - Server-generated — Graphviz, matplotlib, SVG generation on server. Best for: static/semi-static diagrams. - Client-rendered — D3.js, Cytoscape.js, Chart.js. Best for: interactive, real-time visualizations. - Hybrid — Server generates data, client renders. Best for: large datasets with interactive exploration. Document rationale for each choice, especially impact on testability and build complexity. ### 4. Scan Skills & Reference Implementations Query Playbook Skills where `capability_domain` in: - `APP_STRUCTURE` - `DOMAIN_MODELING` - `DEPENDENCY_INJECTION` Report coverage: ``` Skill Coverage for Application Blocks: APP_STRUCTURE \| [Django App Architecture Skill] ✅ \| Reference: Repository pattern, service layers, dependency rules \| Example: Mimir methodology/ app structure DOMAIN_MODELING \| [DDD Bounded Contexts Skill] ✅ \| Reference: Entity modeling, aggregate boundaries \| Example: Playbook → Workflow → Activity hierarchy DEPENDENCY_INJECTION \| ❌ No Skill - will create custom patterns \| Estimated impact: +1 iteration for pattern definition ``` If reference implementations exist: "Following Django app patterns from [Django App Architecture Skill](#skill-456), recommend service layer approach with estimated 2-day implementation." If gaps exist: "No Skill for Dependency Injection — will need to define patterns. Estimated impact: +1 iteration." --- ## Deliverables - ✅ Bounded contexts / domain packages identified and documented - ✅ Module dependency rules defined (what imports what) - ✅ Foundational pattern chosen with rationale - ✅ UI architecture patterns defined (if applicable): rendering model, layout, interaction model, visualization - ✅ Skill coverage assessed for this domain with reference implementations - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#3	Define Integration & API Design	Read the 'DTA-3 Define Integration & API Design' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Integration & API Design ## Objective Choose API style, versioning strategy, contract approach, external integration patterns, and inter-service communication model. --- ## Decisions to Make ### 1. API Style Choose one or hybrid: - REST — Resource-oriented, HTTP verbs, JSON. Best for: standard CRUD web apps. - GraphQL — Query language, single endpoint. Best for: complex data fetching, mobile clients. - gRPC — Binary protocol, protobuf. Best for: internal service-to-service, high throughput. - MCP (Model Context Protocol) — stdio-based, tool-oriented. Best for: AI agent integration. - Hybrid — e.g., REST for web UI + MCP for AI agents. ### 2. API Versioning Strategy Choose one: - URL path — `/api/v1/playbooks/` → simple, visible, easy to route - Header — `Accept: application/vnd.mimir.v1+json` → clean URLs - Query param — `/api/playbooks/?version=1` → easy to test - No versioning — acceptable for internal-only APIs in early stages ### 3. Contract Approach Choose one: - Contract-first — Write OpenAPI/AsyncAPI spec first, generate code from it - Code-first — Write code first, generate spec from annotations/decorators - No formal contract — acceptable for internal APIs with single consumer ### 4. External Integrations - Identify 3rd party APIs the system consumes (if any) - Define webhook patterns (inbound/outbound) - Define event bus usage (if applicable) - Define retry and error handling for external calls ### 5. Inter-Service Communication If multiple services/processes exist: - Sync (HTTP/gRPC) — Request-response. Simple but creates coupling. - Async (Message Queue) — Fire-and-forget. Decoupled but complex. - Shared Database — Both processes read/write same DB. Simple but limits scaling. - File-based — Export/import via files. Simple for batch scenarios. ### 6. Implementation Patterns (document during/after implementation) For each chosen API style, document recurring implementation patterns as they emerge: - Service-to-transport mapping — How business logic maps to API endpoints/tools. Example: thin controller/tool wrapping a service method. - Sync/async boundary — If the API layer is async but business logic is sync (or vice versa), document the bridging pattern and any pitfalls discovered. - Protocol-specific constraints — Transport-layer constraints that affect architecture. Examples: stdio pollution in MCP, CORS in REST, N+1 in GraphQL. - Shared service layer — If multiple transports (e.g., web UI + API + MCP) share business logic, document how the service layer is structured to serve all consumers. - Error propagation — How errors from the service layer translate to API responses per transport (HTTP status codes, MCP error objects, gRPC status codes). > Note: This subsection starts as placeholder during DTA. Populate it during implementation and feed findings back into SAO.md via the "Discovered Patterns" section (DTA-18). ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `API_REST` - `API_GRAPHQL` - `API_GRPC` - `API_CONTRACT` Report coverage and gaps. --- ## Deliverables - ✅ API style chosen with rationale - ✅ Versioning strategy defined - ✅ Contract approach selected - ✅ External integrations identified and patterns defined - ✅ Inter-service communication model chosen (if applicable) - ✅ Implementation patterns placeholder created (populated during/after implementation) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#4	Define Code Organization	Read the 'DTA-4 Define Code Organization' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Code Organization ## Objective Define project layout, layer separation, naming conventions, and shared library approach. This translates the logical application blocks (DTA-02) into a physical directory and file structure. --- ## Decisions to Make ### 1. Repository Strategy Choose one: - Monorepo — Single repository, all code together. Best for: small teams, shared tooling. - Polyrepo — Separate repos per service/component. Best for: independent teams, different release cycles. - Monorepo with packages — Single repo with npm/pip workspaces. Best for: shared code with clear boundaries. ### 2. Directory Structure & Layer Separation Define the top-level project layout: - Where do models live? - Where do services (business logic) live? - Where do views/controllers live? - Where do templates/frontend assets live? - Where do tests live? - Where do docs live? Example (Django): ``` project/ ├── app_name/ │ ├── models/ # Data layer │ ├── services/ # Business logic │ ├── views/ # HTTP interface (Django views) │ └── templates/ # HTML templates ├── mcp/ # MCP interface ├── tests/ # All tests ├── docs/ # Documentation └── manage.py ``` ### 3. Naming Conventions Define rules for: - Files: snake_case.py, kebab-case.html, PascalCase.tsx - Classes: PascalCase - Functions/methods: snake_case - URLs: kebab-case (`/playbooks/playbook/list/`) - Database tables: snake_case (auto from models) - Constants: UPPER_SNAKE_CASE ### 4. Shared Libraries / Common Utilities - Where do cross-cutting concerns live? (logging, error handling, decorators) - How are shared types/interfaces defined? - Import rules: what can import from `common/`? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `CODE_ORG` - `PROJECT_LAYOUT` Report coverage and gaps. --- ## Deliverables - ✅ Repository strategy chosen - ✅ Directory structure defined with layer separation - ✅ Naming conventions documented - ✅ Shared library approach defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#5	Define Data Architecture	Read the 'DTA-5 Define Data Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Data Architecture ## Objective Choose database engine, define schema strategy, select data access patterns, and plan migration and caching approaches. --- ## Decisions to Make ### 1. Database Engine Choose one (or combination): - SQLite — File-based, zero config. Best for: desktop apps, prototypes, single-user. - PostgreSQL — Full-featured relational. Best for: production web apps, complex queries. - MySQL/MariaDB — Relational, widely supported. Best for: standard web apps. - Neo4j — Graph database. Best for: relationship-heavy data, graph traversals. - MongoDB — Document store. Best for: flexible schemas, rapid prototyping. - Combination — e.g., SQLite for FOB + Neo4j for HOMEBASE. Document rationale: performance needs, data model fit, team expertise, licensing. ### 2. Schema Strategy - Migration tool: Django migrations, Alembic, Flyway, manual SQL - Versioning: How are schema changes tracked? Numbered migrations? Timestamps? - Seed data: How is initial/test data loaded? Fixtures, factories, management commands? - Schema evolution: How are breaking changes handled? Expand-contract pattern? ### 3. Data Access Patterns Choose one: - ORM — Object-Relational Mapping (Django ORM, SQLAlchemy). Best for: standard CRUD. - Repository Pattern — Abstract interface over storage. Best for: storage-agnostic design, testability. - Raw Queries — Direct SQL/Cypher. Best for: complex queries, performance-critical paths. - Hybrid — ORM for simple CRUD + raw queries for complex operations. ### 4. Read/Write Separation & Caching - Is read/write separation needed? (CQRS pattern) - Cache strategy: application-level cache, query cache, HTTP cache - Cache invalidation approach - Connection pooling configuration ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `DB_RELATIONAL` - `DB_GRAPH` - `DATA_ACCESS` Report coverage and gaps. --- ## Deliverables - ✅ Database engine chosen with rationale - ✅ Schema strategy defined (migrations, versioning, seed data) - ✅ Data access pattern selected - ✅ Caching strategy defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#6	Define Test Strategy	Read the 'DTA-6 Define Test Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Test Strategy ## Objective Define the test approach (prefer Test Trophy over Pyramid when integration-heavy), choose frameworks per layer, establish coverage targets, plan test data management, and configure CI integration for tests. Seed only: Record motivators, layer weights, and framework choices for inclusion in `docs/architecture/SAO.md` § Test Strategy via DTA-18. Do not finalize AT/E2E directory layout or step-library paths here — TFK-01 fleshes those details into the same SAO section before BPE. --- ## Decisions to Make ### 1. Trophy / Pyramid & Coverage Targets Define ratio and targets per level: - Unit tests — Isolated logic, services, utilities. Target: thin / focused coverage. - Integration tests — Views, DB queries, service interactions. Target: all CRUD paths (main bet when using Trophy). - Acceptance (AT) — BDD `.feature` scenarios; executable requirements. - E2E tests — Full user journeys via browser. Target: critical paths only. - Contract tests — API contract validation (if applicable). Define what "100% pass rate" means (all non-`@wip` tests must pass before declaring feature complete). ### 2. Frameworks per Layer Choose frameworks for each test level: - Unit: pytest, unittest, Jest, Vitest - Integration: pytest + Django test client, supertest - AT: behave-django (Django test client in steps) - E2E: Playwright, Cypress, Selenium - Contract: Pact, Schemathesis - Performance: Locust, k6, Artillery ### 3. Test Data Management - Fixtures: Static JSON/YAML fixtures loaded before tests - Factories: Dynamic data generation (factory_boy, Faker) - DB seeding: Management commands for consistent test state - Isolation: How are tests isolated? Transaction rollback? Fresh DB? - Makefile targets: `make test`, `make test-unit`, `make test-at`, `make test-e2e` ### 4. CI Integration - When do tests run? On every push? On PR? Nightly? - Failure gates: Which test failures block merge/deploy? - Test reporting: Where are results published? - Flaky test policy: How are flaky tests handled? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `TEST_UNIT` - `TEST_INTEGRATION` - `TEST_E2E` Report coverage and gaps. ### 6. Agent test lanes (when SAO §17 applies) When the project has in-app LLM agents (SAO §17 is not "Not applicable"), seed four agent test lanes in the Test Strategy section for TFK-01 to flesh out before BPE: \| Lane \| Name \| CI gate \| Assert \| \|------\|------\|---------\|--------\| \| 1 \| Control-plane proofs \| PR when `AGENTS_ENABLED=true` \| PRF-* rows + CAP-004 ScriptedLLM + run trace (`assert_agent_story`) \| \| 2 \| Deterministic shell \| PR (normal integration) \| D0 pre-filter, JSON parse, validate-before-LLM — no LLM mock \| \| 3 \| Live contract eval \| Nightly / optional CD \| temp=0, schema/contract bounds only — not PR merge gate \| \| 4 \| Task performance quality \| Promotion band \| TASK-* golden oracle vs structured ground truth \| Seed only here: record that lanes 1–2 belong in default PR quality gates when agents are enabled; lanes 3–4 use separate `agent-eval.yml` (workflow_dispatch + schedule) and do not block merge. Do not finalize PRF test file paths, `tests/support/agent_story.py`, `tests/fixtures/llm_scripts/`, Makefile targets (`test-agent-proof`, `test-agent-quality`), or pytest markers here — TFK-01 fleshes lane wiring, directory layout, and CI/Makefile integration into SAO § Test Strategy before BPE. --- ## Deliverables - ✅ Test approach (Trophy/Pyramid) defined with coverage targets - ✅ Frameworks chosen per test level - ✅ Test data management approach defined - ✅ CI integration rules established - ✅ Skill coverage assessed for this domain - ✅ Seed decision recorded for SAO.md § Test Strategy (DTA-18); TFK-01 will flesh the section before BPE - ✅ Agent test lanes seeded (when SAO §17 applies); TFK-01 will flesh lane details before BPE
#7	Define Performance & Scalability	Read the 'DTA-7 Define Performance & Scalability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Performance & Scalability ## Objective Define expected load profile, caching tiers, async processing strategy, connection pooling, scaling approach, and capacity planning. --- ## Decisions to Make ### 1. Expected Load Profile Characterize the system's expected usage: - Concurrent users: How many at peak? - Requests/sec: Expected throughput per endpoint category - Data volume: How much data at launch? At 1 year? At 5 years? - Read/write ratio: What percentage of requests are reads vs writes? - Burst patterns: Are there predictable spikes (daily, weekly, seasonal)? ### 2. Caching Tiers Define caching at each level: - Application cache: In-memory cache (Django cache framework, Redis) - CDN: Static assets, pre-rendered pages - DB query cache: Query result caching, materialized views - Session cache: Session storage (DB, Redis, cookie-based) - HTTP cache: Cache-Control headers, ETags, conditional requests For each tier: what to cache, TTL, invalidation strategy. ### 3. Async Processing - Task queues: Celery, RQ, Dramatiq — for background jobs - Workers: How many? Auto-scaling? - Use cases: Email sending, PDF generation, data import/export, AI inference - Priority queues: Critical vs. best-effort tasks ### 4. Connection Pooling - DB connections: Pool size, timeout, max overflow - HTTP clients: Connection reuse for external API calls - WebSocket connections (if applicable) ### 5. Scaling Strategy - Horizontal: Add more instances behind load balancer - Vertical: Increase instance resources (CPU, RAM) - Auto-scaling: Triggers (CPU%, request count, queue depth) - Database scaling: Read replicas, sharding, connection pooling ### 6. Capacity Planning - Baseline resource requirements - Growth projections (linear, exponential) - Cost model per scaling tier - When to re-evaluate architecture ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `PERF_CACHING` - `PERF_ASYNC` - `PERF_SCALING` Report coverage and gaps. --- ## Deliverables - ✅ Load profile characterized - ✅ Caching strategy defined per tier - ✅ Async processing approach chosen - ✅ Connection pooling configured - ✅ Scaling strategy defined - ✅ Capacity plan with cost model - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#8	Define Error Handling & Resilience	Read the 'DTA-8 Define Error Handling & Resilience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Error Handling & Resilience ## Objective Define error taxonomy, error response format, retry policies, circuit breaker patterns, graceful degradation strategy, and idempotency requirements. --- ## Decisions to Make ### 1. Error Taxonomy Classify errors into categories: - Domain errors — Business rule violations (e.g., "Cannot delete released playbook") - Validation errors — Input validation failures (e.g., "Name is required") - Infrastructure errors — DB connection lost, disk full, OOM - External service errors — 3rd party API timeout, rate limit exceeded - Authentication/Authorization errors — Invalid session, insufficient permissions For each category: how is it logged, how is it presented to the user, what's the HTTP status code? ### 2. Error Response Format Define a standard error envelope: ```json { "error": { "code": "PLAYBOOK_NOT_FOUND", "message": "Playbook with ID abc-123 does not exist", "details": {}, "request_id": "req-xyz-789" } } ``` Decide: - Standard error codes (enum or free-text?) - User-facing messages (localization needed?) - Technical details (shown in dev, hidden in prod?) - Correlation/request IDs for tracing ### 3. Retry Policies For each type of retriable operation: - Which operations are retriable? (network calls, DB transactions, queue publish) - Backoff strategy: linear, exponential, jitter - Max attempts before giving up - Dead letter queue for permanently failed operations ### 4. Circuit Breakers For external service dependencies: - Failure threshold before circuit opens (e.g., 5 failures in 30 seconds) - Fallback behavior when circuit is open - Half-open recovery: how and when to retry - Monitoring: how to alert on open circuits ### 5. Graceful Degradation - Which features can operate in degraded mode? - How are users notified of degraded functionality? - Fallback data sources (cached data, default values) - Feature flags for emergency feature disabling ### 6. Idempotency - Which write operations must be idempotent? (payment processing, data import) - How is idempotency ensured? (idempotency keys, upsert patterns, deduplication) - Timeout handling: what happens if a request times out but the operation completed? ### 7. Scan Skills Query Playbook Skills where `capability_domain` in: - `ERR_HANDLING` - `ERR_RESILIENCE` - `ERR_RETRY` Report coverage and gaps. --- ## Deliverables - ✅ Error taxonomy defined with handling rules per category - ✅ Error response format standardized - ✅ Retry policies defined for retriable operations - ✅ Circuit breaker patterns defined (if applicable) - ✅ Graceful degradation strategy documented - ✅ Idempotency requirements identified - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#9	Define Infrastructure	Read the 'DTA-9 Define Infrastructure' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Infrastructure ## Objective Define the local development environment, cloud provider and compute model, networking setup, and Infrastructure as Code tooling. --- ## Decisions to Make ### 1. Local Development Environment - Containerization: Docker, Podman, or native? - Dev/prod parity: How close is local to production? - Makefile targets: `make provision` (install all deps), `make run` (start everything) - Required tools: Which CLI tools, SDKs, runtimes must be installed? - Environment variables: How are they managed locally? (.env file, direnv) ### 2. Cloud Provider & Compute Model Choose compute model: - Kubernetes (EKS/GKE/AKS) — Container orchestration. Best for: complex deployments, auto-scaling. - Container service (ECS/Cloud Run) — Managed containers. Best for: simpler container deployments. - Serverless (Lambda/Cloud Functions) — Event-driven functions. Best for: sporadic workloads. - VMs (EC2/Compute Engine) — Traditional. Best for: legacy apps, specific OS needs. - PaaS (Heroku/Railway/Render) — Managed platform. Best for: fast start, less ops overhead. - Desktop only — No cloud. Best for: single-user desktop applications. ### 3. Networking - VPC: Network isolation, subnets (public/private) - DNS: Domain management, Route53/Cloudflare - Load balancing: ALB/NLB, health checks, SSL termination - CDN: Static asset distribution, edge caching ### 4. Infrastructure as Code Choose one: - AWS CDK — TypeScript/Python, AWS-native. Best for: AWS-only, programmatic infra. - Terraform — HCL, multi-cloud. Best for: cloud-agnostic, declarative. - Pulumi — General-purpose languages. Best for: developers who prefer Python/TS. - CloudFormation — YAML/JSON, AWS-native. Best for: simple AWS setups. - None — Manual/console setup. Best for: prototypes, desktop apps. ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `INFRA_LOCAL` - `INFRA_CLOUD` - `INFRA_K8S` Report coverage and gaps. --- ## Deliverables - ✅ Local dev environment defined with provisioning instructions - ✅ Cloud provider & compute model chosen with rationale - ✅ Networking architecture defined - ✅ IaC tool selected - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#10	Define CI/CD Pipeline	Read the 'DTA-10 Define CI/CD Pipeline' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define CI/CD Pipeline ## Objective Choose CI platform, define pipeline stages, configure artifact registry, set promotion gates, and establish trunk-based development flow. --- ## Decisions to Make ### 1. CI Platform Choose one: - GitHub Actions — GitHub-native, YAML workflows. Best for: GitHub-hosted repos. - GitLab CI — GitLab-native, `.gitlab-ci.yml`. Best for: GitLab-hosted repos. - Jenkins — Self-hosted, Groovy pipelines. Best for: complex custom pipelines. - CircleCI — Cloud-hosted, YAML config. Best for: fast builds, Docker-native. - None — Local-only builds. Best for: desktop apps, early prototypes. ### 2. Pipeline Stages Define the standard pipeline stages: ``` lint → test → build → publish → deploy ``` For each stage: - What runs? (commands, scripts) - What triggers it? (push, PR, tag, manual) - What blocks the next stage? (failure criteria) - Estimated duration target ### 3. Artifact Registry - Container images: Docker Hub, ECR, GCR, GitHub Container Registry - Packages: npm registry, PyPI, private registry - Build artifacts: S3, GCS, artifact storage in CI platform - Retention policy: How long are artifacts kept? ### 4. Promotion Gates - Automated gates: All tests pass, linting clean, security scan clean - Manual gates: Human approval for production deploy - Environment promotion: dev → staging → production - Rollback trigger: Automated on health check failure? Manual only? ### 5. Trunk-Based Development Flow - Branch strategy: Trunk-based (short-lived feature branches, merge to main) - PR requirements: Reviews, CI pass, no conflicts - Merge strategy: Squash, rebase, merge commit - Release tagging: Semantic versioning, automated changelog ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `CICD_BUILD` - `CICD_DEPLOY` - `CICD_PIPELINE` Report coverage and gaps. --- ## Deliverables - ✅ CI platform chosen - ✅ Pipeline stages defined with triggers and gates - ✅ Artifact registry configured - ✅ Promotion gates established - ✅ Trunk-based flow documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#11	Define Release & Rollback	Read the 'DTA-11 Define Release & Rollback' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Release & Rollback ## Objective Choose deployment strategy, define version tagging, establish rollback triggers and procedures, and set release cadence. --- ## Decisions to Make ### 1. Deployment Strategy Choose one: - Blue-Green — Two identical environments, switch traffic. Best for: zero-downtime, instant rollback. - Canary — Gradual traffic shift to new version. Best for: risk mitigation, large user base. - Rolling Update — Replace instances one by one. Best for: K8s default, resource-efficient. - Recreate — Stop old, start new. Best for: stateful apps, dev environments. - Feature Flags — Deploy code dark, enable via flags. Best for: decoupling deploy from release. ### 2. Version Tagging & Changelog - Semantic Versioning: MAJOR.MINOR.PATCH - Tagging: Git tags on release commits - Changelog generation: Automated from commit messages (conventional commits) - Release notes: Automated or manual? Where published? ### 3. Rollback Triggers - Automated: Health check failures, error rate spike, latency threshold - Manual: Operator decision, customer report - Rollback procedure: Revert traffic? Redeploy previous version? DB rollback? - Rollback time target: How fast must rollback complete? ### 4. Release Cadence & Policies - Cadence: Continuous delivery (every merge)? Weekly? Sprint-aligned? - Freeze policies: Code freeze before major releases? - Hotfix process: How are urgent fixes deployed outside normal cadence? - Communication: Who is notified of releases? How? ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `RELEASE_DEPLOY` - `RELEASE_ROLLBACK` Report coverage and gaps. --- ## Deliverables - ✅ Deployment strategy chosen with rationale - ✅ Version tagging and changelog approach defined - ✅ Rollback triggers and procedures established - ✅ Release cadence and policies documented - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#12	Define Observability	Read the 'DTA-12 Define Observability' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Observability ## Objective Define logging, metrics, distributed tracing, dashboards, alerting, and incident response approach. --- ## Decisions to Make ### 1. Logging - Format: Structured logging (JSON) vs. plain text - Library: Python logging, structlog, loguru - Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL — when to use each - Aggregation: CloudWatch, ELK stack, Loki, local file rotation - Retention: How long are logs kept? Per environment? - Sensitive data: What must NOT be logged? (passwords, tokens, PII) ### 2. Metrics - Application metrics: Request count, response time, error rate, queue depth - Infrastructure metrics: CPU, memory, disk, network - Business metrics: Features used, user actions, conversion rates - Tools: Prometheus, CloudWatch Metrics, Datadog, StatsD - Naming convention: `app.request.duration`, `app.db.query.count` ### 3. Distributed Tracing - Correlation IDs: How are requests traced across services/processes? - Span collection: OpenTelemetry, Jaeger, Zipkin, X-Ray - Trace sampling: Sample all requests or a percentage? - Trace context propagation: How are trace IDs passed between services? ### 4. Dashboards & Alerting - Dashboard tool: Grafana, CloudWatch Dashboards, Datadog - SLIs/SLOs: Service Level Indicators and Objectives - e.g., "99.9% of requests complete in < 500ms" - e.g., "Error rate < 0.1%" - Alert channels: Email, Slack, PagerDuty, OpsGenie - Alert severity levels: P1 (page immediately) through P4 (review next day) ### 5. Incident Response - Runbooks: Standard operating procedures for common incidents - Postmortems: Blameless postmortem template and cadence - On-call rotation: Who is on call? How are they reached? - Escalation path: P1 → on-call → team lead → management ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `OBS_LOGGING` - `OBS_METRICS` - `OBS_TRACING` Report coverage and gaps. --- ## Deliverables - ✅ Logging strategy defined (format, aggregation, retention) - ✅ Metrics approach chosen (tools, naming, key metrics) - ✅ Distributed tracing configured (if applicable) - ✅ Dashboards & alerting defined (SLIs/SLOs, alert channels) - ✅ Incident response procedures established - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#13	Define Config & Secrets	Read the 'DTA-13 Define Config & Secrets' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Config & Secrets ## Objective Define environment configuration strategy, secrets management, feature flag approach, and per-environment overrides. --- ## Decisions to Make ### 1. Environment Configuration - Config source: Environment variables, config files (.env, YAML, TOML), Django settings - Per-environment overrides: How do dev/staging/prod configs differ? - Config validation: Are required configs validated at startup? - Config documentation: Where are all config options documented? Example patterns: ``` # .env file (local) DEBUG=True DATABASE_URL=sqlite:///db.sqlite3 SECRET_KEY=dev-only-key # Production (env vars from secrets manager) DEBUG=False DATABASE_URL=postgresql://... SECRET_KEY=<from-vault> ``` ### 2. Secrets Management Choose approach: - Environment variables — Simple, works everywhere. Risk: leakage in logs/errors. - Secrets manager — AWS Secrets Manager, HashiCorp Vault, Azure Key Vault. Best for: production. - Sealed secrets — Encrypted in Git, decrypted in cluster. Best for: GitOps. - .env files — Local only, gitignored. Best for: development. - Django's SECRET_KEY rotation — How often? How to rotate without downtime? ### 3. Feature Flags - Approach: Config-based, database-based, external service (LaunchDarkly, Unleash) - Flag types: Boolean (on/off), percentage rollout, user segment - Management: Who can toggle flags? Via UI, CLI, API? - Cleanup: How are stale flags removed? ### 4. Scan Skills Query Playbook Skills where `capability_domain` in: - `CONFIG_ENV` - `CONFIG_SECRETS` - `CONFIG_FLAGS` Report coverage and gaps. --- ## Deliverables - ✅ Environment configuration strategy defined - ✅ Secrets management approach chosen - ✅ Feature flag approach defined (if applicable) - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#14	Define Security	Read the 'DTA-14 Define Security' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Security ## Objective Define authentication model, authorization approach, API security measures, dependency scanning, and OWASP compliance targets. --- ## Decisions to Make ### 1. Authentication Model Choose one: - Session-based — Server-side sessions, cookie-based. Best for: traditional web apps. - JWT — Stateless tokens. Best for: SPAs, mobile apps, microservices. - OAuth2/OIDC — Delegated auth via provider. Best for: SSO, social login. - API keys — Simple key-based auth. Best for: machine-to-machine. - mTLS — Mutual TLS. Best for: service-to-service in zero-trust. Decide: - Password hashing algorithm (bcrypt, Argon2, PBKDF2) - Session/token lifetime and refresh strategy - MFA requirements (if any) - Password complexity rules ### 2. Authorization Model Choose one: - RBAC — Role-Based Access Control. Roles → Permissions. Best for: most web apps. - ABAC — Attribute-Based Access Control. Policy rules on attributes. Best for: complex permission logic. - Object-level — Per-object ownership checks. Best for: multi-tenant apps. - Hybrid — RBAC for coarse-grained + object-level for fine-grained. Define permission model: - What roles exist? - What can each role do? - How are permissions checked in code? (decorators, middleware, service layer) ### 3. API Security - Rate limiting: Per-user, per-endpoint, per-IP - CORS: Allowed origins, methods, headers - Input validation: Where validated? (serializer, model, view) - CSRF protection: Tokens, SameSite cookies - Content Security Policy: CSP headers configuration ### 4. Dependency Scanning - Tool: Dependabot, Snyk, pip-audit, npm audit, Trivy - Cadence: On every PR? Nightly? Weekly? - Policy: Block merge on critical CVEs? Warning only? - License compliance: Check for incompatible licenses? ### 5. OWASP Compliance Target OWASP Top 10 coverage: - A01: Broken Access Control - A02: Cryptographic Failures - A03: Injection - A05: Security Misconfiguration - A07: Identification and Authentication Failures For each: current mitigation strategy. ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `SEC_AUTH` - `SEC_AUTHZ` - `SEC_API` - `SEC_SCAN` Report coverage and gaps. --- ## Deliverables - ✅ Authentication model chosen with configuration details - ✅ Authorization model defined with role/permission structure - ✅ API security measures configured - ✅ Dependency scanning tool and policy established - ✅ OWASP compliance targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#15	Define Backup & Recovery	Read the 'DTA-15 Define Backup & Recovery' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Backup & Recovery ## Objective Define backup schedule, retention policy, RTO/RPO targets, disaster recovery plan, and data export/import procedures. --- ## Decisions to Make ### 1. Backup Schedule & Retention - Backup frequency: Hourly, daily, weekly, continuous (WAL archiving) - Backup type: Full, incremental, differential - Retention policy: How long are backups kept? - Daily backups: keep 7 days - Weekly backups: keep 4 weeks - Monthly backups: keep 12 months - Storage: Where are backups stored? (S3, GCS, local disk, off-site) - Encryption: Are backups encrypted at rest? ### 2. RTO & RPO Targets - RPO (Recovery Point Objective): Maximum acceptable data loss - e.g., "15 minutes" means we can lose at most 15 minutes of data - RTO (Recovery Time Objective): Maximum acceptable downtime - e.g., "1 hour" means the system must be restored within 1 hour - These targets drive backup frequency and recovery procedure complexity ### 3. Disaster Recovery Plan - Failover: Automatic or manual? - Geo-redundancy: Multi-region, multi-AZ, single region? - Recovery procedure: Step-by-step restoration from backup - DR testing: How often is the recovery procedure tested? - Communication plan: Who is notified during a disaster? ### 4. Data Export/Import - Export formats: JSON, CSV, SQL dump, custom format - Export triggers: Manual, scheduled, API-driven - Import validation: How is imported data validated? - Makefile targets: `make backup`, `make restore`, `make export-data` ### 5. Scan Skills Query Playbook Skills where `capability_domain` in: - `BACKUP_DB` - `BACKUP_DR` Report coverage and gaps. --- ## Deliverables - ✅ Backup schedule and retention policy defined - ✅ RTO/RPO targets set with rationale - ✅ Disaster recovery plan documented - ✅ Data export/import procedures defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#16	Define Developer Experience	Read the 'DTA-16 Define Developer Experience' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Developer Experience ## Objective Define IDE setup, code quality tooling, local debugging approach, onboarding flow, and inner loop speed targets. --- ## Decisions to Make ### 1. IDE Setup - Recommended IDE: VS Code, PyCharm, Cursor, Windsurf, etc. - Extensions/plugins: Which are required? Which are recommended? - Workspace settings: Shared `.vscode/settings.json` or `.idea/` config - Debug configurations: Launch configs for backend, frontend, tests - AI assistant config: MCP server configuration for Mimir integration ### 2. Code Quality Tooling - Linter: flake8, ruff, pylint, eslint - Formatter: black, ruff format, prettier - Type checker: mypy, pyright - Pre-commit hooks: Which checks run before commit? - Configuration files: `pyproject.toml`, `.flake8`, `.prettierrc` - Makefile targets: `make lint`, `make format`, `make typecheck` ### 3. Local Debugging - Breakpoint debugging: IDE debugger, pdb, ipdb - Log tailing: How to watch logs in real-time during development - DB inspection: Django admin, DB browser, management commands - Network inspection: How to inspect HTTP requests (Django Debug Toolbar) - Test debugging: How to run and debug individual tests ### 4. Onboarding - README: What must be in the root README for a new developer? - `make provision`: Single command to install all prerequisites - `make run`: Single command to start the full application - Time-to-first-feature target: "New developer ships first feature within X hours" - Onboarding checklist: Step-by-step from `git clone` to running tests ### 5. Inner Loop Speed - Hot reload: Auto-restart on file changes (Django runserver, webpack HMR) - Incremental builds: Only rebuild what changed - Test watch mode: Auto-run affected tests on save - Build performance: Target build times per operation ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DEVEX_IDE` - `DEVEX_QUALITY` - `DEVEX_ONBOARD` Report coverage and gaps. --- ## Deliverables - ✅ IDE setup documented with recommended extensions and debug configs - ✅ Code quality tooling configured (linter, formatter, pre-commit) - ✅ Local debugging approach defined - ✅ Onboarding flow documented with time-to-first-feature target - ✅ Inner loop speed targets set - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#17	Define Documentation Strategy	Read the 'DTA-17 Define Documentation Strategy' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define Documentation Strategy ## Objective Define Architecture Decision Record (ADR) process, API documentation approach, living documentation standards, runbook format, and knowledge base structure. --- ## Decisions to Make ### 1. Architecture Decision Records (ADRs) - Template: Standard ADR format (Title, Status, Context, Decision, Consequences) - Storage location: `docs/architecture/decisions/` or `docs/adr/` - Numbering: Sequential (ADR-001, ADR-002, ...) - Review process: PR-based? Team discussion? Informal? - When to write: Any significant architecture or technology choice ### 2. API Documentation - Approach: OpenAPI/Swagger spec generation - Generation: Contract-first (write spec, generate code) or code-first (generate spec from code) - Publishing: Auto-published on build? Swagger UI endpoint? - MCP tool documentation: How are MCP tools documented? - Versioning: Spec versioned with API version ### 3. Living Documentation - Code comments policy: When to comment (non-obvious logic), when NOT to comment (obvious code) - Docstring standards: Sphinx format with `:param:`, `:return:`, `:raises:` and examples - Type hints: Required on all public methods and functions - README hierarchy: Root README → app-level READMEs → module docs ### 4. Runbook Standards - Format: Markdown with structured sections (Trigger, Impact, Steps, Verification) - Storage: `docs/runbooks/` or alongside infrastructure code - Update cadence: After every incident that reveals a gap - Review: Quarterly runbook review for staleness ### 5. Knowledge Base - Wiki: GitHub Wiki, Confluence, Notion, or docs/ in repo - Onboarding guides: For new developers, new operators - FAQ: Common questions and troubleshooting - Search: How is documentation discoverable? ### 6. Scan Skills Query Playbook Skills where `capability_domain` in: - `DOCS_ADR` - `DOCS_API` - `DOCS_RUNBOOK` Report coverage and gaps. --- ## Deliverables - ✅ ADR process established with template and storage location - ✅ API documentation approach chosen - ✅ Living documentation standards defined (comments, docstrings, type hints) - ✅ Runbook standards set - ✅ Knowledge base structure defined - ✅ Skill coverage assessed for this domain - ✅ Decision recorded for inclusion in SAO.md (DTA-18)
#18	Define MCP Architecture	Read the 'DTA-18 Define MCP Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define MCP Architecture Condition: Run only if the system exposes tools or resources via the Model Context Protocol. Skip and write "Not applicable" in SAO §18 if MCP is not in scope. Depends on DTA-03 (API style chosen). Reference: Playbook artifact MCP FastMCP Reference Architecture (latest released Edda version). ## Objective Decide the MCP integration case (A / B / hybrid), transport topology, tool inventory, and authentication pattern; document all decisions in SAO §18. ## Process 1. Fetch the latest MCP FastMCP Reference Architecture from the playbook and read the Purpose & Mission Assessment sections before answering any question below. 2. Answer mission questions — determine integration case and transport. 3. Inventory tools — decide which service callables become MCP tools. 4. Design auth pattern — process user, PAT per call, or both. 5. Handle stdout hygiene if stdio transport is selected. 6. Record decisions for SAO §18. ## Decisions to Make ### 1. Mission Assessment (Q1–Q7) \| # \| Question \| Answer \| Impact \| \|---\|----------\|--------\|--------\| \| Q1 \| Who are the MCP clients? (AI IDE, Claude Desktop, custom script, cloud AI) \| \| Transport and auth \| \| Q2 \| Embed business logic or delegate to HTTP API? \| \| Case A vs B vs hybrid \| \| Q3 \| How is user identity established per tool call? \| \| Auth pattern \| \| Q4 \| Are any tools destructive? (write, delete, deploy) \| \| HITL and write-tool policy \| \| Q5 \| Low-latency local IDE integration required? \| \| stdio transport \| \| Q6 \| Multi-tenant or remote-client access required? \| \| HTTP+SSE transport \| \| Q7 \| Stdout logging interference needs prevention? \| \| Log routing for stdio \| ### 2. Integration Case - [ ] Case A — Service Bridge: MCP calls internal service layer directly. Best for single-deployment systems. - [ ] Case B — API Facade: MCP calls the public HTTP API. Best for multi-tenant / remote clients. - [ ] Hybrid: Mix of A and B. Rationale: _____ ### 3. Transport Topology \| Target \| Transport \| Port / Path \| Notes \| \|--------\|-----------\|-------------\|-------\| \| Local IDE (Cursor, Claude Desktop) \| stdio \| n/a \| Requires stdout hygiene \| \| Remote AI clients \| HTTP+SSE \| :8001/mcp \| Auth header required \| Topology decision: stdio only / HTTP+SSE only / Both (dual server) ### 4. Tool Inventory \| Tool name \| Service method \| Write? \| HITL? \| Case \| \|-----------\|----------------\|--------\|-------\|------\| \| \| \| \| \| \| Write-tool policy: Require explicit confirmation param / HITL prompt before execute / Audit log only ### 5. Authentication Pattern Selected pattern(s): Process user / PAT per call / Session cookie / Mixed PAT injection point: Tool argument (explicit) / HTTP header (Bearer — avoids prompt injection) ### 6. Stdout Hygiene (if stdio) - Redirect all logging to stderr or file - Suppress third-party libraries that print to stdout - Add T3 test verifying no stdout noise on server boot ### 7. Case B: API Readiness Contract (if Case B or hybrid) \| Tool \| HTTP endpoint \| Method \| Auth header \| \|------\|---------------\|--------\|-------------\| \| \| \| \| \| ### 8. Scan Skills Query Skills where `capability_domain` in: MCP, API_INTEGRATION, AUTH. Report gaps. ## Deliverables - Mission questions answered (Q1–Q7) - Integration case chosen (A / B / hybrid) with rationale - Transport topology defined - Tool inventory table (tool → service method → write? → HITL?) - Auth pattern defined with injection point - Stdout hygiene addressed (if stdio) - API readiness contract defined (if Case B) - Skill coverage assessed - Decision recorded for SAO §18 (DTA-18)
#19	Define AI Agent Architecture	Read the 'DTA-19 Define AI Agent Architecture' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. # Define AI Agent Architecture Condition: Run only if the system has in-app LLM agents (agentic loops, plan/worker execution, or LLM calls inside the application). Skip and write "Not applicable" in SAO §17 if none of: in-app agentic loop, LLM calls initiated by the app, plan/worker execution. Reference: Playbook artifact AI Agent Reference Architecture (latest released Edda version). ## Objective Confirm components (Part 1), pick design patterns and scenarios (Part 2), choose serving mode (Part 3), select capabilities (`CAP-xxx`), choose an assembly template, and record decisions in SAO §17. ## Process 1. Fetch the latest AI Agent Reference Architecture from the playbook. 2. Read How to use this document and Part 1 — Components; complete infra, model, vector (if needed), framework, memory, and observability checklist in SAO §17. 3. Pick Part 2 — Design patterns and primary SC-xx scenario(s); use Part 5 — Quick reference for secondary CAP additions. 4. Choose Part 3 — Serving mode (real-time, batch/queue, or both). 5. Copy required + chosen optional CAP-IDs into SAO §17 from Part 4.1 Capability table. 6. Confirm dependencies in Part 4.3 Module wiring. 7. Note starting assembly template from Part 4.4 (T-01, T-02, T-03, or T-00 custom). 8. Name integration proof test IDs (`PRF-SCxx-xx`, `PRF-OBS-01`) from Part 4.5 as DoD gate. 9. If both SC-02 and SC-05 are selected, read Pattern 5 · SC-02 × SC-05 · Full rescan invariants and record checklist in SAO §17. 10. If Pattern 4 / SC-01 with large domain state, decide dual execution path (CAP-037, CAP-038, CAP-039) and memory tiers (Component 5 / CAP-091–094). 11. Record Pattern 4 anti-pattern checklist (mechanical step execution; worker failure bridge) when CAP-060 selected. 12. Record decisions for SAO §17 via Write SAO.md (Activity 59). ## Decisions to Make ### 1. Infra layer (Component 1) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| LLM provider \| anthropic / openai / ollama / … \| \| \| Ollama readiness probe at startup \| Yes / No / N/A \| \| \| Broker + result backend (CAP-060) \| Configured / N/A \| \| \| Secrets server-side only \| Yes \| \| ### 2. Vector tier (Component 3) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Vector store needed \| Yes / No \| \| \| Backend \| pgvector / dedicated / in-process \| \| \| CAP-090 / CAP-094 selected \| Yes / No \| \| ### 3. Design pattern & scenario selection Read Part 2 pattern sections before ticking. Record primary scenario(s) and rationale. \| SC-ID \| Pattern \| Name \| Selected? \| Rationale \| \|-------\|---------\|------\|-----------\|-----------\| \| SC-01 \| 4 \| Conversational planner \| \| \| \| SC-02 \| 2 \| Field extractor / batch ingest \| \| \| \| SC-03 \| 7 \| Compiled pipeline \| \| \| \| SC-04 \| 3 \| Event-driven nudge \| \| \| \| SC-05 \| 5 \| Governed mutations \| \| \| ### 4. Serving mode (Part 3) \| Mode \| Selected? \| CAP-IDs \| \|------\|-----------\|---------\| \| Real-time (3.1) \| \| CAP-040, CAP-003, CAP-100 \| \| Batch / queue (3.2) \| \| CAP-060–066 \| \| Observability for serving (3.3) \| \| CAP-101, CAP-100 \| ### 5. Dual execution path (Pattern 4 / SC-01 with large state) \| Decision \| Choice \| Rationale \| \|----------\|--------\|-----------\| \| Context snapshot in chat (CAP-037) \| Yes / No \| \| \| Snapshot invalidation on writes (CAP-038) \| Yes / No \| \| \| Mutation-only tools in conversation (CAP-039) \| Yes / No \| \| \| Full tool registry in plan worker only \| Yes / No \| \| ### 6. Memory tiers (Component 5) \| Tier \| CAP-IDs \| Selected? \| Rationale \| \|------\|---------\|-----------\|-----------\| \| 1 Hot snapshot \| 037, 038, 039 \| \| \| \| 2 Semantic search \| 091 \| \| \| \| 3 AI profile \| 092 \| \| \| \| 4 Reference library \| 094, 090 \| \| \| \| 5 Entity notes \| 093 \| \| \| ### 7. Capability checklist From Part 4.1 — tick every CAP your project implements: \| CAP-ID \| Name \| Required for SC? \| Implement? \| Module path in project \| \|--------\|------\|------------------\|------------\|------------------------\| \| CAP-001 \| LLM Port protocol \| \| \| \| \| CAP-037 \| Context snapshot hydration \| \| \| \| \| CAP-038 \| Snapshot invalidation hooks \| \| \| \| \| CAP-039 \| Dual tool exposure \| \| \| \| \| CAP-091 \| Semantic context search \| \| \| \| \| CAP-092 \| AI-managed profile memory \| \| \| \| \| CAP-093 \| Entity notes graph \| \| \| \| \| CAP-094 \| Reference knowledge library \| \| \| \| \| CAP-101 \| Agent interaction trace \| \| \| \| \| … \| (copy remaining rows for each selected CAP) \| \| \| \| Minimum: all required CAP-IDs from your selected SC-xx row in Part 5 — Scenario index. ### 8. Assembly template - [ ] T-01 Planner (SC-01 / Pattern 4) - [ ] T-02 Field (SC-02 / Pattern 2) - [ ] T-03 Pipeline (SC-03) - [ ] T-00 Custom — list CAP-IDs: _______________ ### 9. Agent identities (CAP-121, CAP-122) \| Identity \| Role \| Model tier \| Allowed tools \| \|----------\|------\|------------\|---------------\| \| \| \| planning / execution / field \| \| ### 10. Agent Blackboard (if CAP-070 selected) - Durability tier: A — in-process / B — run-persistent - Schema keys: phase, hypothesis, current_plan, last_actions, next_intent - Max board size (chars): ______ ### 11. Worker anti-patterns (if CAP-060 selected) - [ ] Worker uses LLM per step (CAP-054) — not mechanical tool script (Pattern 4 anti-patterns) - [ ] Worker failure bridged to UI (CAP-100 plan_failed and/or chat context injection) - [ ] PRF-SC01-06 mapped if hybrid worker is new ### 12. Observability (Component 6 / CAP-101) - correlation_id header/name: ______ - Cost rate table location: ______ - PRF-OBS-01 test file: ______ ### 13. Integration proof (DoD gate) \| PRF ID \| Scenario \| Test file \| Selected? \| \|--------\|----------\|-----------\|-----------\| \| PRF-SC02-01 \| SC-02 thinking JSON \| \| \| \| PRF-SC02-02 \| SC-02 parse fail loud \| \| \| \| PRF-SC02-03 \| SC-02 domain D0 pre-filter \| \| \| \| PRF-SC02-04 \| SC-02 D1 parse fail loud \| \| \| \| PRF-SC01-01 \| SC-01 plan handoff \| \| \| \| PRF-SC01-02 \| SC-01 429 retry \| \| \| \| PRF-SC01-03 \| SC-01 blackboard retain \| \| \| \| PRF-SC01-04 \| SC-01 dual tool exposure \| \| \| \| PRF-SC01-05 \| SC-01 snapshot invalidation \| \| \| \| PRF-SC01-06 \| SC-01 no mechanical worker \| \| \| \| PRF-SC01-07 \| SC-01 worker failure bridge \| \| \| \| PRF-SC05-01 \| SC-05 HITL \| \| \| \| PRF-SC05-02 \| SC-02+05 full rescan invariants \| \| \| \| PRF-OBS-01 \| all \| correlation + usage trace \| \| \| ### 14. SC-02 × SC-05 full rescan (if both selected) From Pattern 5 · SC-02 × SC-05 · Full rescan invariants: - [ ] Rescan delete ops meet auto-apply confidence threshold (or rescan disables partial auto-apply) - [ ] ChangeSet apply ordering: deletes → updates → adds when rescan flag is set - [ ] PRF-SC05-02 mapped to integration test file ### 15. Scan Skills Query Skills where `capability_domain` in: AI_AGENT, LLM_INTEGRATION, ASYNC_TASK, OBSERVABILITY. Report gaps. ### 16. Task performance quality (TASK-) From artifact 56 Part 4.6 — Task performance quality. Mirror the Part 4.5 Integration proof* table style. These are lane 4 evals — measure model + prompt + tools against structured ground truth, not orchestration wiring (lane 1) or deterministic parse/validate (lane 2). \| TASK ID \| Scenario \| Oracle type \| Pass band \| Selected? \| Test file \| \|---------\|----------\|-------------\|-----------\|-----------\|-----------\| \| TASK-SC02-01 \| SC-02 \| set_recall \| recall ≥ 0.95, extras ≤ 1 \| \| \| \| TASK-SC02-02 \| SC-02 \| graph_diff \| zero unexpected deletes on rescan corpus \| \| \| \| TASK-SC01-01 \| SC-01 \| plan_steps \| expected tool sequence + final state \| \| \| \| TASK-SC05-01 \| SC-05 \| hitl_rate \| destructive ops blocked until approval \| \| \| \| … \| (copy remaining Part 4.6 rows for selected SC-xx) \| \| \| \| \| Eval vs merge DoD: \| Gate \| Lanes \| When \| Blocks merge? \| \|------\|-------\|------\|---------------\| \| Merge DoD \| 1–2 \| PR when `AGENTS_ENABLED=true` \| Yes — PRF-* under CAP-004 ScriptedLLM; lane 2 deterministic shell in normal integration \| \| Contract eval \| 3 \| Nightly / optional CD cert \| No — temp=0 schema/contract bounds only \| \| Promotion DoD \| 4 \| `make test-agent-quality` / scheduled eval \| No — regression vs last certified TASK-* band; human promotion decision \| Record chosen TASK rows, fixture paths (`tests/fixtures/agent_tasks/<task-id>/`), and certified pass bands in SAO §17. Full catalog fields (`fixture_ref`, `n_runs`, oracle asserts) live in artifact 56 Part 4.6 — link there; do not duplicate prose in SAO. ## Deliverables - Infra + vector tier decisions documented - Primary pattern(s) and SC-xx scenario(s) chosen with rationale - Serving mode (Part 3) selected - Dual execution path + memory tier decisions (when Pattern 4 / SC-01) - CAP-ID checklist complete for selected scenarios - Assembly template (T-01 / T-02 / T-03 / T-00) named - Agent identities + model tiers documented - Worker anti-pattern checklist completed (when CAP-060) - Observability trace documented (CAP-101) - PRF test IDs mapped to project test files - TASK-* rows mapped to golden task fixtures (when lane 4 in scope) - SC-02 × SC-05 rescan checklist completed (when both scenarios selected) - Skill coverage assessed - Decision recorded for SAO §17 via Write SAO.md (Activity 59)
#20	Write SAO.md	Read the 'DTA-20 Write SAO.md' activity from playbook 'Junior Edda' (workflow 'Define Architecture'). Follow its guidance when assisting me. Position in workflow: Terminal activity of Define Architecture (DTA) — order 20 of 20. Run only after all prior DTA domain activities are complete (DTA-02 through DTA-17, and when applicable DTA-19 AI Agent Architecture and DTA-20 MCP Architecture). # Write SAO.md (System Architecture Overview) ## Objective Compile all architectural decisions from DTA-02 through DTA-17 (and optionally DTA-19 and DTA-20 if applicable) into a single, authoritative document: `docs/architecture/SAO.md`. ## Process ### 1. Gather All Decisions Collect recorded decisions from each domain activity: - DTA-02: Application Blocks - DTA-03: Integration & API Design - DTA-04: Code Organization - DTA-05: Data Architecture - DTA-06: Test Strategy - DTA-07: Performance & Scalability - DTA-08: Error Handling & Resilience - DTA-09: Infrastructure - DTA-10: CI/CD Pipeline - DTA-11: Release & Rollback - DTA-12: Observability - DTA-13: Config & Secrets - DTA-14: Security - DTA-15: Backup & Recovery - DTA-16: Developer Experience - DTA-17: Documentation Strategy - DTA-19: AI Agent Architecture (if applicable) - DTA-20: MCP Architecture (if applicable) ### 2. Write SAO.md Structure — add sections 17 and 18 after section 16: ``` ## 16. Documentation Strategy [Decision from DTA-17] ## 17. AI Agent Architecture [Decision from DTA-19 — skip section if no in-app agent] ## 18. MCP Architecture [Decision from DTA-20 — skip section if no MCP interface] ``` ### 3. Skill Gap Analysis Compile coverage reports from all domain activities into a single matrix: ``` Domain \| Covered Skills \| Gaps Application Blocks \| [list] \| [list] ... AI Agent Architecture \| [list] \| [list] MCP Architecture \| [list] \| [list] ``` ### 4. Review with User Present SAO.md for review. Get explicit approval before proceeding to Bootstrap Project. ### 5. Post-Implementation Updates The SAO is a living document. During and after implementation, update it with critical discoveries, retrospective corrections, and recurring patterns. Each update should reference the original DTA decision. ## Deliverables - SAO.md written at `docs/architecture/SAO.md` - All domain decisions (16 core + up to 2 optional: AI Agent, MCP) compiled - Skill coverage report included - Key decisions summary with rationale - User approval obtained - Ready to proceed to Define Software Process (DSP). DSP requires SAO.md to generate the AI IDE configuration — run DSP before BSP. When ESM, DTA, DSP, and BSP are all complete, proceed to BSP-08 for the Construction Handoff and mode selection.
Test Automation Framework
#1	Define Test Architecture	Read the 'TFK-1 Define Test Architecture' activity from playbook 'Junior Edda' (workflow 'Test Automation Framework'). Follow its guidance when assisting me. # Define Test Architecture ## Objective Consume DTA-06 "Define Test Strategy" decisions (already seeded into `docs/architecture/SAO.md` § Test Strategy) and flesh out that SAO section with the project's Test Trophy model, runner mapping, coverage policy, directory layout, and zero-bug / zero-length-feedback workflow. Authoritative output: update `docs/architecture/SAO.md` § Test Strategy. Do not treat a separate Test Architecture Document as the source of truth. A thin local pointer file (e.g. `docs/architecture/test-architecture.md` linking to SAO §5) is allowed for navigation only. Handoff: DTA-06 / DTA-18 write motivators and broad strokes. TFK-01 (run before BPE) completes directory layout, AT/E2E runner paths, and quality gates so construction can execute against a finished Test Strategy section. --- ## Decisions to Flesh Out in SAO.md ### 1. Test Trophy (not Pyramid) Our model is the Test Trophy — integration tests are the main bet: \| Level \| Weight \| Runner \| What it proves \| \|-------\|--------\|--------\|----------------\| \| Unit \| Thin \| pytest \| Custom queryset logic, pure utility functions, business logic methods — only where isolation adds value. Do NOT test default Model CRUD, auto-generated views, or framework behavior. \| \| Integration \| Thick \| pytest \| Feature works end-to-end with real DB, real services, real connections. No mocking. Think of them as acceptance tests minus the GUI. \| \| Acceptance (AT) \| Medium \| behave-django \| `.feature` scenarios in `docs/features/` executed against the app via Django test client. Steps from the TFK Step Library. BDD-grade executable requirements. \| \| E2E \| Selective \| behave + Playwright \| Full user journey in `tests/e2e/`. Sequential, slow, runs on staging before release. Screenshots for visual verification. \| ### 2. Why Test Trophy over Pyramid - Unit tests are limited: testing `model.save()` returns OK tells us nothing about whether data actually persisted - Acceptance tests with a real browser are expensive: slow, flaky - Integration tests hit the sweet spot: real thing, no GUI overhead, fast enough for CI - AT tests are integration tests with BDD syntax — the `.feature` file IS the requirements document made executable ### 3. Runner Mapping - pytest: everything up to and including integration tests - behave-django (`make test-at`): acceptance tests — `docs/features/` (spec + runner; Django test client; `tags = ~@wip`) - behave + Playwright (`make test-e2e`): E2E tests — `tests/e2e/` (LiveServer + browser; own `environment.py`) ### 4. Coverage Policy - Coverage metrics are necessary but not sufficient - Coverage is meaningless without quality — 90% coverage with useless tests is worse than 60% with real tests - Quality gates: no mocking in integration tests, no testing framework behavior, no tests > 10 lines without extraction - `@wip` scenarios excluded from CI; all other `docs/features/` scenarios must pass AT before merge ### 5. Zero-Bug and Zero-Length Feedback Document in SAO: bug = failing integration/AT scenario; fix same day with a permanent regression test; continuous pytest feedback via `tests.log`. ### 6. Agent test lanes When SAO §17 (AI Agent Architecture) applies — i.e. the project has agent workflows, tool registries, or LLM orchestration — extend the Test Strategy with a four-lane agent eval model. When SAO §17 is N/A (no agents), skip this subsection entirely; lanes 3–4 and agent Makefile targets are optional no-ops (see TFK-05). Four lanes: \| Lane \| Name \| Runner \| What it proves \| \|------\|------\|--------\|----------------\| \| 1 \| Control-plane proofs \| pytest `@agent_proof` + CAP-004 ScriptedLLM \| Orchestration: workflow id, tools offered/called, domain writes, plan/blackboard transitions — not model quality \| \| 2 \| Deterministic shell \| pytest integration (no LLM) \| D0 prefilter, JSON parse, validate-before-LLM, schema bounds — pure code paths \| \| 3 \| Live contract eval \| pytest `@live_llm` (nightly / optional CD) \| Provider contracts at temp=0: response shape, tool-call envelope, rate-limit handling \| \| 4 \| Task performance quality \| pytest `@quality` (promotion band) \| Frozen TASK-* golden tasks: structured oracle (recall, graph diff, schema bounds) \| Gate matrix (CI stage vs lane): \| Lane \| PR merge (`ci.yml`) \| Nightly (`agent-eval.yml`) \| Promotion / release \| \|------\|---------------------\|----------------------------\|---------------------\| \| 1 \| ✅ when `AGENTS_ENABLED=true` — `make test-agent-proof` \| — \| — \| \| 2 \| ✅ normal integration job (`make test-integration`) \| — \| — \| \| 3 \| ❌ not a PR gate \| ✅ scheduled / `workflow_dispatch` \| Optional CD cert when `AGENT_EVAL_ENABLED=true` \| \| 4 \| ❌ not a PR gate \| Optional regression run \| ✅ vs last certified pass band before promote \| PRF vs TASK (artifact 56): \| Artifact row \| Lane \| Assert helper \| Fixture root \| \|--------------\|------\|---------------\|--------------\| \| PRF-* (integration proof) \| 1 (+ lane 2 for non-LLM steps) \| `assert_agent_story(trace, …)` \| `tests/fixtures/llm_scripts/<prf-id>/` \| \| TASK-* (golden task) \| 4 \| structured oracle + optional domain asserts \| `tests/fixtures/agent_tasks/<task-id>/` \| PRF rows prove control plane under scripted LLM turns; TASK rows prove outcome quality under live (or promoted) models. Do not use lane 4 to prove 429 retry or HITL gates — those belong in PRF lane 1. Skip when SAO §17 N/A: If the project has no agent architecture section, do not add lane Makefile targets to required CI, do not block BPE/MIN on `agent_proof_command`, and do not create empty `llm_scripts/` / `agent_tasks/` trees. Artifact 11–13 templates add capability, not mandate. Document in SAO § Test Strategy: which PRF-* and TASK-* rows are in scope for this release, lane assignment, and `AGENTS_ENABLED` / `AGENT_EVAL_ENABLED` env conventions. --- ## Deliverables - ✅ SAO.md § Test Strategy fleshed out (Trophy, runners, paths, coverage, zero-bug, zero-length feedback) - ✅ SAO.md § Test Strategy § Agent lanes (when §17 applies): four-lane table, gate matrix, PRF vs TASK mapping, skip rules - ✅ Ready for TFK-02 Bootstrap Test Harness and BPE