Rules

Title	Slug	Playbook	Actions
Add Todos For Incomplete Items	`do-add-todos-for-incomplete-items`	Junior Edda
Assert Agent Story	`assert-agent-story`	Junior Edda	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)
Assert Log Story	`assert-log-story`	Junior Edda	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
Check Before Deleting	`do-check-before-deleting`	Junior Edda	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.
Check Previous Commits	`do-check-previous-commits`	Junior Edda
Continuous Testing	`do-continuous-testing`	Junior Edda	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
Diagrams Element By Element	`do-diagrams-element-by-element`	Junior Edda
Docstring Format	`do-docstring-format`	Junior Edda	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.
Fix Tests	`do-fix-tests`	Junior Edda
Follow Commit Convention	`do-follow-commit-convention`	Junior Edda	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
Github Issues	`do-github-issues`	Junior Edda	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).
Import On Module Level	`do-import-on-module-level`	Junior Edda
Informative Logging	`do-informative-logging`	Junior Edda	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.
Keep Docstrings Consistent	`keep-docstrings-consistent`	Junior Edda
Look Via Human Eye	`do-look-via-human-eye`	Junior Edda	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.
Never Delete Mindlessly	`never-delete-mindlessly`	Junior Edda	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.
Not Go Into Debugging Loops	`do-not-go-into-debugging-loops`	Junior Edda	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.
Not Mock In Integration Tests	`do-not-mock-in-integration-tests`	Junior Edda	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.
Plan Before Doing	`do-plan-before-doing`	Junior Edda	Read the 'Plan Before Doing' rule from playbook 'Junior Edda'. Slug: do-plan-before-doing. always_apply: false. # Rule: Plan Before Doing 1. Read the feature or spec in full. 2. If you need new packages, pick one path with the user when multiple fit; update `requirements.txt` when adding dependencies. 3. Assess the codebase: what exists, what must change, what must be added. Do not trust signature + docstring alone—open the body; you may find `TODO` or `NotImplementedError`. 4. Scan `docs/architecture/`; note doc vs code drift and ask the user to resolve. 5. Write a step-by-step plan (models, APIs, services, views, tests, templates, styles). 6. Show the plan and get approval or refinements before coding. 7. After each step: update the plan, show where you stand, state the next step, then implement. 8. When reality diverges (e.g. missing API you assumed), revise the plan and repeat from step 6.
Pull Frequently	`do-pull-frequently`	Junior Edda
Pytest	`pytest`	Junior Edda
Runner	`do-runner`	Junior Edda
Semantic Versioning On Ui Elements	`do-semantic-versioning-on-ui-elements`	Junior Edda	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.
Skeletons First	`do-skeletons-first`	Junior Edda	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 `.windsurf/rules/do-write-concise-methods.md` - Read .windsurf/rules/keep-docstrings-consistent.md - 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.
Small Increments	`do-small-increments`	Junior Edda	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.
Test First	`do-test-first`	Junior Edda	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 `.windsurf/rules/do-skeletons-first.md` (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 `.windsurf/rules/do-not-mock-in-integration-tests.md`. - 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/` \|
Test Fixture Data Management	`do-test-fixture-data-management`	Junior Edda	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.
Tooltips	`tooltips`	Junior Edda
Update Tests After Bugfixing	`do-update-tests-after-bugfixing`	Junior Edda	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.
Validate Api Contracts	`do-validate-api-contracts`	Junior Edda	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
View Drawio Diagrams	`do-view-drawio-diagrams`	Junior Edda	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
Write Concise Methods	`do-write-concise-methods`	Junior Edda	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.
Write Scenarios	`do-write-scenarios`	Junior Edda	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.
Artifact types: use Document as universal fallback	`artifact-types-use-document-as-universal-fallback`	Playbook for Playbooks	Read the 'Artifact types: use Document as universal fallback' rule from playbook 'Playbook for Playbooks'. Slug: artifact-types-use-document-as-universal-fallback. always_apply: true. Mimir's artifact type field has a restricted set of valid values that is not documented in the MCP schema. When creating artifacts for datasets, models, code, or other non-document outputs, use type "Document" as the universal fallback. Capture the true nature (dataset, trained model, etc.) in the artifact description instead.
Goals go in descriptions	`goals-go-in-descriptions`	Playbook for Playbooks
Granularity rule	`granularity-rule`	Playbook for Playbooks
Loose mapping for unmappable content	`unmappable-content-becomes-a-rule`	Playbook for Playbooks	Read the 'Loose mapping for unmappable content' rule from playbook 'Playbook for Playbooks'. Slug: unmappable-content-becomes-a-rule. always_apply: true. When source content doesn't map cleanly to any Mimir entity, use loose mapping: find the nearest ontology type and capture the nuance in the description field. Nothing should be dropped — it just lands at the right level of fidelity. Loose mapping guide: - Background / Related Work → summarize in playbook or phase description - Problem / task definitions → map as a Rule with the formal definition in the content field - Mathematical or formal content → summarize in activity guidance or rule content; transcribe verbatim only if the exact formulation is operationally critical - Motivating examples → skip, or include as an illustrative note in activity guidance - Conclusions / discussion → extract any constraints or rules; discard the rest
Make implicit agents explicit — only when useful	`make-implicit-agents-explicit`	Playbook for Playbooks	Read the 'Make implicit agents explicit — only when useful' rule from playbook 'Playbook for Playbooks'. Slug: make-implicit-agents-explicit. always_apply: true. If the source has named roles, define them as Agents. If roles are implicit, use source-type heuristics: - Books/notes: define at minimum the practitioner role - Scientific papers: infer from implementation team structure (ML Engineer, Data Engineer, Researcher) If all activities would share the same agent, omit agents entirely — undifferentiated agents add no value. Agents are useful only when they differentiate who does what.
Naming convention	`naming-convention`	Playbook for Playbooks
No release without intern test	`no-release-without-intern-test`	Playbook for Playbooks	Read the 'No release without intern test' rule from playbook 'Playbook for Playbooks'. Slug: no-release-without-intern-test. always_apply: true. Do not release a playbook until Run intern test has passed. Pass means a capable intern or coding agent with no prior domain knowledge, given only an activity packet (name, guidance, and that activity's linked skills, artifacts, rules, and agent), can tell what to do or at least find pointers to the pieces they need. Oral briefings, hidden files, and author memory do not count. Sample at least one activity per workflow, including the hardest assembly step — not only the easy ones. Failures are fixed on the activity (guidance and links) and re-tested.
Single-pass extraction preferred	`single-pass-extraction-preferred`	Playbook for Playbooks	Read the 'Single-pass extraction preferred' rule from playbook 'Playbook for Playbooks'. Slug: single-pass-extraction-preferred. always_apply: true. Work through the source sequentially and drop content into the appropriate bucket as you encounter it. Do not make separate passes per bucket — that wastes time and loses the flow context that helps with correct categorization. The Extraction Worksheet template is designed to accept content in any order.
Source fidelity	`source-fidelity`	Playbook for Playbooks
Always add backward edges	`always-add-backward-edges`	Program Graphs for Code Analysis
Code must be fully compilable	`code-must-be-fully-compilable`	Program Graphs for Code Analysis	Read the 'Code must be fully compilable' rule from playbook 'Program Graphs for Code Analysis'. Slug: code-must-be-fully-compilable. always_apply: true. All projects must compile successfully before graph construction. Precise type information — including types from external libraries — is required to extract data flow edges and type hierarchy embeddings. Discard any project that cannot be fully compiled.
Randomly sample supertypes during training	`randomly-sample-supertypes-during-training`	Program Graphs for Code Analysis	Read the 'Randomly sample supertypes during training' rule from playbook 'Program Graphs for Code Analysis'. Slug: randomly-sample-supertypes-during-training. always_apply: true. During training, randomly select a non-empty subset of τ(v) (the full supertype set) for each variable. This acts as dropout over the type lattice and ensures all known types in the lattice are trained. Use the full τ(v) at inference time.
Split dataset by file, not by example	`split-dataset-by-file-not-by-example`	Program Graphs for Code Analysis
Use exactly 8 GGNN propagation steps	`use-exactly-8-ggnn-propagation-steps`	Program Graphs for Code Analysis