Read the 'Assert Agent Story' rule from playbook 'Junior Edda'. Slug: assert-agent-story. always_apply: true. **Mimir metadata:** slug `do-assert-agent-story`; `always_apply: false` (link to BPE-02 / MIN-04 / TFK-02 / DTA-19). When a plan, iteration manifest, or SAO §17 row declares **Agent proof** scenarios (`PRF-*`, `agent_proof_script[]`, or `agent_proof_command`), you MUST prove orchestration with pytest integration tests using **CAP-004 ScriptedLLM** and the shared trace helper — not by asserting chat prose, grepping `logs/app.log` alone, or "the agent loop exists" checklists. ## Requirements 1. For each PRF row mapped in SAO §17, a test asserts **run trace beats** (workflow, tools offered/called, domain effects, blackboard/plan state as applicable) via `tests/support/agent_story.py` → `assert_agent_story(...)`. 2. Cover **happy** and **reject** paths when the PRF is marked adverse or has a reject sketch (`test_*_agent_story_happy` / `test_*_agent_story_reject`). 3. Use ordered LLM scripts from `tests/fixtures/llm_scripts/<prf-id>/` injected through the agent factory — only **CAP-004 ScriptedLLM** may stand in for the LLM in integration tests. 4. Agent-proof tests ship in the **same commit** as the CAP/worker behavior they prove — never a deferred "agent testing pass". 5. Never assert on raw secrets, tokens, or passwords in trace or log lines. 6. Do not mock domain services, tools, or brokers in `@agent_proof` tests — real DB and real tool registry per Test Trophy. ## Relationship to log story - **Log story** (`do-assert-log-story`): proves **logging beats** at decision points (caplog). - **Agent story**: proves **control-plane behavior** (trace + domain) under scripted LLM turns. - Both may apply to the same slice; both must green in the same commit when declared. ## Anti-patterns - Behavior test green while PRF trace absent or weakened to "agent completed" - `FakeLLM` that returns `[]` on exhaustion instead of raising (hides missing script turns) - Mocking ToolExecutor or domain services in `@agent_proof` integration tests - Skipping `checkpoint.agent_proof_command` when the manifest lists PRF proofs - Using live LLM in PR merge gate (belongs to lane 3/4 — see TFK-01 §6)

Read the 'Assert Log Story' rule from playbook 'Junior Edda'. Slug: assert-log-story. always_apply: true. **Mimir metadata:** slug `do-assert-log-story`; `always_apply: false` (link to BPE-02 / MIN-04 / TFK-02). When a plan or iteration manifest declares a **Log Story Script** (or `log_story_script[]` / `log_tests[]`), you MUST prove those beats with pytest `caplog` (or equivalent log capture) — not by grepping `logs/app.log` alone, and not by "logging statements exist" checklists. ## Requirements 1. For each Log Story Script row, a test asserts the `where` + `beat` + `must_include` fragments appear in captured logs at the declared level (default INFO; WARNING/ERROR when the script says so). 2. Cover **happy** and **reject** paths when the scenario has both (`test_*_log_story_happy` / `test_*_log_story_reject`). 3. Use the shared helper from skill *Pytest Log Story Assertions* (`tests/support/log_story.py` → `assert_log_story(...)`) once TFK-02 has bootstrapped it. 4. Log-story tests ship in the **same commit** as behavior green — never a deferred logging slice. 5. Never assert on raw secrets, tokens, or passwords in log lines. ## Relationship to agent story When the same slice also declares **Agent proof** scenarios (BPE-01 Section G, `agent_proof_command`, or SAO §17 PRF rows), apply rule **`do-assert-agent-story`** in the same commit. Log story proves **logging beats** (caplog); agent story proves **control-plane trace beats** (ScriptedLLM + `assert_agent_story`). Both gates apply independently — neither substitutes for the other. ## Anti-patterns - Behavior test green while log story absent or weakened to `logger.info("done")` - Manual `logs/app.log` inspection as the only DoD for observability - Skipping `checkpoint.log_story_command` when the manifest lists `log_tests` - Passing log-story tests while skipping declared `agent_proof_command` on the same slice

Read the 'Band → Ticket Type Mapping' rule from playbook 'Junior Edda'. Slug: band-ticket-type-mapping. always_apply: true. # Rule: Band to Ticket Type Mapping - Green = no open concern ticket. - Yellow or Orange = one Risk ticket. - Red = one Problem ticket. - Unknown = never Green and never an automatic close. Create or update the same concern as a measurement-health Risk unless the Charter declares a stricter treatment. Risk means a chance that a Problem will materialize; Problem means the risk has materialized and requires active handling. Tickets are filed in the Charter/Huginn-configured GH or Jira target and owned by the named variable owner with Delivery Manager oversight. The ticket type does not by itself decide delivery gating; use the Charter's gating_policy for that.

Read the 'Cadence and Iteration Length by Team Maturity' rule from playbook 'Junior Edda'. Slug: cadence-and-iteration-length-by-team-maturity. always_apply: true. # Rule: Cadence and Iteration Length by Team Maturity Determine cadence at the start of every RIN cycle from the current Charter maturity classification and dated evidence: - L2 or early-L3: one-week iteration. - late-L3 or L4: one-day iteration. If maturity/evidence is absent or older than one completed iteration, reassess and version the Charter before choosing cadence. A different length requires Delivery Manager rationale, evidence, approval, and a review/expiry date. Recurring meeting overhead applies only when team size is greater than one; solo delivery uses asynchronous records and decision points.

Read the 'Charter Is Source of Truth for Variables' rule from playbook 'Junior Edda'. Slug: charter-is-source-of-truth-for-variables. always_apply: true. # Rule: Charter Is the Source of Truth for Variables Variable definitions and measurement contracts live in Charter section 3 and nowhere else. Every row must contain a stable variable_id, definition, unit, source, exact query/command, aggregation/window, freshness limit, measured bands, Unknown behavior, owner, and gating_policy. AIN reads the Charter version captured by its Assessment Run Record and never redefines thresholds locally. Drift between implementation and Charter is a versioned Charter-update decision at Bootstrap/Iteration retrospective, not an ad hoc assessment choice.

Read the 'Add Todos For Incomplete Items' rule from playbook 'Junior Edda'. Slug: do-add-todos-for-incomplete-items. always_apply: false. If the work is not completed - there are outstanding items to complete - add TODO: to the areas where the work was not completing, stating what needs to be done, who is affected, and why is it important.

Read the 'Check Before Deleting' rule from playbook 'Junior Edda'. Slug: do-check-before-deleting. always_apply: false. # Rule: Check Before Deleting Code Never mindlessly delete functions, variables, classes etc. Follow these steps: - First ask yourself: "Why do I need to delete it? What will happen if it's not there?" - Check if there are instantiations of the class or calls to a function. - Even when you see that there is not a single instantiation of the class or call to a function - ask the user with the proposal to delete it, explain your analysis and tell why you think it's safe to delete it. - Even if the user agrees - add a tag "deleted def func_x" on the commit.

Read the 'Check Previous Commits' rule from playbook 'Junior Edda'. Slug: do-check-previous-commits. always_apply: false. # Rule: Check Previous Commits When you encounter missing imports, parts of the files missing, or files missing - always check: 1. Previous commit. 2. Commit from which branch originates. Likely you will find it there and can restore from there.

Read the 'Continuous Testing' rule from playbook 'Junior Edda'. Slug: do-continuous-testing. always_apply: true. # Rule: Continuous Testing and Error Monitoring ## Requirements 1. **All tests must be runnable via `pytest tests/`** - Ensure pytest compatibility for all test files - Use pytest fixtures and conventions - Maintain Django test compatibility where needed 2. **Tests must add their output to `tests.log`** - Configure pytest logging to write to `tests.log` - Include detailed test results, errors, and timing - Preserve log history for analysis 3. **Run tests continuously** - Monitor file changes and auto-run tests for the new and/or affected scenarios - Use watch mode or interval-based execution - Provide real-time feedback on test status 4. **Monitor and fix errors automatically** - Parse test output and `tests.log` for failures - Identify root causes of test failures - Implement fixes proactively - Re-run tests to validate fixes ## Implementation ### Pytest Configuration - Configure `pytest.ini` or `pyproject.toml` for logging - Set up proper test discovery patterns - Configure Django settings for pytest ### Continuous Monitoring - Use file watchers (e.g., `pytest-watch`, `entr`) - Parse test results in real-time - Log analysis for error patterns ### Error Fixing Protocol - Categorize errors (syntax, logic, dependency, etc.) - Apply appropriate fixes based on error type - Formulate the target state (what should be the result of the fix) - Inform user that you found the error, how you see target state, and what you are going to do to fix it - Apply the fix - Validate fixes with immediate test re-run - Update tests if requirements have changed ## Usage When working on any codebase: 1. Ensure pytest setup is complete 2. Check background processes. If there is no continuous_test_runner.py - start it 3. Do continuous test output monitoring 3. Also monitor `tests.log` for issues 4. Fix errors as they are detected 5. Maintain test health continuously

Read the 'Diagrams Element By Element' rule from playbook 'Junior Edda'. Slug: do-diagrams-element-by-element. always_apply: false. First, create an empty diagram file and save it. Then start adding your edits one by one, saving after each edit.

Read the 'Docstring Format' rule from playbook 'Junior Edda'. Slug: do-docstring-format. always_apply: false. # Docstring format (with examples) Every public function/method needs a docstring in this shape: ```python def name(p: T) -> R: """ One-line summary. :param p: what it is as Type. Example: concrete_value :return: what you return as Type. Example: concrete_value :raises SomeError: when """ ``` **Rules:** summary line, blank line, then `:param` / `:return` / `:raises` with **example values** on every param and return (and raises where applicable). Types belong in the signature; docstring repeats them for humans. **Minimal good example** ```python def get_workflow(workflow_id: str) -> dict: """ Load workflow by id. :param workflow_id: id as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :return: workflow dict. Example: {"id": "a1b2c3d4", "name": "Build Feature"} :raises ValueError: if id invalid """ ``` **Anti-patterns:** no examples; vague "the name"; missing return example; docstring contradicts implementation (ask user which wins). **Optional / *args / **kwargs:** document each; examples show typical values.

Read the 'Fix Tests' rule from playbook 'Junior Edda'. Slug: do-fix-tests. always_apply: false. Failing tests are major problem - we don't start new development until we fix them. If its a test problem - fix it. If its a implementation details VS test diff - either fix the test, or ask user what takes precedence.

Read the 'Follow Commit Convention' rule from playbook 'Junior Edda'. Slug: do-follow-commit-convention. always_apply: true. # Rule: Follow Angular Commit Convention When committing, follow the Angular convention: ``` <type>(<scope>): <subject> <BLANK LINE> <body - what changed> <BLANK LINE> <footer> ``` Reference: https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines

Read the 'Github Issues' rule from playbook 'Junior Edda'. Slug: do-github-issues. always_apply: false. **Mimir metadata:** slug `do-github-issues`; `always_apply: true` (extended 2026-08-17 — BPE/MIN commit–issue traceability; was `false`). ## Issue Creation Issues are created during Activity "Publish" (PIN-04) of the Plan Iteration (PIN) Workflow. Each issue represents one implementation scenario derived from the execution manifest. **Goal:** Issues must be self-sufficient — an implementer with no prior domain knowledge must be able to complete the work from the issue alone. **Requirements:** 1. Label with type: Feature / Scenario / Enhancement / Bug / Refactoring / Infra; and complexity: easy / medium / hard. 2. Name the issue with its scenario identifier prefix where available (e.g., "LOG1.1: Scenario A"). 3. Transfer the full scenario content into the description. 4. Embed the implementation plan from `docs/plans/` as a checklist-style guidance block in the description, if one exists. 5. Before creating, verify no issue with the same prefix already exists. If a duplicate exists, halt and report to the user. --- ## Issue Update Issues are updated during Activity "Execute" (MIN-04) of the Manage Iteration (MIN) Workflow, and during Activities "Implement Backend" through "Finalize Feature" (BPE-02 through BPE-07) of the Build Feature (BPE) Workflow. **Goal:** Every update must allow any team member to reconstruct what happened, why, and what is planned next. **Requirements:** 1. Reference a specific commit in every update. 2. Describe what was done and the reason. 3. If implementation deviated from the original plan, state the cause: user direction, technical constraint, or scope change. 4. State the next steps explicitly. 5. Update the checklist: mark completed items, add items completed but not originally planned, revise upcoming steps. 6. Summarize the intended update to the user and obtain approval before posting. --- ## BPE / MIN — Commit–issue traceability (execution) When GitHub issue **#N** tracks the work (BPE-01 handoff or MIN manifest scenario): ### Hard gate — issue before code - Do **not** commit changes under the implementation footprint until issue #N exists with sections A–F inline (or manifest scenario body) and a handoff commit is on the branch: `docs(plan): … Refs #N` or equivalent plan/docs-only commit cited in the first issue comment. - Creating the issue **after** implementation is a process violation. ### Per plan slice (not per wave) After **each** plan slice (or BPE step that maps to a slice): 1. `git commit` with Angular convention; footer **`Refs #N`** on every slice commit. 2. **`gh issue comment N`** immediately — must include: short commit SHA, what changed, reason if deviated, **next step/slice name**. 3. Do **not** start the next slice until both commit and issue comment are done. 4. Only the **final** slice commit for #N uses **`Closes #N`** (or close via MIN checkpoint after that commit). ### Anti-patterns - Entire wave/feature in one commit with `Closes #N` at the end only. - Commits with no `#N` reference while issue is active. - Issue closed with no commit SHA in the closing comment. --- ## Issue Closure Issues are closed during Activity "Execute" (MIN-04) of the Manage Iteration (MIN) Workflow, after the checkpoint command from the `<!-- SCENARIO -->` YAML block passes. **Prerequisite — Lessons Learned section:** The issue body must contain a `## Lessons Learned` section. This section is authored during Activity "Plan Feature" (BPE-01) of the Build Feature (BPE) Workflow and captures observations that feed Activity "Close Iteration" (MIN-05) of the Manage Iteration (MIN) Workflow, which in turn provides input to Activity "Orient & Validate Scope" (PIN-02) of the next Plan Iteration (PIN) Workflow. **Requirements:** 1. Confirm the issue body contains a `## Lessons Learned` section. If absent, reconstruct it from implementation experience before closing. 2. Include in the closing comment: "Lessons Learned reviewed — {N observations / none}." 3. If the `## Lessons Learned` section contains architectural decisions not yet reflected in `docs/architecture/SAO.md`, state this explicitly in the closing comment: "SAO.md update required: {section}." These decisions must be applied to SAO.md before or immediately after closure — not deferred silently. 4. An issue without a `## Lessons Learned` section in the body must not be closed. 5. Closing comment must cite the **final commit SHA** that passed checkpoint (not close-only with no SHA).

Read the 'Import On Module Level' rule from playbook 'Junior Edda'. Slug: do-import-on-module-level. always_apply: false. Do not import locally inside the method - import at the module level. It will make patching and mocking easier for you.

Read the 'Informative Logging' rule from playbook 'Junior Edda'. Slug: do-informative-logging. always_apply: false. **Mimir metadata (required on apply):** `always_apply: true` (currently false). This rule absorbs and replaces `add-logging`. Every service call or controller action must log to `logs/app.log` (or the project’s designated app log) at **INFO**. Configure logging if missing: logger + file handler that rotates / clears on every app relaunch so diagnosis starts clean. Use `logs/app.log` to troubleshoot who was doing what with which data when error X occurred. For UI / HTMX flows use `console.log` for decisions, actions, and results (map to the same story beats below). **Ban deferred-logging slices.** Logging ships in the same green slice as behavior — never a final “informative logging pass” after tests are green. **Ask yourself before writing each log line:** - What information will I need to precisely pinpoint where the error is occurring? - What context will I need in the logs to understand why it happened? - What data transformations or validations occurred? - Which decisions led to the current point? ## Story beats (minimum narrative) On each major step emit the applicable beats so a reader can reconstruct the path: `entry → config → validation → processing → branch → exit → error` ## Preferred line format (grep / caplog friendly) ```text {logger_name} | {Class.method} | {beat} | key=value ... ``` Legacy `Class.method: message | key=value` is acceptable if `where` + beat intent remain searchable. ## Logging setup ```python import logging import io from pprint import pformat from tabulate import tabulate logger = logging.getLogger(__name__) buffer = io.StringIO() # structured dumps ``` **Buffers:** use `StringIO`; log `buffer.getvalue()`, then `truncate(0)` (and `seek(0)` if reusing). **Summaries:** include shape/types, `head`/`tail`/`describe`, null counts where useful. ## Patterns (examples) **1. Entry** ```python def method_name(self, param1, param2): logger.info( f'{self.__class__.__name__}.method_name | entry | param1={param1} param2_shape={getattr(param2, "shape", type(param2))}' ) ``` **2. Structures** ```python df.info(buf=buffer) logger.info(f'{dataset_name}:\n{buffer.getvalue()}') buffer.truncate(0) logger.info(f'Config:\n{pformat(config_dict)}') logger.info(f'Preview:\n{tabulate(df.head(), headers=df.columns.tolist())}') ``` **3. Branches** ```python if condition: logger.info(f'{self.__class__.__name__}.method_name | branch | column={column_name} present=true') else: logger.warning(f'{self.__class__.__name__}.method_name | branch | column={column_name} missing default={default}') ``` **4. Validation / transforms** ```python logger.debug(f'Input dtypes: {df.dtypes.to_dict()}') logger.info(f'{operation_name}:\n{result.describe()}') ``` **5. Errors** ```python try: logger.info(f'{operation_name} | exit | status=ok') except Exception as e: logger.error(f'{operation_name} | error | err={e} param1={param1} data_shape={getattr(data, "shape", None)}') logger.info('Attempting recovery...') ``` ## Minimum on each major step - **Method entry:** operation name, key parameters, data shapes/types - **Configuration:** setup decisions, rule books, parameters used - **Data validation:** input validation results, type conversions, missing data handling - **Processing steps:** each major transformation with before/after summaries - **Conditional logic:** why paths were taken - **Results / exit:** success/failure indicators, output shapes - **Error context:** full parameter context, data state, recovery attempts ## Levels - **DEBUG:** flow, dtypes, internal state; sample values when feasible - **INFO:** entry/exit, config, main steps, outcomes - **WARNING:** recoverable issues, fallbacks, data quality - **ERROR:** failures needing attention ## Every INFO line must answer (when relevant) - Who triggered the action (user or AI agent) - What the action did (inputs, affected models/records) - Why the action occurred (intent, rule, or logic) - Where it happened (class, method/function) - Key identifiers (never raw secrets/tokens/passwords) - Unexpected condition (if any) - Relevant context (user ID, request/run ID, environment) Design messages so you can find root cause without reproducing the problem blindly. **Prove the story in tests** — see rule `do-assert-log-story` and skill *Pytest Log Story Assertions*.

Read the 'Look Via Human Eye' rule from playbook 'Junior Edda'. Slug: do-look-via-human-eye. always_apply: false. Render and review as a human would: zoom to ~50% and scan for clarity. **Layout:** no overlapping shapes; consistent spacing/grid; readable text size and contrast; legend if symbols/colors need explanation. **Flow:** obvious direction; minimize crossing lines; stagger parallel edges; separate error/retry paths from happy path; decision diamonds readable (clear branches). **Hierarchy:** group related shapes; similar nodes similar size; primary journey visually strongest. **Before sign-off:** zoom-out test; “fresh eyes” readability; print/B&W sanity; trace each arrow without ambiguity.

Read the 'Not Go Into Debugging Loops' rule from playbook 'Junior Edda'. Slug: do-not-go-into-debugging-loops. always_apply: false. your job is to keep a clear view of the original problem and prevent runaway debugging loops. Always follow these steps: 1. **Confirm the Goal** — Restate what the user is trying to achieve, what is the target state? 2. **Diagnose, Don’t Guess** — Do not blindly patch symptoms. Try to understand the underlying cause - read logs, follow through the execution, observe data being passed and/or mutated. 3. **Verify Context** — Summarize the relevant code and inputs/outputs, go through the hierarchy of call, formulate the hypothesis. 4. **Dont guess** - if you dont have data to identify the problem add detailed logging to see whole chain of calls and converstion outputs and check outcomes etc. 5. **Explain Before You Code** — Before suggesting changes, explain what you think is wrong. 6. **Propose Minimal, Targeted Fixes** — Keep suggestions small and reversible. 7. **Reflect After Each Fix** — Evaluate if the result aligns with the goal. If not, go back to Step 1. 8. When completed the fix - write/update the test and RUN IT to verify the fix. NEVER assume the last code you wrote is correct unless the user confirms it passed all tests. Ask for clarification if confused.

Read the 'Not Mock In Integration Tests' rule from playbook 'Junior Edda'. Slug: do-not-mock-in-integration-tests. always_apply: false. Do not use mocks in integration tests — use real objects, real connections, real or real-like data from fixtures. Think of them as acceptance tests minus the UI. ## CAP-004 carve-out (agent integration proofs) When SAO §17 applies and a test is marked `@pytest.mark.agent_proof`, **only CAP-004 ScriptedLLM** may stand in for the LLM provider. Everything else stays real: - Real database and transactions - Real tool registry / ToolExecutor wiring - Real broker and result backend (when CAP-060 in scope) - Real domain services — no `@patch` on services the agent invokes ScriptedLLM replays ordered responses from `tests/fixtures/llm_scripts/<prf-id>/`. It proves **orchestration**, not model quality. ## FakeLLM ban Do **not** use `FakeLLM`, hand-rolled stub clients, or test doubles that: - Return empty lists / `{}` when the script queue is exhausted (hides missing turns) - Silently swallow parse errors - Bypass the LLM port protocol (CAP-001) If the scripted queue runs out, the test must **fail loudly**. Use CAP-004 ScriptedLLM or a real provider in lane 3/4 eval tests — never a silent fallback mock in PR merge gates. ## Lane 2 reminder Deterministic shell tests (D0 pre-filter, JSON parse, validate-before-LLM) are ordinary integration tests — **no LLM mock at all**.

Read the 'Plan Before Doing' rule from playbook 'Junior Edda'. Slug: do-plan-before-doing. always_apply: true. # Rule: Plan Before Doing Use this rule before any activity that will mutate code, playbook state, project artifacts, tickets, infrastructure, or an external system. ## Procedure 1. Read the activity guidance, required inputs, linked artifacts/rules, and relevant architecture/specification material in full. Inspect implementation bodies and live state; do not infer completeness from names, signatures, or generated files. 2. Validate prerequisites and identify unknowns, human gates, side effects, rollback/retry behavior, and the evidence required for Done. 3. If the ADE provides an enforced **Plan mode**, enter it. Otherwise create or update the activity's explicit execution plan in the location named by its guidance. 4. The plan must name ordered steps, dependencies, read/write footprints, safe parallel groups, convergence checks, tests/validation, and approval points. 5. Show the plan and obtain required human approval before mutation. Approval of a parent plan covers only side effects explicitly listed there. 6. Execute against the approved plan. Update status and evidence after material steps; when reality invalidates an assumption, pause affected work, revise the plan, and renew approval where scope or side effects change. 7. Do not invent ADE capabilities. If enforced planning, subagents, or background tasks are unavailable, preserve the same plan/dependency/convergence semantics serially. ## Bounded exceptions - Read-only inspection may precede the plan when needed to make it accurate. - A deterministic scheduled AIN run may execute from the already approved Charter and Huginn Assessment Contract without new approval per run; changing the contract, variables, thresholds, gating, ticket target, or schedule still requires planning and approval. - Trivial status reads and idempotent retries that use the same approved inputs and side-effect key do not require a new plan.

Read the 'Pull Frequently' rule from playbook 'Junior Edda'. Slug: do-pull-frequently. always_apply: false. Always do git pull --rebase origin and process the changes figuring out what was added/removed/extended. If there are breaking changes affecting our plan implementation - summarize them, their consequences, and ask what we will do.

Read the 'Runner' rule from playbook 'Junior Edda'. Slug: do-runner. always_apply: false. # Rule: Test Runners Use the following runners: - **Unit and integration tests**: pytest - **API view tests**: Django test client - **Acceptance (end-to-end) tests**: Playwright

Read the 'Semantic Versioning On Ui Elements' rule from playbook 'Junior Edda'. Slug: do-semantic-versioning-on-ui-elements. always_apply: false. # UI naming for Playwright and accessibility **Selector order (use in this order):** `get_by_test_id` → `get_by_role` → `get_by_label` → `get_by_text` (stable only). Do **not** use CSS/XPath for primary flows. **Every interactive control:** stable `data-testid`, plus `aria-label` or visible label; forms need `Label` + `aria-describedby` for errors; dialogs need unique accessible name. **Naming:** hierarchical `feature-area--role`, e.g. `intent-form-dialog`, `intent-name-input`, `save-intent-button`. Lists/cards: container + per-item ids (`data-intent-id`). **State:** expose `data-state`, `data-valid`, `aria-invalid`, `aria-pressed` where it affects tests. **Portals (dialogs/menus):** query from `page`, not a nested container—`page.get_by_test_id("…")`. **Tests:** disable animations in test env (1ms transitions). Prefer stable `data-testid` over dynamic button text. **Checklist before merge:** ids on interactive nodes; labels on inputs; dialog names; no CSS-only E2E selectors; portals from `page`. See project E2E docs for full examples when needed.

Read the 'Skeletons First' rule from playbook 'Junior Edda'. Slug: do-skeletons-first. always_apply: false. The core principle is that the developer who has no knowledge of the system can implement methods/properties etc. following only documentation in the skeleton - think its like you are a designer defining the task for the implementer. Do as follows: - Read playbook rule **Write Concise Methods** (`do-write-concise-methods`) - Read playbook rule **Keep Docstrings Consistent** (`keep-docstrings-consistent`) - Create class and method/function stubs and document them - Include full docstrings, return types (eg "-> list[str]", and sample return values (per global rules) - Use `raise NotImplementedError()` in each method. - Do not skip type hints or documentation - Add comments inside the methods pointing attention to the logic flow, exception handling, logging etc.

Read the 'Small Increments' rule from playbook 'Junior Edda'. Slug: do-small-increments. always_apply: true. # Rule: Small Increments Work in method-by-method steps. - Implement small vertical slices. - After every change: write → run → test → evaluate → fix. - No large PRs or 1000-line commits. When a tracker issue is active, a slice is not done until the commit and the issue update exist together. GitHub mechanics (`Refs #N` / `Closes #N`, `gh issue comment`) live in rule `do-github-issues`, not here.

Read the 'Test First' rule from playbook 'Junior Edda'. Slug: do-test-first. always_apply: false. Tests prove behavior. You **cannot claim** a scenario, class, or method is implemented until tests pass. - New code structure: follow playbook rule **Skeletons First** (`do-skeletons-first`) (docstrings, types, stubs). - Write tests **before** implementation. Do not write tests whose only purpose is to hit `NotImplementedError`—write assertions that **should pass** once real behavior exists. - Cover **success** (returns) **and** **failure** (`raises`, errors, edge cases) for each unit of behavior. - If implementation contradicts docstring, ask the user which wins. - Use `docs/features/` to align scenarios with tests. - Order: method-level → API → integration. For integration, follow playbook rule **Not Mock In Integration Tests** (`do-not-mock-in-integration-tests`). - Red–green: make the test fail, then implement until green. - Use pytest; avoid mocks unless unavoidable. **Layout (never put tests in repo root):** | Kind | Path | |------|------| | Unit | `tests/unit/` | | Integration | `tests/integration/` | | API | `tests/api/` | | E2E | `tests/e2e/` | | Service | `tests/services/` |

Read the 'Test Fixture Data Management' rule from playbook 'Junior Edda'. Slug: do-test-fixture-data-management. always_apply: false. APPEND TO RULE: --- ## behave AT: Background + scenario idempotency Applies to acceptance tests (`docs/features/`) using behave-django, not only E2E preset JSON. When `Background:` loads or seeds entities and a scenario `Given` creates the same logical record (same slug, username, or other natural unique key): - Use `get_or_create` / update-in-place in the step definition. - Prefer factory `django_get_or_create` on stable keys when using FactoryBoy in Givens. - Treat `IntegrityError` during AT as a **fixture contract bug** until proven otherwise. Reference: Skill 45 Pattern 5; TFK-04 Build Fixture Library activity.

Read the 'Update Tests After Bugfixing' rule from playbook 'Junior Edda'. Slug: do-update-tests-after-bugfixing. always_apply: false. When the bug was discovered, you performed and investigation anf fix, ask yourself - "why our current test(s) was not able to find it?" If there is no test for that part of functionality - time to create it. If there are test(s) for that part of functionality - extend it to prove that the bug does not exist anymore. When completing the fix - run the test to prove that bug does not exist.

Read the 'Validate Api Contracts' rule from playbook 'Junior Edda'. Slug: do-validate-api-contracts. always_apply: false. ## Requirements ### 1. Frontend Interface Validation - **Always** define TypeScript interfaces that match exact backend response structure - Include ALL fields returned by backend, including nested objects and metadata - Validate both success and error response formats - Example: ```typescript // ❌ WRONG - Missing authentication fields interface UserResponse { id: number; username: string; email: string; } // ✅ CORRECT - Matches backend response exactly interface UserResponse { user: { id: number; username: string; email: string; first_name?: string; last_name?: string; // ... all user fields }; authenticated: boolean; token_valid: boolean; token_expires_at?: string; } ``` ### 2. Response Validation Logic - **Never** assume HTTP 200 means success - always check response data fields - Validate authentication/authorization flags in response - Handle nested response structures correctly - Example: ```typescript // ❌ WRONG - Only checking HTTP status if (response.status === 200 && response.data) { setUser(response.data); // Assumes flat structure } // ✅ CORRECT - Full validation with nested structure if (response.status === 200 && response.data && response.data.authenticated && response.data.token_valid) { setUser(response.data.user); // Correctly accessing nested user } ``` ### 3. Documentation Requirements - Document exact API response formats in Architecture_FULL.md - Include example JSON responses for all authentication endpoints - Specify frontend validation requirements - Update documentation when API contracts change ### 4. Testing Requirements - Write integration tests that validate actual API responses - Test both success and failure scenarios - Verify frontend handles all response fields correctly - Include API contract tests in continuous testing ## Prevention Checklist Before implementing frontend API calls: - [ ] Check Architecture_FULL.md for documented response format - [ ] Define TypeScript interface matching exact backend response - [ ] Implement full response validation (not just HTTP status) - [ ] Test with actual backend responses - [ ] Update documentation if response format differs Before deploying API changes: - [ ] Verify frontend interfaces match new backend response - [ ] Update all affected frontend validation logic - [ ] Run integration tests to validate contract compatibility - [ ] Update Architecture_FULL.md with new response formats ## Common Pitfalls to Avoid 1. **Assuming flat response structure** - Many APIs return nested objects 2. **Only checking HTTP status** - 200 OK doesn't guarantee valid data 3. **Missing authentication flags** - Backend may return success with auth failures 4. **Outdated interfaces** - Frontend types drift from backend reality 5. **No integration testing** - Unit tests don't catch contract mismatches

Read the 'View Drawio Diagrams' rule from playbook 'Junior Edda'. Slug: do-view-drawio-diagrams. always_apply: false. # Rule: View Draw.io Diagrams with Embedded Images When you encounter a Draw.io file (.drawio extension) that contains embedded images or screenshots, automatically convert it to a viewable format to analyze the visual content and annotations. ## Process 1. **Detect Draw.io Files**: When asked to analyze a .drawio file 2. **Check for Embedded Content**: Look for embedded images or screenshots 3. **Convert to Viewable Format**: Use one of these methods: - Export to PNG using Draw.io CLI: `drawio -x -f png -o output.png input.drawio` - Export to SVG using Draw.io CLI: `drawio -x -f svg -o output.svg input.drawio` - Open in browser and capture screenshot if CLI not available 4. **Analyze Visual Content**: View the converted image to understand: - Red annotation rectangles and their purpose - Embedded screenshots and UI mockups - Design patterns being highlighted - Implementation guidance provided ## Tools to Use - Draw.io CLI (if available): /Applications/draw.io.app/Contents/MacOS/draw.io - Browser preview with screenshot capture - File conversion utilities ## Expected Outcome - Ability to see and analyze embedded images within Draw.io files - Understanding of red annotation system and design guidance - Clear interpretation of UI patterns and implementation notes

Read the 'Write Concise Methods' rule from playbook 'Junior Edda'. Slug: do-write-concise-methods. always_apply: true. # Rule: Write Concise Methods When designing new methods: - Ensure the top-level (public) method is concise—ideally 20–30 lines maximum. - Move all supporting logic and details into well-named private (or inner/helper) methods. - The top-level method should clearly express the main workflow, delegating specifics to lower-level helpers. Example: ```python class SomeObject: def main_method(self, id): # Inner/helper method for a single, focused operation def _short_method(arg): return op(arg) target = self._get_target(_short_method(id)) result = self._do_magic_on(target) return result def _get_target(self, id): # Implementation here pass def _do_magic_on(self, target): # Implementation here pass ``` Guidelines: - Keep the top-level method readable and high-level—think of it as a summary of the operation. - Each helper/private method should do one thing and have a clear, descriptive name. - Avoid cramming complex logic into the top-level method; instead, encapsulate details in private helpers.

Read the 'Write Scenarios' rule from playbook 'Junior Edda'. Slug: do-write-scenarios. always_apply: false. # Writing Effective BDD Feature Files ## 1. Principle: Always Start With a Feature Specification - Before writing any feature story, check if a feature specification exists. - If it does **not** exist, write one first. A good feature spec: - Assess docs/ux/demo-flow.md - what we are doing and why? what will be affected? - Defines the **user** (role or persona). - States the **goal** (what the user wants to achieve). - Describes the **context** (why the goal matters). - Clarifies any **assumptions** or **preconditions**. - Consist of one or many scenarios user is going through to achieve the goal - Pick an ID (like a prefix for all scenarios in the file), like abbreviation "Library" -> LIB, "Dataset" - DS etc. - Analyze the codebase - which pages/views are already available? what we will use? what we will build? ### Example Feature Spec > Alex Chen wants to apply a moving average to Apple stock price data so they can observe trends and test signals over a historical period. --- ## 2. Principle: Be Specific — Who Does What, and Why Each `Scenario` should: - Identify the **actor** clearly (`Fund Analyst`, `Quant`, `User`). - Describe **what they are trying to do**, in plain English, very specific - "Enters ABC into XYZ" - State **why** it matters for the workflow or outcome. - Capture precise values — asset identifiers, transformations, expected results. - Have ID like "Scenario: LIB 1.1 Add Dataset" ## 3. Structure Each `Scenario` should follow the format: ```gherkin Scenario: <ID> <User goal> Given <initial system state or data> When <action is taken> Then <expected result or outcome> ``` Include **exact DSL inputs**, **parameter values**, and **visual/verbal feedback** expectations. --- ## 4. Example: Data Transformation Scenario ```gherkin Feature: DSL 1.1 Applying SMA transformation to a selected equity Scenario: Applies applies 12-month simple moving average to AAPL equity Given the user is in the "Workspace" And the asset "US.Equity.AAPL" is selected in the data table "Assets" When the user applies "transformation" "SMA(12)" to the time series in the row Then the chart "Moving Avg: should update to show a new line representing the 12-month SMA And the data table "Moving Avg: Table" should display the transformed values under a new column ``` --- ## 5. Example: Error Handling Scenario ```gherkin Feature: DSL 1.2 Handling invalid DSL expression Scenario: Quant enters malformed DSL syntax Given the user is on the Asset Selection screen When the user enters "US.Equity..AAPL.SMA(" Then the system should display an error message "Invalid DSL syntax: unexpected token '.' at position 13" And no data should be loaded And the input field should remain editable ``` --- ## 6. Common BDD Mistakes to Avoid - ❌ Vague actor roles (e.g., "user" instead of "Fund Manager or Alex Chen") - ❌ Missing context (why is the user doing this?) - ❌ Leaving values generic (e.g., “some stock” instead of “US.Equity.AAPL”) - ❌ Ambiguous outcomes (“should work” instead of what exactly should happen) --- ## 7. When in Doubt: Ask These Questions - **Who** is performing the action? (Analyst, Fund Manager, Quant…) - **What** are they trying to achieve? - **Why** is it important? - **Which exact input(s)** are used? - **What are the expected outputs**, UI reactions, or system responses? --- ## 8. Optional Extensions - Tag scenarios with `@core`, `@error`, `@backtest`, `@universe`, etc. - Pick a FA Pro icon and add it to comments if user did not do that --- By adhering to these principles, we ensure every story is understandable, testable, and traceable to real user needs.

Read the 'Fan Out Independent Work' rule from playbook 'Junior Edda'. Slug: fan-out-independent-work. always_apply: true. # Rule: Fan Out Independent Work Use this rule whenever an activity's work naturally decomposes into a list of items (scenarios, features, architectural domains, work packages) that can be planned or built without waiting on each other. Do not use it to force parallelism onto genuinely sequential work — see the activity's own guidance for whether this rule applies. ## Procedure 1. **Enumerate the items.** Produce the explicit list this activity will fan out over (e.g. all in-scope BDD scenarios, all architectural domains, all work packages). This list is the unit of dispatch — one worker per item. 2. **Declare a footprint per item, before dispatch.** For each item, state which files/artifacts it will read and which it will write. An item that only reads shared upstream material (e.g. a single requirements document) and writes its own distinct output has an empty write-conflict footprint by construction. 3. **Derive the conflict map.** For every pair of items, intersect their declared write-footprints. Non-empty intersection → conflict → these items must be serialized relative to each other. Empty intersection → safe to run concurrently. 4. **Assign parallel groups.** Items with no mutual conflict go in the same dispatch wave. Conflicting items are ordered or assigned to different waves. Record the grouping (this is the same shape as an execution manifest's `parallel_groups`). 5. **Dispatch one worker per item in a wave.** Each worker operates only within its declared footprint. A worker must not touch files outside its footprint, and must not pick up another item's work. 6. **Collect results explicitly.** Each worker reports pass/fail (and, if it writes code, a commit reference) before the activity is considered done for that item. Do not treat silence as success. 7. **Converge deliberately.** After all items in scope report back, run one explicit convergence step that: (a) confirms every item passed, and (b) checks for *cross-item* consequences that no single item's worker could see on its own — e.g. two architectural domains making incompatible choices, or two scenarios that turn out to need the same infrastructure. Serial execution gives an agent incidental cross-item awareness just by having read everything in order; parallel execution does not, so this convergence step must do that checking explicitly rather than assuming it happened implicitly. ## When not to use this If an item's plan or output is a required input to another item (not just a shared upstream artifact both read), that is a real dependency, not a footprint conflict — sequence those items, don't force them into the same wave. ## Source This pattern is not new: it is the mechanism Activity 181 (MIN-03, TL Dispatches Workers to Build) already uses for build-time node dispatch, and that Activity 142 (PIN-03, Contract) already uses for its footprint/conflict_map/parallel_groups manifest. This rule names it once so other activities can cite it by slug instead of re-deriving it.

Read the 'Keep Docstrings Consistent' rule from playbook 'Junior Edda'. Slug: keep-docstrings-consistent. always_apply: false. When performing edits - always check docstring and keep them up-to-date with :param:, :raises:, :return: etc.

Read the 'Never Delete Mindlessly' rule from playbook 'Junior Edda'. Slug: never-delete-mindlessly. always_apply: true. Never mindlessly delete functions, variables, classes etc. - first ask yoursefl "why I do I need to delete it? what will happen if its not there?" First check if there are instantions of the class or calls to a function. Even when you see that there is not a single instantiation of the class or call to a function - ask user with the proposal to delete it, explain your analysis and tell why you think its safe to delete it. Even if user agreed - add a tag "deleted def func_x" on the commit.

Read the 'One Ticket Per Concern' rule from playbook 'Junior Edda'. Slug: one-ticket-per-concern. always_apply: true. # Rule: One Ticket Per Concern The stable concern key is project_id plus variable_id. Each Charter variable has at most one active bad-state/measurement-health lifecycle, reclassified and updated in place across assessment runs. Never create one ticket per run and never consolidate multiple variables into one ticket. Read-only lookups may run in parallel, but creates, updates, conversions, and closes must be serialized per concern key. When a tracker cannot change type in place, atomically link the replacement representation and close the old one so the concern still has one authoritative active ticket.

Read the 'Pytest' rule from playbook 'Junior Edda'. Slug: pytest. always_apply: true. Always use pytest as test runner. Build your tests to be run with pytest.

Read the 'Release Roadmap Is Aspirational' rule from playbook 'Junior Edda'. Slug: release-roadmap-is-aspirational. always_apply: true. # Rule: Release Roadmap Is Aspirational Charter section 6 (alpha to beta to gamma to RC) must be labeled aspirational/unvalidated in the Charter itself and cross-referenced to EST for feasibility. Dates or phases become commitments only after EST evidence and explicit authorized approval. Parallel planning, a generated roadmap, or an agent forecast does not create a commitment.

Read the 'Ticket Lifecycle Transitions' rule from playbook 'Junior Edda'. Slug: ticket-lifecycle-transitions. always_apply: true. # Rule: Ticket Lifecycle Transitions Maintain one stable concern per project plus Charter variable_id; update it in place whenever the adapter supports that. - Green with no open concern: no action. - Green to Yellow/Orange: open Risk. - Yellow to/from Orange: keep Risk but update band, severity, evidence, freshness, assessment run, and gating policy. - Yellow/Orange to Red: reclassify the same concern to Problem. - Red to Yellow/Orange: reclassify the same concern to Risk and update evidence. - Fresh non-Green to Green: resolve the concern with recovery evidence. - Green to Red: open Problem. - Red to Green: resolve with fresh recovery evidence. - Any to Unknown: never close or mark Green; create/update the same concern as a measurement-health Risk unless Charter policy is stricter. - Unknown to measured band: transition that same concern according to the measured band. Use run_id plus variable_id as the side-effect idempotency key. Retry updates the same ticket/action record. Ticket-adapter failure leaves the assessment incomplete; it never authorizes a duplicate.

Read the 'Tooltips' rule from playbook 'Junior Edda'. Slug: tooltips. always_apply: false. Font Awesome Pro Icons Required - Every action button/link needs an icon; if not specified, you shall propose 3 options Bootstrap Tooltips Required - Every button needs hover text that: Explains the action for active buttons Explains why it's disabled and how to enable it for disabled buttons

Read the 'Variable Band Scale Flexibility' rule from playbook 'Junior Edda'. Slug: variable-band-scale-flexibility. always_apply: true. # Rule: Variable Band Scale Flexibility A tracked variable may use a binary measured scale (Green/Red) or the full measured scale (Green/Yellow/Orange/Red). Unknown sits outside either performance scale and means evidence is missing, stale, inaccessible, malformed, or non-reproducible. Unknown is never coerced to zero or Green. Binary variables go directly Green to/from Red when measured; both scale forms still use the same stable concern, evidence, idempotency, and gating rules.