Rules

Title	Slug	Playbook	Actions
Big Picture Before Detail	`big-picture-before-detail`	Delivery Constraint & Opportunity Analysis	Read the 'Big Picture Before Detail' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: big-picture-before-detail. always_apply: true. Open with the reconstructed delivery cycle (all BizDevTestSecOps stages) showing effort, wall-clock, and impact on each stage. Then the opportunity quadrant (gain vs effort). Then the deficiency register (dE/dK/dI + routes). Then only promoted stage detail or starter mart tabs. Never lead with Feature Cycle Time, Commits, or any single-stage chart. The rendering tool (Streamlit, Jupyter, QuickSight, Power BI) is a skill pick, not the opening.
Eliminate Before Automate Before Delegate	`eliminate-before-automate-before-delegate`	Delivery Constraint & Opportunity Analysis	Read the 'Eliminate Before Automate Before Delegate' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: eliminate-before-automate-before-delegate. always_apply: true. Work every constraint in this order: eliminate the step if it's pure waste; if it must stay, automate it with the smallest tool (a Lambda paired with Guardrails); only delegate the remaining judgment-requiring work to an agent once eliminate and automate are exhausted. Don't automate a step that should have been eliminated, and don't delegate to an agent what a Lambda could safely do.
Execute by Workflow Order	`execute-by-step-labels`	Delivery Constraint & Opportunity Analysis	Read the 'Execute by Workflow Order' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: execute-by-step-labels. always_apply: true. Run the four workflows in the `order` field sequence (1→4): (1) scope and stand up the lake as code, (2) land operational history, (3) reconstruct the cycle, score impact, look until trusted, triage, (4) tell the story. Names and descriptions do not carry STEP numbers. Jupyter / Streamlit / QuickSight / Power BI are skills, not workflows.
Fix the Constraint, Not Everything	`fix-the-constraint-not-everything`	Delivery Constraint & Opportunity Analysis	Read the 'Fix the Constraint, Not Everything' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: fix-the-constraint-not-everything. always_apply: true. Per the DevOps Handbook's 1st Way, continually identify and address the single most significant bottleneck in the BizDevTestSecOps flow. Optimizing a non-constraint just moves the queue elsewhere and burns effort without moving end-to-end lead time.
GitHub OIDC Trust Both Sub Shapes	`github-oidc-trust-both-sub-shapes`	Delivery Constraint & Opportunity Analysis	Read the 'GitHub OIDC Trust Both Sub Shapes' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: github-oidc-trust-both-sub-shapes. always_apply: true. GitHub Actions OIDC `sub` claims come in two shapes: name-only `repo:{org}/{repo}:` and ID-qualified `repo:{org}@{ORG_ID}/{repo}@{REPO_ID}:ref:...`. The deploy IAM role must trust both*. Trusting only the name-only pattern causes AssumeRoleWithWebIdentity to fail on `main` pushes.
Headcount Is an Assumptions Table	`headcount-is-an-assumptions-table`	Delivery Constraint & Opportunity Analysis
Infrastructure as Code First	`infrastructure-as-code-first`	Delivery Constraint & Opportunity Analysis	Read the 'Infrastructure as Code First' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: infrastructure-as-code-first. always_apply: true. Every AWS resource this playbook creates — S3 buckets, Lambda functions, Glue database/crawlers, the Athena workgroup, IAM roles/policies, ECS Fargate Streamlit mart, GitHub OIDC deploy role — is defined in the CDK app (four stacks: Deploy, Ingestion, Catalog, Eda), not clicked into existence in the console. Deploy that app exclusively through CI (GitHub Actions or GitLab CI, matching wherever the repo lives) via `cdk deploy`; a laptop only ever runs `cdk bootstrap` plus one sandbox mint of the OIDC DeployStack, never a shared environment after that.
Least-Privilege IAM and Encryption by Default	`least-privilege-iam-and-encryption-by-default`	Delivery Constraint & Opportunity Analysis	Read the 'Least-Privilege IAM and Encryption by Default' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: least-privilege-iam-and-encryption-by-default. always_apply: true. Use IAM user/role policies (not just bucket ACLs) scoped to what each ingestion function and analytics tool actually needs. Encrypt data at rest with SSE-KMS and S3 Bucket Keys (`bucket_key_enabled=True` on raw, curated, and Athena-results buckets) and keep API tokens for GitLab/GitHub/Jira in Secrets Manager or SSM Parameter Store — never in code or SAM templates.
Lifecycle Cold Data to Cheaper Tiers	`lifecycle-cold-data-to-cheaper-tiers`	Delivery Constraint & Opportunity Analysis
Never Name GitHub Actions Secrets GITHUB_*	`never-name-gha-secrets-github-prefix`	Delivery Constraint & Opportunity Analysis	Read the 'Never Name GitHub Actions Secrets GITHUB_*' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: never-name-gha-secrets-github-prefix. always_apply: true. Do not name GitHub Actions repository secrets with the `GITHUB_` prefix (for example `GITHUB_PAT`). GitHub rejects that prefix. Use `AWS_DEPLOY_ROLE_ARN` for OIDC and `OPSLAKE_GITHUB_PAT` (or similar) for the GitHub API token, then sync the PAT into Secrets Manager from populate-lake.
No AI on Low Impact Just Because Easy	`no-ai-on-low-impact-just-because-easy`	Delivery Constraint & Opportunity Analysis
No EMR or Persistent Clusters for Ingestion	`no-emr-or-persistent-clusters-for-ingestion`	Delivery Constraint & Opportunity Analysis	Read the 'No EMR or Persistent Clusters for Ingestion' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: no-emr-or-persistent-clusters-for-ingestion. always_apply: true. Keep the ingestion path serverless and simple: CDK-modeled Lambda functions (and a CDK-modeled Kinesis Firehose delivery stream for streams) only. Do not stand up EMR or any persistent cluster to get operational data from GitLab/GitHub/Jira into the lake — that complexity belongs, if ever, to the broader analytics portfolio, not to basic ingestion.
No Huginn MCP Yet — Treat as Manual	`no-huginn-mcp-yet-treat-as-manual`	Delivery Constraint & Opportunity Analysis	Read the 'No Huginn MCP Yet — Treat as Manual' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: no-huginn-mcp-yet-treat-as-manual. always_apply: true. There is no MCP connector for Huginn today. Configure Huginn Agents through browser automation against its web UI (check the ../huginn repo for existing agent/scenario definitions first), and flag this as a candidate for a future MCP connector rather than trying to script around the gap.
Parquet Over Raw Formats	`parquet-over-raw-formats`	Delivery Constraint & Opportunity Analysis	Read the 'Parquet Over Raw Formats' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: parquet-over-raw-formats. always_apply: true. Transform raw JSON/CSV into Apache Parquet before it's queried at scale. AWS's benchmark: ~87% space savings, ~34x faster Athena queries, ~99.7% lower query cost versus CSV on the same 1 TB of log data. Raw format is fine for the landing zone; Parquet is required for anything queried repeatedly.
Partition by Source and Date at Minimum	`partition-by-source-and-date-at-minimum`	Delivery Constraint & Opportunity Analysis	Read the 'Partition by Source and Date at Minimum' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: partition-by-source-and-date-at-minimum. always_apply: true. Every curated table is Hive-partitioned as `{table}/source={source}/dt={yyyy-mm-dd}/` so Athena and Glue crawlers prune scans. `{table}` is a Lake Scope Contract view name. Raw JSON uses prefix `{source}/{yyyy}/{mm}/{dd}/` in a separate bucket. Add finer partitions only if query patterns justify them.
Partition Keys Stay Out of Parquet Body	`partition-keys-out-of-parquet-body`	Delivery Constraint & Opportunity Analysis	Read the 'Partition Keys Stay Out of Parquet Body' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: partition-keys-out-of-parquet-body. always_apply: true. Hive partition keys (`source`, `dt`) live in the S3 path `{table}/source={source}/dt={yyyy-mm-dd}/`. Do not also write those columns into the Parquet body. Glue crawlers then see duplicate columns and cataloging fails. Template: `infra/lambdas/parquet_transform.py` `_normalize_row` omits `source`.
S3 Bucket Keys With SSE-KMS	`s3-bucket-keys-with-sse-kms`	Delivery Constraint & Opportunity Analysis	Read the 'S3 Bucket Keys With SSE-KMS' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: s3-bucket-keys-with-sse-kms. always_apply: true. SSE-KMS on lake buckets (raw, curated, Athena results) must set `bucket_key_enabled=True` (S3 Bucket Keys). Without it, every PutObject is a KMS `GenerateDataKey` and every GetObject is a `Decrypt`. One-file-per-event Parquet plus Glue/Athena reads burned the 20k always-free KMS requests in a single backfill morning (opsdl, 2026-09-15). Template: `infra/ops_lake/ingestion_stack.py` `_make_bucket` / `_make_results_bucket`. Bucket Keys apply to new objects; existing objects keep per-object keys until overwritten. Do not attach a customer-managed `kms.Key` to buckets that also have S3→SQS notifications — CloudFormation hits `LakeKey -> RawBucket -> LakeKey`. Use `BucketEncryption.KMS_MANAGED` + Bucket Keys.
Streamlit Mart on ECS ALB Never App Runner	`streamlit-mart-ecs-alb-not-apprunner`	Delivery Constraint & Opportunity Analysis	Read the 'Streamlit Mart on ECS ALB Never App Runner' rule from playbook 'Delivery Constraint & Opportunity Analysis'. Slug: streamlit-mart-ecs-alb-not-apprunner. always_apply: true. Host the Streamlit data mart on ECS Fargate behind an ALB (WebSocket-capable). Do not use AWS App Runner: it does not support Streamlit WebSockets (`/_stcore/stream` → 403, blank loading skeleton). Image platform `linux/amd64`. Dockerfile must COPY all `*.py`, `pages/`, and `data/`.
Touch Time Is Not Wait Time	`touch-time-is-not-wait-time`	Delivery Constraint & Opportunity Analysis
Always check r together with its p-value	`always-check-r-together-with-its-p-value`	EDA with Python, Pandas and Jupyter
A non-significant linear correlation doesn't rule out a relationship	`a-non-significant-linear-correlation-doesnt-rule-out-a-relationship`	EDA with Python, Pandas and Jupyter	Read the 'A non-significant linear correlation doesn't rule out a relationship' rule from playbook 'EDA with Python, Pandas and Jupyter'. Slug: a-non-significant-linear-correlation-doesnt-rule-out-a-relationship. always_apply: false. Absence of significant linear correlation may just mean the relationship is non-linear — investigate alternative relation models such as clustering instead of concluding "no relationship."
Avoid glyph-based multivariate displays	`avoid-glyph-based-multivariate-displays`	EDA with Python, Pandas and Jupyter
Bar-graph zero baseline	`bar-graph-zero-baseline`	EDA with Python, Pandas and Jupyter
Box plots beat all else for comparing distributions	`box-plots-beat-all-else-for-comparing-distributions`	EDA with Python, Pandas and Jupyter
Check for spurious or missed patterns before concluding	`check-for-spurious-or-missed-patterns-before-concluding`	EDA with Python, Pandas and Jupyter	Read the 'Check for spurious or missed patterns before concluding' rule from playbook 'EDA with Python, Pandas and Jupyter'. Slug: check-for-spurious-or-missed-patterns-before-concluding. always_apply: true. Before committing to a finding — statistical or visual — verify it against the underlying detail data, and deliberately re-examine with fresh eyes for a pattern that was missed or isn't really there.
Choose the right accuracy metric for the use case	`choose-the-right-accuracy-metric-for-the-use-case`	EDA with Python, Pandas and Jupyter
Colorblind-safe, non-black-midpoint heatmap coloring	`colorblind-safe-non-black-midpoint-heatmap-coloring`	EDA with Python, Pandas and Jupyter	Read the 'Colorblind-safe, non-black-midpoint heatmap coloring' rule from playbook 'EDA with Python, Pandas and Jupyter'. Slug: colorblind-safe-non-black-midpoint-heatmap-coloring. always_apply: false. In multivariate/heatmap displays, use a colorblind-safe diverging palette (e.g., blue↔gray↔red) rather than red/green, and avoid using a highly salient color like black to represent "near zero/average" values.
Confirm statistics with a visualization	`confirm-statistics-with-a-visualization`	EDA with Python, Pandas and Jupyter
Correlation is not causation	`correlation-is-not-causation`	EDA with Python, Pandas and Jupyter
Data science is science first	`data-science-is-science-first`	EDA with Python, Pandas and Jupyter
Design for working-memory limits	`design-for-working-memory-limits`	EDA with Python, Pandas and Jupyter
Dot plot instead of narrowed bars	`dot-plot-instead-of-narrowed-bars`	EDA with Python, Pandas and Jupyter
Justify the imputation method by domain knowledge	`justify-the-imputation-method-by-domain-knowledge`	EDA with Python, Pandas and Jupyter
k is an analyst's judgment call	`k-is-an-analysts-judgment-call`	EDA with Python, Pandas and Jupyter
Log scale or % change for comparing growth rates	`log-scale-or-change-for-comparing-growth-rates`	EDA with Python, Pandas and Jupyter
map() is not vectorized	`map-is-not-vectorized`	EDA with Python, Pandas and Jupyter
Merge for complementary data, concat for similar data	`merge-for-complementary-data-concat-for-similar-data`	EDA with Python, Pandas and Jupyter
Missing values can't be dropped cell-by-cell	`missing-values-cant-be-dropped-cell-by-cell`	EDA with Python, Pandas and Jupyter
Model quality must be measured, not assumed	`model-quality-must-be-measured-not-assumed`	EDA with Python, Pandas and Jupyter
Never plot missing values as zero	`never-plot-missing-values-as-zero`	EDA with Python, Pandas and Jupyter
Never touch test data while building a model	`never-touch-test-data-while-building-a-model`	EDA with Python, Pandas and Jupyter
Over-plotting remedy order	`over-plotting-remedy-order`	EDA with Python, Pandas and Jupyter	Read the 'Over-plotting remedy order' rule from playbook 'EDA with Python, Pandas and Jupyter'. Slug: over-plotting-remedy-order. always_apply: false. To fix over-plotted scatter/point charts, try in order: reduce point size → remove fill color (outline only) → change point shape → jitter → add transparency → encode density via contours/heatmap cells → reduce the data itself (aggregate, filter, trellis, or sample).
pandas correlation lacks significance testing	`pandas-correlation-lacks-significance-testing`	EDA with Python, Pandas and Jupyter
Pie charts underperform bar graphs	`pie-charts-underperform-bar-graphs`	EDA with Python, Pandas and Jupyter
Precision hierarchy of pre-attentive attributes	`precision-hierarchy-of-pre-attentive-attributes`	EDA with Python, Pandas and Jupyter
Prefer scriptable, reproducible pipelines	`prefer-scriptable-reproducible-pipelines`	EDA with Python, Pandas and Jupyter
Recommended train/test split is 70:30	`recommended-traintest-split-is-7030`	EDA with Python, Pandas and Jupyter
Resistant statistics for skewed/outlier-prone data	`resistant-statistics-for-skewedoutlier-prone-data`	EDA with Python, Pandas and Jupyter
Round numbers on axes	`round-numbers-on-axes`	EDA with Python, Pandas and Jupyter
Running averages over single trend lines for time series	`running-averages-over-single-trend-lines-for-time-series`	EDA with Python, Pandas and Jupyter	Read the 'Running averages over single trend lines for time series' rule from playbook 'EDA with Python, Pandas and Jupyter'. Slug: running-averages-over-single-trend-lines-for-time-series. always_apply: false. Smooth a volatile time series with a running (moving) average rather than a single linear trend line, because a trend line's slope depends heavily and misleadingly on the exact start/end dates chosen.
Scale variables before clustering	`scale-variables-before-clustering`	EDA with Python, Pandas and Jupyter
Square scatterplot aspect ratio	`square-scatterplot-aspect-ratio`	EDA with Python, Pandas and Jupyter
Trellis consistency	`trellis-consistency`	EDA with Python, Pandas and Jupyter
Trend-line model matching	`trend-line-model-matching`	EDA with Python, Pandas and Jupyter
Validate regression by comparing train vs. test fit	`validate-regression-by-comparing-train-vs-test-fit`	EDA with Python, Pandas and Jupyter
Watch for duplicate keys after vertical concat	`watch-for-duplicate-keys-after-vertical-concat`	EDA with Python, Pandas and Jupyter
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
Band → Ticket Type Mapping	`band-ticket-type-mapping`	Junior Edda	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.
Cadence and Iteration Length by Team Maturity	`cadence-and-iteration-length-by-team-maturity`	Junior Edda	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.
Charter Is Source of Truth for Variables	`charter-is-source-of-truth-for-variables`	Junior Edda	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.
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.
Fan Out Independent Work	`fan-out-independent-work`	Junior Edda	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.
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.
One Ticket Per Concern	`one-ticket-per-concern`	Junior Edda	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.
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: 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.
Pull Frequently	`do-pull-frequently`	Junior Edda
Pytest	`pytest`	Junior Edda
Release Roadmap Is Aspirational	`release-roadmap-is-aspirational`	Junior Edda	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.
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 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.
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 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/` \|
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.
Ticket Lifecycle Transitions	`ticket-lifecycle-transitions`	Junior Edda	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.
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
Variable Band Scale Flexibility	`variable-band-scale-flexibility`	Junior Edda	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.
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