Skills

Title	Capability Domain	Technology Stack	Playbook	Actions
Agent Integration Proof Patterns	—	—	Junior Edda	Read the 'Agent Integration Proof Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. # Skill: Agent Integration Proof Patterns Capability Domain: TEST_INTEGRATION Technology Stack: pytest, CAP-004, artifact-56 Linked Activities: TFK-02, BPE-02, DTA-19 ## Overview Patterns for lane 1 (control-plane proofs) and lane 2 (deterministic shell) agent testing. Proves orchestration under ScriptedLLM — not model quality. Generic for any project with SAO §17 and selected PRF-* rows from artifact 56 Part 4.5. ## Principles 1. Only CAP-004 mocks the LLM. Real DB, real broker (if used), real tool registry. 2. Assert the control plane, not chat prose. Workflow id, tool names, domain writes, plan/step transitions, blackboard keys. 3. Scripted queue = test oracle for LLM turns. Temperature irrelevant in lane 1. 4. Happy + reject for adverse PRF rows (429, parse fail, HITL block, exhausted queue). ## Harness (TFK-02) See rule `do-assert-agent-story` and TFK-02 for `assert_agent_story` and `@pytest.mark.agent_proof`. ## Lane 2 (deterministic shell) Non-LLM steps are ordinary pytest — no `@agent_proof`, no ScriptedLLM. ## CI Lane 1 via `make test-agent-proof` when `AGENTS_ENABLED=true`. Do not add `-m agent_proof` to default PR CI until PRF tests exist. ## Anti-patterns FakeLLM silent fallback; `@patch` on ToolExecutor; asserting assistant wording. ## References Artifact 56 Part 4.5; Rule `do-assert-agent-story`.
Agent Task Eval	—	—	Junior Edda	Read the 'Agent Task Eval' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. # Skill: Agent Task Eval Capability Domain: TEST_INTEGRATION Technology Stack: pytest, golden-tasks, optional-deepeval Linked Activities: TFK-04, TFK-05, TFK-09, DTA-19 ## Overview Patterns for lane 4 (task performance quality): frozen tasks with structured ground truth. ## Principles 1. Structured oracle is source of truth. 2. Same harness as lane 1; live provider at temp=0. 3. Not a PR merge gate — promotion band vs last certified baseline. 4. Deepeval optional overlay for fuzzy SC-01 only. ## Golden task catalog See artifact 56 Part 4.6 — TASK-* under `tests/fixtures/agent_tasks/`. ## Makefile / CI `make test-agent-quality` gated on `AGENTS_ENABLED`; separate `agent-eval.yml`. ## References Artifact 56 Part 4.6; DTA-19 §16.
AutoFixture and FactoryBoy Patterns	Test Data Management	factory-boy, pytest-fixtures, django-orm	Junior Edda	Read the 'AutoFixture and FactoryBoy Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: Test Data Management Technology stack: factory-boy, pytest-fixtures, django-orm # Skill: AutoFixture and FactoryBoy Patterns Capability Domain: TEST_DATA Technology Stack: FactoryBoy+Django+AutoFixture ## Overview Patterns for dynamic test data generation using FactoryBoy and AutoFixture. Covers when to use JSON fixtures vs factories, scoping strategies, preset patterns, and the lazy AutoFixture approach. ## Reference Implementation ### Pattern 1: FactoryBoy Model Factories ```python import factory from factory.django import DjangoModelFactory class UserFactory(DjangoModelFactory): class Meta: model = 'auth.User' username = factory.Sequence(lambda n: f'user_{n}') email = factory.LazyAttribute(lambda o: f'{o.username}@example.com') is_active = True class PlaybookFactory(DjangoModelFactory): class Meta: model = 'methodology.Playbook' name = factory.Sequence(lambda n: f'Playbook {n}') description = factory.Faker('paragraph') author = factory.SubFactory(UserFactory) ``` ### Pattern 2: AutoFixture — For Lazy Guys Create model instances with sensible random defaults when you don't care about specific field values. ### Pattern 3: Four Fixture Tiers \| Tier \| Tool \| Scope \| When \| \|------\|------\|-------\|------\| \| Session \| JSON (seed.json) \| Entire test run \| Static reference data \| \| Suite \| JSON (presets/) \| Group of tests \| Shared scenario setup \| \| Test \| FactoryBoy \| Single test \| Dynamic, parameterized \| \| Lazy \| AutoFixture \| Single test \| Don't care about specifics \|
AWS CDK with Python	INFRASTRUCTURE_AS_CODE	AWS CDK + Python	Junior Edda	Read the 'AWS CDK with Python' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: INFRASTRUCTURE_AS_CODE Technology stack: AWS CDK + Python # Skill: AWS CDK with Python Capability Domain: INFRASTRUCTURE_AS_CODE Technology Stack: AWS CDK + Python ## Overview Reference patterns for building AWS infrastructure using CDK with Python. Covers EKS and Elastic Beanstalk deployment styles. All patterns follow CDK best practices: typed constructs, explicit dependencies, proper tagging. Choose path per `INFRA_REQUIREMENTS.md` § Deployment Style. --- ## EKS Patterns (Patterns 1–8) (Existing patterns unchanged: VPC, EKS cluster, ECR, Route53 hosted zone, security groups, OIDC for GitHub Actions, CDK context, CDK testing, cost reference ~$160/mo baseline.) See playbook v39+ for full EKS pattern code blocks. --- ## Elastic Beanstalk Patterns ### Pattern 9: EB Application + Twin Environments ```python from aws_cdk import Stack, aws_elasticbeanstalk as eb, aws_ecr as ecr, aws_iam as iam from constructs import Construct EB_SOLUTION_STACK = "64bit Amazon Linux 2023 v4.x running Docker" class AppStack(Stack): def __init__(self, scope, id, , vpc, eb_sg, acm_cert_arn, kwargs): super().__init__(scope, id, kwargs) # Reference existing ECR repo — do not recreate if CI already created it self.web_repo = ecr.Repository.from_repository_name(self, "EcrRepo", "{project}") self.app = eb.CfnApplication(self, "App", application_name="{project}") # Import pre-existing EB service/instance roles when migrating # Create env_a ({project}-prod) and env_b ({project}-idle) with option_settings ``` Key decisions:* - `from_repository_name` when ECR pre-exists — avoids "already exists" deploy failures - Import existing IAM roles (`aws-elasticbeanstalk-ec2-role`) during brownfield migration - Platform settings loaded from exported JSON snapshot (Pattern 11) ### Pattern 10: Route53 CNAME via Lambda UPSERT Public domain CNAME → `{project}-prod.eba-xxxxx.elasticbeanstalk.com`. Use Lambda custom resource (not raw `CnameRecord`) for idempotent UPSERT on re-deploy. Never point Route53 at ALB ARN — breaks EB CNAME swap on promotion. ### Pattern 11: EB Platform Settings Export Two sources of truth: \| What \| Where \| \|------\|--------\| \| Platform settings \| `eb_live_platform_settings.json` (exported, committed) \| \| Secrets \| `infra/.env` at synth/deploy (gitignored) \| ```python # stacks/eb_env.py EB_SECRET_KEYS = frozenset({"DATABASE_URL", "DJANGO_SECRET_KEY", ...}) def secret_env_values() -> dict[str, str]: load_dotenv("infra/.env") return {k: os.environ[k] for k in EB_SECRET_KEYS if os.environ.get(k)} ``` Refresh after console changes: ```bash python infra/scripts/export_eb_live_settings.py python infra/scripts/diff_eb_live_vs_cdk.py # 0 diffs before deploy ``` ### Pattern 12: Pre-Migrate Backup Stack ```python class BackupsStack(Stack): # S3 bucket: {project}-db-backups-{account} # Lifecycle: expire pre-migrate/ prefix after 90 days # IAM: MimirDbBackup policy on aws-elasticbeanstalk-ec2-role # Attach AmazonSSMManagedInstanceCore for SSM SendCommand backup ``` Backup runs in deploy-idle.sh before `update-environment`, not in container entrypoint. ### Pattern 13: CI Deploy IAM User Create `mimir-ci`-style user with scoped policy: - `ecr:` push to app repo - `elasticbeanstalk:` deploy - `s3:PutObject` on EB bundle bucket + backup bucket list/verify - `ssm:SendCommand` on EB instances for pre-deploy backup Prefer OIDC over long-lived keys when feasible. ### EB Cost Reference \| Resource \| Approximate Monthly Cost \| \|----------\|-------------------------\| \| 2× EB t3.small Docker envs \| ~$30–60 \| \| NAT Gateway (1) \| ~$30 + transfer \| \| Route53 hosted zone \| ~$0.50 \| \| S3 backups \| ~$1–5 \| \| Total (baseline) \| ~$65–95/month \| --- ## Common Pitfalls (Both Paths) 1. EKS creation time — ~15 min; don't abort early 2. CDK drift — don't modify CDK-managed resources in console without re-export 3. EB: recreating ECR — use `from_repository_name` for brownfield 4. EB: ALB-alias Route53 — breaks CNAME swap; use EB label CNAME 5. Removal policies — `RETAIN` for ECR, S3 backups, databases
AWS Elastic Beanstalk Blue/Green Deployment	—	—	Junior Edda	Read the 'AWS Elastic Beanstalk Blue/Green Deployment' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. # Skill: AWS Elastic Beanstalk Blue/Green Deployment Capability Domain: CI_CD Technology Stack: AWS Elastic Beanstalk + ECR + GitHub Actions ## Overview Reference patterns for deploying applications to AWS Elastic Beanstalk using a two-environment CNAME-swap blue/green model. One environment always holds the `prod` CNAME (live traffic); the other is `idle` (staging). Deployments always go to idle first, are smoke-tested, then promoted by swapping CNAMEs. Roles flip on every swap — no environment is permanently "prod" or "idle". ## Mental Model ``` EB_ENV_A ({project}-prod) ↔ EB_ENV_B ({project}-idle) ↑ ↑ CNAME: {project}-prod.* CNAME: {project}-idle.* Live = whichever env currently owns the {project}-prod CNAME. Idle = the other one. After swap-environment-cnames: roles are reversed. ``` - Never hard-code which physical env is prod — resolve at runtime by CNAME inspection. - Both envs run the same Docker image (from ECR); only the CNAME differs. - The EB application version is tracked by `VersionLabel` (e.g. `v-v0.0.41-abc1234-r42`). ## Pattern 1: Idle-First Deploy (`deploy-idle.sh`) ### 1a. Resolve live/idle dynamically ```bash CNAME_A=$(aws elasticbeanstalk describe-environments \ --application-name "$EB_APP" \ --environment-names "$EB_ENV_A" \ --query 'Environments[0].CNAME' --output text) if echo "$CNAME_A" \| grep -q "{project}-prod"; then LIVE_ENV="$EB_ENV_A"; IDLE_ENV="$EB_ENV_B" else LIVE_ENV="$EB_ENV_B"; IDLE_ENV="$EB_ENV_A" fi echo "Deploying to idle: $IDLE_ENV" ``` Critical: grep pattern must match the exact prod subdomain prefix. A mismatch silently deploys to the wrong environment. ### 1b. Pre-deploy DB backup (fail-closed) Before uploading bundle or calling `update-environment`: ```bash bash scripts/run-eb-backup.sh # SSM SendCommand on idle EC2 aws s3 ls "s3://${S3_BACKUP_BUCKET}/pre-migrate/${GIT_REVISION}/" --recursive \| head -5 # Abort deploy if backup missing ``` Uses SSM to run `pre_deploy_backup` on idle host: `pg_dump` + `dumpdata` → S3. Requires `AmazonSSMManagedInstanceCore` on EB instance role. ### 1c. Upload bundle and create application version ```bash S3_KEY="${EB_APP}/${VERSION_LABEL}/deploy-bundle.zip" aws s3 cp "$DEPLOY_BUNDLE_PATH" "s3://${EB_BUCKET}/${S3_KEY}" --quiet EXISTS=$(aws elasticbeanstalk describe-application-versions \ --application-name "$EB_APP" \ --version-labels "$VERSION_LABEL" \ --query "length(ApplicationVersions)" --output text) [ "${EXISTS}" = "0" ] && aws elasticbeanstalk create-application-version \ --application-name "$EB_APP" \ --version-label "$VERSION_LABEL" \ --source-bundle "S3Bucket=${EB_BUCKET},S3Key=${S3_KEY}" \ --no-auto-create-application --output text > /dev/null ``` ### 1d. Deploy and poll until Ready ```bash OPTION_SETTINGS="Namespace=aws:elasticbeanstalk:application:environment,OptionName={PROJECT}_GIT_REVISION,Value=${GIT_REVISION}" # Optional: propagate GH_BUG_REPORT_TOKEN → GITHUB_TOKEN on EB env if [ -n "${GH_BUG_REPORT_TOKEN:-}" ]; then OPTION_SETTINGS="${OPTION_SETTINGS} Namespace=aws:elasticbeanstalk:application:environment,OptionName=GITHUB_TOKEN,Value=${GH_BUG_REPORT_TOKEN}" fi aws elasticbeanstalk update-environment \ --application-name "$EB_APP" \ --environment-name "$IDLE_ENV" \ --version-label "$VERSION_LABEL" \ --option-settings ${OPTION_SETTINGS} \ --output text > /dev/null for i in $(seq 1 40); do STATUS=$(aws elasticbeanstalk describe-environments ... --query "Environments[0].Status" --output text) HEALTH=$(aws elasticbeanstalk describe-environments ... --query "Environments[0].Health" --output text) [ "${STATUS}" = "Ready" ] && { [ "${HEALTH}" = "Red" ] && exit 1 \|\| break; } sleep 15 done ``` > Use `{PROJECT}_GIT_REVISION` env var (e.g. `MIMIR_GIT_REVISION`) — set by CI, read by `/health/`. ### 1e. Smoke-test idle — verify revision ```bash HTTP_STATUS=$(curl -o /tmp/idle-health.json -s -w "%{http_code}" \ --max-time 30 --retry 15 --retry-delay 10 --retry-all-errors \ "http://${IDLE_CNAME}/health/") ACTUAL=$(python3 -c 'import json; print(json.load(open("/tmp/idle-health.json")).get("revision","unknown"))') [ "$ACTUAL" != "$GIT_REVISION" ] && exit 1 echo "Idle smoke OK. Run 'make swap' to promote." ``` ## Pattern 2: CNAME Swap & Prod Smoke (`promote-prod.sh`) ### 2a. Revision guard Accept release tag (e.g. `v0.0.47`) or EB VersionLabel (e.g. `v-v0.0.47-abc-r42`): ```bash IDLE_LABEL=$(aws elasticbeanstalk describe-environments ... --query 'Environments[0].VersionLabel' --output text) IDLE_REVISION=$(curl -s "http://${IDLE_CNAME}/health/" \| python3 -c 'import json,sys; print(json.load(sys.stdin).get("revision",""))') if [ -n "${EXPECTED_REVISION:-}" ]; then [ "$EXPECTED_REVISION" != "$IDLE_REVISION" ] && [ "$EXPECTED_REVISION" != "$IDLE_LABEL" ] && exit 1 fi EXPECTED_REVISION="${EXPECTED_REVISION:-$IDLE_REVISION}" ``` ### 2b. Swap CNAMEs ```bash aws elasticbeanstalk swap-environment-cnames \ --source-environment-name "$IDLE_ENV" \ --destination-environment-name "$LIVE_ENV" sleep 90 # Route53 TTL 60s + resolver cache — do not shorten ``` ### 2c. Poll prod URL until revision matches Poll `https://app.example.com/health/` up to 18×10s for HTTP 200 + revision match. ## Pattern 3: GitHub Actions Wiring Release-triggered (Huginn model), not push-triggered: ```yaml on: release: types: [published] workflow_dispatch: jobs: test: { ... } build-and-push: needs: test # ECR: web image; Docker Hub: client-side MCP facade (not deployed to EB) deploy-idle: needs: build-and-push if: vars.AWS_ACCOUNT_ID != '' run: bash scripts/deploy-idle.sh # Separate promote.yml — workflow_dispatch only # environment: production (approval gate) ``` ## Pattern 4: Required Secrets & Variables \| Name \| Type \| Description \| \|------\|------\|-------------\| \| `AWS_ACCESS_KEY_ID` \| Secret \| IAM key (or use OIDC) \| \| `AWS_SECRET_ACCESS_KEY` \| Secret \| IAM secret \| \| `DOCKERHUB_USERNAME` \| Secret \| For MCP facade image (optional) \| \| `DOCKERHUB_TOKEN` \| Secret \| Docker Hub token \| \| `GH_BUG_REPORT_TOKEN` \| Secret \| PAT → mapped to `GITHUB_TOKEN` on EB at deploy \| \| `AWS_ACCOUNT_ID` \| Variable \| S3 bucket + ECR URI construction \| \| `S3_BACKUP_BUCKET` \| Variable \| Pre-migrate backup bucket \| ## Pattern 5: Smoke-Test Contract `GET /health/` → `{"status":"ok","revision":"<GIT_REVISION>"}`. Idle uses HTTP on EB CNAME; prod uses HTTPS on custom domain. ## Pattern 6: Pre-Deploy Backup via SSM Order: resolve idle → SSM backup → verify S3 → upload bundle → update-environment → migrate in entrypoint → smoke. S3 layout: `s3://{bucket}/pre-migrate/{GIT_REVISION}/{timestamp}/mimir.sql.gz` Manual: `make backup` (requires `DATABASE_URL`, `S3_BACKUP_BUCKET`). ## Pattern 7: Route53 for EB Public domain CNAME → `{project}-prod.eba-….elasticbeanstalk.com` (fixed label). Promotion = EB CNAME swap only. Route53 record unchanged. Anti-pattern: Route53 A-alias to ALB ARN — swap has no effect on live traffic. ## Pattern 8: CDK Platform Snapshot Export live EB settings (no secrets) → `eb_live_platform_settings.json`. Diff before deploy: `diff_eb_live_vs_cdk.py` → 0 platform diffs. Secrets via `infra/.env` at `cdk deploy`. ## Common Pitfalls 1. Wrong CNAME grep pattern — deploys to live env 2. DNS sleep too short — prod smoke hits old env 3. Hardcoded idle env name — after swap, `{project}-idle` may be live 4. Skipping idle smoke — bad image becomes prod after swap 5. Health=Red on Ready — always check Health after poll 6. ALB-alias Route53 — CNAME swap ineffective 7. ELB health 400 — add instance private IP to ALLOWED_HOSTS (IMDSv2) 8. Concurrent deploys — use release-only trigger, not push + release simultaneously
Behave-Django BDD Runner	BDD Test Execution	behave, django, behave-django	Junior Edda	Read the 'Behave-Django BDD Runner' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: BDD Test Execution Technology stack: behave, django, behave-django # Skill: Behave-Django BDD Runner Capability Domain: BDD_RUNNER Technology Stack: behave+Django+Playwright ## Overview Patterns for running BDD acceptance and E2E tests using behave-django. AT uses Django test client under `docs/features/`. E2E uses Playwright + LiveServer under `tests/e2e/`. Same Gherkin phrases; separate step libraries and `environment.py` files. ## Reference Implementation ### Pattern 1: behave.ini Configuration ```ini [behave] paths = docs/features format = pretty logging_level = INFO tags = ~@wip stdout_capture = false stderr_capture = false log_capture = false ``` Makefile: `make test-at` → `docs/features/`; `make test-e2e` → `tests/e2e/` (overrides path). ### Pattern 2: environment.py Lifecycle (Acceptance Tests) ```python # docs/features/environment.py import django from django.test.utils import setup_test_environment, teardown_test_environment from django.core.management import call_command def before_all(context): django.setup() setup_test_environment() call_command('loaddata', 'tests/fixtures/seed.json') def before_scenario(context, scenario): from django.test import TestCase context._test = TestCase('__init__') context._test._pre_setup() def after_scenario(context, scenario): context._test._post_teardown() def after_all(context): teardown_test_environment() ``` ### Pattern 3: environment.py Lifecycle (E2E Tests with Playwright) ```python # tests/e2e/environment.py # Playwright browser, LiveServerTestCase, base_url targeting, screenshot-on-step. ``` AT is not LiveServer. LiveServer belongs to E2E only. ### Pattern 4: E2E Session Auth (Django + Playwright) Problem: Hand-rolling `SessionStore` keys or skipping auth causes Playwright requests to hit the app as anonymous — steps time out looking for authenticated UI. Solution: Create the user in the test DB, authenticate via Django's test `Client`, copy the `sessionid` cookie into Playwright before navigation. ```python from django.test import Client def force_login_playwright(context, user, live_server_url: str) -> None: """Inject Django session cookie so Playwright requests are authenticated.""" client = Client() client.force_login(user) client.get("/") # materialize session session_key = client.cookies["sessionid"].value base = live_server_url.rstrip("/") context.page.goto(base + "/") context.page.context.add_cookies( [ { "name": "sessionid", "value": session_key, "domain": "localhost", "path": "/", } ] ) ``` Do not: construct session keys manually; assume login UI exists when AT/E2E can seed users via factories. When: any E2E step that needs an authenticated browser session on a Django app using session middleware. ### Pattern 5: Idempotent behave Fixture Givens Problem: A `Background:` block and a scenario-specific `Given` both `create()` entities with the same natural key (slug, username, unique together) → `IntegrityError` on the second insert. Solution: In step definitions that seed data, use `get_or_create` or update-in-place when the natural key is stable across Background + scenario. ```python from behave import given @given('the tenant "{slug}" exists') def step_tenant_exists(context, slug): obj, created = Tenant.objects.get_or_create( slug=slug, defaults={"name": slug.title()}, ) if not created: obj.name = slug.title() obj.save(update_fields=["name"]) ``` Rule: If Background already seeds entity X, scenario Givens that touch X must be idempotent — not blind `create()`. When: any behave feature with shared Background + per-scenario data setup.
Bootstrap 5-based Design System for Django & HTMX	—	—	Junior Edda	Read the 'Bootstrap 5-based Design System for Django & HTMX' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. # Skill: Bootstrap 5-based Design System for Django & HTMX Capability Domain: FRONTEND_FRAMEWORK Technology Stack: Bootstrap 5.3+ · Django 5 · HTMX ## Overview Reference implementation for ESM-03 "Define Information Architecture" when the stack is Bootstrap 5 + Django + HTMX. Covers all 9 sections of the IA outline — the original 4 (tokens, layouts, navigation, components) and the 5 added by this PIP (page header, CRUDLF templates, button placement, feedback system, component states). Use this skill as a starting point. Copy the patterns that fit your project and adjust tokens, column splits, and colour semantics to match your design decisions. --- ## 1. Design Tokens (Bootstrap 5 Extension Pattern) Extend Bootstrap's CSS variables rather than overriding them. Prefix Mimir/project-specific tokens with `--{project}-`. ```css /* base.css / :root { / Project palette — extend Bootstrap, never shadow it / --project-bg-body: #f5f5f5; --project-bg-surface: #ffffff; / Card chrome / --project-card-shadow: 0 2px 4px rgba(0,0,0,.08); --project-card-shadow-hover: 0 4px 12px rgba(0,0,0,.15); --project-card-radius: 0.5rem; / Stat-card accent colours / --project-purple: #5856d6; --project-blue: #38a9f0; --project-orange: #ffa726; --project-red: #ef5350; } [data-bs-theme="dark"] { --project-bg-body: #1a1a1a; --project-bg-surface: #2d2d2d; --project-purple: #7c7aec; --project-blue: #64c3ff; --project-orange: #ffb74d; --project-red: #f77673; } ``` Naming rule: `--{namespace}-{element}-{property}[-{modifier}]`. Use semantic names (`--project-bg-surface`) not literal values (`--project-white`). --- ## 2. Layout Patterns ### 2-Column (main + metadata sidebar) ```html <div class="container-fluid"> <div class="row"> <main class="col-lg-9"><!-- primary content --></main> <aside class="col-lg-3 bg-light p-3"><!-- metadata only — never navigation --></aside> </div> </div> ``` ### 3-Column (filters + content + metadata) ```html <div class="container-fluid"> <div class="row"> <aside class="col-lg-2"><!-- filters / quick actions --></aside> <main class="col-lg-8"><!-- content --></main> <aside class="col-lg-2"><!-- metadata / related info --></aside> </div> </div> ``` ### Grid (dashboard cards) ```html <div class="row g-3 mb-4"> <div class="col-12 col-sm-6 col-lg-3"><!-- stat card --></div> <!-- repeat 4 times --> </div> ``` --- ## 3. Navigation Design ```html <nav class="navbar navbar-expand-lg bg-white shadow-sm sticky-top"> <div class="container-fluid"> <a class="navbar-brand" href="/">Brand</a> <div class="collapse navbar-collapse"> <ul class="navbar-nav me-auto"> <li class="nav-item"> {# active state: exact match for single-page sections #} <a class="nav-link {% if request.path == '/dashboard/' %}active{% endif %}" href="/dashboard/" {% if request.path == '/dashboard/' %}aria-current="page"{% endif %} data-bs-toggle="tooltip" title="Dashboard"> <i class="fa-solid fa-gauge"></i> Dashboard </a> </li> <li class="nav-item"> {# active state: contains check for multi-page sections #} <a class="nav-link {% if '/playbooks/' in request.path %}active{% endif %}" href="/playbooks/" {% if '/playbooks/' in request.path %}aria-current="page"{% endif %} data-bs-toggle="tooltip" title="Playbooks"> <i class="fa-solid fa-book-sparkles"></i> Playbooks </a> </li> </ul> <ul class="navbar-nav ms-auto"> <!-- dark-mode toggle, notification badges, user dropdown --> </ul> </div> </div> </nav> ``` Breadcrumbs: ```html <nav aria-label="breadcrumb"> <ol class="breadcrumb"> <li class="breadcrumb-item"><a href="/">Home</a></li> <li class="breadcrumb-item"><a href="/playbooks/">Playbooks</a></li> <li class="breadcrumb-item active" aria-current="page">React Frontend</li> </ol> </nav> ``` --- ## 4. Component Patterns (Atomic Design) ### Button atom ```html <!-- icon before text (default) --> <button class="btn btn-primary" data-bs-toggle="tooltip" title="Save changes"> <i class="fa-solid fa-save me-2"></i>Save </button> <!-- icon-only (must have tooltip) --> <button class="btn btn-outline-secondary" data-bs-toggle="tooltip" title="Edit"> <i class="fa-solid fa-pen-to-square"></i> </button> ``` ### Empty state ```html <div class="text-center py-5"> <i class="fa-light fa-inbox fa-4x text-muted mb-3"></i> <h5>No items yet</h5> <p class="text-muted">Get started by creating your first item.</p> <button class="btn btn-primary mt-2"> <i class="fa-solid fa-plus me-2"></i>Create </button> </div> ``` --- ## 5. Page Header Pattern Every non-dashboard page uses a consistent two-row header immediately after the breadcrumb. ```html {# Row 1: breadcrumb (see section 3) #} {# Row 2: title + action cluster #} <div class="d-flex justify-content-between align-items-center mb-4"> <div> <h1 class="h3 mb-0">{{ page_title }}</h1> {# Detail pages only: metadata sub-row #} <div class="text-muted small mt-1">v{{ object.version }} · Updated {{ object.updated_at\|timesince }} ago</div> </div> {# Action cluster — see Section 7 for placement rules #} <div class="d-flex gap-2 flex-wrap"> {% block page_actions %}{% endblock %} </div> </div> ``` Rules: - List and View pages: action cluster in `{% block page_actions %}` - The sub-row (version / timestamp) is only shown on View and Edit pages - On mobile, action cluster wraps below the title (`flex-wrap`) --- ## 6. Baseline CRUDLF Page Templates ### List+Find (FOB-{ENTITY}-LIST+FIND) ```html {% extends "base.html" %} {% block content %} <div class="container-fluid p-4"> {# breadcrumb #} {# page header with "Create" primary action #} <div class="d-flex justify-content-between align-items-center mb-4"> <h1 class="h3 mb-0">{{ entity_plural }}</h1> <a href="{% url 'entity-create' %}" class="btn btn-primary"> <i class="fa-solid fa-plus me-2"></i>Create </a> </div> {# search / filter bar #} <div class="d-flex gap-2 mb-3"> <div class="input-group" style="max-width:360px;"> <span class="input-group-text"><i class="fa-solid fa-magnifying-glass"></i></span> <input type="text" class="form-control" placeholder="Search..." name="q" value="{{ request.GET.q }}"> </div> </div> {# table or empty state #} {% if object_list %} <div class="table-responsive"> <table class="table table-hover align-middle"> <thead> <tr> <th>Name</th> <th>Status</th> <th>Last Updated</th> <th class="text-end">Actions</th> </tr> </thead> <tbody> {% for item in object_list %} <tr> <td><a href="{{ item.get_absolute_url }}">{{ item.name }}</a></td> <td><span class="badge bg-success">{{ item.status }}</span></td> <td>{{ item.updated_at\|timesince }} ago</td> <td class="text-end"> <a href="{% url 'entity-edit' item.pk %}" class="btn btn-sm btn-outline-primary" data-bs-toggle="tooltip" title="Edit"> <i class="fa-solid fa-pen-to-square"></i> </a> <button class="btn btn-sm btn-outline-danger" data-bs-toggle="modal" data-bs-target="#deleteModal" data-id="{{ item.pk }}" data-bs-toggle2="tooltip" title="Delete"> <i class="fa-solid fa-trash"></i> </button> </td> </tr> {% endfor %} </tbody> </table> </div> {% else %} {# empty state — see Section 4 #} {% endif %} </div> {% endblock %} ``` ### View (FOB-{ENTITY}-VIEW) ```html <div class="container-fluid p-4"> <div class="row"> <main class="col-lg-9"> {# breadcrumb #} {# page header with Edit + Back actions #} <div class="tab-content">{# tabs for content sections #}</div> </main> <aside class="col-lg-3 bg-light p-3"> <h6 class="text-uppercase text-muted small mb-3">Details</h6> {# version, author, timestamps, tags — metadata only #} </aside> </div> </div> ``` ### Edit (FOB-{ENTITY}-EDIT) ```html <form method="post"> {% csrf_token %} <div class="row"> <div class="col-md-8"> {# primary fields #} </div> <div class="col-md-4"> <div class="card"> <div class="card-header">Settings</div> <div class="card-body">{# visibility, flags, secondary fields #}</div> </div> </div> </div> {# form footer — see Section 7 for button order #} <div class="d-flex justify-content-end gap-2 mt-4"> <a href="{{ cancel_url }}" class="btn btn-outline-secondary">Cancel</a> <button type="submit" class="btn btn-primary"> <i class="fa-solid fa-save me-2"></i>Save </button> </div> </form> ``` ### Delete — confirmation modal (no dedicated page) ```html <div class="modal fade" id="deleteModal" tabindex="-1"> <div class="modal-dialog"> <div class="modal-content"> <div class="modal-header"> <h5 class="modal-title">Delete {{ entity_name }}?</h5> <button type="button" class="btn-close" data-bs-dismiss="modal"></button> </div> <div class="modal-body"> <p>Are you sure you want to delete <strong id="deleteItemName"></strong>?</p> <div class="alert alert-warning"> <i class="fa-solid fa-triangle-exclamation me-2"></i>This action cannot be undone. </div> </div> <div class="modal-footer"> <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button> <form id="deleteForm" method="post"> {% csrf_token %} <button type="submit" class="btn btn-danger"> <i class="fa-solid fa-trash me-2"></i>Delete </button> </form> </div> </div> </div> </div> ``` --- ## 7. Button Placement Rules Universal rules: - Primary action is always rightmost* in its cluster. - Destructive action (Delete) is always leftmost in its cluster — never adjacent to the primary. - Use `d-flex justify-content-end gap-2 flex-wrap` for all action clusters. \| Context \| Corner \| Left → Right order \| \|---\|---\|---\| \| List / View page header \| Top-right \| Secondary actions … Primary \| \| Create / Edit form footer \| Bottom-right \| Cancel → Save draft → Submit \| \| Detail page with destructive action \| Top-right \| Delete … Secondary … Back \| \| Modal footer \| Bottom-right \| Cancel → Confirm \| ```html {# List / View header #} <div class="d-flex justify-content-end gap-2 flex-wrap"> <button class="btn btn-outline-secondary">Export</button> <a href="{% url 'entity-create' %}" class="btn btn-primary"> <i class="fa-solid fa-plus me-2"></i>Create </a> </div> {# Form footer #} <div class="d-flex justify-content-end gap-2 flex-wrap mt-4"> <a href="{{ cancel_url }}" class="btn btn-outline-secondary">Cancel</a> <button type="submit" name="action" value="draft" class="btn btn-outline-primary">Save draft</button> <button type="submit" class="btn btn-primary">Submit</button> </div> {# Detail page with Delete #} <div class="d-flex justify-content-end gap-2 flex-wrap"> <button class="btn btn-outline-danger" data-bs-toggle="modal" data-bs-target="#deleteModal">Delete</button> <a href="{% url 'entity-edit' object.pk %}" class="btn btn-outline-primary">Edit</a> <a href="{{ back_url }}" class="btn btn-secondary">Back</a> </div> ``` --- ## 8. Feedback / Notification System ### Toast container (in base.html) ```html <div class="toast-container position-fixed top-0 end-0 p-3" style="z-index:1090;"> {# toasts injected here by showToast() or Django message rendering #} </div> ``` ### Toast variants ```html {# success — auto-dismiss 5 s #} <div class="toast align-items-center text-bg-success border-0" role="alert"> <div class="d-flex"> <div class="toast-body"><i class="fa-solid fa-circle-check me-2"></i>{{ message }}</div> <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button> </div> </div> {# error — manual dismiss only #} <div class="toast align-items-center text-bg-danger border-0" role="alert"> <div class="d-flex"> <div class="toast-body"><i class="fa-solid fa-circle-exclamation me-2"></i>{{ message }}</div> <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button> </div> </div> ``` Same pattern for `text-bg-warning` (info icon) and `text-bg-info` (info icon), both auto-dismiss 5 s. Dismissal rules: - `success` + `info` + `warning`: `autohide: true, delay: 5000` - `error` / `danger`: `autohide: false` — user must dismiss manually ### showToast() JS helper ```javascript function showToast(message, type = 'success') { const container = document.querySelector('.toast-container'); const icons = { success: 'fa-circle-check', error: 'fa-circle-exclamation', warning: 'fa-triangle-exclamation', info: 'fa-circle-info' }; const bg = { success: 'text-bg-success', error: 'text-bg-danger', warning: 'text-bg-warning', info: 'text-bg-info' }; const autohide = type !== 'error'; container.insertAdjacentHTML('beforeend', ` <div class="toast align-items-center ${bg[type]} border-0" role="alert"> <div class="d-flex"> <div class="toast-body"><i class="fa-solid ${icons[type]} me-2"></i>${message}</div> <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button> </div> </div>`); const el = container.lastElementChild; const t = new bootstrap.Toast(el, { autohide, delay: 5000 }); t.show(); el.addEventListener('hidden.bs.toast', () => el.remove()); } ``` ### Django view → HTMX integration ```python # In Django view — set headers so HTMX can read them response['X-Toast'] = 'Playbook saved successfully!' response['X-Toast-Type'] = 'success' # success \| error \| warning \| info ``` ```javascript // In base.html — read headers after any HTMX request document.addEventListener('htmx:afterRequest', function (evt) { const msg = evt.detail.xhr.getResponseHeader('X-Toast'); const type = evt.detail.xhr.getResponseHeader('X-Toast-Type') \|\| 'success'; if (msg) showToast(msg, type); }); ``` ### Field validation — always inline, never a toast ```html <div class="mb-3"> <label for="name" class="form-label">Name <span class="text-danger"></span></label> <input type="text" class="form-control is-invalid" id="name" value="{{ form_data.name }}"> <div class="invalid-feedback"> <i class="fa-solid fa-circle-exclamation me-1"></i>{{ errors.name }} </div> </div> ``` --- ## 9. Component State Catalogue Document these 6 states for every interactive component. Minimum required: Button, Input, Card, Nav link. ### Button states ```css .btn-primary { / default / } .btn-primary:hover { transform: translateY(-1px); box-shadow: 0 4px 8px rgba(0,0,0,.15); } .btn-primary:focus { box-shadow: 0 0 0 .25rem rgba(13,110,253,.5); } .btn-primary:active { transform: translateY(0); } .btn-primary:disabled, .btn-primary[disabled] { opacity: .65; cursor: not-allowed; pointer-events: none; } / Loading: replace label with spinner, keep disabled / ``` ```html {# Loading state #} <button class="btn btn-primary" disabled> <span class="spinner-border spinner-border-sm me-2"></span>Saving... </button> ``` ### Input states ```css .form-control { / default / } .form-control:focus { border-color: var(--bs-primary); box-shadow: 0 0 0 .25rem rgba(13,110,253,.25); } .form-control.is-valid { border-color: var(--bs-success); } .form-control.is-invalid { border-color: var(--bs-danger); } .form-control:disabled { background: var(--bs-gray-200); cursor: not-allowed; } ``` ### Card states ```css .card { box-shadow: var(--project-card-shadow); transition: box-shadow .2s ease, transform .2s ease; } .card:hover { box-shadow: var(--project-card-shadow-hover); transform: translateY(-2px); } .card:focus-within { outline: 2px solid var(--bs-primary); outline-offset: 2px; } .card.selected { border: 2px solid var(--bs-primary); background: rgba(13,110,253,.04); } / Disabled: opacity .5, pointer-events none / / Loading: replace body content with skeleton shimmer */ ``` ### Skeleton shimmer (loading state for cards) ```css .skeleton { background: linear-gradient(90deg, var(--bs-gray-200) 25%, var(--bs-gray-100) 50%, var(--bs-gray-200) 75%); background-size: 200% 100%; animation: shimmer 1.5s ease-in-out infinite; border-radius: .25rem; } @keyframes shimmer { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } } .skeleton-title { height: 1.5rem; width: 40%; } .skeleton-text { height: 1rem; width: 100%; } ``` ### Nav link states ```css .nav-link { color: var(--bs-gray-700); transition: all .15s ease; } .nav-link:hover { color: var(--bs-primary); background: var(--bs-gray-100); border-radius: .375rem; } .nav-link:focus { outline: 2px solid var(--bs-primary); outline-offset: 2px; } .nav-link.active { color: var(--bs-primary); font-weight: 600; } .nav-link.disabled { color: var(--bs-gray-400); pointer-events: none; cursor: default; } ``` --- ## Quick-Start Checklist Before building any screen against this design system: - [ ] Tokens defined and CSS variables declared in `base.css` - [ ] Dark-mode overrides set under `[data-bs-theme="dark"]` - [ ] `showToast()` helper and `htmx:afterRequest` listener in `base.html` - [ ] Toast container `div` present in `base.html` - [ ] Page header template block wired in base template - [ ] CRUDLF skeletons available as Django template fragments - [ ] All buttons have tooltips (`data-bs-toggle="tooltip"`) - [ ] All interactive elements have `data-testid` attributes - [ ] Component states verified in both light and dark mode
Claude Token Tracking	TOKEN_CONSUMPTION	Claude API	Junior Edda	Read the 'Claude Token Tracking' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: TOKEN_CONSUMPTION Technology stack: Claude API # Skill: Claude Token Tracking Capability Domain: TOKEN_CONSUMPTION Technology Stack: Claude API ## Overview Track AI token consumption for EST workflow calibration. Logs token usage at the scenario level to `logs/consumption.log` in JSON format, enabling sprint-by-sprint estimate refinement via velocity factor calculation and K-token baseline updates. ## Reference Implementation ### Pattern 1: TokenTracker Utility Class Create `{app_name}/utils/token_tracker.py`: ```python import logging import json from datetime import datetime from typing import Optional, Dict, Any from dataclasses import dataclass, asdict # Dedicated logger for token consumption (writes to logs/consumption.log) consumption_logger = logging.getLogger('consumption') @dataclass class TokenConsumption: """Token consumption record for EST workflow.""" timestamp: str scenario_id: str user_id: int sprint: int tokens_used: int model: str operation: str status: str metadata: Optional[Dict[str, Any]] = None def to_json(self) -> str: """Convert to JSON string for logging.""" data = asdict(self) return json.dumps(data, separators=(',', ':')) class TokenTracker: """ Track AI token consumption for EST workflow calibration. Usage: tracker = TokenTracker( scenario_id="FOB-PLAYBOOKS-LIST-01", user_id=request.user.id, sprint=1 ) tracker.start() # ... AI-assisted work happens ... tracker.end(tokens_used=15234, model="claude-3-5-sonnet-20241022") The tracker logs to consumption.log in JSON format compatible with EST-08 Sprint Close & Rebaseline activity. """ def __init__( self, scenario_id: str, user_id: int, sprint: int = 1, operation: str = "implement" ): """ Initialize token tracker. :param scenario_id: BDD scenario ID (e.g., "FOB-PLAYBOOKS-LIST-01") :param user_id: User ID performing the work :param sprint: Sprint number (default: 1) :param operation: Operation type (default: "implement") """ self.scenario_id = scenario_id self.user_id = user_id self.sprint = sprint self.operation = operation self.start_time = None self.metadata = {} def start(self, metadata): """ Start tracking token consumption. :param metadata: Additional metadata to log (e.g., feature_name, activity) """ self.start_time = datetime.utcnow() self.metadata.update(metadata) consumption_logger.debug( f"Token tracking started \| " f"scenario_id={self.scenario_id} \| " f"user_id={self.user_id} \| " f"sprint={self.sprint}" ) def end( self, tokens_used: int, model: str, status: str = "completed", additional_metadata ): """ End tracking and log token consumption. :param tokens_used: Total tokens consumed :param model: AI model used (e.g., "claude-3-5-sonnet-20241022") :param status: Status (default: "completed", or "partial", "failed") :param additional_metadata: Additional metadata to include """ if self.start_time is None: consumption_logger.warning( f"Token tracking ended without start \| " f"scenario_id={self.scenario_id}" ) self.start_time = datetime.utcnow() # Merge metadata self.metadata.update(additional_metadata) # Create consumption record record = TokenConsumption( timestamp=datetime.utcnow().isoformat() + 'Z', scenario_id=self.scenario_id, user_id=self.user_id, sprint=self.sprint, tokens_used=tokens_used, model=model, operation=self.operation, status=status, metadata=self.metadata if self.metadata else None ) # Log as JSON (one line per record) consumption_logger.info(record.to_json()) # Also log human-readable summary to app.log duration = (datetime.utcnow() - self.start_time).total_seconds() logging.info( f"[TokenTracker] Token consumption logged \| " f"scenario_id={self.scenario_id} \| " f"tokens={tokens_used} \| " f"model={model} \| " f"duration_sec={duration:.1f}" ) def log_immediate( self, tokens_used: int, model: str, status: str = "completed", metadata ): """ Log token consumption immediately without start/end tracking. :param tokens_used: Total tokens consumed :param model: AI model used :param status: Status (default: "completed") :param metadata: Additional metadata """ self.metadata.update(metadata) record = TokenConsumption( timestamp=datetime.utcnow().isoformat() + 'Z', scenario_id=self.scenario_id, user_id=self.user_id, sprint=self.sprint, tokens_used=tokens_used, model=model, operation=self.operation, status=status, metadata=self.metadata if self.metadata else None ) consumption_logger.info(record.to_json()) def log_token_consumption( scenario_id: str, user_id: int, tokens_used: int, model: str, sprint: int = 1, operation: str = "implement", status: str = "completed", metadata ): """ Convenience function to log token consumption in one call. :param scenario_id: BDD scenario ID :param user_id: User ID :param tokens_used: Tokens consumed :param model: AI model used :param sprint: Sprint number :param operation: Operation type :param status: Status :param metadata: Additional metadata """ tracker = TokenTracker(scenario_id, user_id, sprint, operation) tracker.log_immediate(tokens_used, model, status, metadata) ``` ### Pattern 2: Integration with BPE Workflow Track tokens during feature implementation: ```python # In BPE-02 (Implement Backend) or similar from {app_name}.utils.token_tracker import TokenTracker def implement_scenario(scenario_id, user_id, sprint=1): """Implement a BDD scenario with token tracking.""" tracker = TokenTracker( scenario_id=scenario_id, user_id=user_id, sprint=sprint, operation="implement" ) tracker.start( feature_name="Playbook Management", activity="BPE-02-Implement_Backend" ) try: # AI-assisted implementation happens here # (This would be done via Cascade/Windsurf in practice) # Example: Track tokens from Claude API response tokens_used = get_tokens_from_claude_response() # See Pattern 3 tracker.end( tokens_used=tokens_used, model="claude-3-5-sonnet-20241022", status="completed", files_modified=["models.py", "services.py", "views.py"], tests_written=5 ) except Exception as e: # Log partial completion if failed tracker.end( tokens_used=get_tokens_from_claude_response(), model="claude-3-5-sonnet-20241022", status="failed", error=str(e) ) raise ``` ### Pattern 3: Extract Tokens from Claude API Methods to extract token usage from Claude API responses: ```python import anthropic import os def get_claude_client(): """Get Claude API client.""" return anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY")) def call_claude_with_tracking( prompt: str, scenario_id: str, user_id: int, sprint: int = 1, model: str = "claude-3-5-sonnet-20241022", max_tokens: int = 4096 ) -> tuple[str, int]: """ Call Claude API and return response with token count. :param prompt: Prompt to send to Claude :param scenario_id: Scenario ID for tracking :param user_id: User ID :param sprint: Sprint number :param model: Claude model to use :param max_tokens: Max tokens in response :return: Tuple of (response_text, tokens_used) """ client = get_claude_client() response = client.messages.create( model=model, max_tokens=max_tokens, messages=[{"role": "user", "content": prompt}] ) # Extract token usage from response tokens_used = response.usage.input_tokens + response.usage.output_tokens # Log token consumption log_token_consumption( scenario_id=scenario_id, user_id=user_id, tokens_used=tokens_used, model=model, sprint=sprint, operation="ai_call", status="completed", input_tokens=response.usage.input_tokens, output_tokens=response.usage.output_tokens ) return response.content[0].text, tokens_used def aggregate_tokens_from_api_logs(api_key: str, start_date: str, end_date: str) -> dict: """ Aggregate token usage from Claude API usage logs. :param api_key: Claude API key :param start_date: Start date (ISO format) :param end_date: End date (ISO format) :return: Dict with aggregated token usage Note: This requires access to Anthropic's usage API. Check https://docs.anthropic.com/claude/reference/usage """ # This is a placeholder - actual implementation depends on # Anthropic's usage API availability client = anthropic.Anthropic(api_key=api_key) # Hypothetical usage API call # usage = client.usage.list(start_date=start_date, end_date=end_date) # For now, parse from consumption.log return parse_consumption_log(start_date, end_date) ``` ### Pattern 4: Parse consumption.log for EST Workflow Utilities for EST-08 Sprint Close & Rebaseline: ```python import json from pathlib import Path from datetime import datetime from typing import List, Dict from collections import defaultdict def parse_consumption_log( log_file: Path = Path('logs/consumption.log'), sprint: Optional[int] = None, start_date: Optional[str] = None, end_date: Optional[str] = None ) -> List[Dict]: """ Parse consumption.log and return records. :param log_file: Path to consumption.log :param sprint: Filter by sprint number :param start_date: Filter by start date (ISO format) :param end_date: Filter by end date (ISO format) :return: List of consumption records """ records = [] if not log_file.exists(): return records with open(log_file, 'r') as f: for line in f: try: # Parse JSON log entry record = json.loads(line.strip()) # Apply filters if sprint is not None and record.get('sprint') != sprint: continue if start_date and record.get('timestamp', '') < start_date: continue if end_date and record.get('timestamp', '') > end_date: continue records.append(record) except json.JSONDecodeError: continue return records def aggregate_tokens_by_scenario(records: List[Dict]) -> Dict[str, int]: """ Aggregate token usage by scenario ID. :param records: List of consumption records :return: Dict mapping scenario_id to total tokens """ totals = defaultdict(int) for record in records: scenario_id = record.get('scenario_id') tokens = record.get('tokens_used', 0) totals[scenario_id] += tokens return dict(totals) def compute_velocity_factor( scenario_id: str, estimated_tokens: int, records: List[Dict] ) -> float: """ Compute velocity factor for a scenario. Velocity Factor = Actual Tokens / Estimated Tokens :param scenario_id: Scenario ID :param estimated_tokens: Estimated tokens from EST-05 :param records: Consumption records :return: Velocity factor """ actual_tokens = sum( r.get('tokens_used', 0) for r in records if r.get('scenario_id') == scenario_id ) if estimated_tokens == 0: return 1.0 return actual_tokens / estimated_tokens def generate_sprint_report(sprint: int, log_file: Path = Path('logs/consumption.log')) -> str: """ Generate sprint token consumption report for EST-08. :param sprint: Sprint number :param log_file: Path to consumption.log :return: Markdown report """ records = parse_consumption_log(log_file, sprint=sprint) totals = aggregate_tokens_by_scenario(records) report = f"# Sprint {sprint} Token Consumption Report\n\n" report += f"Total Scenarios: {len(totals)}\n" report += f"Total Tokens: {sum(totals.values()):,}\n\n" report += "## By Scenario\n\n" report += "\| Scenario ID \| Tokens Used \| Status \|\n" report += "\|-------------\|-------------\|--------\|\n" for scenario_id, tokens in sorted(totals.items()): # Get status from last record for this scenario scenario_records = [r for r in records if r.get('scenario_id') == scenario_id] status = scenario_records[-1].get('status', 'unknown') if scenario_records else 'unknown' report += f"\| {scenario_id} \| {tokens:,} \| {status} \|\n" return report ``` ### Pattern 5: Django Management Command Create management command for sprint reports: File*: `{app_name}/management/commands/sprint_token_report.py` ```python from django.core.management.base import BaseCommand from pathlib import Path from {app_name}.utils.token_tracker import generate_sprint_report class Command(BaseCommand): help = 'Generate sprint token consumption report' def add_arguments(self, parser): parser.add_argument('sprint', type=int, help='Sprint number') parser.add_argument( '--output', type=str, default=None, help='Output file path (default: stdout)' ) def handle(self, args, options): sprint = options['sprint'] output_file = options.get('output') self.stdout.write(f'Generating report for Sprint {sprint}...') report = generate_sprint_report(sprint) if output_file: Path(output_file).write_text(report) self.stdout.write( self.style.SUCCESS(f'Report written to {output_file}') ) else: self.stdout.write(report) ``` Usage: ```bash python manage.py sprint_token_report 1 python manage.py sprint_token_report 1 --output docs/plans/SPRINT_1_TOKENS.md ``` ### Pattern 6: Windsurf/Cascade Integration Track tokens when using Windsurf/Cascade for development: ```python # Add to project's AI context or workflow scripts def track_cascade_session(scenario_id: str, user_id: int, sprint: int): """ Track a Cascade development session. Note: This requires manual token extraction from Cascade logs or API usage dashboard. """ from {app_name}.utils.token_tracker import TokenTracker tracker = TokenTracker( scenario_id=scenario_id, user_id=user_id, sprint=sprint, operation="cascade_session" ) tracker.start( tool="Windsurf/Cascade", session_type="feature_implementation" ) # Development happens... # After session, manually log tokens from Cascade usage dashboard # Example: User checks Claude dashboard and sees 45,230 tokens used tracker.end( tokens_used=45230, model="claude-3-5-sonnet-20241022", status="completed", files_modified=12, tests_written=8, commits=3 ) ``` ## consumption.log Format Each line is a JSON object: ```json {"timestamp": "2026-04-08T14:30:00.123Z", "scenario_id": "FOB-PLAYBOOKS-LIST-01", "user_id": 1, "sprint": 1, "tokens_used": 15234, "model": "claude-3-5-sonnet-20241022", "operation": "implement", "status": "completed", "metadata": {"feature_name": "Playbook Management", "activity": "BPE-02", "files_modified": ["models.py", "services.py"], "tests_written": 5}} ``` Fields: - `timestamp`: ISO 8601 UTC timestamp - `scenario_id`: BDD scenario ID (e.g., "FOB-PLAYBOOKS-LIST-01") - `user_id`: User ID performing work - `sprint`: Sprint number - `tokens_used`: Total tokens consumed - `model`: AI model identifier - `operation`: Operation type ("implement", "test", "refactor", "debug", etc.) - `status`: "completed", "partial", "failed" - `metadata`: Optional dict with additional context ## EST-08 Integration ### Sprint Close Workflow 1. Collect actuals from `consumption.log`: ```python records = parse_consumption_log(sprint=1) totals = aggregate_tokens_by_scenario(records) ``` 2. Compute velocity factors: ```python for scenario_id, actual_tokens in totals.items(): estimated = get_estimate_from_excel(scenario_id) vf = compute_velocity_factor(scenario_id, estimated, records) print(f"{scenario_id}: VF={vf:.2f}") ``` 3. Update K-token baselines in Reference Table 4. Re-run Monte Carlo simulation with calibrated data ## Testing Token Tracking ```python # tests/test_token_tracker.py import json from pathlib import Path from {app_name}.utils.token_tracker import TokenTracker, parse_consumption_log def test_token_tracker_logs_json(tmp_path): """Verify TokenTracker logs valid JSON.""" log_file = tmp_path / 'consumption.log' # Configure logger to use temp file # ... logger configuration ... tracker = TokenTracker( scenario_id="TEST-01", user_id=1, sprint=1 ) tracker.log_immediate( tokens_used=1000, model="claude-3-5-sonnet-20241022" ) # Verify log file assert log_file.exists() # Verify JSON format with open(log_file) as f: record = json.loads(f.readline()) assert record['scenario_id'] == "TEST-01" assert record['tokens_used'] == 1000 def test_parse_consumption_log(): """Verify consumption log parsing.""" records = parse_consumption_log(sprint=1) assert isinstance(records, list) if records: assert 'scenario_id' in records[0] assert 'tokens_used' in records[0] ``` ## References - Activity EST-08 (Sprint Close and Rebaseline) - Sprint close workflow - Activity EST-05** (Produce Rough Estimates) - Token estimation - Anthropic Claude API: https://docs.anthropic.com/claude/reference/ - Anthropic Usage API: https://docs.anthropic.com/claude/reference/usage
Django Backend Implementation Patterns	BACKEND_FRAMEWORK	Django+Python+pytest	Junior Edda	Read the 'Django Backend Implementation Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: BACKEND_FRAMEWORK Technology stack: Django+Python+pytest # Skill: Django Backend Implementation Patterns Capability Domain: BACKEND_FRAMEWORK Technology Stack: Django+Python+pytest ## Overview Comprehensive patterns for implementing Django backend services following test-first development, repository pattern, and service layer architecture. Covers models, views, services, URL routing, and testing with Django TestCase and pytest. ## Reference Implementation ### Pattern 1: Django Views Architecture Django views should return rendered HTML templates (NOT JSON/DRF): ```python # methodology/views.py from django.shortcuts import render, redirect, get_object_or_404 from django.contrib.auth.decorators import login_required from django.contrib import messages from .services.playbook_service import PlaybookService @login_required def playbook_list(request): """List all playbooks for current user.""" service = PlaybookService() playbooks = service.get_user_playbooks(request.user) return render(request, 'playbooks/list.html', { 'playbooks': playbooks, 'page_title': 'My Playbooks' }) @login_required def playbook_create(request): """Create new playbook.""" if request.method == 'POST': service = PlaybookService() try: playbook = service.create_playbook( name=request.POST['name'], description=request.POST['description'], category=request.POST['category'], author=request.user ) messages.success(request, f'Playbook "{playbook.name}" created successfully') return redirect('playbook_detail', playbook_id=playbook.id) except ValidationError as e: messages.error(request, str(e)) return render(request, 'playbooks/create.html') ``` ### Pattern 2: Services Layer (Business Logic) Business logic shared between MCP and Web UI lives in services: ```python # methodology/services/playbook_service.py from django.core.exceptions import ValidationError from decimal import Decimal from ..models import Playbook class PlaybookService: """Business logic for playbook management.""" @staticmethod def create_playbook(name: str, description: str, category: str, author): """ Create a new playbook. :param name: Playbook name as str. Example: "React Development" :param description: Description as str. Example: "Modern React patterns" :param category: Category as str. Example: "development" :param author: User instance. Example: User(id=1, username="maria") :return: Created Playbook instance. Example: Playbook(id=1, name="React Development") :raises ValidationError: If name is empty or duplicate """ if not name or not name.strip(): raise ValidationError("Playbook name cannot be empty") if Playbook.objects.filter(name=name, author=author).exists(): raise ValidationError(f"Playbook '{name}' already exists") playbook = Playbook.objects.create( name=name, description=description, category=category, author=author, version=Decimal('0.1'), status='draft' ) return playbook @staticmethod def get_user_playbooks(user): """ Get all playbooks for a user. :param user: User instance. Example: User(id=1) :return: QuerySet of Playbooks. Example: <QuerySet [<Playbook: React Dev>]> """ return Playbook.objects.filter(author=user).order_by('-updated_at') ``` ### Pattern 3: Repository Pattern (Data Access Abstraction) Currently using Django ORM directly, but structured to allow swapping: ```python # methodology/repositories/playbook_repository.py from ..models import Playbook class PlaybookRepository: """Data access layer for Playbooks.""" def get_by_id(self, playbook_id: int): """Get playbook by ID.""" return Playbook.objects.get(id=playbook_id) def filter_by_user(self, user): """Get all playbooks for user.""" return Playbook.objects.filter(author=user) def create(self, kwargs): """Create new playbook.""" return Playbook.objects.create(kwargs) ``` ### Pattern 4: URL Pattern Registration Register views in app urls.py with descriptive names: ```python # methodology/urls.py from django.urls import path from . import views urlpatterns = [ # Playbook URLs path('playbooks/', views.playbook_list, name='playbook_list'), path('playbooks/create/', views.playbook_create, name='playbook_create'), path('playbooks/<int:playbook_id>/', views.playbook_detail, name='playbook_detail'), path('playbooks/<int:playbook_id>/edit/', views.playbook_edit, name='playbook_edit'), path('playbooks/<int:playbook_id>/delete/', views.playbook_delete, name='playbook_delete'), ] ``` Follow RESTful conventions: - List: `/resource/` - Create: `/resource/create/` - Detail: `/resource/<id>/` - Edit: `/resource/<id>/edit/` - Delete: `/resource/<id>/delete/` ### Pattern 5: Testing Django Views Use Django TestCase (NOT DRF test clients): ```python # tests/integration/test_playbook_views.py from django.test import TestCase, Client from django.contrib.auth.models import User from methodology.models import Playbook class PlaybookViewsTest(TestCase): """Test playbook views with Django test client.""" def setUp(self): """Set up test fixtures.""" self.client = Client() self.user = User.objects.create_user( username='testuser', password='testpass123' ) self.client.login(username='testuser', password='testpass123') def test_playbook_list_returns_correct_template(self): """Test playbook list view returns correct template.""" response = self.client.get('/playbooks/') self.assertEqual(response.status_code, 200) self.assertTemplateUsed(response, 'playbooks/list.html') self.assertIn('playbooks', response.context) def test_playbook_create_success(self): """Test creating playbook via POST.""" response = self.client.post('/playbooks/create/', { 'name': 'Test Playbook', 'description': 'Test description', 'category': 'test' }) self.assertEqual(response.status_code, 302) # Redirect self.assertTrue(Playbook.objects.filter(name='Test Playbook').exists()) def test_playbook_create_validation_error(self): """Test playbook create with invalid data.""" response = self.client.post('/playbooks/create/', { 'name': '', # Empty name 'description': 'Test', 'category': 'test' }) self.assertEqual(response.status_code, 200) # Re-render form self.assertContains(response, 'error') self.assertFalse(Playbook.objects.filter(description='Test').exists()) ``` ### Pattern 6: Testing with pytest Use pytest for unit and integration tests: ```python # tests/unit/test_playbook_service.py import pytest from django.contrib.auth.models import User from django.core.exceptions import ValidationError from methodology.services.playbook_service import PlaybookService from methodology.models import Playbook @pytest.mark.django_db class TestPlaybookService: """Test PlaybookService business logic.""" def test_create_playbook_success(self): """Test successful playbook creation.""" user = User.objects.create_user(username='testuser') service = PlaybookService() playbook = service.create_playbook( name='Test Playbook', description='Test description', category='test', author=user ) assert playbook.id is not None assert playbook.name == 'Test Playbook' assert playbook.status == 'draft' assert playbook.version == Decimal('0.1') def test_create_playbook_duplicate_name_raises_error(self): """Test creating duplicate playbook raises ValidationError.""" user = User.objects.create_user(username='testuser') service = PlaybookService() service.create_playbook( name='Duplicate', description='First', category='test', author=user ) with pytest.raises(ValidationError, match="already exists"): service.create_playbook( name='Duplicate', description='Second', category='test', author=user ) ``` ### Pattern 7: Model Registration with Admin Register new models with Django admin for easy data management: ```python # methodology/admin.py from django.contrib import admin from .models import Playbook, Workflow, Activity @admin.register(Playbook) class PlaybookAdmin(admin.ModelAdmin): list_display = ('name', 'version', 'status', 'author', 'updated_at') list_filter = ('status', 'category') search_fields = ('name', 'description') readonly_fields = ('created_at', 'updated_at') @admin.register(Workflow) class WorkflowAdmin(admin.ModelAdmin): list_display = ('name', 'playbook', 'order', 'updated_at') list_filter = ('playbook',) search_fields = ('name', 'description') ``` ## Common Pitfalls ### ❌ Don't: Use DRF test clients for template views ```python # Wrong - DRF APIClient for template views from rest_framework.test import APIClient client = APIClient() response = client.get('/playbooks/') ``` ### ✅ Do: Use Django test client ```python # Correct - Django Client for template views from django.test import Client client = Client() response = client.get('/playbooks/') ``` ### ❌ Don't: Put business logic in views ```python # Wrong - business logic in view def create_playbook(request): if Playbook.objects.filter(name=request.POST['name']).exists(): # validation logic in view messages.error(request, 'Duplicate name') return render(request, 'form.html') playbook = Playbook.objects.create(...) # direct ORM in view ``` ### ✅ Do: Use service layer ```python # Correct - delegate to service def create_playbook(request): service = PlaybookService() try: playbook = service.create_playbook(...) # service handles logic messages.success(request, 'Created') return redirect('detail', playbook.id) except ValidationError as e: messages.error(request, str(e)) return render(request, 'form.html') ``` ### ❌ Don't: Mix sync and async incorrectly ```python # Wrong - async view with sync ORM async def playbook_list(request): playbooks = Playbook.objects.all() # SynchronousOnlyOperation error ``` ### ✅ Do: Keep views sync or use sync_to_async ```python # Correct - sync view with sync ORM def playbook_list(request): playbooks = Playbook.objects.all() # Works fine # Or use sync_to_async wrapper from asgiref.sync import sync_to_async async def playbook_list(request): playbooks = await sync_to_async(list)(Playbook.objects.all()) ``` ## Quality Gates Before declaring backend implementation complete: - [ ] All views properly registered in `urls.py` with descriptive names - [ ] Services layer properly structured (business logic separate from views) - [ ] Repository pattern used for data access (or direct ORM with clear separation) - [ ] All models registered with Django admin - [ ] Views return HTML templates (not JSON) unless building API - [ ] Template context always validated and documented - [ ] Unit tests written with pytest for services - [ ] Integration tests written with Django TestCase for views - [ ] All tests use real database (no mocking in integration tests) - [ ] 100% test pass rate - [ ] URL patterns follow RESTful conventions - [ ] Business logic reusable between MCP and Web UI ## Testing Strategy ### Unit Tests (pytest) - Test services in isolation - Test model methods - Test utility functions - Fast (<1s per test) ### Integration Tests (Django TestCase) - Test views with Django test client - Test complete workflows - Test database state changes - Use real database, no mocking - Fast (<5s per test class) ### Test Organization ``` tests/ ├── unit/ │ ├── test_playbook_service.py │ ├── test_workflow_service.py │ └── test_activity_service.py ├── integration/ │ ├── test_playbook_views.py │ ├── test_workflow_views.py │ └── test_activity_views.py └── conftest.py ```
Django + HTMX Frontend Implementation Patterns	FRONTEND_FRAMEWORK	Django+HTMX+Graphviz	Junior Edda	Read the 'Django + HTMX Frontend Implementation Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: FRONTEND_FRAMEWORK Technology stack: Django+HTMX+Graphviz # Skill: Django + HTMX Frontend Implementation Patterns Capability Domain: FRONTEND_FRAMEWORK Technology Stack: Django+HTMX+Graphviz ## Overview Patterns for implementing server-rendered frontends using Django templates with HTMX for dynamic interactions, minimal JavaScript, and Graphviz for visualizations. Emphasizes testability with Django test client (no browser automation needed). ## Reference Implementation ### Pattern 1: Page Templates (Full HTML Pages) Full pages inherit from base template: ```django {# templates/playbooks/list.html #} {% extends "base.html" %} {% block title %}My Playbooks{% endblock %} {% block content %} <div class="container" data-testid="playbooks-page"> <div class="d-flex justify-content-between align-items-center mb-4"> <h1>My Playbooks</h1> <a href="{% url 'playbook_create' %}" class="btn btn-primary" data-testid="create-playbook-button" data-bs-toggle="tooltip" title="Create a new playbook"> <i class="fa-solid fa-plus"></i> New Playbook </a> </div> <div id="playbook-list" data-testid="playbook-list"> {% include "playbooks/partials/_playbook_table.html" %} </div> </div> {% endblock %} ``` ### Pattern 2: Template Partials (HTML Fragments for HTMX) Partials are reusable HTML fragments in `templates//partials/`: ```django {# templates/playbooks/partials/_playbook_table.html #} <table class="table" data-testid="playbooks-table"> <thead> <tr> <th>Name</th> <th>Version</th> <th>Status</th> <th>Updated</th> <th>Actions</th> </tr> </thead> <tbody> {% for playbook in playbooks %} <tr data-testid="playbook-row" data-playbook-id="{{ playbook.id }}"> <td> <a href="{% url 'playbook_detail' playbook.id %}" hx-get="{% url 'playbook_detail' playbook.id %}" hx-target="#main-content" hx-push-url="true" data-testid="playbook-name-link"> {{ playbook.name }} </a> </td> <td>{{ playbook.version }}</td> <td> <span class="badge bg-{{ playbook.status_color }}"> {{ playbook.get_status_display }} </span> </td> <td>{{ playbook.updated_at\|date:"Y-m-d H:i" }}</td> <td> <button class="btn btn-sm btn-outline-primary" hx-get="{% url 'playbook_edit' playbook.id %}" hx-target="#modal-content" data-testid="edit-playbook-button" data-bs-toggle="tooltip" title="Edit this playbook"> <i class="fa-solid fa-edit"></i> </button> </td> </tr> {% empty %} <tr> <td colspan="5" class="text-center text-muted"> No playbooks yet. Create your first one! </td> </tr> {% endfor %} </tbody> </table> ``` ### Pattern 3: HTMX Interaction Patterns #### Navigation (hx-get with target swap) ```django {# Click link, swap content, update URL #} <a href="{% url 'workflow_detail' workflow.id %}" hx-get="{% url 'workflow_detail' workflow.id %}" hx-target="#main-content" hx-push-url="true" data-testid="workflow-link"> {{ workflow.name }} </a> ``` #### Forms (hx-post returning updated content) ```django {# Form submission with HTMX #} <form hx-post="{% url 'playbook_create' %}" hx-target="#playbook-list" hx-swap="innerHTML" data-testid="playbook-form"> {% csrf_token %} <div class="mb-3"> <label for="name" class="form-label">Name </label> <input type="text" class="form-control" id="name" name="name" data-testid="playbook-name-input" required> </div> <div class="mb-3"> <label for="description" class="form-label">Description</label> <textarea class="form-control" id="description" name="description" data-testid="playbook-description-input" rows="3"></textarea> </div> <button type="submit" class="btn btn-primary" data-testid="save-playbook-button" data-bs-toggle="tooltip" title="Save the new playbook"> <i class="fa-solid fa-save"></i> Save </button> </form> ``` #### Dynamic Lists (hx-get to refresh partials) ```django {# Refresh list after action #} <button hx-get="{% url 'playbook_list_partial' %}" hx-target="#playbook-list" hx-swap="innerHTML" data-testid="refresh-list-button"> <i class="fa-solid fa-refresh"></i> Refresh </button> ``` #### Modals/Dialogs (HTML dialog with HTMX content loading) ```django {# Base template with modal container #} <dialog id="modal-dialog" data-testid="modal-dialog"> <div id="modal-content"></div> </dialog> {# Button that loads content into modal #} <button hx-get="{% url 'playbook_edit' playbook.id %}" hx-target="#modal-content" onclick="document.getElementById('modal-dialog').showModal()" data-testid="edit-button"> Edit </button> {# Modal content (partial) #} {# templates/playbooks/partials/_edit_modal.html #} <div class="modal-header"> <h5>Edit Playbook</h5> <button onclick="document.getElementById('modal-dialog').close()" data-testid="close-modal-button"> <i class="fa-solid fa-times"></i> </button> </div> <div class="modal-body"> <form hx-post="{% url 'playbook_update' playbook.id %}" hx-target="#playbook-list" hx-swap="innerHTML"> {# form fields #} </form> </div> ``` ### Pattern 4: Graphviz SVG Visualization Server-generated graphs embedded in templates: ```python # views.py import graphviz from django.shortcuts import render def workflow_diagram(request, workflow_id): """Render workflow as Graphviz diagram.""" workflow = get_object_or_404(Workflow, id=workflow_id) # Create graph dot = graphviz.Digraph(comment=workflow.name) dot.attr(rankdir='TB', bgcolor='transparent') # Add nodes for activity in workflow.activities.all(): dot.node( str(activity.id), activity.name, shape='box', style='filled', fillcolor='lightblue' ) # Add edges (dependencies) for activity in workflow.activities.all(): if activity.predecessor: dot.edge(str(activity.predecessor.id), str(activity.id)) # Render to SVG svg_content = dot.pipe(format='svg').decode('utf-8') return render(request, 'workflows/diagram.html', { 'workflow': workflow, 'svg_content': svg_content }) ``` ```django {# templates/workflows/diagram.html #} <div class="workflow-diagram" data-testid="workflow-diagram"> {{ svg_content\|safe }} </div> <script> // Make SVG links work with HTMX document.querySelectorAll('.workflow-diagram svg a').forEach(link => { link.addEventListener('click', function(e) { e.preventDefault(); const url = this.getAttribute('href'); htmx.ajax('GET', url, {target: '#main-content', swap: 'innerHTML'}); }); }); </script> ``` ### Pattern 5: Minimal JavaScript (Only When Needed) Use JavaScript sparingly for: - SVG link handling - Client-side validation enhancement - Tooltips/hover effects ```javascript // static/js/app.js // Initialize Bootstrap tooltips document.addEventListener('DOMContentLoaded', function() { var tooltipTriggerList = [].slice.call( document.querySelectorAll('[data-bs-toggle="tooltip"]') ); tooltipTriggerList.map(function(tooltipTriggerEl) { return new bootstrap.Tooltip(tooltipTriggerEl); }); }); // Make Graphviz SVG links work with HTMX document.addEventListener('htmx:afterSwap', function(event) { if (event.detail.target.querySelector('svg')) { document.querySelectorAll('svg a').forEach(link => { link.addEventListener('click', function(e) { e.preventDefault(); const url = this.getAttribute('href'); htmx.ajax('GET', url, { target: '#main-content', swap: 'innerHTML', pushUrl: true }); }); }); } }); ``` ### Pattern 6: Testing Django Templates (No Browser Needed) Test server-side rendering with Django test client: ```python # tests/integration/test_playbook_templates.py from django.test import TestCase, Client from django.contrib.auth.models import User from methodology.models import Playbook class PlaybookTemplateTest(TestCase): """Test playbook templates without browser.""" def setUp(self): self.client = Client() self.user = User.objects.create_user(username='test', password='test') self.client.login(username='test', password='test') self.playbook = Playbook.objects.create( name='Test Playbook', description='Test', category='test', author=self.user ) def test_playbook_list_contains_playbook_name(self): """Test list page contains playbook name.""" response = self.client.get('/playbooks/') self.assertEqual(response.status_code, 200) self.assertContains(response, 'Test Playbook') self.assertContains(response, 'data-testid="playbook-row"') def test_playbook_detail_returns_correct_template(self): """Test detail page uses correct template.""" response = self.client.get(f'/playbooks/{self.playbook.id}/') self.assertTemplateUsed(response, 'playbooks/detail.html') self.assertEqual(response.context['playbook'], self.playbook) def test_htmx_request_returns_partial(self): """Test HTMX request returns partial template.""" response = self.client.get( f'/playbooks/{self.playbook.id}/', HTTP_HX_REQUEST='true' # Simulate HTMX request ) self.assertTemplateUsed(response, 'playbooks/partials/_detail.html') self.assertNotContains(response, '<html>') # No full page def test_graph_contains_all_activities(self): """Test Graphviz graph includes all activities.""" workflow = Workflow.objects.create( name='Test Workflow', playbook=self.playbook ) activity1 = Activity.objects.create(name='A1', workflow=workflow) activity2 = Activity.objects.create(name='A2', workflow=workflow) response = self.client.get(f'/workflows/{workflow.id}/diagram/') svg_content = response.content.decode('utf-8') self.assertIn('A1', svg_content) self.assertIn('A2', svg_content) self.assertIn('<svg', svg_content) ``` ## Common Pitfalls ### ❌ Don't: Use full page reload for everything ```django {# Wrong - full page reload #} <a href="{% url 'playbook_detail' playbook.id %}"> {{ playbook.name }} </a> ``` ### ✅ Do: Use HTMX for dynamic updates ```django {# Correct - HTMX partial update #} <a href="{% url 'playbook_detail' playbook.id %}" hx-get="{% url 'playbook_detail' playbook.id %}" hx-target="#main-content" hx-push-url="true"> {{ playbook.name }} </a> ``` ### ❌ Don't: Return JSON from Django views for HTMX ```python # Wrong - returning JSON def playbook_list(request): playbooks = Playbook.objects.all() return JsonResponse({'playbooks': list(playbooks.values())}) ``` ### ✅ Do: Return HTML fragments ```python # Correct - returning HTML def playbook_list(request): playbooks = Playbook.objects.all() if request.headers.get('HX-Request'): # HTMX request - return partial return render(request, 'playbooks/partials/_list.html', { 'playbooks': playbooks }) else: # Regular request - return full page return render(request, 'playbooks/list.html', { 'playbooks': playbooks }) ``` ### ❌ Don't: Write complex JavaScript for interactions ```javascript // Wrong - complex JS state management let playbooks = []; fetch('/api/playbooks/') .then(r => r.json()) .then(data => { playbooks = data; renderPlaybooks(playbooks); }); ``` ### ✅ Do: Let server handle state, use HTMX ```django {# Correct - server-side state, HTMX updates #} <button hx-get="{% url 'playbook_list_partial' %}" hx-target="#playbook-list"> Refresh </button> ``` ### ❌ Don't: Forget data-testid attributes ```django {# Wrong - no test IDs #} <button class="btn btn-primary">Save</button> <div class="playbook-list">...</div> ``` ### ✅ Do: Add semantic test IDs ```django {# Correct - semantic test IDs #} <button class="btn btn-primary" data-testid="save-playbook-button"> Save </button> <div class="playbook-list" data-testid="playbook-list">...</div> ``` ## Quality Gates Before declaring frontend implementation complete: - [ ] All templates use semantic HTML elements - [ ] HTMX interactions work without full page reloads - [ ] All interactive elements have `data-testid` attributes - [ ] Forms handle validation errors properly (server-side) - [ ] Responsive design verified (mobile, tablet, desktop) - [ ] All buttons have Font Awesome icons - [ ] All buttons have Bootstrap tooltips - [ ] Tooltips explain what will happen (active) or why disabled - [ ] Template partials properly organized in `partials/` subdirectories - [ ] HTMX requests detected and return partials (not full pages) - [ ] Graphviz SVG graphs render correctly - [ ] SVG links work with HTMX navigation - [ ] Minimal JavaScript (only for enhancements) - [ ] All templates tested with Django test client (no browser) - [ ] Template context validated and documented ## Template Organization ``` templates/ ├── base.html # Base template ├── playbooks/ │ ├── list.html # Full page │ ├── detail.html # Full page │ ├── create.html # Full page │ └── partials/ │ ├── _list.html # List partial for HTMX │ ├── _detail.html # Detail partial for HTMX │ ├── _form.html # Form partial │ └── _card.html # Card component ├── workflows/ │ ├── detail.html │ ├── diagram.html │ └── partials/ │ └── _activity_list.html └── components/ ├── _navbar.html ├── _sidebar.html └── _modal.html ``` ## HTMX Attributes Reference - `hx-get` - Issue GET request - `hx-post` - Issue POST request - `hx-target` - Element to swap content into - `hx-swap` - How to swap (innerHTML, outerHTML, beforeend, etc.) - `hx-push-url` - Update browser URL - `hx-trigger` - What triggers the request (click, change, etc.) - `hx-indicator` - Loading indicator element - `hx-confirm` - Confirmation dialog before request ## Testing Strategy ### Server-Side Template Tests (Django TestCase) - Test template rendering - Test context data - Test HTMX partial responses - Test form validation errors - Validate SVG graph content - No browser automation needed - Fast (<5s per test class)
Django Logging Setup	BACKEND_LOGGING	Django+Python	Junior Edda	Read the 'Django Logging Setup' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: BACKEND_LOGGING Technology stack: Django+Python # Skill: Django Logging Setup Capability Domain: BACKEND_LOGGING Technology Stack: Django+Python ## Overview Configure Django's LOGGING settings to implement informative, structured logging with file rotation. Enables effective troubleshooting by logging who, what, why, where, and when for every significant operation. Supports three log files: `app.log` (backend operations), `gui.log` (frontend events), and `consumption.log` (token tracking). ## Reference Implementation ### Pattern 1: Django LOGGING Configuration Add to `{project_name}/settings.py`: ```python import os from pathlib import Path # Build paths inside the project BASE_DIR = Path(__file__).resolve().parent.parent # Logging Configuration LOGGING = { 'version': 1, 'disable_existing_loggers': False, 'formatters': { 'verbose': { 'format': '{levelname} {asctime} [{name}:{funcName}:{lineno}] {message}', 'style': '{', 'datefmt': '%Y-%m-%d %H:%M:%S', }, 'simple': { 'format': '{levelname} {asctime} {message}', 'style': '{', 'datefmt': '%Y-%m-%d %H:%M:%S', }, 'json': { 'format': '{message}', 'style': '{', }, }, 'handlers': { 'app_file': { 'level': 'INFO', 'class': 'logging.handlers.RotatingFileHandler', 'filename': BASE_DIR / 'logs' / 'app.log', 'maxBytes': 10 * 1024 * 1024, # 10 MB 'backupCount': 5, 'formatter': 'verbose', }, 'gui_file': { 'level': 'INFO', 'class': 'logging.handlers.RotatingFileHandler', 'filename': BASE_DIR / 'logs' / 'gui.log', 'maxBytes': 10 * 1024 * 1024, # 10 MB 'backupCount': 5, 'formatter': 'verbose', }, 'consumption_file': { 'level': 'INFO', 'class': 'logging.handlers.RotatingFileHandler', 'filename': BASE_DIR / 'logs' / 'consumption.log', 'maxBytes': 10 * 1024 * 1024, # 10 MB 'backupCount': 5, 'formatter': 'json', # JSON format for EST workflow parsing }, 'console': { 'level': 'DEBUG' if DEBUG else 'INFO', 'class': 'logging.StreamHandler', 'formatter': 'verbose', }, }, 'loggers': { 'django': { 'handlers': ['app_file', 'console'], 'level': 'INFO', 'propagate': False, }, '{project_name}': { 'handlers': ['app_file', 'console'], 'level': 'DEBUG' if DEBUG else 'INFO', 'propagate': False, }, 'gui': { 'handlers': ['gui_file', 'console'], 'level': 'INFO', 'propagate': False, }, 'consumption': { 'handlers': ['consumption_file'], 'level': 'INFO', 'propagate': False, }, }, 'root': { 'handlers': ['app_file', 'console'], 'level': 'INFO', }, } ``` ### Pattern 2: Create Logs Directory Add to project initialization (e.g., `manage.py` or `wsgi.py`): ```python import os from pathlib import Path # Ensure logs directory exists BASE_DIR = Path(__file__).resolve().parent LOGS_DIR = BASE_DIR / 'logs' LOGS_DIR.mkdir(exist_ok=True) ``` Or create via shell script in BSP workflow: ```bash mkdir -p logs touch logs/.gitkeep # Add to .gitignore cat >> .gitignore << 'EOF' # Logs logs/.log !logs/.gitkeep EOF ``` ### Pattern 3: Informative Logging in Services Follow informative logging pattern - include context for troubleshooting: ```python import logging logger = logging.getLogger(__name__) class PlaybookService: """Service layer for playbook operations.""" def create_playbook(self, name, description, category, author): """ Create a new playbook. :param name: Playbook name :param description: Playbook description :param category: Category (e.g., 'development', 'testing') :param author: User instance :return: Created Playbook instance :raises ValidationError: If validation fails """ logger.info( f"[{__name__}.create_playbook] Starting playbook creation \| " f"user_id={author.id} \| name={name} \| category={category}" ) try: # Validation if not name or len(name) < 3: raise ValidationError("Playbook name must be at least 3 characters") # Create playbook playbook = Playbook.objects.create( name=name, description=description, category=category, author=author, status='draft', version='0.1' ) logger.info( f"[{__name__}.create_playbook] Playbook created successfully \| " f"user_id={author.id} \| playbook_id={playbook.id} \| " f"name={playbook.name} \| version={playbook.version}" ) return playbook except ValidationError as e: logger.warning( f"[{__name__}.create_playbook] Validation failed \| " f"user_id={author.id} \| name={name} \| error={str(e)}" ) raise except Exception as e: logger.error( f"[{__name__}.create_playbook] Unexpected error \| " f"user_id={author.id} \| name={name} \| " f"error_type={type(e).__name__} \| error={str(e)}", exc_info=True ) raise ``` ### Pattern 4: Logging in Views ```python import logging from django.shortcuts import render, redirect from django.contrib.auth.decorators import login_required from django.contrib import messages logger = logging.getLogger(__name__) @login_required def playbook_create(request): """Create new playbook.""" logger.info( f"[{__name__}.playbook_create] View accessed \| " f"user_id={request.user.id} \| method={request.method}" ) if request.method == 'POST': try: service = PlaybookService() playbook = service.create_playbook( name=request.POST.get('name'), description=request.POST.get('description'), category=request.POST.get('category'), author=request.user ) logger.info( f"[{__name__}.playbook_create] Playbook created via view \| " f"user_id={request.user.id} \| playbook_id={playbook.id}" ) messages.success(request, f'Playbook "{playbook.name}" created successfully') return redirect('playbook_detail', playbook_id=playbook.id) except ValidationError as e: logger.warning( f"[{__name__}.playbook_create] Form validation failed \| " f"user_id={request.user.id} \| error={str(e)}" ) messages.error(request, str(e)) return render(request, 'playbooks/create.html', { 'page_title': 'Create Playbook' }) ``` ### Pattern 5: Logging in Models (Signals) ```python import logging from django.db.models.signals import post_save, pre_delete from django.dispatch import receiver logger = logging.getLogger(__name__) @receiver(post_save, sender=Playbook) def log_playbook_save(sender, instance, created, kwargs): """Log playbook creation/update.""" action = 'created' if created else 'updated' logger.info( f"[signals.log_playbook_save] Playbook {action} \| " f"playbook_id={instance.id} \| name={instance.name} \| " f"author_id={instance.author.id} \| version={instance.version} \| " f"status={instance.status}" ) @receiver(pre_delete, sender=Playbook) def log_playbook_delete(sender, instance, kwargs): """Log playbook deletion.""" logger.warning( f"[signals.log_playbook_delete] Playbook being deleted \| " f"playbook_id={instance.id} \| name={instance.name} \| " f"author_id={instance.author.id}" ) ``` ### Pattern 6: Logging Database Queries (Debug) For development debugging, enable SQL query logging: ```python # In settings.py (DEBUG mode only) if DEBUG: LOGGING['loggers']['django.db.backends'] = { 'handlers': ['console'], 'level': 'DEBUG', 'propagate': False, } ``` ### Pattern 7: Request/Response Middleware Logging Create custom middleware for request/response logging: ```python # {app_name}/middleware/logging_middleware.py import logging import time logger = logging.getLogger(__name__) class RequestLoggingMiddleware: """Log all HTTP requests and responses.""" def __init__(self, get_response): self.get_response = get_response def __call__(self, request): # Log request start_time = time.time() user_id = request.user.id if request.user.is_authenticated else 'anonymous' logger.info( f"[RequestLoggingMiddleware] Request started \| " f"method={request.method} \| path={request.path} \| " f"user_id={user_id}" ) # Process request response = self.get_response(request) # Log response duration_ms = (time.time() - start_time) 1000 logger.info( f"[RequestLoggingMiddleware] Request completed \| " f"method={request.method} \| path={request.path} \| " f"user_id={user_id} \| status={response.status_code} \| " f"duration_ms={duration_ms:.2f}" ) return response ``` Add to `settings.py`: ```python MIDDLEWARE = [ # ... other middleware ... '{app_name}.middleware.logging_middleware.RequestLoggingMiddleware', ] ``` ## Informative Logging Checklist Every log message should include: - ✅ Location: `[module.function]` prefix - ✅ Action: What operation is being performed - ✅ Context: Key identifiers (user_id, entity_id, etc.) - ✅ Result: Success/failure indication - ✅ Error details: Exception type and message (if applicable) Good Example: ```python logger.info( f"[playbook_service.create_playbook] Playbook created successfully \| " f"user_id={user.id} \| playbook_id={playbook.id} \| name={playbook.name}" ) ``` Bad Example: ```python logger.info("Playbook created") # Missing context, location, identifiers ``` ## Testing Logging Verify logging is working: ```python # tests/test_logging.py import logging from pathlib import Path from django.test import TestCase class LoggingTestCase(TestCase): """Test logging configuration.""" def test_app_log_exists(self): """Verify app.log is created.""" log_file = Path('logs/app.log') # Trigger a log entry logger = logging.getLogger('test') logger.info("Test log entry") # Verify file exists self.assertTrue(log_file.exists()) def test_log_rotation(self): """Verify log rotation is configured.""" logger = logging.getLogger('test') handler = logger.handlers[0] self.assertEqual(handler.maxBytes, 10 * 1024 * 1024) self.assertEqual(handler.backupCount, 5) ``` ## Common Patterns ### Pattern: Logging with Timing ```python import time start_time = time.time() # ... operation ... duration_ms = (time.time() - start_time) * 1000 logger.info( f"[{__name__}.operation] Completed \| " f"duration_ms={duration_ms:.2f}" ) ``` ### Pattern: Logging with Exception Context ```python try: # ... operation ... except SpecificException as e: logger.error( f"[{__name__}.operation] Operation failed \| " f"context_id={id} \| error={str(e)}", exc_info=True # Include full traceback ) raise ``` ### Pattern: Conditional Debug Logging ```python if logger.isEnabledFor(logging.DEBUG): logger.debug( f"[{__name__}.operation] Debug info \| " f"variable_state={expensive_to_compute()}" ) ``` ## Integration with EST Workflow The `consumption.log` uses JSON format for EST-08 parsing: ```python import json import logging consumption_logger = logging.getLogger('consumption') def log_token_consumption(scenario_id, user_id, tokens_used, model, sprint=1): """Log token consumption for EST workflow.""" entry = { 'timestamp': datetime.utcnow().isoformat() + 'Z', 'scenario_id': scenario_id, 'user_id': user_id, 'sprint': sprint, 'tokens_used': tokens_used, 'model': model, 'operation': 'implement', 'status': 'completed' } consumption_logger.info(json.dumps(entry)) ``` ## References - informative logging pattern - Informative logging requirements - Activity EST-08 (Sprint Close and Rebaseline) - consumption.log format - Django Logging Documentation: https://docs.djangoproject.com/en/stable/topics/logging/
Drift Detection and Classification	DRIFT_DETECTION	GitHub CLI + YAML	Junior Edda	Read the 'Drift Detection and Classification' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: DRIFT_DETECTION Technology stack: GitHub CLI + YAML # Skill: Drift Detection and Classification Capability Domain: DRIFT_DETECTION Technology Stack: GitHub CLI + YAML ## Overview Patterns for detecting, classifying, and responding to execution deviations during MIT. Covers signal type definitions, severity thresholds, detection commands, and the absorbed/escalated response protocol. Time-based signals are not used — Claude Code cannot reliably measure wall-clock time in autonomous mode. All drift detection is based on observable artifacts: git diffs, method signatures, and explicit SAO.md compliance review. ## Signal Type Reference \| Signal Type \| Trigger Condition \| Severity \| \|---\|---\|---\| \| `footprint_violation` \| any file in `git diff {skeleton_commit} --name-only` is NOT in `codebase_footprint[]` \| escalated \| \| `method_explosion` \| unplanned public method added since skeleton commit (not prefixed with `_`) \| escalated \| \| `sao_violation` \| SAO compliance check finds implementation breaches an architectural constraint \| escalated \| \| `checkpoint_fail` \| checkpoint command exits non-zero (first occurrence) \| absorbed (retry once) \| \| `checkpoint_fail_retry` \| checkpoint fails after one retry \| escalated \| ## Reference Implementation ### Pattern 1: Detect Footprint Violation ```bash # Get files changed since skeleton commit git diff {skeleton_commit} --name-only > /tmp/actual_files.txt # Compare against declared footprint python3 - <<EOF footprint = {codebase_footprint_list} # from issue <!-- SCENARIO --> YAML with open('/tmp/actual_files.txt') as f: actual = set(f.read().splitlines()) violations = actual - set(footprint) if violations: for f in sorted(violations): print(f"SIGNAL: footprint_violation \| severity: escalated \| file: {f}") else: print("footprint check: PASS — no unexpected files") EOF ``` All footprint violations escalate. There is no absorbed path for this signal. ### Pattern 2: Detect Method Explosion ```bash # Find new public methods added since skeleton commit (non-underscore def at class indent level) NEW_PUBLIC=$(git diff {skeleton_commit} -- {file} \ \| grep "^+ def " \ \| grep -v "^+ def _") if [ -n "$NEW_PUBLIC" ]; then echo "SIGNAL: method_explosion \| severity: escalated" echo "Evidence: unplanned public methods:" echo "$NEW_PUBLIC" else echo "method explosion check: PASS — no unplanned public methods" fi ``` Run this check for each file in `codebase_footprint[]` separately so evidence is file-specific. ### Pattern 3: SAO Compliance Check This is a reasoning step, not a script. For each section listed in `sao_sections[]` from the issue body: 1. Read that section of `docs/architecture/SAO.md` 2. For each constraint in the section, state explicitly: - `complies: {constraint summary}` — implementation respects it - `violation: {constraint summary} — {what was built that breaches it}` ``` Reviewing §Services Layer: - "Services are shared by MCP and Web UI, no MCP-specific logic" → complies - "Services call ORM directly, no intermediate layer" → violation: added WorkflowRepository between service and ORM SIGNAL: sao_violation \| severity: escalated Evidence: WorkflowRepository class violates §Services Layer — services must call ORM directly ``` If all constraints pass: "SAO compliance check: PASS — no violations." ### Pattern 4: Classify Checkpoint Failure ```bash # Run checkpoint and capture exit code {checkpoint.command} > /tmp/checkpoint_out.txt 2>&1 CHECKPOINT_EXIT=$? if [ $CHECKPOINT_EXIT -ne 0 ]; then # Check if a retry has already been attempted on this issue RETRY_COUNT=$(gh issue view {issue_number} --json comments \ --jq '[.comments[].body \| select(contains("DRIFT absorbed") and contains("checkpoint_fail"))] \| length') if [ "$RETRY_COUNT" -eq 0 ]; then echo "SIGNAL: checkpoint_fail \| severity: absorbed \| action: retry once" # Apply targeted fix, then re-run checkpoint else echo "SIGNAL: checkpoint_fail_retry \| severity: escalated" cat /tmp/checkpoint_out.txt \| tail -20 fi fi ``` ## Severity Decision Tree ``` Drift detected? ├─ footprint_violation: │ any file outside codebase_footprint[] → escalated (no absorbed path) │ ├─ method_explosion: │ any unplanned public method → escalated (no absorbed path) │ ├─ sao_violation: │ any architectural constraint breached → escalated (no absorbed path) │ └─ checkpoint_fail: first occurrence → absorbed (retry once) retry fails → checkpoint_fail_retry → escalated ``` ## Post-Detection Actions ### Absorbed (checkpoint_fail first occurrence): ```bash gh issue comment {issue_number} --body "<!-- DRIFT absorbed --> type: checkpoint_fail action: {targeted fix applied} retry: PASS <!-- /DRIFT -->" gh issue edit {issue_number} --add-label "drift-absorbed" ``` ### Escalated (any signal): ```bash gh issue comment {issue_number} --body "<!-- ESCALATE --> type: {footprint_violation\|method_explosion\|sao_violation\|checkpoint_fail_retry} evidence: {specific: file name / method name / SAO constraint / test output} jedao_recommendation: {A: fix and retry \| B: resequence \| C: scope reduce} await_human_decision: true <!-- /ESCALATE -->" gh issue edit {issue_number} --add-label "drift-escalated" --remove-label "status-in-progress" ``` ## Quality Gates - [ ] Every drift event has a signal type from the defined enum (footprint_violation, method_explosion, sao_violation, checkpoint_fail, checkpoint_fail_retry) - [ ] Footprint check run against `skeleton_commit` hash (not HEAD~1) - [ ] Method explosion check run per file, not across entire diff - [ ] SAO compliance check explicitly states "complies" or "violation" per constraint — not a blanket statement - [ ] Absorbed signals: action taken described in comment - [ ] Escalated signals: `jedao_recommendation` and specific `evidence` present in comment
Generate Estimation XLS	ESTIMATION	Python+openpyxl	Junior Edda	Read the 'Generate Estimation XLS' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: ESTIMATION Technology stack: Python+openpyxl # Generate Estimation XLS Python script for generating estimation spreadsheets. ```python #!/usr/bin/env python3 """ generate_estimation_xls.py — FeatureFactory EST Skill ======================================================== Produces docs/plans/ESTIMATION_TEMPLATE.xlsx (9 tabs, Monte Carlo, EBS charts) from a project data dictionary. Usage ----- 1. Fill in PROJECT_DATA below (Windsurf: run BPE-01 in estimation mode per scenario to get the wbs dict; use EST-03 sizing table for sizes). 2. Install dependency (once): pip install xlsxwriter 3. Run: python generate_estimation_xls.py Called by Windsurf as part of the EST workflow. Can also be run standalone. Tabs produced ------------- 0-Client Quote AFP pricing, delivery commitment bands 1-Setup Project params, reference story baselines 2-Scenario List All BDD scenarios with L1 sizing + adjusted K ranges 3-ECF Environmental Complexity Factors (internal) 4-TCF Technical Complexity Factors (internal) 5-Rough Estimates Sprint-level PERT totals (L1) 6-Monte Carlo 10K-iteration simulation + EBS S-curve charts 7-WBS Features Per-artifact BPE-01 breakdown (L2, if wbs filled) 8-Detailed Estimates L1/L2 cross-check per scenario """ import math import random import os import xlsxwriter # pip install xlsxwriter # ══════════════════════════════════════════════════════════════════════════════ # PROJECT_DATA ← WINDSURF FILLS THIS IN # ══════════════════════════════════════════════════════════════════════════════ PROJECT_DATA = { # ── Identity ────────────────────────────────────────────────────────────── "project_name": "My Project — MVP v1", "output_path": "docs/plans/ESTIMATION_TEMPLATE.xlsx", # relative to repo root # ── Pricing parameters ──────────────────────────────────────────────────── # stack_factor: 1.0 = standard single stack (Django+HTMX+SQLite) # add +0.2 per extra stack tier (e.g. React FE, external API) "stack_factor": 1.0, "org_factor": 0.8, # 0.8 solo dev \| 1.0 small team \| 1.2 large team "rate_per_fp": 250, # $/FP — SEED until calibrated after 3 sprints (EST-08) # ── Simulation parameters ───────────────────────────────────────────────── "sprint_days": 1, # calendar days per sprint "throughput_k_day": 1500, # K tokens per working day (from Setup tab calibration) "iterations": 10_000, "multiplier": 0.87, # ECF×TCF combined — auto-computed from tabs 3/4 if left as None # set a float here to override (e.g. 0.87 for architecture-complete) # ── Scenarios ───────────────────────────────────────────────────────────── # EST-03 sizing: XS=0.5SP S=1SP M=2SP L=5SP XL=8SP # Columns: (scenario_id, feature_file, act/group, description, size, sprint, notes) # # Anti-patterns to avoid: # ✗ Size 2nd/3rd CRUD entity same as 1st — downgrade with reuse (XS→S, S→M) # ✗ Size by scenario count — size by CODE complexity, not test count # ✗ Size all config/nav as S — config-heavy work is XS "scenarios": [ # ── EXAMPLE — replace with your project's scenarios ─────────────────── # (sid, feature_file, group, description, size, sprint, notes) ("PROJ-AUTH-01", "auth.feature", "Sprint 1", "Login / logout / session", "S", 1, "First auth entity — novel model+service"), ("PROJ-HOME-01", "home.feature", "Sprint 1", "Home dashboard", "XS", 1, "Read-only, template-heavy"), ("PROJ-ITEM-LIST-01", "items.feature", "Sprint 1", "Item list + search", "M", 1, "First CRUD entity — full BPE cycle"), ("PROJ-ITEM-CREATE-01", "items.feature", "Sprint 2", "Create item", "M", 2, "New model + service"), ("PROJ-ITEM-EDIT-01", "items.feature", "Sprint 2", "Edit item", "S", 2, "Reuses create pattern — EXTEND"), ("PROJ-ITEM-DELETE-01", "items.feature", "Sprint 2", "Delete item modal", "S", 2, "Modal confirm — REUSE pattern"), ], # ── WBS (Level 2 — optional) ────────────────────────────────────────────── # Run BPE-01 in estimation mode (EST-06) for each scenario to get this list. # If a scenario SID is absent from wbs, L1 K-range is used for that scenario. # # Artifact types K ranges (min/exp/max): # Plan 5 / 8 / 15 — BPE-01 implementation plan # Model 8 / 15 / 28 — Django model + admin # Repo 5 / 10 / 20 — Repository methods # Service 8 / 18 / 35 — Service layer business logic # View 6 / 12 / 22 — Django view + URL pattern # Template 8 / 16 / 30 — Django template (full page) # Partial 4 / 8 / 15 — HTMX partial / reusable fragment # Tests 10 / 20 / 40 — Unit + integration tests # FAT 8 / 15 / 28 — Feature acceptance tests # Journey 5 / 10 / 18 — Journey certification tests # DoD 3 / 6 / 12 — DoD checklist (NEVER omit) # E2E 6 / 12 / 22 — E2E Playwright tests + PR # # Reuse flags: # NEW → 1.0× build from scratch # EXTEND → 0.6× existing code needs significant modification # REUSE → 0.3× trivial wiring / config only "wbs": { "PROJ-AUTH-01": [ ("Plan", "BPE-01 implementation plan", "NEW"), ("Model", "User model (Django auth extension)", "NEW"), ("Repo", "UserRepo.authenticate / get_by_id", "NEW"), ("Service", "AuthService.login / logout / session", "NEW"), ("View", "LoginView / LogoutView + URL patterns", "NEW"), ("Template", "login.html / logout confirmation", "NEW"), ("Tests", "Auth unit + integration tests", "NEW"), ("FAT", "Login / logout / session FAT", "NEW"), ("DoD", "DoD checklist", "NEW"), ("E2E", "E2E Playwright: login flow", "NEW"), ], "PROJ-ITEM-LIST-01": [ ("Plan", "BPE-01 implementation plan", "NEW"), ("Model", "Item model + admin", "NEW"), ("Repo", "ItemRepo.list / filter / search", "NEW"), ("Service", "ItemService.get_list", "NEW"), ("View", "ItemListView + URL", "NEW"), ("Template", "items/list.html", "NEW"), ("Tests", "Item list unit + integration tests", "NEW"), ("FAT", "List + search FAT", "NEW"), ("DoD", "DoD checklist", "NEW"), ("E2E", "E2E Playwright: item list", "NEW"), ], "PROJ-ITEM-CREATE-01": [ ("Plan", "BPE-01 implementation plan", "NEW"), ("Model", "Item model (extends List model)", "EXTEND"), ("Repo", "ItemRepo.create", "EXTEND"), ("Service", "ItemService.create", "NEW"), ("View", "ItemCreateView + URL", "NEW"), ("Template", "items/create.html", "NEW"), ("Tests", "Create unit + integration tests", "NEW"), ("FAT", "Create item FAT", "NEW"), ("DoD", "DoD checklist", "REUSE"), ("E2E", "E2E Playwright: create item", "NEW"), ], "PROJ-ITEM-EDIT-01": [ ("Plan", "BPE-01 implementation plan", "REUSE"), ("Model", "Item model (no change)", "REUSE"), ("Repo", "ItemRepo.update", "EXTEND"), ("Service", "ItemService.update", "NEW"), ("View", "ItemEditView + URL", "EXTEND"), ("Template", "items/edit.html (reuses create form)", "EXTEND"), ("Tests", "Edit unit + integration tests", "NEW"), ("FAT", "Edit item FAT", "NEW"), ("DoD", "DoD checklist", "REUSE"), ("E2E", "E2E Playwright: edit item", "NEW"), ], "PROJ-ITEM-DELETE-01": [ ("Plan", "BPE-01 implementation plan", "REUSE"), ("Model", "Item model (no change)", "REUSE"), ("Repo", "ItemRepo.delete", "EXTEND"), ("Service", "ItemService.delete", "NEW"), ("View", "ItemDeleteView + URL", "REUSE"), ("Partial", "delete_confirm_modal.html (REUSE)", "REUSE"), ("Tests", "Delete unit + integration tests", "NEW"), ("FAT", "Delete item FAT", "NEW"), ("DoD", "DoD checklist", "REUSE"), ("E2E", "E2E Playwright: delete item", "NEW"), ], # "PROJ-HOME-01": [], # omit or leave empty → L1 sizing used }, # ── ECF ratings (0–5) ───────────────────────────────────────────────────── # Rate each factor for your team/project. Default 3 = neutral. "ecf_ratings": { "E1": 3, # Familiarity with AI model/tooling (high=good → +weight) "E2": 3, # Part-time / context switching (low=good → -weight) "E3": 3, # Analyst / prompt engineering skill (high=good → +weight) "E4": 3, # Lead dev application experience (high=good → +weight) "E5": 3, # Team motivation (high=good → +weight) "E6": 3, # Requirements stability (high=good → +weight) "E7": 3, # Part-time users / product owners (low=good → -weight) "E8": 3, # Difficulty of stack / language (low=good → -weight) "A1": 3, # AI model tier (Opus=5, Sonnet=3, Haiku=1) "A2": 3, # Prompt maturity (mature BPE=4-5, first project=1-2) "A3": 3, # Hallucination risk (well-known stack=4-5, novel=1-2) "A4": 3, # Context window pressure (small features=4-5, huge=1-2) "A5": 3, # AI code rework rate (41% baseline = 3) }, # ── TCF ratings (0–5) ───────────────────────────────────────────────────── "tcf_ratings": { "T1": 2, # Distributed / microservices (monolith=1, full dist=5) "T2": 2, # Response time / performance SLA "T3": 3, # End-user efficiency / UX optimised "T4": 2, # Complex internal algorithms "T5": 3, # Code reusability requirement "T6": 3, # Easy to install / deploy "T7": 3, # Usability "T8": 2, # Portability across platforms "T9": 4, # Maintainability (methodology evolves) "T10": 1, # Concurrent users / multi-tenant "T11": 2, # Security requirements "T12": 2, # Third-party / external API integration "T13": 2, # Special user training required }, # ── Calibration notes ───────────────────────────────────────────────────── "notes": [ "SEED estimates — calibrate $/FP after Sprint 1 close via EST-08.", "Level 2 (WBS) populated for scenarios in wbs dict; others use L1 K-range.", "Rerun this script after each sprint close to update Monte Carlo.", ], } # ══════════════════════════════════════════════════════════════════════════════ # CONSTANTS (derived — do not edit below unless you know what you're doing) # ══════════════════════════════════════════════════════════════════════════════ # K-token PERT baselines per artifact type (min, exp, max) K_ART = { "Plan": (5, 8, 15), "Model": (8, 15, 28), "Repo": (5, 10, 20), "Service": (8, 18, 35), "View": (6, 12, 22), "Template":(8, 16, 30), "Partial": (4, 8, 15), "Tests": (10, 20, 40), "FAT": (8, 15, 28), "Journey": (5, 10, 18), "DoD": (3, 6, 12), "E2E": (6, 12, 22), } MULT_FLAG = {"NEW": 1.0, "EXTEND": 0.6, "REUSE": 0.3} # L1 size → (sp, fp, kmin, kexp, kmax) SIZE_TABLE = { "XS": (0.5, 0.5, 12, 22, 36), "S": (1.0, 1.0, 25, 45, 72), "M": (2.0, 2.0, 60, 100, 160), "L": (5.0, 3.0, 155, 250, 410), "XL": (8.0, 5.0, 275, 440, 720), } def artifact_pert(atype, flag): """Return (min, exp, max) K-tokens for one artifact after reuse multiplier.""" lo, mi, hi = K_ART[atype] m = MULT_FLAG[flag] return round(lo * m, 1), round(mi * m, 1), round(hi * m, 1) def triangular_sample(lo, mi, hi): """Draw one sample from Triangular(lo, mi, hi).""" return random.triangular(lo, hi, mi) def run_monte_carlo(sc_data, wbs, multiplier, throughput, iterations): """ 10K-iteration Monte Carlo over scenario PERT triplets. Returns list of 100 (probability%, K-tokens, days) sorted by K ascending. """ results_k = [] for _ in range(iterations): total_k = 0.0 for sc in sc_data: sid = sc["sid"] arts = wbs.get(sid) if arts: # L2: sum artifact samples sc_k = sum(triangular_sample(artifact_pert(a, f)) for _, a, f in [(wp,) + (atype, flag) for wp, (atype, _, flag) in enumerate(arts, 1)]) else: # L1: sample from scenario PERT sc_k = triangular_sample(sc["kmin"], sc["kexp"], sc["kmax"]) total_k += sc_k multiplier results_k.append(total_k) results_k.sort() n = len(results_k) percentiles = [] for i in range(1, 101): idx = max(0, min(n - 1, int(i / 100 * n) - 1)) k = results_k[idx] days = k / throughput percentiles.append((i, round(k, 1), round(days, 3))) return percentiles def build_sprint_summary(sc_data, multiplier, throughput): """Aggregate scenario data by sprint for Tab 5.""" sprints = {} for sc in sc_data: sp_num = sc["sprint"] if sp_num not in sprints: sprints[sp_num] = {"scenarios": 0, "sp": 0, "fp": 0, "kmin": 0, "kexp": 0, "kmax": 0} s = sprints[sp_num] s["scenarios"] += 1 s["sp"] += sc["sp"] s["fp"] += sc["fp"] s["kmin"] += sc["kmin"] * multiplier s["kexp"] += sc["kexp"] * multiplier s["kmax"] += sc["kmax"] * multiplier rows = [] for sp_num in sorted(sprints): s = sprints[sp_num] rows.append(( sp_num, s["scenarios"], round(s["sp"], 1), round(s["fp"], 1), round(s["kmin"], 0), round(s["kexp"], 0), round(s["kmax"], 0), round(s["kmin"] / throughput, 2), round(s["kexp"] / throughput, 2), round(s["kmax"] / throughput, 2), round(s["fp"], 1), round(s["fp"] * 250, 0), "Architecture Complete", "SEED", "", )) return rows # ══════════════════════════════════════════════════════════════════════════════ # MAIN — build workbook # ══════════════════════════════════════════════════════════════════════════════ def main(): pd = PROJECT_DATA name = pd["project_name"] out = pd["output_path"] os.makedirs(os.path.dirname(out) if os.path.dirname(out) else ".", exist_ok=True) stack = pd["stack_factor"] org = pd["org_factor"] rate = pd["rate_per_fp"] mult = pd["multiplier"] if pd["multiplier"] else 0.87 thru = pd["throughput_k_day"] iters = pd["iterations"] ecf_r = pd["ecf_ratings"] tcf_r = pd["tcf_ratings"] # ── Enrich scenario list ─────────────────────────────────────────────────── sc_data = [] for sid, feat, grp, desc, size, sprint, notes in pd["scenarios"]: sp, fp, kmin, kexp, kmax = SIZE_TABLE[size] afp = round(fp * stack * org * rate, 0) # Apply multiplier to L1 K ranges sc_data.append({ "sid": sid, "feat": feat, "grp": grp, "desc": desc, "size": size, "sprint": sprint, "notes": notes, "sp": sp, "fp": fp, "kmin": round(kmin * mult, 1), "kexp": round(kexp * mult, 1), "kmax": round(kmax * mult, 1), "afp": afp, }) # Normalise wbs: each entry is (atype, desc, flag) tuple wbs = {} for sid, arts in pd["wbs"].items(): wbs[sid] = [(atype, desc, flag) for atype, desc, flag in arts] # ── Run Monte Carlo ──────────────────────────────────────────────────────── # For Monte Carlo L2 we need (atype, flag) only — strip desc wbs_mc = {sid: [(a, f) for a, _, f in arts] for sid, arts in wbs.items()} # Patch run_monte_carlo for wbs_mc format results_k = [] random.seed(42) for _ in range(iters): total_k = 0.0 for sc in sc_data: sid = sc["sid"] arts = wbs_mc.get(sid) if arts: sc_k = sum(triangular_sample(artifact_pert(atype, flag)) for atype, flag in arts) else: sc_k = triangular_sample(sc["kmin"] / mult, sc["kexp"] / mult, sc["kmax"] / mult) mult total_k += sc_k results_k.append(total_k) results_k.sort() n = len(results_k) pct = [] for i in range(1, 101): idx = max(0, min(n - 1, int(i / 100 * n) - 1)) k = results_k[idx] pct.append((i, round(k, 1), round(k / thru, 3))) sprint_rows = build_sprint_summary(sc_data, mult, thru) total_fp = sum(sc["fp"] for sc in sc_data) total_sp = sum(sc["sp"] for sc in sc_data) total_afp = round(total_fp * stack * org * rate, 0) # ── Workbook ─────────────────────────────────────────────────────────────── wb = xlsxwriter.Workbook(out) def F(*kw): base = {"font_name": "Calibri", "font_size": 10} base.update(kw) return wb.add_format(base) # Formats fHdr = F(bold=True, font_size=12, font_color="white", bg_color="#1B4332", align="center", border=1) fSub = F(bold=True, font_color="white", bg_color="#2D6A4F", align="center", border=1) fBold = F(bold=True, border=1) fData = F(border=1) fDataR= F(border=1, align="right") fNum = F(border=1, align="right", num_format="#,##0.0") fDol = F(border=1, align="right", num_format="$#,##0") fTot = F(bold=True, font_color="white", bg_color="#1B4332", border=1, align="right", num_format="#,##0.0") fTotL = F(bold=True, font_color="white", bg_color="#1B4332", border=1) fTotD = F(bold=True, font_color="white", bg_color="#1B4332", border=1, align="right", num_format="$#,##0") fWrap = F(border=1, text_wrap=True) fXS = F(border=1, bg_color="#F0FFF4") fS = F(border=1, bg_color="#D1FAE5") fM = F(border=1, bg_color="#A7F3D0") fL = F(border=1, bg_color="#6EE7B7") fNew = F(border=1, bg_color="#FFF3CD", align="center") fExt = F(border=1, bg_color="#D1ECF1", align="center") fReu = F(border=1, bg_color="#D4EDDA", align="center") fNumN = F(border=1, align="right", num_format="#,##0.0", bg_color="#FFF3CD") fNumE = F(border=1, align="right", num_format="#,##0.0", bg_color="#D1ECF1") fNumR = F(border=1, align="right", num_format="#,##0.0", bg_color="#D4EDDA") fRowN = F(border=1, bg_color="#FFF3CD") fRowE = F(border=1, bg_color="#D1ECF1") fRowR = F(border=1, bg_color="#D4EDDA") fSub7 = F(bold=True, border=1, bg_color="#E8F5E9") fSub7R= F(bold=True, border=1, bg_color="#E8F5E9", align="right", num_format="#,##0.0") fEBS = F(bold=True, font_color="white", bg_color="#048A81", align="center", border=1) fGreen = F(border=1, align="right", num_format="#,##0.0", bg_color="#E8F5E9") fAmber = F(border=1, align="right", num_format="#,##0.0", bg_color="#FFF3E0") fRed = F(border=1, align="right", num_format="#,##0.0", bg_color="#FFEBEE") fGreenI= F(border=1, align="right", bg_color="#E8F5E9") fAmberI= F(border=1, align="right", bg_color="#FFF3E0") fRedI = F(border=1, align="right", bg_color="#FFEBEE") SIZE_FMT = {"XS": fXS, "S": fS, "M": fM, "L": fL, "XL": fL} NUM_FMT = {s: F(border=1, align="right", num_format="#,##0.0", bg_color={"XS":"#F0FFF4","S":"#D1FAE5","M":"#A7F3D0", "L":"#6EE7B7","XL":"#6EE7B7"}[s]) for s in SIZE_TABLE} FLAG_ROW = {"NEW": (fRowN, fNumN, fNew), "EXTEND": (fRowE, fNumE, fExt), "REUSE": (fRowR, fNumR, fReu)} # ── TAB 0 Client Quote ──────────────────────────────────────────────────── ws0 = wb.add_worksheet("0-Client Quote") ws0.set_column("A:A", 28); ws0.set_column("B:B", 14); ws0.set_column("C:C", 55) ws0.set_row(0, 24) ws0.merge_range("A1:C1", f"{name} — Client Quote (AFP × $/FP)", fHdr) ws0.write("A3", "A. PRICING PARAMETERS", fBold) ws0.write_row("A4", ["Parameter", "Value", "Description / Source"], fSub) p_rows = [ ("Stack Factor", stack, "1.0 = standard single stack (Django+HTMX+SQLite)"), ("Org Factor", org, "0.8 solo \| 1.0 small team \| 1.2 large team"), ("$/FP Rate", rate, "SEED — update after 3 sprints via EST-08"), ("$/FP Status", "SEED", "Change to CALIBRATED after 3 sprints of actuals"), ] for i, (a, b, c) in enumerate(p_rows, 5): ws0.write(i, 0, a, fData); ws0.write(i, 1, b, fDataR); ws0.write(i, 2, c, fData) ws0.write("A10", "B. QUOTE SUMMARY (AFP = FP × Stack × Org)", fBold) ws0.write_row("A11", ["Line Item", "FP", "Stack×Org", "AFP", "$ Total (AFP × $/FP)"], fSub) ws0.write("A12", "Sprint 0 — Project Setup (BSP+DSP)", fData) ws0.write("B12", 15, fDataR); ws0.write("C12", round(stack org, 2), fDataR) sprint0_afp = round(15 * stack * org, 1) ws0.write("D12", sprint0_afp, fDataR); ws0.write("E12", round(sprint0_afp * rate, 0), fDol) ws0.write("A13", "Feature Delivery (from Scenario List)", fData) ws0.write("B13", round(total_fp, 1), fDataR); ws0.write("C13", round(stack * org, 2), fDataR) feat_afp = round(total_fp * stack * org, 1) ws0.write("D13", feat_afp, fDataR); ws0.write("E13", round(feat_afp * rate, 0), fDol) ws0.write("A14", "PROJECT TOTAL", fBold) ws0.write("B14", round(total_fp + 15, 1), fDataR); ws0.write("C14", round(stack * org, 2), fDataR) total_proj_afp = sprint0_afp + feat_afp ws0.write("D14", round(total_proj_afp, 1), fDataR) ws0.write("E14", round(total_proj_afp * rate, 0), fDol) ws0.write("A16", "C. DELIVERY COMMITMENT BANDS (from Monte Carlo — EST-07)", fBold) ws0.write_row("A17", ["Percentile", "AFP", "$ Total", "K Tokens", "Duration (days)"], fSub) p10k, p50k, p80k, p95k = pct[9][1], pct[49][1], pct[79][1], pct[94][1] p10d, p50d, p80d, p95d = pct[9][2], pct[49][2], pct[79][2], pct[94][2] for i, (label, k, d) in enumerate([ ("P10", p10k, p10d), ("P50 — Median ★", p50k, p50d), ("P80 — Planning ★★", p80k, p80d), ("P95 — Conservative",p95k, p95d), ], 18): ratio = k / p50k if p50k else 1 band_afp = round(feat_afp * ratio, 1) ws0.write(i, 0, label, fData); ws0.write(i, 1, band_afp, fDataR) ws0.write(i, 2, round(band_afp * rate, 0), fDol) ws0.write(i, 3, round(k, 0), fDataR); ws0.write(i, 4, round(d, 2), fDataR) ws0.write("A23", "D. NOTES", fBold) for i, note in enumerate(pd["notes"], 24): ws0.write(i, 0, note, fWrap) # ── TAB 1 Setup ─────────────────────────────────────────────────────────── ws1 = wb.add_worksheet("1-Setup") ws1.set_column("A:A", 30); ws1.set_column("B:H", 14) ws1.merge_range("A1:H1", f"{name} — Setup & Calibration", fHdr) ws1.write("A3", "A. PROJECT PARAMETERS", fBold) sp_params = [ ("Project Name", name), ("Sprint Duration (days)", pd["sprint_days"]), ("Daily Throughput (K/day)",thru), ("AI Model", "Claude Sonnet 4.x"), ("ECF×TCF Combined Mult.", mult), ("$/FP Rate", rate), ("Stack Factor", stack), ("Org Factor", org), ("Estimation Phase", "Architecture Complete"), ("Iterations (Monte Carlo)",iters), ] for i, (k, v) in enumerate(sp_params, 4): ws1.write(i, 0, k, fData); ws1.write(i, 1, v, fData if isinstance(v, str) else fDataR) ws1.write("A15", "B. REFERENCE STORY BASELINES", fBold) ws1.write_row("A16", ["Size", "SP (internal)", "FP (client)", "K Min", "K Exp", "K Max", "Status", "Notes"], fSub) ref_notes = { "XS": "Simple modal, inline form, config entry", "S": "Single CRUD screen, service+repo+view+tests", "M": "Full BPE cycle, first-time entity or novel component", "L": "Cross-cutting / network integration", "XL": "Complex subsystem — split into L if possible", } for i, (sz, (sp, fp, kmin, kexp, kmax)) in enumerate(SIZE_TABLE.items(), 17): ws1.write_row(i, 0, [sz, sp, fp, kmin, kexp, kmax, "SEED", ref_notes[sz]], fData) # ── TAB 2 Scenario List ─────────────────────────────────────────────────── ws2 = wb.add_worksheet("2-Scenario List") ws2.set_column("A:A", 20); ws2.set_column("B:B", 28) ws2.set_column("C:C", 10); ws2.set_column("D:D", 40) ws2.set_column("E:E", 6); ws2.set_column("F:G", 8) ws2.set_column("H:M", 10); ws2.set_column("N:N", 8); ws2.set_column("O:O", 35) ws2.merge_range("A1:O1", f"{name} — Scenario List ({len(sc_data)} scenarios)", fHdr) ws2.write_row("A2", ["Scenario ID", "Feature", "Group", "Description", "Size", "SP", "FP", "K Min", "K Exp", "K Max", "Adj Min", "Adj Exp", "Adj Max", "Sprint", "Notes"], fSub) for i, sc in enumerate(sc_data): r = i + 2 sf = SIZE_FMT.get(sc["size"], fData) nf = NUM_FMT.get(sc["size"], fDataR) sp, fp, kmin, kexp, kmax = SIZE_TABLE[sc["size"]] ws2.write(r, 0, sc["sid"], sf); ws2.write(r, 1, sc["feat"], sf) ws2.write(r, 2, sc["grp"], sf); ws2.write(r, 3, sc["desc"], sf) ws2.write(r, 4, sc["size"], sf) ws2.write(r, 5, sp, nf); ws2.write(r, 6, fp, nf) ws2.write(r, 7, kmin, nf); ws2.write(r, 8, kexp, nf); ws2.write(r, 9, kmax, nf) ws2.write(r, 10, sc["kmin"], nf); ws2.write(r, 11, sc["kexp"], nf) ws2.write(r, 12, sc["kmax"], nf) ws2.write(r, 13, sc["sprint"], nf); ws2.write(r, 14, sc["notes"], sf) ws2.freeze_panes(2, 0) # ── TAB 3 ECF ───────────────────────────────────────────────────────────── ECF_FACTORS = [ ("E1", "Familiarity with AI model/tooling", 1.5), ("E2", "Part-time / context switching", -1.0), ("E3", "Analyst/prompt engineering experience", 0.5), ("E4", "Lead developer application experience", 0.5), ("E5", "Team motivation", 1.0), ("E6", "Requirements stability", 2.0), ("E7", "Part-time users/product owners", -1.0), ("E8", "Difficulty of stack/language", -1.0), ("A1", "AI model tier (Opus=5, Sonnet=3, Haiku=1)", 0.8), ("A2", "Prompt maturity (mature=5, first=1)", 0.6), ("A3", "Hallucination risk (low=5, high=1)", -0.5), ("A4", "Context window pressure (large=5)", -0.4), ("A5", "AI code rework rate (41% baseline=3)", -0.6), ] ws3 = wb.add_worksheet("3-ECF") ws3.set_column("A:B", 30); ws3.set_column("C:E", 12); ws3.set_column("F:F", 45) ws3.merge_range("A1:F1", "Environmental Complexity Factors (ECF) — INTERNAL", fHdr) ws3.write("A2", "INTERNAL: ECF feeds combined multiplier (token budget). Never shown to client.", fWrap) ws3.write_row("A3", ["#", "Factor", "Weight", "Rating (0–5)", "Weighted", "Notes"], fSub) for i, (num, factor, weight) in enumerate(ECF_FACTORS, 4): rating = ecf_r.get(num, 3) ws3.write(i, 0, num, fData); ws3.write(i, 1, factor, fData) ws3.write(i, 2, weight, fDataR); ws3.write(i, 3, rating, fDataR) ws3.write(i, 4, f"=C{i+1}D{i+1}", fDataR) ws3.write(i, 5, f"Rating={rating}", fData) # Rows 17–19 (0-indexed) = Excel rows 18–20 ws3.write(17, 0, "ECF Base", fBold); ws3.write(17, 1, "=1.4+(-0.03SUM(E5:E12))", fDataR) ws3.write(18, 0, "AI Adjustment", fBold); ws3.write(18, 1, "=1+(0.05SUM(E13:E17))", fDataR) ws3.write(19, 0, "ECF Final = Base × AI", fBold); ws3.write(19, 1, "=B18B19", fDataR) # ── TAB 4 TCF ───────────────────────────────────────────────────────────── TCF_FACTORS = [ ("T1", "Distributed system / microservices", 2.0), ("T2", "Response time / performance requirements", 1.0), ("T3", "End-user efficiency (UX optimised)", 1.0), ("T4", "Complex internal processing / algorithms", 1.0), ("T5", "Code reusability requirement", 1.0), ("T6", "Easy to install / deploy", 0.5), ("T7", "Easy to use (usability)", 0.5), ("T8", "Portability across platforms", 2.0), ("T9", "Maintainability", 1.0), ("T10", "Concurrent use / multi-user", 1.0), ("T11", "Security features", 1.0), ("T12", "Third-party API / direct access", 1.0), ("T13", "Special user training required", 1.0), ] ws4 = wb.add_worksheet("4-TCF") ws4.set_column("A:B", 30); ws4.set_column("C:E", 12); ws4.set_column("F:F", 45) ws4.merge_range("A1:F1", "Technical Complexity Factors (TCF) — INTERNAL", fHdr) ws4.write("A2", "INTERNAL: TCF feeds combined multiplier. Client complexity → Stack Factor (Tab 0).", fWrap) ws4.write_row("A3", ["#", "Factor", "Weight", "Rating (0–5)", "Weighted", "Notes"], fSub) for i, (num, factor, weight) in enumerate(TCF_FACTORS, 4): rating = tcf_r.get(num, 3) ws4.write(i, 0, num, fData); ws4.write(i, 1, factor, fData) ws4.write(i, 2, weight, fDataR); ws4.write(i, 3, rating, fDataR) ws4.write(i, 4, f"=C{i+1}D{i+1}", fDataR) ws4.write(i, 5, f"Rating={rating}", fData) # TCF Final at row 17 (0-indexed) = Excel row 18; factors in Excel rows 5–17 ws4.write(17, 0, "TCF Final", fBold); ws4.write(17, 1, "=0.6+(0.01SUM(E5:E17))", fDataR) ws4.write(18, 0, "ECF Final (from ECF tab)", fBold); ws4.write(18, 1, "='3-ECF'!B20", fDataR) ws4.write(19, 0, "Combined Multiplier ECF×TCF",fBold); ws4.write(19, 1, "=B18B19", fDataR) # ── TAB 5 Rough Estimates ───────────────────────────────────────────────── ws5 = wb.add_worksheet("5-Rough Estimates") ws5.set_column("A:A", 8); ws5.set_column("B:L", 12); ws5.set_column("M:O", 18) ws5.merge_range("A1:O1", f"{name} — Rough Estimates (L1 Token Budget + AFP Preview)", fHdr) ws5.write_row("A2", ["Sprint", "Scenarios", "SP", "FP", "Min K", "Exp K", "Max K", "Min d", "Exp d", "Max d", "AFP", "AFP $", "Phase", "Calib", "Notes"], fSub) tot = dict(sc=0, sp=0, fp=0, kmin=0, kexp=0, kmax=0) for i, row in enumerate(sprint_rows, 3): ws5.write_row(i, 0, row, fData) tot["sc"] += row[1]; tot["sp"] += row[2]; tot["fp"] += row[3] tot["kmin"] += row[4]; tot["kexp"] += row[5]; tot["kmax"] += row[6] tr = len(sprint_rows) + 3 ws5.write(tr, 0, "TOTAL", fTotL) for c in range(1, 15): ws5.write(tr, c, "", fTot) ws5.write(tr, 1, tot["sc"], fTot); ws5.write(tr, 2, round(tot["sp"], 1), fTot) ws5.write(tr, 3, round(tot["fp"], 1), fTot) ws5.write(tr, 4, round(tot["kmin"], 0), fTot); ws5.write(tr, 5, round(tot["kexp"], 0), fTot) ws5.write(tr, 6, round(tot["kmax"], 0), fTot) # ── TAB 6 Monte Carlo ──────────────────────────────────────────────────── ws6 = wb.add_worksheet("6-Monte Carlo") ws6.set_column("A:A", 6); ws6.set_column("B:B", 16) ws6.set_column("C:C", 22); ws6.set_column("D:D", 18) ws6.merge_range("A1:D1", f"EBS SIMULATION DATA — 100-percentile distribution " f"({iters:,} iterations · triangular dist · {len(sc_data)} scenarios)", fEBS) ws6.write_row("A2", ["#", "Probability (%)", "Token Budget (K)", "Duration (days)"], fSub) for i, (p, k, d) in enumerate(pct): r = i + 2 if p <= 50: fi, fn = fGreenI, fGreen elif p <= 80: fi, fn = fAmberI, fAmber else: fi, fn = fRedI, fRed ws6.write(r, 0, i + 1, fi); ws6.write(r, 1, p, fi) ws6.write(r, 2, k, fn); ws6.write(r, 3, d, fn) # Summary block for j, (label, pidx) in enumerate([("P10",9),("P50",49),("P80",79),("P95",94)], 103): ws6.write(j, 0, label, fBold) ws6.write(j, 1, round(pct[pidx][1], 0), fNum) ws6.write(j, 2, round(pct[pidx][2], 2), fNum) # Token Budget S-curve max_k = math.ceil(max(p[1] for p in pct) / 1000) 1000 ch_k = wb.add_chart({"type": "line"}) ch_k.add_series({ "name": "Token Budget", "categories": ["6-Monte Carlo", 2, 1, 101, 1], "values": ["6-Monte Carlo", 2, 2, 101, 2], "line": {"color": "#048A81", "width": 2}, "marker": {"type": "none"}, "smooth": True, }) ch_k.set_title({"name": "Token Budget S-Curve (EBS — internal)"}) ch_k.set_x_axis({"name": "Probability (%)", "min": 0, "max": 100, "major_gridlines": {"visible": True}}) ch_k.set_y_axis({"name": "K Tokens", "min": 0, "max": max_k, "major_gridlines": {"visible": True}}) ch_k.set_legend({"none": True}); ch_k.set_size({"width": 480, "height": 300}) ws6.insert_chart("F2", ch_k) # Duration S-curve ch_d = wb.add_chart({"type": "line"}) ch_d.add_series({ "name": "Duration", "categories": ["6-Monte Carlo", 2, 1, 101, 1], "values": ["6-Monte Carlo", 2, 3, 101, 3], "line": {"color": "#F4A261", "width": 2}, "marker": {"type": "none"}, "smooth": True, }) ch_d.set_title({"name": "Duration S-Curve (EBS — internal)"}) ch_d.set_x_axis({"name": "Probability (%)", "min": 0, "max": 100, "major_gridlines": {"visible": True}}) ch_d.set_y_axis({"name": "Duration (days)", "min": 0, "major_gridlines": {"visible": True}}) ch_d.set_legend({"none": True}); ch_d.set_size({"width": 480, "height": 300}) ws6.insert_chart("F26", ch_d) # ── TAB 7 WBS Features ──────────────────────────────────────────────────── ws7 = wb.add_worksheet("7-WBS Features") ws7.set_column("A:A", 20); ws7.set_column("B:B", 28) ws7.set_column("C:C", 7); ws7.set_column("D:D", 5) ws7.set_column("E:E", 38); ws7.set_column("F:F", 10) ws7.set_column("G:G", 8); ws7.set_column("H:H", 8); ws7.set_column("I:K", 9) ws7.set_column("L:L", 35) ws7.merge_range("A1:L1", "Work Breakdown Structure — BPE-01 Estimation Mode (EST-06)", fHdr) ws7.write_row("A2", ["Scenario ID", "Feature", "Sprint", "WP#", "Artifact (BPE-01)", "Type", "Flag", "Reuse×", "K Min", "K Exp", "K Max", "Notes"], fSub) row7 = 2 wbs_totals = {} for sc in sc_data: sid = sc["sid"] arts = wbs.get(sid, []) sc_lo = sc_mi = sc_hi = 0.0 for wp, (atype, desc, flag) in enumerate(arts, 1): lo, mi, hi = artifact_pert(atype, flag) sc_lo += lo; sc_mi += mi; sc_hi += hi fr, fn, ff = FLAG_ROW[flag] ws7.write(row7, 0, sid, fr); ws7.write(row7, 1, sc["feat"], fr) ws7.write(row7, 2, sc["sprint"], fr); ws7.write(row7, 3, wp, fr) ws7.write(row7, 4, desc, fr); ws7.write(row7, 5, atype, fr) ws7.write(row7, 6, flag, ff); ws7.write(row7, 7, MULT_FLAG[flag], fn) ws7.write(row7, 8, lo, fn); ws7.write(row7, 9, mi, fn) ws7.write(row7, 10, hi, fn) ws7.write(row7, 11, f"BPE-01 est. · {atype} · {flag}", fr) ws7.set_row(row7, 14); row7 += 1 # sub-total row l1exp = sc["kexp"] delta = (sc_mi - l1exp) / l1exp if l1exp else 0 warn = " ⚠️ WARNING >30%" if abs(delta) > 0.30 else "" note = f"L1={l1exp}K L2={sc_mi:.0f}K Δ={delta:+.0%}{warn}" if arts: ws7.write(row7, 0, f" ▶ {sid} total", fSub7) for c in range(1, 8): ws7.write(row7, c, "", fSub7) ws7.write(row7, 8, round(sc_lo, 1), fSub7R) ws7.write(row7, 9, round(sc_mi, 1), fSub7R) ws7.write(row7, 10, round(sc_hi, 1), fSub7R) ws7.write(row7, 11, note, fSub7) ws7.set_row(row7, 14); row7 += 1 wbs_totals[sid] = (round(sc_lo, 1), round(sc_mi, 1), round(sc_hi, 1)) ws7.freeze_panes(2, 0) # ── TAB 8 Detailed Estimates ────────────────────────────────────────────── ws8 = wb.add_worksheet("8-Detailed Estimates") ws8.set_column("A:A", 20); ws8.set_column("B:B", 28) ws8.set_column("C:F", 7); ws8.set_column("G:K", 10) ws8.set_column("L:M", 10); ws8.set_column("N:N", 12) ws8.set_column("O:P", 10); ws8.set_column("Q:Q", 35) ws8.merge_range("A1:Q1", "Detailed Estimates — L2 vs L1 Cross-Check (EST-06 · rebaseline after each sprint close)", fHdr) ws8.write_row("A2", ["Scenario ID", "Feature", "Sprint", "Size", "SP", "FP", "L2 Min(K)", "L2 Exp(K)", "L2 Max(K)", "L1 Exp(K)", "L1/L2 Δ%", "Actual(K)", "Token VF", "AFP Est($)", "AFP VF", "Status", "Notes"], fSub) grand = dict(l2min=0, l2exp=0, l2max=0, l1exp=0, fp=0, afp=0) for i, sc in enumerate(sc_data): r = i + 2 sf = SIZE_FMT.get(sc["size"], fData) nf = NUM_FMT.get(sc["size"], fDataR) l2lo, l2mi, l2hi = wbs_totals.get(sc["sid"], (sc["kmin"], sc["kexp"], sc["kmax"])) l1exp = sc["kexp"]; afp = sc["afp"] delta = (l2mi - l1exp) / l1exp if l1exp else 0 if abs(delta) > 0.30: note = f"Δ={delta:+.0%} ⚠️ WARNING >30%" elif abs(delta) > 0.15: note = f"Δ={delta:+.0%} — review" else: note = f"Δ={delta:+.0%} — consistent" delta_fmt = F(border=1, align="right", num_format="0%", bg_color="#F0FFF4" if abs(delta) <= 0.15 else "#FFF3CD" if abs(delta) <= 0.30 else "#FFEBEE") ws8.write(r, 0, sc["sid"], sf); ws8.write(r, 1, sc["feat"], sf) ws8.write(r, 2, sc["sprint"],nf); ws8.write(r, 3, sc["size"], sf) ws8.write(r, 4, sc["sp"], nf); ws8.write(r, 5, sc["fp"], nf) ws8.write(r, 6, l2lo, nf); ws8.write(r, 7, l2mi, nf) ws8.write(r, 8, l2hi, nf); ws8.write(r, 9, l1exp, nf) ws8.write(r, 10, delta, delta_fmt) ws8.write(r, 11, "", fData); ws8.write(r, 12, "", fData) ws8.write(r, 13, afp, fDol) ws8.write(r, 14, "", fData); ws8.write(r, 15, "PLANNED", sf) ws8.write(r, 16, note, fWrap) ws8.set_row(r, 15) grand["l2min"] += l2lo; grand["l2exp"] += l2mi; grand["l2max"] += l2hi grand["l1exp"] += l1exp; grand["fp"] += sc["fp"]; grand["afp"] += afp tr = len(sc_data) + 2 ws8.write(tr, 0, "TOTAL", fTotL) for c in range(1, 17): ws8.write(tr, c, "", fTot) ws8.write(tr, 5, round(grand["fp"], 1), fTot) ws8.write(tr, 6, round(grand["l2min"],1), fTot) ws8.write(tr, 7, round(grand["l2exp"],1), fTot) ws8.write(tr, 8, round(grand["l2max"],1), fTot) ws8.write(tr, 9, round(grand["l1exp"],1), fTot) ws8.write(tr, 13, round(grand["afp"], 0), fTotD) ws8.set_row(tr, 18); ws8.freeze_panes(2, 0) wb.close() # ── Summary ──────────────────────────────────────────────────────────────── l1_total = grand["l1exp"] l2_total = grand["l2exp"] delta_pct = (l2_total - l1_total) / l1_total * 100 if l1_total else 0 print(f"\n✅ Written: {out}") print(f" Scenarios : {len(sc_data)}") print(f" WBS rows : {row7 - 2}") print(f" L1 total : {l1_total:,.0f} K") print(f" L2 total : {l2_total:,.0f} K Δ={delta_pct:+.1f}%") print(f" FP total : {grand['fp']:.1f} AFP: ${grand['afp']:,.0f}") print(f" EBS P50 : {pct[49][1]:,.0f} K / {pct[49][2]:.2f} d") print(f" EBS P80 : {pct[79][1]:,.0f} K / {pct[79][2]:.2f} d") print(f" EBS P95 : {pct[94][1]:,.0f} K / {pct[94][2]:.2f} d") if __name__ == "__main__": main() ```
Gherkin Step Library Patterns	BDD Step Engineering	gherkin, behave, step-definitions	Junior Edda	Read the 'Gherkin Step Library Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: BDD Step Engineering Technology stack: gherkin, behave, step-definitions # Skill: Gherkin Step Library Patterns Capability Domain: BDD_AUTHORING Technology Stack: Gherkin+behave ## Overview Patterns for organizing, versioning, and composing reusable Gherkin step definitions. The step library is the shared vocabulary between ESM (which writes .feature files) and TFK (which implements the steps). AT steps live under `docs/features/steps/` (Django test client). E2E counterparts live under `tests/e2e/steps/` (Playwright). Catalog phrases are shared; Python implementations are not merged. ## Reference Implementation ### Pattern 1: Step Library Organization ``` docs/features/steps/ # AT — Django test client ├── navigation_steps.py ├── form_steps.py ├── table_steps.py ├── auth_steps.py ├── assertion_steps.py ├── dialog_steps.py ├── common_steps.py └── (catalog: docs/features/CATALOG.md) tests/e2e/steps/ # E2E — Playwright-backed counterparts ``` ### Pattern 2: Step Naming Convention Steps should be generic and parameterized. Entity names come from parameters, not hardcoded: ```gherkin # GOOD — reusable across any entity Given a "Playbook" named "FeatureFactory" exists When the user clicks "Create" button # BAD — hardcoded to one entity Given the FeatureFactory playbook exists ``` ### Pattern 3: Step Composition in .feature Files ESM writes scenarios by composing steps from the library like building blocks when the catalog already exists. Write `.feature` files to `docs/features/act-*/`. On greenfield first-pass ESM (before TFK), write clear unconstrained Gherkin; TFK later binds phrases to implementations (see ESM-05 guidance).
GitHub Actions Patterns	CI_CD	GitHub Actions	Junior Edda	Read the 'GitHub Actions Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: CI_CD Technology stack: GitHub Actions # Skill: GitHub Actions Patterns Capability Domain: CI_CD Technology Stack: GitHub Actions ## Overview Reference patterns for CI/CD with GitHub Actions. Covers triggers, AWS auth (OIDC and access keys), environment protection, Makefile-first architecture, and release-gated deploy (Huginn model). --- ## Existing Patterns 1–10 (Unchanged: OIDC federation, ECR auth, environment protection rules, workflow triggers, Makefile-first, conditional jobs, job outputs, caching, badges, emergency rollback workflow.) --- ## Pattern 11: Release-Gated Deploy (Huginn Model) Pipeline runs only on published GitHub Releases (or manual dispatch). Pushes to `main` do not deploy. ```yaml name: Build and Deploy on: release: types: [published] workflow_dispatch: jobs: test: runs-on: ubuntu-latest steps: - run: make test build-and-push: needs: test steps: - run: # build ECR image + optional Docker Hub client image deploy-idle: needs: build-and-push if: vars.AWS_ACCOUNT_ID != '' steps: - run: bash scripts/deploy-idle.sh # Promote is SEPARATE workflow — workflow_dispatch + production environment ``` Release process: ```bash gh release create vX.Y.Z --title "..." --notes "..." # CI: test → build → deploy-idle → idle smoke # Human reviews idle URL make swap # or: gh workflow run promote.yml ``` Why release-gated: - Explicit semver control - Avoids concurrent EB deploy races - Matches Huginn/GitLab promote-after-staging model When to use continuous (push) instead: Fast-moving dev/staging, no EB concurrency concerns, feature branches need CI on every push. --- ## Pattern 12: Dual Registry Build ```yaml # Web app → private ECR (deployed to EB/EKS) - uses: docker/build-push-action@v5 with: tags: ${{ steps.ecr.outputs.registry }}/myapp:${{ steps.tag.outputs.suffix }} # Client tool (MCP facade) → public Docker Hub (NOT deployed to cloud) - uses: docker/build-push-action@v5 with: file: Dockerfile.mcp tags: myorg/myapp-mcp:${{ steps.tag.outputs.suffix }} ``` --- ## Pattern 13: Auth — OIDC vs Access Keys \| Method \| Setup \| Best for \| \|--------\|-------\|----------\| \| OIDC \| IAM role + `role-to-assume` \| Org repos, no long-lived secrets \| \| Access keys \| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` secrets \| Single-team, simpler bootstrap \| Both are valid. Document choice in `CICD_REQUIREMENTS.md`. EB skill Pattern 3 uses access keys as the simpler default; upgrade to OIDC when ready. --- ## Pattern 14: Separate Promote Workflow ```yaml # .github/workflows/promote.yml on: workflow_dispatch: inputs: expected_revision: required: false jobs: promote: environment: production steps: - run: bash scripts/promote-prod.sh ``` Never auto-promote to production after idle deploy — always require human review or environment approval. --- ## GitHub Environment Configuration \| Environment \| Reviewers \| Purpose \| \|-------------\|-----------\|---------\| \| `infrastructure` \| 0–1 \| CDK deploy \| \| `staging` \| None \| Auto-deploy to idle (optional) \| \| `production` \| 1–2 \| CNAME swap / traffic switch \| --- ## Common Pitfalls 1. Storing AWS keys when OIDC available — prefer OIDC for org scale 2. Business logic in YAML — use Makefile 3. Auto-promote to prod — always gate 4. Push + release both triggering deploy — pick one trigger model 5. workflow_run gotcha — uses default branch workflow file
GitHub Issue Operations	GITHUB_ISSUE	GitHub CLI	Junior Edda	Read the 'GitHub Issue Operations' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: GITHUB_ISSUE Technology stack: GitHub CLI # Skill: GitHub Issue Operations Capability Domain: GITHUB_ISSUE Technology Stack: GitHub CLI ## Overview Patterns for managing GitHub Milestones and Issues as iteration execution records. Covers the `<!-- SCENARIO -->` YAML embedding convention, label management for iteration state, and structured comment templates for checkpoints and drift signals. ## Bootstrap Labels ```bash for label in \ "status-queued:#e4e669:Scenario waiting to start" \ "status-in-progress:#0075ca:Scenario being executed" \ "status-done:#0e8a16:Scenario complete" \ "drift-absorbed:#fef2c0:Drift absorbed within threshold" \ "drift-escalated:#e11d48:Drift escalated to human" \ "parallel-group-A:#bfd4f2:" \ "parallel-group-B:#d4c5f9:" \ "parallel-group-C:#f9d0c4:" \ "backlog:#ededed:"; do name=$(echo $label \| cut -d: -f1) color=$(echo $label \| cut -d: -f2) desc=$(echo $label \| cut -d: -f3) gh label create "$name" --color "$color" --description "$desc" 2>/dev/null \|\| true done ``` ## Pattern 1 — Create Milestone ```bash gh api repos/{owner}/{repo}/milestones \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="$(cat <<'EOF' <!-- MANIFEST --> {paste full ITER-*.yaml verbatim} <!-- /MANIFEST --> ## Iteration Goal {iteration_goal} ## Scenarios - S1: {title} EOF )" # Record returned milestone number ``` ## Pattern 2 — Create Scenario Issue ```bash gh issue create \ --title "[S1][A] {scenario title}" \ --label "status-queued,parallel-group-A" \ --milestone "{milestone_number}" \ --body "$(cat <<'EOF' <!-- SCENARIO --> id: S1 parallel_group: A skeleton_commit: "{hash}" codebase_footprint: - path/to/file.py checkpoint: command: "pytest tests/integration/test_feature.py -x" expected_exit_code: 0 dependencies: [] sao_sections: - "§Services Layer" do_not_do: - "Do NOT create a new Django app" system_dependencies: - notification_service # or empty list [] if none; append [STUBBED] if stubbed in skeleton rollback_point: "git stash" <!-- /SCENARIO --> ## Context Map \| File \| Lines \| Note \| \|------\|-------\|------\| \| path/to/service.py \| 45–80 \| Follow this pattern \| ## Do Not Do - Do NOT create a new Django app ## SAO.md Sections That Apply - §Services Layer ## Implementation Plan {BPE-01 plan content — full text} ## Acceptance Criteria - [ ] `pytest tests/integration/test_feature.py -x` passes - [ ] No regressions: `pytest tests/ -x --ignore=tests/e2e` passes - [ ] Changes committed with Angular convention message EOF )" ``` ## Pattern 2b — Parse SCENARIO Block from Issue Body ```bash # Get issue body ISSUE_BODY=$(gh issue view {issue_number} --json body --jq '.body') # Extract and parse SCENARIO block python3 - <<EOF import re, yaml body = """$ISSUE_BODY""" match = re.search(r'<!-- SCENARIO -->(.+?)<!-- /SCENARIO -->', body, re.DOTALL) if match: scenario = yaml.safe_load(match.group(1)) print('ID:', scenario['id']) print('Group:', scenario['parallel_group']) print('Skeleton commit:', scenario['skeleton_commit']) print('Checkpoint:', scenario['checkpoint']['command']) print('Footprint:', scenario['codebase_footprint']) print('SAO sections:', scenario['sao_sections']) print('Do not do:', scenario['do_not_do']) print('Dependencies:', scenario['dependencies']) print('System deps:', scenario.get('system_dependencies', [])) EOF ``` ## Pattern 3 — Label State Transitions ```bash # queued → in-progress gh issue edit {N} --add-label "status-in-progress" --remove-label "status-queued" # in-progress → done gh issue close {N} gh issue edit {N} --add-label "status-done" --remove-label "status-in-progress" # drift escalation gh issue edit {N} --add-label "drift-escalated" --remove-label "status-in-progress" ``` ## Pattern 4 — Checkpoint Pass Comment ```bash gh issue comment {N} --body "<!-- CHECKPOINT_PASS --> Checkpoint passed at: $(date -u +%Y-%m-%dT%H:%M:%SZ) Command: {command} <!-- /CHECKPOINT_PASS -->" ``` ## Pattern 5 — Absorbed Drift Comment ```bash gh issue comment {N} --body "<!-- DRIFT absorbed --> type: checkpoint_fail detected_at: $(date -u +%Y-%m-%dT%H:%M:%SZ) action: {fix applied} retry: PASS <!-- /DRIFT -->" gh issue edit {N} --add-label "drift-absorbed" ``` ## Pattern 6 — Escalate Comment ```bash gh issue comment {N} --body "<!-- ESCALATE --> type: {footprint_violation\|method_explosion\|sao_violation\|checkpoint_fail_retry\|system_dependency_missing} evidence: {specific — file / method / constraint / test output / missing dependency name} jedao_recommendation: {A: fix and retry \| B: resequence \| C: scope reduce} await_human_decision: true <!-- /ESCALATE -->" gh issue edit {N} --add-label "drift-escalated" --remove-label "status-in-progress" ``` ## Pattern 7 — Next Eligible Scenario ```bash # Get all queued issues for milestone gh issue list \ --milestone {N} \ --label "status-queued" \ --json number,title,body \ --jq '.[] \| {number, title}' # Filter for scenarios with all dependencies met python3 - <<EOF import subprocess, json, re, yaml issues = json.loads(subprocess.check_output([ 'gh', 'issue', 'list', '--milestone', '{N}', '--label', 'status-queued', '--json', 'number,title,body' ])) for issue in issues: body = issue['body'] match = re.search(r'<!-- SCENARIO -->(.+?)<!-- /SCENARIO -->', body, re.DOTALL) if not match: continue scenario = yaml.safe_load(match.group(1)) deps = scenario.get('dependencies', []) # For each dependency issue number, verify it is closed with status-done all_done = all( 'status-done' in subprocess.check_output( ['gh', 'issue', 'view', str(dep), '--json', 'labels', '--jq', '[.labels[].name]'] ).decode() for dep in deps ) if deps else True if all_done: print(f"ELIGIBLE: #{issue['number']} {issue['title']}") break EOF ``` ## Quality Gates - [ ] Every scenario issue has `<!-- SCENARIO -->` block parseable as YAML - [ ] `skeleton_commit` field present and is a valid git hash - [ ] `sao_sections[]` and `do_not_do[]` fields present and non-empty - [ ] `system_dependencies[]` field present (empty list `[]` is valid) - [ ] Context Map, Do Not Do, SAO Sections, and Implementation Plan all present inline (not linked) - [ ] Every scenario issue linked to correct milestone - [ ] Labels transition correctly through state machine - [ ] Drift comments include `type`, `detected_at`, `evidence` - [ ] Escalate comments include `jedao_recommendation` and specific `evidence`
GitHub Milestone Operations	GITHUB_MILESTONE	GitHub CLI	Junior Edda	Read the 'GitHub Milestone Operations' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: GITHUB_MILESTONE Technology stack: GitHub CLI # Skill: GitHub Milestone Operations Capability Domain: GITHUB_MILESTONE Technology Stack: GitHub CLI ## Overview Patterns for creating, reading, updating, and closing GitHub Milestones as Iteration records. Covers the `<!-- MANIFEST -->` YAML embedding convention used by PIT and MIT. ## Reference Implementation ### Pattern 1: Create Milestone with MANIFEST Block ```bash # Create iteration milestone with embedded YAML manifest gh api repos/{owner}/{repo}/milestones \ --method POST \ --field title="ITER-$(date +%Y%m%d) \| {iteration_goal}" \ --field due_on="$(date -u -v+1d +%Y-%m-%dT23:59:59Z)" \ --field description="$(cat <<'ENDDESC' <!-- MANIFEST --> iteration: goal: "Ship workflow export+import via MCP" doctrine_version: "2.0" created_at: "2026-04-13T18:00:00Z" conflict_map: mcp_integration/tools.py: [S1, S2] parallel_groups: A: [S1] B: [S3] C: [S2] scenarios: S1: title: "User can export workflow as JSON" github_issue: null parallel_group: A skeleton_commit: null # filled by PIT-02 after skeleton commit sao_sections: - "3.2 Service Layer" - "4.1 MCP Tool Contracts" context_map: - "methodology/services/workflow_service.py:45-89" - "mcp_integration/tools.py:120-145" do_not_do: - "Do not touch auth views — outside footprint" - "Do not add fields to Workflow model" codebase_footprint: - mcp_integration/tools.py - methodology/services/workflow_export_service.py - tests/integration/test_mcp_export.py checkpoint: command: "pytest tests/integration/test_mcp_export.py -x" expected_exit_code: 0 dependencies: [] rollback_point: "git stash" <!-- /MANIFEST --> ## Iteration Goal Ship workflow export+import via MCP so that AI-to-AI handoff works. ## Scenarios - [S1] User can export workflow as JSON - [S2] User can import workflow from JSON ENDDESC )" ``` ### Pattern 2: Read and Parse MANIFEST from Milestone ```bash # Get milestone description MILESTONE_DESC=$(gh api repos/{owner}/{repo}/milestones/{N} --jq '.description') # Extract MANIFEST block MANIFEST_YAML=$(echo "$MILESTONE_DESC" \| \ awk '/<!-- MANIFEST -->/{found=1; next} /<!-- \/MANIFEST -->/{found=0} found{print}') # Parse with Python (reliable YAML parsing) python3 - <<EOF import yaml, sys manifest = yaml.safe_load("""$MANIFEST_YAML""") print('Goal:', manifest['iteration']['goal']) print('Doctrine version:', manifest['iteration']['doctrine_version']) for sid, scenario in manifest['scenarios'].items(): print(f' {sid}: {scenario["title"]} [{scenario["parallel_group"]}]') print(f' skeleton_commit: {scenario.get("skeleton_commit")}') print(f' sao_sections: {scenario.get("sao_sections")}') EOF ``` ### Pattern 3: Update MANIFEST in Milestone Description ```bash # Read current description CURRENT_DESC=$(gh api repos/{owner}/{repo}/milestones/{N} --jq '.description') # Replace MANIFEST block with updated YAML UPDATED_DESC=$(python3 - <<EOF import re, yaml desc = """$CURRENT_DESC""" new_manifest = """iteration: goal: "{new_goal}" ...""" updated = re.sub( r'<!-- MANIFEST -->.?<!-- /MANIFEST -->', f'<!-- MANIFEST -->\n{new_manifest}\n<!-- /MANIFEST -->', desc, flags=re.DOTALL ) print(updated) EOF ) # Patch milestone gh api repos/{owner}/{repo}/milestones/{N} \ --method PATCH \ --field description="$UPDATED_DESC" ``` ### Pattern 4: Close Milestone ```bash # Verify all issues are closed first OPEN_COUNT=$(gh issue list --milestone {N} --state open --json number \| jq 'length') if [ "$OPEN_COUNT" -gt 0 ]; then echo "ERROR: $OPEN_COUNT issues still open. Cannot close milestone." exit 1 fi # Close the milestone gh api repos/{owner}/{repo}/milestones/{N} \ --method PATCH \ --field state="closed" echo "Milestone {N} closed." ``` ### Pattern 5: Get Milestone Progress ```bash # Get milestone stats gh api repos/{owner}/{repo}/milestones/{N} \ --jq '{title: .title, open: .open_issues, closed: .closed_issues, pct: (.closed_issues / (.open_issues + .closed_issues) 100 \| floor)}' ``` ## MANIFEST YAML Schema ```yaml iteration: goal: string # "Verb noun so that success signal" doctrine_version: string # "2.0" created_at: ISO8601 # "2026-04-13T18:00:00Z" conflict_map: {filename}: [S1, S2] # files shared between scenarios; derived from # git diff of skeleton commits, not speculative parallel_groups: A: [S1] # first group to execute B: [S3] # can run parallel with A C: [S2] # depends on A scenarios: S{N}: title: string github_issue: int # null until PIT-03 runs parallel_group: string # A/B/C skeleton_commit: string # commit hash after PIT-02 skeleton; null until then sao_sections: [string] # SAO.md section headings that constrain this scenario context_map: [string] # 3-5 "file:line_range" references for cold-start do_not_do: [string] # explicit out-of-scope guardrails codebase_footprint: [string] # exact file paths from skeleton diff checkpoint: command: string # pytest command expected_exit_code: int # 0 dependencies: [string] # ["S1"] or [] rollback_point: string # "git stash" ``` ## Quality Gates - [ ] Milestone title follows `ITER-YYYYMMDD \| {goal}` pattern - [ ] `<!-- MANIFEST -->` block present and parseable as YAML - [ ] `doctrine_version` is `"2.0"` - [ ] All required scenario fields present: `title`, `github_issue`, `parallel_group`, `skeleton_commit`, `sao_sections`, `context_map`, `do_not_do`, `codebase_footprint`, `checkpoint`, `dependencies`, `rollback_point` - [ ] No `time_budget_minutes` or `target_duration_minutes` fields present - [ ] `conflict_map` entries derived from actual skeleton commit diffs (not speculative)
GitLab Issue Operations	GITLAB_ISSUE	GitLab CLI (glab)	Junior Edda	Read the 'GitLab Issue Operations' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: GITLAB_ISSUE Technology stack: GitLab CLI (glab) # Skill: GitLab Issue Operations Capability Domain: GITLAB_ISSUE Technology Stack: GitLab CLI (glab) ## Overview Patterns for managing GitLab Milestones and Issues as iteration execution records using `glab`. Mirrors the GitHub Issue Operations skill. Covers `<!-- SCENARIO -->` YAML embedding, label management, and structured comment templates. ## Bootstrap Labels ```bash for label in \ "status-queued:#e4e669" \ "status-in-progress:#0075ca" \ "status-done:#0e8a16" \ "drift-absorbed:#fef2c0" \ "drift-escalated:#e11d48" \ "parallel-group-A:#bfd4f2" \ "parallel-group-B:#d4c5f9" \ "parallel-group-C:#f9d0c4"; do name=$(echo $label \| cut -d: -f1) color=$(echo $label \| cut -d: -f2) glab label create "$name" --color "$color" 2>/dev/null \|\| true done ``` ## Pattern 1 — Create Milestone ```bash PROJECT=$(glab api projects/:fullpath --jq '.id') glab api "projects/$PROJECT/milestones" \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="$(cat <<'EOF' <!-- MANIFEST --> {paste full ITER-*.yaml verbatim} <!-- /MANIFEST --> ## Iteration Goal {iteration_goal} ## Scenarios - S1: {title} EOF )" # Record returned milestone id ``` ## Pattern 2 — Create Scenario Issue ```bash glab issue create \ --title "[S1][A] {scenario title}" \ --label "status-queued,parallel-group-A" \ --milestone "{milestone_title}" \ --description "$(cat <<'EOF' <!-- SCENARIO --> id: S1 parallel_group: A skeleton_commit: "{hash}" codebase_footprint: - path/to/file.py checkpoint: command: "pytest tests/integration/test_feature.py -x" expected_exit_code: 0 dependencies: [] sao_sections: - "§Services Layer" do_not_do: - "Do NOT create a new Django app" system_dependencies: - notification_service # or empty list [] if none; append [STUBBED] if stubbed in skeleton rollback_point: "git stash" <!-- /SCENARIO --> ## Context Map \| File \| Lines \| Note \| \|------\|-------\|------\| \| path/to/service.py \| 45–80 \| Follow this pattern \| ## Do Not Do - Do NOT create a new Django app ## SAO.md Sections That Apply - §Services Layer ## Implementation Plan {BPE-01 plan content — full text} ## Acceptance Criteria - [ ] `pytest tests/integration/test_feature.py -x` passes - [ ] No regressions: `pytest tests/ -x --ignore=tests/e2e` passes - [ ] Changes committed with Angular convention message EOF )" ``` ## Pattern 3 — Label State Transitions ```bash # queued → in-progress glab issue update {N} --add-label "status-in-progress" --remove-label "status-queued" # in-progress → done glab issue close {N} glab issue update {N} --add-label "status-done" --remove-label "status-in-progress" # drift escalation glab issue update {N} --add-label "drift-escalated" --remove-label "status-in-progress" ``` ## Pattern 4 — Checkpoint Pass Comment ```bash glab issue note {N} --message "<!-- CHECKPOINT_PASS --> Checkpoint passed at: $(date -u +%Y-%m-%dT%H:%M:%SZ) Command: {command} <!-- /CHECKPOINT_PASS -->" ``` ## Pattern 5 — Absorbed Drift Comment ```bash glab issue note {N} --message "<!-- DRIFT absorbed --> type: checkpoint_fail detected_at: $(date -u +%Y-%m-%dT%H:%M:%SZ) action: {fix applied} retry: PASS <!-- /DRIFT -->" glab issue update {N} --add-label "drift-absorbed" ``` ## Pattern 6 — Escalate Comment ```bash glab issue note {N} --message "<!-- ESCALATE --> type: {footprint_violation\|method_explosion\|sao_violation\|checkpoint_fail_retry\|system_dependency_missing} evidence: {specific — file / method / constraint / test output / missing dependency name} jedao_recommendation: {A: fix and retry \| B: resequence \| C: scope reduce} await_human_decision: true <!-- /ESCALATE -->" glab issue update {N} --add-label "drift-escalated" --remove-label "status-in-progress" ``` ## Pattern 7 — Next Eligible Scenario ```bash glab issue list \ --milestone "{milestone_title}" \ --label "status-queued" \ --output json \| python3 -c " import sys, json, re, yaml issues = json.load(sys.stdin) for issue in issues: match = re.search(r'<!-- SCENARIO -->(.+?)<!-- /SCENARIO -->', issue.get('description',''), re.DOTALL) if not match: continue s = yaml.safe_load(match.group(1)) print(f\"#{issue['iid']} {issue['title']} deps:{s.get('dependencies',[])}\")" ```
HTMX Frontend Logging	FRONTEND_LOGGING	HTMX+JavaScript	Junior Edda	Read the 'HTMX Frontend Logging' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: FRONTEND_LOGGING Technology stack: HTMX+JavaScript # Skill: HTMX Frontend Logging Capability Domain: FRONTEND_LOGGING Technology Stack: HTMX+JavaScript ## Overview Implement frontend logging for HTMX interactions, JavaScript errors, and user actions. Logs are captured in the browser console and sent to a Django backend endpoint for persistence in `logs/gui.log`. Enables troubleshooting of frontend issues and tracking user interaction patterns. ## Reference Implementation ### Pattern 1: JavaScript Logger Class Create `static/js/logger.js`: ```javascript /** * Frontend Logger - logs to console and sends to backend for gui.log * * Usage: * Logger.info('Button clicked', { button_id: 'save-btn', entity_id: 123 }); * Logger.error('Form validation failed', { form: 'playbook-create', errors: [...] }); / const Logger = { /* * Internal log method - sends to console and backend / _log(level, message, context = {}) { const timestamp = new Date().toISOString(); const logEntry = { level: level.toUpperCase(), timestamp: timestamp, message: message, context: context, url: window.location.pathname, user_agent: navigator.userAgent, }; // Console output (always) const consoleMethod = console[level] \|\| console.log; consoleMethod( `[${level.toUpperCase()}] ${timestamp} ${message}`, context ); // Send to backend for gui.log (async, non-blocking) this._sendToBackend(logEntry); }, /* * Send log entry to Django backend / _sendToBackend(logEntry) { fetch('/api/log/gui/', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRFToken': this._getCsrfToken(), }, body: JSON.stringify(logEntry), }).catch(err => { // Don't log to backend again (avoid infinite loop) console.error('Failed to send log to backend:', err); }); }, /* * Get CSRF token from DOM / _getCsrfToken() { const token = document.querySelector('[name=csrfmiddlewaretoken]')?.value; if (!token) { // Try cookie fallback const cookieValue = document.cookie .split('; ') .find(row => row.startsWith('csrftoken=')) ?.split('=')[1]; return cookieValue \|\| ''; } return token; }, /* * Public logging methods / debug(message, context) { this._log('debug', message, context); }, info(message, context) { this._log('info', message, context); }, warn(message, context) { this._log('warn', message, context); }, error(message, context) { this._log('error', message, context); }, }; // Make Logger globally available window.Logger = Logger; ``` ### Pattern 2: HTMX Event Logging Add HTMX event listeners to `static/js/logger.js` or separate file: ```javascript /* * HTMX Event Logging * Automatically logs all HTMX requests and responses / // Log when HTMX request starts document.body.addEventListener('htmx:beforeRequest', (event) => { const target = event.detail.target; const targetId = target.id \|\| target.getAttribute('data-testid') \|\| target.tagName; Logger.info('HTMX request started', { event: 'htmx:beforeRequest', target: targetId, method: event.detail.verb, url: event.detail.path, trigger: event.detail.triggeringEvent?.type, }); }); // Log when HTMX request completes document.body.addEventListener('htmx:afterRequest', (event) => { const target = event.detail.target; const targetId = target.id \|\| target.getAttribute('data-testid') \|\| target.tagName; const successful = event.detail.successful; const level = successful ? 'info' : 'error'; Logger[level]('HTMX request completed', { event: 'htmx:afterRequest', target: targetId, method: event.detail.verb, url: event.detail.path, status: event.detail.xhr.status, successful: successful, elapsed_ms: event.detail.elapsed, }); }); // Log HTMX response errors document.body.addEventListener('htmx:responseError', (event) => { const target = event.detail.target; const targetId = target.id \|\| target.getAttribute('data-testid') \|\| target.tagName; Logger.error('HTMX response error', { event: 'htmx:responseError', target: targetId, method: event.detail.verb, url: event.detail.path, status: event.detail.xhr.status, response_text: event.detail.xhr.responseText?.substring(0, 200), // Truncate }); }); // Log HTMX swap events (DOM updates) document.body.addEventListener('htmx:afterSwap', (event) => { const target = event.detail.target; const targetId = target.id \|\| target.getAttribute('data-testid') \|\| target.tagName; Logger.debug('HTMX content swapped', { event: 'htmx:afterSwap', target: targetId, swap_style: event.detail.xhr.getResponseHeader('HX-Reswap'), }); }); // Log HTMX validation errors document.body.addEventListener('htmx:validation:failed', (event) => { const target = event.detail.target; const targetId = target.id \|\| target.getAttribute('data-testid') \|\| target.tagName; Logger.warn('HTMX validation failed', { event: 'htmx:validation:failed', target: targetId, form: target.closest('form')?.id, }); }); ``` ### Pattern 3: User Action Logging Log specific user actions: ```javascript /* * User Action Logging * Log important user interactions / // Log button clicks document.addEventListener('click', (event) => { const button = event.target.closest('button, a.btn'); if (button) { const action = button.getAttribute('data-action') \|\| button.textContent.trim() \|\| 'unknown'; Logger.info('Button clicked', { action: action, button_id: button.id, button_class: button.className, test_id: button.getAttribute('data-testid'), }); } }); // Log form submissions document.addEventListener('submit', (event) => { const form = event.target; Logger.info('Form submitted', { form_id: form.id, form_action: form.action, form_method: form.method, test_id: form.getAttribute('data-testid'), }); }); // Log navigation window.addEventListener('popstate', (event) => { Logger.info('Navigation (back/forward)', { url: window.location.pathname, state: event.state, }); }); ``` ### Pattern 4: JavaScript Error Logging Catch and log JavaScript errors: ```javascript /* * Global Error Handler * Catch unhandled JavaScript errors / window.addEventListener('error', (event) => { Logger.error('JavaScript error', { message: event.message, filename: event.filename, line: event.lineno, column: event.colno, error: event.error?.toString(), stack: event.error?.stack, }); }); // Catch unhandled promise rejections window.addEventListener('unhandledrejection', (event) => { Logger.error('Unhandled promise rejection', { reason: event.reason?.toString(), promise: event.promise, }); }); ``` ### Pattern 5: Django Backend Endpoint Create view to receive frontend logs: File: `{app_name}/views/logging_views.py` ```python import logging import json from django.http import JsonResponse from django.views.decorators.http import require_POST from django.views.decorators.csrf import csrf_exempt # GUI logger (writes to logs/gui.log) gui_logger = logging.getLogger('gui') @require_POST def log_gui_event(request): """ Receive frontend log events and write to gui.log Expected JSON payload: { "level": "INFO", "timestamp": "2026-04-08T10:30:00.000Z", "message": "Button clicked", "context": {"button_id": "save-btn"}, "url": "/playbooks/create/", "user_agent": "Mozilla/5.0..." } """ try: data = json.loads(request.body) level = data.get('level', 'INFO').upper() message = data.get('message', '') context = data.get('context', {}) url = data.get('url', '') user_agent = data.get('user_agent', '') # Get user info user_id = request.user.id if request.user.is_authenticated else 'anonymous' # Format log message log_message = ( f"[GUI] {message} \| " f"url={url} \| " f"user_id={user_id} \| " f"context={json.dumps(context)} \| " f"user_agent={user_agent[:50]}" # Truncate user agent ) # Log at appropriate level if level == 'DEBUG': gui_logger.debug(log_message) elif level == 'INFO': gui_logger.info(log_message) elif level == 'WARN': gui_logger.warning(log_message) elif level == 'ERROR': gui_logger.error(log_message) else: gui_logger.info(log_message) return JsonResponse({'status': 'logged'}) except json.JSONDecodeError as e: logging.error(f"Failed to parse GUI log JSON: {e}") return JsonResponse({'status': 'error', 'message': 'Invalid JSON'}, status=400) except Exception as e: logging.error(f"Failed to log GUI event: {e}", exc_info=True) return JsonResponse({'status': 'error', 'message': str(e)}, status=500) ``` Add URL route* in `{app_name}/urls.py`: ```python from django.urls import path from .views import logging_views urlpatterns = [ # ... other URLs ... path('api/log/gui/', logging_views.log_gui_event, name='log_gui_event'), ] ``` ### Pattern 6: Include Logger in Base Template Add to `templates/base.html`: ```html <!DOCTYPE html> <html lang="en"> <head> <!-- ... other head content ... --> <!-- Logger (load early) --> <script src="{% static 'js/logger.js' %}"></script> </head> <body> <!-- ... body content ... --> <!-- HTMX --> <script src="https://unpkg.com/htmx.org@1.9.10"></script> <!-- Initialize logging after HTMX loads --> <script> // Log page load Logger.info('Page loaded', { url: window.location.pathname, referrer: document.referrer, }); </script> </body> </html> ``` ### Pattern 7: Conditional Logging (Production vs Development) Add environment-aware logging: ```javascript const Logger = { // ... existing methods ... /** * Check if we should send logs to backend / _shouldSendToBackend() { // Don't send debug logs in production if (this._isProduction() && this.level === 'debug') { return false; } return true; }, /* * Check if running in production / _isProduction() { return window.location.hostname !== 'localhost' && window.location.hostname !== '127.0.0.1'; }, _log(level, message, context = {}) { // ... existing console logging ... // Only send to backend if appropriate if (this._shouldSendToBackend()) { this._sendToBackend(logEntry); } }, }; ``` ## Usage Examples ### Example 1: Log User Action ```javascript // In your template or JavaScript document.getElementById('save-playbook-btn').addEventListener('click', () => { Logger.info('Save playbook button clicked', { playbook_id: document.getElementById('playbook-id').value, form_valid: document.getElementById('playbook-form').checkValidity(), }); }); ``` ### Example 2: Log HTMX Form Submission ```html <form hx-post="/playbooks/create/" hx-target="#playbook-list" hx-swap="beforeend" data-testid="playbook-create-form"> <!-- Form fields --> <button type="submit" data-action="create-playbook">Create</button> </form> <script> // HTMX events are automatically logged by the event listeners // No additional code needed! </script> ``` ### Example 3: Log Custom Business Logic ```javascript function validatePlaybookName(name) { if (name.length < 3) { Logger.warn('Playbook name validation failed', { name: name, min_length: 3, actual_length: name.length, }); return false; } Logger.debug('Playbook name validated', { name: name, length: name.length, }); return true; } ``` ### Example 4: Log API Call ```javascript async function fetchPlaybooks() { Logger.info('Fetching playbooks', { endpoint: '/api/playbooks/' }); try { const response = await fetch('/api/playbooks/'); const data = await response.json(); Logger.info('Playbooks fetched successfully', { count: data.length, endpoint: '/api/playbooks/', }); return data; } catch (error) { Logger.error('Failed to fetch playbooks', { endpoint: '/api/playbooks/', error: error.message, }); throw error; } } ``` ## Testing Frontend Logging ### Manual Testing 1. Open browser console 2. Perform actions (click buttons, submit forms) 3. Verify console shows log messages 4. Check `logs/gui.log` for persisted entries ### Automated Testing (Playwright) ```python # tests/e2e/test_frontend_logging.py import pytest from playwright.sync_api import Page def test_button_click_logs(page: Page): """Verify button clicks are logged.""" # Set up console listener console_messages = [] page.on('console', lambda msg: console_messages.append(msg.text)) # Navigate and click button page.goto('/playbooks/') page.click('[data-testid="create-playbook-btn"]') # Verify log message assert any('Button clicked' in msg for msg in console_messages) def test_htmx_request_logs(page: Page): """Verify HTMX requests are logged.""" console_messages = [] page.on('console', lambda msg: console_messages.append(msg.text)) # Trigger HTMX request page.goto('/playbooks/') page.fill('[name="search"]', 'test') page.wait_for_selector('[hx-trigger="input"]') # Verify HTMX log messages assert any('HTMX request started' in msg for msg in console_messages) assert any('HTMX request completed' in msg for msg in console_messages) ``` ## Performance Considerations ### Throttling Logs For high-frequency events (e.g., scroll, mousemove), throttle logging: ```javascript const Logger = { // ... existing methods ... /* * Throttled logging for high-frequency events */ _throttledLogs: new Map(), throttle(key, message, context, delay = 1000) { const now = Date.now(); const lastLog = this._throttledLogs.get(key); if (!lastLog \|\| now - lastLog > delay) { this.info(message, context); this._throttledLogs.set(key, now); } }, }; // Usage window.addEventListener('scroll', () => { Logger.throttle('scroll', 'User scrolling', { scroll_y: window.scrollY, }); }); ``` ### Batching Logs Send logs in batches to reduce HTTP requests: ```javascript const Logger = { _logQueue: [], _batchSize: 10, _flushInterval: 5000, // 5 seconds _sendToBackend(logEntry) { this._logQueue.push(logEntry); if (this._logQueue.length >= this._batchSize) { this._flushLogs(); } }, _flushLogs() { if (this._logQueue.length === 0) return; const batch = [...this._logQueue]; this._logQueue = []; fetch('/api/log/gui/batch/', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRFToken': this._getCsrfToken(), }, body: JSON.stringify({ logs: batch }), }).catch(err => console.error('Failed to send log batch:', err)); }, }; // Flush logs periodically setInterval(() => Logger._flushLogs(), Logger._flushInterval); // Flush on page unload window.addEventListener('beforeunload', () => Logger._flushLogs()); ``` ## References - HTMX Events Documentation: https://htmx.org/events/ - MDN Console API: https://developer.mozilla.org/en-US/docs/Web/API/Console - Django Logging: https://docs.djangoproject.com/en/stable/topics/logging/
K8s in EKS Deployment Patterns	CONTAINER_ORCHESTRATION	Kubernetes + AWS EKS	Junior Edda	Read the 'K8s in EKS Deployment Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: CONTAINER_ORCHESTRATION Technology stack: Kubernetes + AWS EKS # Skill: K8s in EKS — Deployment Patterns Capability Domain: CONTAINER_ORCHESTRATION Technology Stack: Kubernetes + AWS EKS ## Overview Reference patterns for deploying applications to EKS with blue/green namespaces, Helm charts, ConfigMaps, Secrets, and health checks. Covers both local (Docker Desktop K8s / minikube) and cloud (EKS) deployment. ## Reference Implementation ### Pattern 1: Blue/Green Namespace Setup ```yaml # namespaces.yaml apiVersion: v1 kind: Namespace metadata: name: blue labels: environment: blue role: active # or "idle" — managed by traffic switch --- apiVersion: v1 kind: Namespace metadata: name: green labels: environment: green role: idle # or "active" ``` Convention: - `blue` and `green` are permanent namespaces - `role` label tracks which is currently `active` (prod) vs `idle` (standby) - Application is always deployed to both namespaces - Traffic switching happens at DNS level (Route53), not K8s level ### Pattern 2: Deployment Manifest ```yaml # deploy/k8s/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: {project} namespace: ${NAMESPACE} # blue or green labels: app: {project} spec: replicas: 2 selector: matchLabels: app: {project} template: metadata: labels: app: {project} spec: containers: - name: app image: ${ECR_REPO}:${IMAGE_TAG} ports: - containerPort: 8000 envFrom: - configMapRef: name: {project}-config - secretRef: name: {project}-secrets livenessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 15 periodSeconds: 10 readinessProbe: httpGet: path: /health port: 8000 initialDelaySeconds: 5 periodSeconds: 5 resources: requests: cpu: 250m memory: 256Mi limits: cpu: 500m memory: 512Mi ``` ### Pattern 3: Service Manifest ```yaml # deploy/k8s/service.yaml apiVersion: v1 kind: Service metadata: name: {project} namespace: ${NAMESPACE} spec: type: ClusterIP # or LoadBalancer for direct access selector: app: {project} ports: - port: 80 targetPort: 8000 protocol: TCP ``` ### Pattern 4: ConfigMap (per environment) ```yaml # deploy/k8s/configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: {project}-config namespace: ${NAMESPACE} data: ENVIRONMENT: ${NAMESPACE} LOG_LEVEL: "INFO" DATABASE_HOST: "${DB_HOST}" # Add application-specific config here ``` ### Pattern 5: Secrets ```yaml # deploy/k8s/secrets.yaml (template — values injected at deploy time) apiVersion: v1 kind: Secret metadata: name: {project}-secrets namespace: ${NAMESPACE} type: Opaque stringData: SECRET_KEY: "${SECRET_KEY}" DATABASE_PASSWORD: "${DB_PASSWORD}" ``` Security note: Never commit actual secret values. Use: - `kubectl create secret` at deploy time, or - AWS Secrets Manager + External Secrets Operator, or - Sealed Secrets ### Pattern 6: Helm Chart Structure ``` deploy/helm/{project}/ ├── Chart.yaml ├── values.yaml ← defaults ├── values-local.yaml ← local Docker Desktop / minikube overrides ├── values-blue.yaml ← blue namespace overrides ├── values-green.yaml ← green namespace overrides └── templates/ ├── deployment.yaml ├── service.yaml ├── configmap.yaml ├── secret.yaml ├── ingress.yaml ← (optional) ALB Ingress Controller └── _helpers.tpl ``` ### Pattern 7: Helm Values (per environment) ```yaml # values.yaml (defaults) replicaCount: 2 image: repository: "{account}.dkr.ecr.{region}.amazonaws.com/{project}" tag: "latest" pullPolicy: IfNotPresent service: type: ClusterIP port: 80 targetPort: 8000 resources: requests: cpu: 250m memory: 256Mi limits: cpu: 500m memory: 512Mi config: LOG_LEVEL: "INFO" ``` ```yaml # values-local.yaml replicaCount: 1 image: repository: "{project}" tag: "local" pullPolicy: Never # Use local image resources: requests: cpu: 100m memory: 128Mi limits: cpu: 250m memory: 256Mi ``` ```yaml # values-blue.yaml namespace: blue config: ENVIRONMENT: "blue" ``` ```yaml # values-green.yaml namespace: green config: ENVIRONMENT: "green" ``` ### Pattern 8: Helm Deploy Commands (Make Targets) ```makefile # In app monorepo Makefile HELM_CHART := deploy/helm/{project} ENV ?= local NAMESPACE ?= $(ENV) deploy: ## Deploy to environment (ENV=local\|blue\|green) helm upgrade --install {project} $(HELM_CHART) \ -f $(HELM_CHART)/values.yaml \ -f $(HELM_CHART)/values-$(ENV).yaml \ --set image.tag=$(shell git rev-parse --short HEAD) \ --namespace $(NAMESPACE) \ --create-namespace \ --wait --timeout 300s deploy-local: ## Deploy to local K8s (Docker Desktop / minikube) $(MAKE) deploy ENV=local deploy-blue: ## Deploy to blue namespace $(MAKE) deploy ENV=blue deploy-green: ## Deploy to green namespace $(MAKE) deploy ENV=green ``` ### Pattern 9: kubectl Cheat Sheet ```bash # Context management aws eks update-kubeconfig --name {cluster} --region {region} kubectl config current-context kubectl config use-context {context} # Namespace operations kubectl get ns kubectl get all -n blue kubectl get all -n green # Pod debugging kubectl get pods -n blue -o wide kubectl logs -n blue {pod-name} --tail=50 -f kubectl exec -it -n blue {pod-name} -- /bin/sh kubectl describe pod -n blue {pod-name} # Deployment management kubectl rollout status deployment/{project} -n blue kubectl rollout undo deployment/{project} -n blue kubectl scale deployment/{project} -n blue --replicas=3 # Quick health check kubectl get pods -n blue -o jsonpath='{range .items[]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}' ``` ### Pattern 10: Local K8s Development ```bash # Docker Desktop K8s # Enable in Docker Desktop → Settings → Kubernetes → Enable Kubernetes # Or minikube minikube start --cpus 2 --memory 4096 # Build and load local image (no ECR needed) docker build -t {project}:local . # For minikube: minikube image load {project}:local # Deploy locally make deploy-local # Port forward for local testing kubectl port-forward -n local svc/{project} 8080:80 # Access at http://localhost:8080 ``` ## Common Pitfalls 1. Image pull errors* — Ensure ECR auth is configured; for local, use `imagePullPolicy: Never` 2. Resource limits — Set them; K8s will OOM-kill pods without limits 3. Health checks — Without them, K8s can't detect unhealthy pods 4. Namespace isolation — Blue and green should never share resources 5. Secret management — Never commit secrets; use external secret managers in production 6. Helm `--wait` — Always use in CI/CD to fail fast if deployment doesn't become ready
Lessons Learned Writing	LESSONS_LEARNED	Markdown + GitHub CLI	Junior Edda	Read the 'Lessons Learned Writing' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: LESSONS_LEARNED Technology stack: Markdown + GitHub CLI # Skill: Lessons Learned Writing Capability Domain: LESSONS_LEARNED Technology Stack: Markdown + GitHub CLI ## Overview Patterns for computing iteration metrics from GitHub data, writing the `docs/lessons_learned/ITER-.md` retrospective file, and identifying PIP candidates. The `<!-- LEARNING -->` YAML block is the machine-readable portion that PIT-01 parses for orient briefing. ## Reference Implementation ### Pattern 1: Compute Metrics from GitHub Data ```python import subprocess, json, re from datetime import datetime def compute_iteration_metrics(milestone_number: int) -> dict: """ Compute iteration metrics from closed GitHub milestone issues and comments. :param milestone_number: GitHub milestone number. Example: 15 :return: Metrics dict. Example: {velocity_ratio: 0.75, dominant_drift_cause: 'checkpoint_fail', ...} """ # Get all issues for milestone issues = json.loads(subprocess.check_output([ 'gh', 'issue', 'list', '--milestone', str(milestone_number), '--state', 'all', '--json', 'number,title,labels,closedAt,body,comments' ])) scenarios_planned = len(issues) scenarios_completed = 0 scenarios_abandoned = 0 drift_causes = [] footprint_violations = [] # files outside declared footprint method_explosion_events = [] sao_violation_events = [] rework_events = 0 for issue in issues: labels = [l['name'] for l in issue['labels']] if 'status-done' in labels: scenarios_completed += 1 elif issue.get('closedAt'): # closed but not status-done = dropped scenarios_abandoned += 1 # Parse comments for drift signal data for comment in issue.get('comments', []): body = comment.get('body', '') # Extract drift signal type from absorbed/escalated comments drift_match = re.search(r'type: (\S+)', body) if ('<!-- DRIFT absorbed -->' in body or '<!-- ESCALATE -->' in body) and drift_match: signal = drift_match.group(1) drift_causes.append(signal) if signal == 'footprint_violation': file_match = re.search(r'evidence: (.+)', body) if file_match: footprint_violations.append(file_match.group(1).strip()) elif signal == 'method_explosion': method_match = re.search(r'evidence: (.+)', body) if method_match: method_explosion_events.append(method_match.group(1).strip()) elif signal == 'sao_violation': sao_match = re.search(r'evidence: (.+)', body) if sao_match: sao_violation_events.append(sao_match.group(1).strip()) # Count rework events (checkpoint_fail absorbed + retried) if 'checkpoint_fail_retry' in body: rework_events += 1 velocity_ratio = scenarios_completed / scenarios_planned if scenarios_planned > 0 else 0 dominant_drift_cause = max(set(drift_causes), key=drift_causes.count) if drift_causes else 'none' footprint_accuracy = (scenarios_completed - len(footprint_violations)) / scenarios_completed if scenarios_completed > 0 else 1.0 return { 'scenarios_planned': scenarios_planned, 'scenarios_completed': scenarios_completed, 'scenarios_abandoned': scenarios_abandoned, 'velocity_ratio': round(velocity_ratio, 2), 'dominant_drift_cause': dominant_drift_cause, 'footprint_violations': footprint_violations, 'footprint_accuracy': round(max(footprint_accuracy, 0.0), 2), 'method_explosion_events': method_explosion_events, 'sao_violation_events': sao_violation_events, 'rework_events': rework_events, } ``` ### Pattern 2: Write Lessons Learned File ```python def write_lessons_learned(milestone_number: int, goal: str, metrics: dict, narrative: str, drift_events: list, pip_candidates: list) -> str: """ Write the lessons learned markdown file for an iteration. :param milestone_number: GitHub milestone number. Example: 15 :param goal: Iteration goal sentence. Example: "Ship workflow export+import via MCP" :param metrics: Computed metrics dict from compute_iteration_metrics(). Example: {velocity_ratio: 0.75, ...} :param narrative: Human-readable description of what happened. Example: "S1 completed cleanly, S2 had a footprint violation..." :param drift_events: List of drift event dicts. Example: [{type: 'checkpoint_fail', scenario: 'S1', resolved: True}] :param pip_candidates: List of PIP proposals. Example: ["Add MCP smoke check to PIT-02"] :return: Path to written file. Example: "docs/lessons_learned/ITER-20260413-1800-workflow-export.md" """ from pathlib import Path from datetime import datetime slug = goal.lower().replace(' ', '-')[:40].rstrip('-') timestamp = datetime.utcnow().strftime('%Y%m%d-%H%M') filename = f"ITER-{timestamp}-{slug}.md" filepath = Path('docs/lessons_learned') / filename filepath.parent.mkdir(exist_ok=True) content = f"""<!-- LEARNING --> milestone: {milestone_number} goal: "{goal}" velocity_ratio: {metrics['velocity_ratio']} scenarios_planned: {metrics['scenarios_planned']} scenarios_completed: {metrics['scenarios_completed']} scenarios_abandoned: {metrics['scenarios_abandoned']} dominant_drift_cause: {metrics['dominant_drift_cause']} footprint_accuracy: {metrics['footprint_accuracy']} footprint_violations: {chr(10).join(f' - {f}' for f in metrics['footprint_violations']) or ' []'} method_explosion_events: {len(metrics['method_explosion_events'])} sao_violation_events: {len(metrics['sao_violation_events'])} rework_events: {metrics['rework_events']} <!-- /LEARNING --> ## What Happened {narrative} ## Drift Events {chr(10).join(f'- {e["type"]}* on {e["scenario"]}: {e.get("resolution", "see issue")}' for e in drift_events) or 'No drift events.'} ## Footprint Accuracy Accuracy: {metrics['footprint_accuracy']:.0%} {f'Footprint violations in: {metrics["footprint_violations"]}' if metrics['footprint_violations'] else 'All files within declared footprint.'} ## SAO & Method Health - Method explosion events: {len(metrics['method_explosion_events'])} - SAO violation events: {len(metrics['sao_violation_events'])} ## What to Change {chr(10).join(f'- [ ] PIP: {p}' for p in pip_candidates) or '- [ ] No PIP candidates identified.'} ## Raw Metrics \| Metric \| Value \| \|---\|---\| \| Velocity ratio \| {metrics['velocity_ratio']:.0%} \| \| Rework events \| {metrics['rework_events']} \| \| Footprint accuracy \| {metrics['footprint_accuracy']:.0%} \| \| Method explosion events \| {len(metrics['method_explosion_events'])} \| \| SAO violation events \| {len(metrics['sao_violation_events'])} \| """ filepath.write_text(content) return str(filepath) ``` ### Pattern 3: Identify PIP Candidates Common PIP trigger patterns from lessons learned data: \| Pattern \| PIP Candidate \| \|---\|---\| \| `dominant_drift_cause == checkpoint_fail` for 2+ iterations \| Add pre-scenario test smoke check to PIT-02 Contract \| \| `footprint_accuracy < 0.7` for 2+ iterations \| Improve footprint estimation in PIT-02 (use AST analysis on skeleton) \| \| Same file in `footprint_violations` 2+ times \| Split that file by domain in architecture \| \| `velocity_ratio < 0.7` for 2+ iterations \| Reduce default scenario scope in PIT-02 Contract \| \| `rework_events > 1` per iteration \| Add test-compile check before checkpoint in MIT-02 \| \| `method_explosion_events > 0` for 2+ iterations \| Add method-size guard to code review checklist \| \| `sao_violation_events > 0` for 2+ iterations \| Improve SAO section tagging in BPE-01 Plan Feature \| ## File Naming Convention ``` docs/lessons_learned/ITER-YYYYMMDD-HHmm-goal-slug.md Examples: ITER-20260413-1800-ship-workflow-export-import.md ITER-20260414-0900-add-agent-crud-web-ui.md ``` ## Quality Gates - [ ] `<!-- LEARNING -->` block is valid YAML (parseable by PyYAML) - [ ] `velocity_ratio`, `dominant_drift_cause`, `footprint_accuracy` all computed - [ ] `footprint_violations` list is accurate (from footprint_violation drift events) - [ ] `method_explosion_events` and `sao_violation_events` counts are present - [ ] `## What to Change` section has at least one PIP candidate or explicit "No PIP candidates" - [ ] File committed to `docs/lessons_learned/` before closing milestone
Playwright Semantic Naming for UI Testing	UI_TESTING	Playwright+HTML	Junior Edda	Read the 'Playwright Semantic Naming for UI Testing' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: UI_TESTING Technology stack: Playwright+HTML # Skill: Playwright Semantic Naming for UI Testing Capability Domain: UI_TESTING Technology Stack: Playwright+HTML ## Overview Comprehensive rules for naming HTML and UI components to ensure reliable Playwright E2E testing. Emphasizes `data-testid` attributes, accessibility, and semantic naming patterns. ## Reference Implementation ### Pattern 1: Playwright Selector Hierarchy (MANDATORY ORDER) Always use selectors in this exact priority order: 1. `get_by_test_id(...)` - Primary choice for all components 2. `get_by_role(name=...)` - Secondary for semantic elements with aria-labels 3. `get_by_label(...)` - For form inputs with labels 4. `get_by_text(...)` - Only for static, stable content 5. NEVER use CSS selectors, XPath, or `locator()` with CSS ### Pattern 2: Hierarchical data-testid Naming ```html <!-- Page-Level Containers --> <div data-testid="playbooks-page"> <div data-testid="playbook-form-dialog"> <div data-testid="playbook-details-modal"> <!-- Feature Components --> <div data-testid="playbook-card"> <div data-testid="playbook-list"> <div data-testid="playbook-filters"> <!-- Action Elements --> <button data-testid="create-playbook-button"> <button data-testid="save-playbook-button"> <button data-testid="edit-playbook-button"> <button data-testid="delete-playbook-button"> <!-- Form Elements --> <input data-testid="playbook-name-input"> <textarea data-testid="playbook-description-input"> <select data-testid="playbook-category-select"> <!-- Status/Feedback --> <div data-testid="success-message"> <div data-testid="error-message"> <div data-testid="loading-spinner"> ``` ### Pattern 3: Mandatory Accessibility Attributes Every interactive element MUST have proper accessibility: ```html <!-- Buttons - MUST have aria-label or descriptive text --> <button aria-label="Create new playbook" data-testid="create-playbook-button"> <i class="fa-solid fa-plus"></i> </button> <!-- Form inputs - MUST have associated labels --> <label for="playbook-name">Playbook Name </label> <input id="playbook-name" data-testid="playbook-name-input" aria-describedby="name-error" required /> <div id="name-error" data-testid="playbook-name-error" role="alert"> {nameError} </div> <!-- Dialogs - MUST have unique accessible names --> <dialog aria-label="Create Playbook Dialog" data-testid="playbook-form-dialog"> <h2>Create New Playbook</h2> </dialog> ``` ### Pattern 4: Component State Visibility Make component states testable via data attributes: ```html <!-- Loading states --> <div data-testid="playbook-list" data-state="loading" data-count="0"> </div> <!-- Form validation states --> <input data-testid="playbook-name-input" data-valid="false" aria-invalid="true" /> <!-- Button states --> <button data-testid="save-playbook-button" data-state="submitting" disabled> Saving... </button> ``` ### Pattern 5: List and Card Components Ensure predictable structure for list items: ```html <!-- List container --> <div data-testid="playbook-list" role="list"> <div data-testid="playbook-card" data-playbook-id="1" data-playbook-status="draft" role="article" aria-label="Playbook: React Development"> <h3 data-testid="playbook-card-title">React Development</h3> <p data-testid="playbook-card-status">Draft</p> <div data-testid="playbook-card-actions"> <button data-testid="edit-playbook-button" aria-label="Edit React Development"> Edit </button> </div> </div> </div> ``` ### Pattern 6: Form Components Structure forms for reliable testing: ```html <form role="form" aria-label="Playbook creation form" data-testid="playbook-form"> <fieldset data-testid="playbook-basic-fields"> <legend>Basic Information</legend> <div data-testid="playbook-name-field"> <label for="playbook-name">Name </label> <input id="playbook-name" data-testid="playbook-name-input" required aria-describedby="name-error" /> <div id="name-error" data-testid="playbook-name-error" role="alert"> {nameError} </div> </div> </fieldset> <div data-testid="playbook-form-actions"> <button type="button" data-testid="cancel-playbook-button"> Cancel </button> <button type="submit" data-testid="save-playbook-button"> Save </button> </div> </form> ``` ## Common Pitfalls ### ❌ Don't: Generic names ```html <div id="main" class="container"> <button class="btn btn-primary"> ``` ### ✅ Do: Semantic, descriptive names ```html <main data-testid="playbooks-page" role="main"> <button data-testid="create-playbook-button" aria-label="Create new playbook"> ``` ### ❌ Don't: Use CSS selectors in tests ```python page.locator('.btn-primary').click() page.locator('div:nth-child(2)').click() ``` ### ✅ Do: Use data-testid selectors ```python page.get_by_test_id("create-playbook-button").click() page.get_by_test_id("playbook-card").filter(has_text="React").click() ``` ### ❌ Don't: Missing accessibility ```html <button><i class="fa-plus"></i></button> <!-- No aria-label --> <input /> <!-- No label --> ``` ### ✅ Do: Proper accessibility ```html <button aria-label="Create new playbook"> <i class="fa-plus"></i> </button> <label for="name">Name</label> <input id="name" /> ``` ## Quality Gates Before committing any component, verify: - [ ] All interactive elements have `aria-label` or descriptive text - [ ] All form inputs have associated `<label>` elements - [ ] All dialogs have unique accessible names - [ ] All components have appropriate `data-testid` attributes - [ ] Component states are visible via data attributes - [ ] List items have predictable structure and identifiers - [ ] Form validation errors are accessible and testable - [ ] No CSS animations interfere with testing - [ ] Naming follows hierarchical pattern (domain-component-element-type) ## Naming Convention Format: `{domain}-{component}-{element}-{type}` Examples: - `playbook-list` (component) - `playbook-card-title` (element in component) - `create-playbook-button` (action) - `playbook-name-input` (form field) - `playbook-form-dialog` (modal) ## Testing Validation Checklist - [ ] All buttons have icons and tooltips - [ ] All forms have proper labels - [ ] All errors have role="alert" - [ ] All modals have aria-label - [ ] All lists have role="list" - [ ] All cards have role="article" - [ ] All interactive elements are keyboard accessible - [ ] All state changes are visible via data attributes
pytest Continuous Testing	TEST_FRAMEWORK	pytest+Python	Junior Edda	Read the 'pytest Continuous Testing' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: TEST_FRAMEWORK Technology stack: pytest+Python # Skill: pytest Continuous Testing Capability Domain: TEST_FRAMEWORK Technology Stack: pytest+Python ## Overview Patterns for continuous testing with pytest, including automated test running, log monitoring, error detection, and automatic fixing. Ensures tests run continuously during development with real-time feedback. ## Reference Implementation ### Pattern 1: pytest Configuration ```ini # pytest.ini [pytest] DJANGO_SETTINGS_MODULE = mimir.settings python_files = test_.py python_classes = Test python_functions = test_* testpaths = tests addopts = -v --strict-markers --tb=short --disable-warnings -p no:warnings --log-cli-level=INFO --log-file=tests.log --log-file-level=INFO --log-file-format=%(asctime)s [%(levelname)s] %(message)s --log-file-date-format=%Y-%m-%d %H:%M:%S markers = unit: Unit tests integration: Integration tests e2e: End-to-end tests slow: Slow running tests ``` ### Pattern 2: Continuous Test Runner Script ```python # continuous_test_runner.py import time import subprocess import sys from pathlib import Path from watchdog.observers import Observer from watchdog.events import FileSystemEventHandler class TestRunner(FileSystemEventHandler): """Watch for file changes and run affected tests.""" def __init__(self): self.last_run = 0 self.debounce_seconds = 2 def on_modified(self, event): """Run tests when Python files change.""" if event.is_directory: return if not event.src_path.endswith('.py'): return # Debounce rapid changes current_time = time.time() if current_time - self.last_run < self.debounce_seconds: return self.last_run = current_time # Determine which tests to run file_path = Path(event.src_path) if 'tests/' in str(file_path): # Test file changed - run that test test_file = file_path else: # Source file changed - run related tests test_file = self.find_related_test(file_path) if test_file and test_file.exists(): self.run_tests(test_file) else: # Run all tests if can't determine specific test self.run_tests() def find_related_test(self, source_file: Path) -> Path: """Find test file for source file.""" # Example: methodology/services/playbook_service.py # -> tests/unit/test_playbook_service.py parts = source_file.parts if 'services' in parts: test_name = f"test_{source_file.stem}.py" return Path('tests/unit') / test_name elif 'views' in parts: test_name = f"test_{source_file.stem}.py" return Path('tests/integration') / test_name return None def run_tests(self, test_file: Path = None): """Run pytest with specified test file.""" cmd = ['pytest'] if test_file: cmd.append(str(test_file)) print(f"\n{'='60}") print(f"Running tests: {test_file}") print('='60) else: cmd.append('tests/') print(f"\n{'='60}") print("Running all tests") print('='60) cmd.extend(['-v', '--tb=short']) result = subprocess.run(cmd, capture_output=True, text=True) # Print output print(result.stdout) if result.stderr: print(result.stderr) # Parse for errors if result.returncode != 0: print(f"\n❌ Tests FAILED") self.analyze_failures(result.stdout) else: print(f"\n✅ All tests PASSED") def analyze_failures(self, output: str): """Analyze test failures and suggest fixes.""" if 'FAILED' in output: print("\nFailed tests detected. Check tests.log for details.") if 'ImportError' in output: print("⚠️ Import errors detected - check dependencies") if 'AssertionError' in output: print("⚠️ Assertion failures - check test expectations") def main(): """Start continuous test runner.""" print("Starting continuous test runner...") print("Watching for changes in Python files...") print("Press Ctrl+C to stop\n") # Initial test run runner = TestRunner() runner.run_tests() # Watch for changes observer = Observer() observer.schedule(runner, path='.', recursive=True) observer.start() try: while True: time.sleep(1) except KeyboardInterrupt: observer.stop() print("\nStopping continuous test runner...") observer.join() if __name__ == '__main__': main() ``` ### Pattern 3: Running Tests ```bash # Run all tests pytest tests/ # Run specific test file pytest tests/unit/test_playbook_service.py # Run specific test class pytest tests/unit/test_playbook_service.py::TestPlaybookService # Run specific test method pytest tests/unit/test_playbook_service.py::TestPlaybookService::test_create_playbook # Run with coverage pytest tests/ --cov=methodology --cov-report=html # Run only unit tests pytest tests/unit/ -v # Run only integration tests pytest tests/integration/ -v # Run with markers pytest -m unit pytest -m "not slow" ``` ### Pattern 4: Test Log Monitoring ```python # monitor_tests.py import time from pathlib import Path def monitor_test_log(): """Monitor tests.log for errors and auto-fix.""" log_file = Path('tests.log') if not log_file.exists(): print("tests.log not found. Run tests first.") return print("Monitoring tests.log for errors...") with open(log_file, 'r') as f: # Read existing content f.seek(0, 2) # Go to end while True: line = f.readline() if not line: time.sleep(0.1) continue # Parse for errors if 'FAILED' in line: print(f"❌ Test failure: {line.strip()}") elif 'ERROR' in line: print(f"⚠️ Error: {line.strip()}") elif 'PASSED' in line: print(f"✅ Test passed: {line.strip()}") if __name__ == '__main__': monitor_test_log() ``` ## Common Pitfalls ### ❌ Don't: Run tests manually every time ```bash # Wrong - manual testing pytest tests/ # ... make changes ... pytest tests/ # ... make changes ... pytest tests/ ``` ### ✅ Do: Use continuous test runner ```bash # Correct - automated testing python continuous_test_runner.py # Tests run automatically on file changes ``` ### ❌ Don't: Ignore failing tests ```bash # Wrong - continuing with failures pytest tests/ # 23/25 passed # Continue development anyway ``` ### ✅ Do: Fix tests immediately ```bash # Correct - fix before continuing pytest tests/ # 23/25 passed # Fix the 2 failing tests pytest tests/ # 25/25 passed ✅ # Now continue development ``` ### ❌ Don't: Skip test logs ```bash # Wrong - no logging pytest tests/ ``` ### ✅ Do: Always log test output ```bash # Correct - with logging pytest tests/ --log-file=tests.log --log-file-level=INFO ``` ## Quality Gates Before declaring testing setup complete: - [ ] pytest.ini configured with proper settings - [ ] tests.log configured and rotating - [ ] Continuous test runner script created - [ ] File watcher monitoring source and test files - [ ] Tests run automatically on file changes - [ ] Test failures immediately visible - [ ] Log monitoring active - [ ] Coverage reporting configured - [ ] Test markers defined (unit, integration, e2e) - [ ] All tests passing (100% pass rate) ## Requirements ```txt # requirements.txt (testing dependencies) pytest>=8.0.0 pytest-django>=4.5.0 pytest-cov>=4.1.0 pytest-asyncio>=0.21.0 watchdog>=3.0.0 # For file watching ``` ## Continuous Testing Workflow 1. Start continuous runner: `python continuous_test_runner.py` 2. Make code changes: Edit source files 3. Tests run automatically: Related tests execute 4. Check output: Green (pass) or red (fail) 5. Fix failures immediately: Don't continue with failing tests 6. Monitor tests.log: Check for patterns and issues 7. Commit when green: Only commit when all tests pass ## Test Organization ``` tests/ ├── unit/ # Fast, isolated tests │ ├── test_playbook_service.py │ ├── test_workflow_service.py │ └── test_activity_service.py ├── integration/ # Real dependencies, no mocking │ ├── test_playbook_views.py │ ├── test_workflow_crud.py │ └── test_activity_dependencies.py ├── e2e/ # Full user journeys │ ├── test_playbook_creation_journey.py │ └── test_workflow_execution_journey.py ├── conftest.py # Shared fixtures └── __init__.py ``` ## Key Principles 1. Fast: Unit tests run in <1s, integration in <5s 2. Comprehensive: Cover all scenarios from feature files 3. No Mocking: Integration tests use real dependencies 4. Clear: One test per scenario, clear docstrings 5. Reliable: No flaky tests, deterministic results 6. Continuous: Tests run automatically on changes 7. Immediate Fixes: Failing tests fixed before continuing
pytest Fixture Management for E2E Tests	TEST_DATA	pytest+Django	Junior Edda	Read the 'pytest Fixture Management for E2E Tests' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: TEST_DATA Technology stack: pytest+Django # Skill: pytest Fixture Management for E2E Tests Capability Domain: TEST_DATA Technology Stack: pytest+Django ## Overview Patterns for managing test data and fixtures in E2E tests, including fixture files, data seeding, and test isolation strategies. ## Reference Implementation ### Pattern 1: JSON Fixture Files ```json // tests/fixtures/e2e_seed.json [ { "model": "auth.user", "pk": 1, "fields": { "username": "admin", "email": "admin@example.com", "is_staff": true, "is_superuser": true } }, { "model": "methodology.playbook", "pk": 1, "fields": { "name": "FeatureFactory", "description": "Complete feature development methodology", "category": "development", "version": "3.8", "status": "released", "author": 1 } }, { "model": "methodology.workflow", "pk": 1, "fields": { "name": "Build Feature", "description": "Complete workflow for building features", "playbook": 1, "order": 1 } } ] ``` ### Pattern 2: Loading Fixtures in Tests ```python # tests/e2e/conftest.py import pytest from django.core.management import call_command @pytest.fixture(scope='session') def django_db_setup(django_db_setup, django_db_blocker): """Load E2E test fixtures once per session.""" with django_db_blocker.unblock(): call_command('loaddata', 'tests/fixtures/e2e_seed.json') @pytest.fixture def e2e_data(db): """Ensure E2E data is available for each test.""" # Data already loaded by django_db_setup # This fixture just ensures db is available pass ``` ### Pattern 3: Factory-Based Fixtures ```python # tests/conftest.py import pytest from django.contrib.auth.models import User from methodology.models import Playbook, Workflow, Activity @pytest.fixture def user_factory(db): """Factory for creating test users.""" def create_user(username='testuser', kwargs): defaults = { 'email': f'{username}@example.com', 'is_active': True } defaults.update(kwargs) return User.objects.create_user(username=username, defaults) return create_user @pytest.fixture def playbook_factory(db, user_factory): """Factory for creating test playbooks.""" def create_playbook(name='Test Playbook', author=None, kwargs): if author is None: author = user_factory() defaults = { 'description': 'Test description', 'category': 'test', 'version': '0.1', 'status': 'draft' } defaults.update(kwargs) return Playbook.objects.create( name=name, author=author, defaults ) return create_playbook @pytest.fixture def workflow_factory(db, playbook_factory): """Factory for creating test workflows.""" def create_workflow(name='Test Workflow', playbook=None, kwargs): if playbook is None: playbook = playbook_factory() defaults = { 'description': 'Test workflow', 'order': 1 } defaults.update(kwargs) return Workflow.objects.create( name=name, playbook=playbook, defaults ) return create_workflow ``` ### Pattern 4: Using Factories in Tests ```python # tests/integration/test_playbook_crud.py import pytest @pytest.mark.django_db class TestPlaybookCRUD: """Test playbook CRUD operations.""" def test_create_playbook(self, user_factory, playbook_factory): """Test creating a playbook.""" user = user_factory(username='maria') playbook = playbook_factory( name='React Development', author=user, category='development' ) assert playbook.id is not None assert playbook.name == 'React Development' assert playbook.author == user def test_list_user_playbooks(self, user_factory, playbook_factory): """Test listing playbooks for a user.""" user1 = user_factory(username='maria') user2 = user_factory(username='john') playbook1 = playbook_factory(name='P1', author=user1) playbook2 = playbook_factory(name='P2', author=user1) playbook3 = playbook_factory(name='P3', author=user2) user1_playbooks = Playbook.objects.filter(author=user1) assert user1_playbooks.count() == 2 assert playbook1 in user1_playbooks assert playbook2 in user1_playbooks assert playbook3 not in user1_playbooks ``` ### Pattern 5: Test Isolation with Transaction Rollback ```python # tests/conftest.py import pytest @pytest.fixture(autouse=True) def enable_db_access_for_all_tests(db): """Enable database access for all tests automatically.""" pass # Each test runs in a transaction that's rolled back # No need for manual cleanup ``` ### Pattern 6: Management Command for Seeding ```python # methodology/management/commands/seed_test_data.py from django.core.management.base import BaseCommand from django.contrib.auth.models import User from methodology.models import Playbook, Workflow, Activity class Command(BaseCommand): help = 'Seed database with test data for E2E tests' def handle(self, args, options): """Create test data.""" self.stdout.write('Seeding test data...') # Create test user user, created = User.objects.get_or_create( username='admin', defaults={ 'email': 'admin@example.com', 'is_staff': True, 'is_superuser': True } ) if created: user.set_password('admin123') user.save() self.stdout.write(f'Created user: {user.username}') # Create test playbook playbook, created = Playbook.objects.get_or_create( name='FeatureFactory', author=user, defaults={ 'description': 'Complete feature development methodology', 'category': 'development', 'version': '3.8', 'status': 'released' } ) if created: self.stdout.write(f'Created playbook: {playbook.name}') # Create test workflow workflow, created = Workflow.objects.get_or_create( name='Build Feature', playbook=playbook, defaults={ 'description': 'Complete workflow for building features', 'order': 1 } ) if created: self.stdout.write(f'Created workflow: {workflow.name}') self.stdout.write(self.style.SUCCESS('Test data seeded successfully')) ``` ## Common Pitfalls ### ❌ Don't: Create fixtures manually in each test ```python # Wrong - repetitive setup def test_playbook_create(): user = User.objects.create_user(username='test') playbook = Playbook.objects.create(name='Test', author=user) # ... test logic ... def test_playbook_update(): user = User.objects.create_user(username='test') # Duplicate playbook = Playbook.objects.create(name='Test', author=user) # Duplicate # ... test logic ... ``` ### ✅ Do: Use factory fixtures ```python # Correct - reusable factories def test_playbook_create(user_factory, playbook_factory): user = user_factory() playbook = playbook_factory(author=user) # ... test logic ... def test_playbook_update(user_factory, playbook_factory): user = user_factory() playbook = playbook_factory(author=user) # ... test logic ... ``` ### ❌ Don't: Share mutable data between tests ```python # Wrong - shared state TEST_USER = User.objects.create_user(username='test') def test_1(): TEST_USER.email = 'new@example.com' # Mutates shared state TEST_USER.save() def test_2(): assert TEST_USER.email == 'test@example.com' # Fails! ``` ### ✅ Do: Create fresh data per test ```python # Correct - isolated data @pytest.fixture def test_user(db): return User.objects.create_user(username='test') def test_1(test_user): test_user.email = 'new@example.com' test_user.save() # Changes rolled back after test def test_2(test_user): assert test_user.email == 'test@example.com' # Passes! ``` ## Quality Gates - [ ] Fixture files created in `tests/fixtures/` - [ ] Factory fixtures defined in `conftest.py` - [ ] Management command for seeding test data - [ ] Test isolation via transaction rollback - [ ] No shared mutable state between tests - [ ] Fixtures scoped appropriately (function/class/session) - [ ] All tests use fixtures (no manual data creation) - [ ] Fixture data realistic and comprehensive ## Fixture Organization ``` tests/ ├── fixtures/ │ ├── e2e_seed.json # E2E test data │ ├── journey_seed.json # Journey test data │ └── playbooks_seed.json # Playbook-specific data ├── conftest.py # Shared fixtures └── e2e/ └── conftest.py # E2E-specific fixtures ``` ## Fixture Scopes - function* (default): New instance per test function - class: Shared across test class methods - module: Shared across test module - session: Created once per test session ```python @pytest.fixture(scope='function') # New per test def test_user(db): return User.objects.create_user(username='test') @pytest.fixture(scope='session') # Once per session def django_db_setup(django_db_setup, django_db_blocker): with django_db_blocker.unblock(): call_command('loaddata', 'e2e_seed.json') ``` ## Best Practices 1. Use factories for dynamic data: User factories, playbook factories 2. Use JSON fixtures for static data: Seed data, reference data 3. Scope fixtures appropriately: Function for isolation, session for performance 4. Name fixtures descriptively: `authenticated_client`, `draft_playbook` 5. Document fixture purpose: Docstrings explaining what fixture provides 6. Keep fixtures DRY: Compose fixtures from other fixtures 7. Isolate tests: Each test gets fresh data via transaction rollback
Pytest Log Story Assertions	—	—	Junior Edda	Read the 'Pytest Log Story Assertions' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. # Skill: Pytest Log Story Assertions Capability Domain: LOG_STORY_TESTING Technology Stack: pytest+caplog+Python ## Overview Prove Log Story Script rows with pytest `caplog` using a shared helper. Turns observability from “statements exist” into a failing test when the narrative regresses. ## Reference Implementation ### Pattern 1: Helper — `tests/support/log_story.py` ```python from __future__ import annotations import logging from typing import Mapping, Sequence def assert_log_story( caplog, *, where: str, beats: Mapping[str, Sequence[str]], level: str = "INFO", ) -> None: """Assert each beat has a matching log record for ``where``. :param caplog: pytest ``caplog`` fixture :param where: Class.method (or stable substring) that must appear :param beats: beat name → list of required substrings (all must appear in one record) :param level: minimum level name (INFO default) :raises AssertionError: naming the missing beat / substring """ min_level = getattr(logging, level.upper(), logging.INFO) records = [ r for r in caplog.records if r.levelno >= min_level and where in r.getMessage() ] messages = [r.getMessage() for r in records] for beat, needles in beats.items(): matched = [ msg for msg in messages if all(n in msg for n in needles) ] if not matched: raise AssertionError( f"log story missing beat={beat!r} where={where!r} " f"needles={list(needles)!r}; saw={messages!r}" ) ``` ### Pattern 2: View / integration test ```python import logging import pytest from django.urls import reverse from tests.support.log_story import assert_log_story @pytest.mark.django_db def test_login_log_story_reject(client, django_user_model, caplog): django_user_model.objects.create_user( username="elena", email="elena@example.com", password="secret" ) with caplog.at_level(logging.INFO, logger="yggdrasil.auth"): client.post( reverse("auth:login"), {"email": "elena@example.com", "password": "wrong"}, ) assert_log_story( caplog, where="LoginView.post", beats={ "entry": ["attempt", "email="], "branch": ["authentication failed"], }, ) ``` ### Pattern 3: Manifest wiring ```yaml log_tests: - {name: test_login_log_story_reject, path: path/to/test_file.py} checkpoint: log_story_command: "pytest path/to/test_file.py::test_login_log_story_reject -x" ``` ## Common Pitfalls - Asserting only status codes and skipping caplog - Matching on password / token values - Using a separate “logging slice” after behavior is green - Over-strict exact full-string match (prefer stable `must_include` fragments) ## Quality Gates - [ ] `tests/support/log_story.py` importable - [ ] Happy and reject log-story tests where both paths exist - [ ] Failure message names missing beat - [ ] Linked from BPE-02 / MIN-04 / TFK-02
pytest Runner Configuration	TEST_FRAMEWORK	pytest	Junior Edda	Read the 'pytest Runner Configuration' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: TEST_FRAMEWORK Technology stack: pytest # Skill: pytest Runner Configuration Capability Domain: TEST_FRAMEWORK Technology Stack: pytest ## Overview Configuration patterns for pytest test runner, including pytest.ini setup, command-line options, markers, and test discovery patterns. ## Reference Implementation ### Pattern 1: pytest.ini Configuration ```ini # pytest.ini [pytest] DJANGO_SETTINGS_MODULE = mimir.settings python_files = test_.py python_classes = Test python_functions = test_* testpaths = tests addopts = -v --strict-markers --tb=short --disable-warnings -p no:warnings --log-cli-level=INFO --log-file=tests.log --log-file-level=INFO --log-file-format=%(asctime)s [%(levelname)s] %(message)s --log-file-date-format=%Y-%m-%d %H:%M:%S --cov-report=term-missing --cov-report=html markers = unit: Unit tests (fast, isolated) integration: Integration tests (real dependencies) e2e: End-to-end tests (full user journeys) slow: Slow running tests django_db: Tests that require database access agent_proof: Lane 1 PRF control-plane proofs (ScriptedLLM + assert_agent_story) quality: Lane 4 TASK-* golden task eval (live LLM, not PR merge gate) live_llm: Requires live LLM provider — skip in default PR CI ``` ### Pattern 2: Running Tests ```bash # Run all tests pytest tests/ # Run with verbose output pytest tests/ -v # Run specific test file pytest tests/unit/test_playbook_service.py # Run specific test class pytest tests/unit/test_playbook_service.py::TestPlaybookService # Run specific test method pytest tests/unit/test_playbook_service.py::TestPlaybookService::test_create_playbook # Run with coverage pytest tests/ --cov=methodology --cov-report=html # Run only unit tests pytest -m unit # Run only integration tests pytest -m integration # Run agent control-plane proofs (lane 1 — when AGENTS_ENABLED) pytest -m agent_proof tests/integration/agent/ # Run TASK-* quality eval (lane 4 — nightly / manual only) pytest -m "quality and live_llm" tests/ # Run all except slow tests pytest -m "not slow" # Run with specific log level pytest tests/ --log-cli-level=DEBUG # Stop on first failure pytest tests/ -x # Run last failed tests pytest tests/ --lf # Run failed tests first, then others pytest tests/ --ff # Run tests in parallel (requires pytest-xdist) pytest tests/ -n auto ``` ### Pattern 3: Test Discovery ```python # tests/conftest.py import pytest from django.contrib.auth.models import User @pytest.fixture(scope='session') def django_db_setup(): """Configure test database.""" pass @pytest.fixture def test_user(db): """Create test user.""" return User.objects.create_user( username='testuser', password='testpass123' ) @pytest.fixture def authenticated_client(client, test_user): """Create authenticated test client.""" client.login(username='testuser', password='testpass123') return client ``` ### Pattern 4: Makefile Targets ```makefile # Makefile .PHONY: test test-unit test-integration test-e2e test-cov test-agent-proof test-agent-quality test: pytest tests/ -v test-unit: pytest tests/unit/ -v -m unit test-integration: pytest tests/integration/ -v -m integration test-e2e: pytest tests/e2e/ -v -m e2e test-agent-proof: ifeq ($(AGENTS_ENABLED),true) pytest tests/integration/agent/ -v -m agent_proof else @echo "skip: agents N/A (SAO §17)" endif test-agent-quality: ifeq ($(AGENTS_ENABLED),true) pytest tests/ -v -m quality else @echo "skip: agents N/A (SAO §17)" endif test-cov: pytest tests/ --cov=methodology --cov-report=html --cov-report=term test-watch: python continuous_test_runner.py test-failed: pytest tests/ --lf -v ``` ## Agent pytest markers (when SAO §17 applies) \| Marker \| Lane \| Default PR CI \| Requires \| \|--------\|------\|---------------\|----------\| \| `agent_proof` \| 1 \| When `AGENTS_ENABLED=true` \| CAP-004 ScriptedLLM, `tests/support/agent_story.py` \| \| `quality` \| 4 \| No — nightly / promotion \| Golden task fixtures under `tests/fixtures/agent_tasks/` \| \| `live_llm` \| 3–4 \| No \| Provider credentials or Ollama; temp=0 for eval \| CI rules: - Do not add `-m agent_proof` to default `ci.yml` until PRF tests exist (empty collection fails). - Never combine `live_llm` with PR merge gates — use separate `agent-eval.yml`. - Lane 2 deterministic shell tests use `integration` marker only — no `agent_proof`. Register all markers in `pytest.ini` with `--strict-markers` to catch typos. ## Common Pitfalls ### ❌ Don't: Run tests without configuration ```bash # Wrong - no pytest.ini pytest ``` ### ✅ Do: Use pytest.ini for consistent configuration ```ini # Correct - pytest.ini with settings [pytest] testpaths = tests addopts = -v --tb=short ``` ### ❌ Don't: Mix test discovery patterns ```python # Wrong - inconsistent naming def check_playbook(): # Won't be discovered class PlaybookTests: # Won't be discovered ``` ### ✅ Do: Follow pytest conventions ```python # Correct - pytest discovers these def test_playbook(): class TestPlaybook: ``` ### ❌ Don't: Run `@live_llm` tests in default PR CI ```bash # Wrong — flaky and credential-dependent pytest -m live_llm ``` ### ✅ Do: Gate live eval behind Makefile + optional workflow ```bash make test-agent-quality # no-op when AGENTS_ENABLED unset ``` ## Quality Gates - [ ] pytest.ini exists with proper configuration - [ ] Test discovery patterns configured - [ ] Markers defined for test categories (including `agent_proof`, `quality`, `live_llm` when SAO §17 applies) - [ ] Logging configured (file and console) - [ ] Coverage reporting configured - [ ] Makefile targets created for common operations (including `test-agent-proof` / `test-agent-quality` when agents enabled) - [ ] All tests discoverable by pytest - [ ] Tests organized in proper directory structure ## Test Organization ``` tests/ ├── unit/ # pytest -m unit ├── integration/ # pytest -m integration │ └── agent/ # pytest -m agent_proof (lane 1) ├── e2e/ # pytest -m e2e ├── fixtures/ │ ├── llm_scripts/ # CAP-004 ScriptedLLM queues per PRF-id │ └── agent_tasks/ # TASK-* golden tasks (lane 4) ├── support/ │ ├── log_story.py │ └── agent_story.py # TFK-02 bootstrap ├── conftest.py # Shared fixtures └── pytest.ini # Configuration ``` ## Recommended pytest Plugins ```txt # requirements.txt pytest>=8.0.0 pytest-django>=4.5.0 pytest-cov>=4.1.0 pytest-asyncio>=0.21.0 pytest-xdist>=3.3.0 # Parallel execution pytest-timeout>=2.1.0 # Test timeouts pytest-mock>=3.11.0 # Mocking support (unit tests only — not agent_proof) ```
Python Docstring Format with Examples	DOCSTRING_FORMAT	Python+Sphinx	Junior Edda	Read the 'Python Docstring Format with Examples' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: DOCSTRING_FORMAT Technology stack: Python+Sphinx # Skill: Python Docstring Format with Examples Capability Domain: DOCSTRING_FORMAT Technology Stack: Python+Sphinx ## Overview Comprehensive docstring format using Sphinx/ReST style with mandatory examples for all parameters and return values. This format makes code self-documenting and dramatically improves maintainability, testing, and onboarding. ## Reference Implementation ### Pattern 1: Simple Function ```python def get_workflow(workflow_id: str) -> Dict: """ Retrieve workflow by ID. :param workflow_id: workflow UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :return: Workflow data as dict. Example: {"id": "a1b2c3d4", "name": "Build Feature", "activities": 5} :raises ValueError: If workflow_id is not a valid UUID. :raises NotFoundError: If workflow does not exist. """ ``` ### Pattern 2: Multiple Parameters ```python def create_activity(name: str, role_id: int, workflow_id: str, estimated_hours: float = 2.0) -> Activity: """ Create a new activity in a workflow. :param name: activity name as str. Example: "Design Component" :param role_id: role identifier as int. Example: 3 :param workflow_id: workflow UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :param estimated_hours: estimated time as float. Example: 4.5 :return: Created activity instance. Example: Activity(id=12, name="Design Component", role=Role(3)) :raises ValueError: If name is empty or role_id is invalid. :raises NotFoundError: If workflow does not exist. """ ``` ### Pattern 3: Complex Return Types ```python def get_workflow_with_activities(workflow_id: str) -> Dict[str, Any]: """ Retrieve workflow with all related activities and metadata. :param workflow_id: workflow UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :return: Workflow data with activities as dict. Example: { "workflow": {"id": "a1b2c3d4", "name": "Build Feature"}, "activities": [{"id": 1, "name": "Design"}, {"id": 2, "name": "Implement"}], "activity_count": 2, "completion_percentage": 50.0 } :raises ValueError: If workflow_id is not a valid UUID. :raises NotFoundError: If workflow does not exist. """ ``` ### Pattern 4: List Return Type ```python def filter_activities_by_role(workflow_id: str, role_id: int) -> List[Dict]: """ Get all activities for a specific role in a workflow. :param workflow_id: workflow UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :param role_id: role identifier as int. Example: 3 :return: List of activity dictionaries. Example: [ {"id": 1, "name": "Design Component", "role_id": 3}, {"id": 5, "name": "Code Review", "role_id": 3} ] :raises ValueError: If workflow_id or role_id is invalid. """ ``` ### Pattern 5: No Parameters ```python def get_all_methodologies() -> List[str]: """ Retrieve list of all available methodology names. :return: Methodology names as list. Example: ["FDD", "Scrum", "Kanban"] """ ``` ### Pattern 6: No Return Value ```python def log_activity_event(activity_id: int, event_type: str, user_id: int) -> None: """ Log an activity event to the system log. :param activity_id: activity identifier as int. Example: 42 :param event_type: event type as str. Example: "started" :param user_id: user identifier as int. Example: 7 :return: None :raises ValueError: If activity_id or user_id does not exist. """ ``` ### Pattern 7: Class Methods ```python class MethodologyService: def __init__(self, repository: Repository): """ Initialize methodology service. :param repository: data access layer. Example: DjangoORMRepository() """ self.repository = repository def add_workflow_to_methodology(self, methodology_id: str, workflow_name: str) -> Workflow: """ Add a new workflow to an existing methodology. :param methodology_id: methodology UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :param workflow_name: workflow name as str. Example: "Build Feature" :return: Created workflow instance. Example: Workflow(id="b2c3d4e5", name="Build Feature") :raises ValueError: If workflow_name is empty. :raises NotFoundError: If methodology does not exist. """ ``` ### Pattern 8: Optional Parameters ```python def search_activities(keyword: str, role_id: Optional[int] = None) -> List[Dict]: """ Search activities by keyword and optionally filter by role. :param keyword: search term as str. Example: "design" :param role_id: optional role filter as int or None. Example: 3 or None :return: Matching activities as list. Example: [{"id": 1, "name": "Design Component"}] """ ``` ### Pattern 9: Variable Arguments ```python def create_activities_batch(names: str) -> List[Activity]: """ Create multiple activities at once. :param names: activity names as variable args. Example: "Design", "Implement", "Test" :return: Created activity instances as list. Example: [Activity(id=1), Activity(id=2), Activity(id=3)] """ ``` ### Pattern 10: Keyword Arguments ```python def update_activity(activity_id: int, updates: Any) -> Activity: """ Update activity with provided field changes. :param activity_id: activity identifier as int. Example: 42 :param updates: field updates as kwargs. Example: name="New Name", estimated_hours=5.0 :return: Updated activity instance. Example: Activity(id=42, name="New Name", estimated_hours=5.0) :raises ValueError: If activity_id does not exist. """ ``` ## Common Pitfalls ### ❌ Bad: No Examples ```python def get_workflow(workflow_id: str) -> Dict: """ Retrieve workflow by ID. :param workflow_id: workflow UUID as str :return: Workflow data as dict """ ``` ### ✅ Good: With Examples ```python def get_workflow(workflow_id: str) -> Dict: """ Retrieve workflow by ID. :param workflow_id: workflow UUID as str. Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" :return: Workflow data as dict. Example: {"id": "a1b2c3d4", "name": "Build Feature", "activities": 5} :raises ValueError: If workflow_id is not a valid UUID. """ ``` ### ❌ Bad: Vague Descriptions ```python def create_activity(name: str, role_id: int) -> Activity: """ Creates an activity. :param name: the name :param role_id: the role :return: the activity """ ``` ### ✅ Good: Descriptive with Examples ```python def create_activity(name: str, role_id: int) -> Activity: """ Create a new activity in a workflow. :param name: activity name as str. Example: "Design Component" :param role_id: role identifier as int. Example: 3 :return: Created activity instance. Example: Activity(id=12, name="Design Component") :raises ValueError: If name is empty or role_id is invalid. """ ``` ### ❌ Bad: Missing Return Example ```python def get_activities() -> List[Dict]: """ Get all activities. :return: List of activities """ ``` ### ✅ Good: Complete with Return Example ```python def get_activities() -> List[Dict]: """ Retrieve all activities in the system. :return: Activity list as list of dicts. Example: [ {"id": 1, "name": "Design", "role": "Engineer"}, {"id": 2, "name": "Test", "role": "QA"} ] """ ``` ## Quality Gates Before declaring documentation complete: - [ ] All functions have docstrings - [ ] All parameters documented with type and example - [ ] All return values documented with type and example - [ ] All exceptions documented - [ ] Examples show realistic values - [ ] Type hints match docstring descriptions - [ ] Docstrings follow Sphinx/ReST format - [ ] Class methods include `__init__` docstring - [ ] Test functions also have docstrings ## Why Examples Are Required 1. Clarity: Shows exact expected format of inputs/outputs 2. Testing: Examples guide test case creation 3. Debugging: Makes troubleshooting easier with concrete values 4. Onboarding: New developers understand usage immediately 5. Documentation: Auto-generated docs are more useful ## Required Format ```python def function_name(param1: Type1, param2: Type2) -> ReturnType: """ A brief summary of what the function does. :param param1: description as Type1. Example: value_example :param param2: description as Type2. Example: value_example :return: Description of the value returned. Example: return_value_example :raises ExceptionType: When this exception is raised. """ ``` ## Key Requirements 1. Summary Line: Brief description of function purpose 2. Blank Line: After summary 3. Parameters: Each parameter documented with: - Name - Description as Type - Example value* (REQUIRED) 4. Return: Description with Example (REQUIRED) 5. Raises: Document exceptions (if any) ## Enforcement - Code Reviews: Check all new functions have proper docstrings - IDE: Configure IDE to show docstring warnings - Tests: Test docstrings should follow same format - Pre-commit: Consider docstring linter
Python Logging Patterns	LOGGING_PATTERN	Python	Junior Edda	Read the 'Python Logging Patterns' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: LOGGING_PATTERN Technology stack: Python # Skill: Python Logging Patterns Capability Domain: LOGGING_PATTERN Technology Stack: Python ## Overview Comprehensive logging patterns for Python applications with emphasis on informative, structured logging at appropriate levels. Enables effective troubleshooting by logging who, what, why, where, and when for every significant operation. ## Reference Implementation ### Pattern 1: Application Logger Setup ```python # mimir/logging_config.py import logging import logging.handlers from pathlib import Path def setup_logging(): """Configure application logging with file rotation.""" # Create logs directory log_dir = Path('logs') log_dir.mkdir(exist_ok=True) # Configure root logger logger = logging.getLogger() logger.setLevel(logging.INFO) # File handler with rotation file_handler = logging.handlers.RotatingFileHandler( 'logs/app.log', maxBytes=1010241024, # 10MB backupCount=5 ) file_handler.setLevel(logging.INFO) # Detailed format for file logs file_formatter = logging.Formatter( '[%(asctime)s] [%(levelname)s] [%(name)s:%(funcName)s:%(lineno)d] ' '[PID:%(process)d:TID:%(thread)d] %(message)s', datefmt='%Y-%m-%d %H:%M:%S' ) file_handler.setFormatter(file_formatter) # Console handler (simpler format) console_handler = logging.StreamHandler() console_handler.setLevel(logging.WARNING) console_formatter = logging.Formatter( '[%(levelname)s] %(name)s: %(message)s' ) console_handler.setFormatter(console_formatter) # Add handlers logger.addHandler(file_handler) logger.addHandler(console_handler) return logger ``` ### Pattern 2: Service Method Logging ```python # methodology/services/playbook_service.py import logging from django.core.exceptions import ValidationError logger = logging.getLogger(__name__) class PlaybookService: """Business logic for playbook management.""" @staticmethod def create_playbook(name: str, description: str, category: str, author): """ Create a new playbook. :param name: Playbook name as str. Example: "React Development" :param description: Description as str. Example: "Modern React patterns" :param category: Category as str. Example: "development" :param author: User instance. Example: User(id=1, username="maria") :return: Created Playbook instance :raises ValidationError: If validation fails """ # Entry logging with context logger.info( f"Creating playbook: name={name!r}, category={category!r}, " f"author={author.username} (id={author.id})" ) # Validation with logging if not name or not name.strip(): logger.warning( f"Playbook creation failed: empty name provided by user {author.username}" ) raise ValidationError("Playbook name cannot be empty") # Check for duplicates if Playbook.objects.filter(name=name, author=author).exists(): logger.warning( f"Playbook creation failed: duplicate name {name!r} " f"for user {author.username}" ) raise ValidationError(f"Playbook '{name}' already exists") # Create playbook try: playbook = Playbook.objects.create( name=name, description=description, category=category, author=author, version=Decimal('0.1'), status='draft' ) # Success logging with result logger.info( f"Playbook created successfully: id={playbook.id}, " f"name={playbook.name!r}, version={playbook.version}, " f"author={author.username}" ) return playbook except Exception as e: # Error logging with full context logger.error( f"Playbook creation failed with exception: {type(e).__name__}: {e}. " f"Context: name={name!r}, category={category!r}, " f"author={author.username} (id={author.id})", exc_info=True ) raise ``` ### Pattern 3: View Logging ```python # methodology/views.py import logging from django.shortcuts import render, redirect from django.contrib.auth.decorators import login_required from django.contrib import messages logger = logging.getLogger(__name__) @login_required def playbook_create(request): """Create new playbook.""" logger.info( f"Playbook create view accessed by user {request.user.username} " f"(id={request.user.id}), method={request.method}" ) if request.method == 'POST': # Log form submission logger.info( f"Playbook create form submitted by {request.user.username}. " f"Data: name={request.POST.get('name')!r}, " f"category={request.POST.get('category')!r}" ) service = PlaybookService() try: playbook = service.create_playbook( name=request.POST['name'], description=request.POST.get('description', ''), category=request.POST['category'], author=request.user ) logger.info( f"Playbook created via web UI: id={playbook.id}, " f"redirecting to detail page" ) messages.success(request, f'Playbook "{playbook.name}" created') return redirect('playbook_detail', playbook_id=playbook.id) except ValidationError as e: logger.warning( f"Playbook creation validation error for user {request.user.username}: {e}" ) messages.error(request, str(e)) return render(request, 'playbooks/create.html') ``` ### Pattern 4: Conditional Logic Logging ```python def process_workflow(workflow_id: int, user): """Process workflow with detailed decision logging.""" logger.info( f"Processing workflow: id={workflow_id}, user={user.username}" ) workflow = Workflow.objects.get(id=workflow_id) # Log decision points if workflow.status == 'draft': logger.info( f"Workflow {workflow_id} is in draft status, " f"allowing modifications" ) can_modify = True elif workflow.status == 'released': logger.info( f"Workflow {workflow_id} is released, " f"modifications require PIP" ) can_modify = False else: logger.warning( f"Workflow {workflow_id} has unexpected status: {workflow.status}" ) can_modify = False # Log data transformations activities = workflow.activities.all() logger.debug( f"Loaded {activities.count()} activities for workflow {workflow_id}" ) # Log results logger.info( f"Workflow processing complete: id={workflow_id}, " f"can_modify={can_modify}, activity_count={activities.count()}" ) return can_modify, activities ``` ### Pattern 5: Error Context Logging ```python def import_workflow_data(file_path: str, user): """Import workflow with comprehensive error logging.""" logger.info( f"Starting workflow import: file={file_path}, user={user.username}" ) try: # Validate file exists if not Path(file_path).exists(): logger.error( f"Workflow import failed: file not found. " f"Path: {file_path}, user: {user.username}" ) raise FileNotFoundError(f"File not found: {file_path}") # Parse file logger.debug(f"Parsing workflow file: {file_path}") with open(file_path, 'r') as f: data = json.load(f) logger.info( f"Workflow file parsed successfully: " f"{len(data.get('activities', []))} activities found" ) # Import activities for idx, activity_data in enumerate(data.get('activities', [])): logger.debug( f"Importing activity {idx+1}: name={activity_data.get('name')!r}" ) # ... import logic ... logger.info( f"Workflow import completed successfully: " f"file={file_path}, activities_imported={len(data.get('activities', []))}" ) except json.JSONDecodeError as e: logger.error( f"Workflow import failed: invalid JSON. " f"File: {file_path}, error: {e}, line: {e.lineno}, col: {e.colno}", exc_info=True ) raise except Exception as e: logger.error( f"Workflow import failed with unexpected error: {type(e).__name__}: {e}. " f"File: {file_path}, user: {user.username}", exc_info=True ) raise ``` ## Common Pitfalls ### ❌ Don't: Log without context ```python logger.info("Creating playbook") logger.error("Failed") ``` ### ✅ Do: Log with full context ```python logger.info( f"Creating playbook: name={name!r}, category={category!r}, " f"author={author.username} (id={author.id})" ) logger.error( f"Playbook creation failed: {e}. Context: name={name!r}, " f"author={author.username}", exc_info=True ) ``` ### ❌ Don't: Use print statements ```python print(f"User {user.username} logged in") ``` ### ✅ Do: Use logger ```python logger.info(f"User {user.username} (id={user.id}) logged in successfully") ``` ### ❌ Don't: Log sensitive data ```python logger.info(f"User login: password={password}") # NEVER! ``` ### ✅ Do: Mask sensitive data ```python logger.info(f"User login attempt: username={username}, password=*") ``` ## Quality Gates Before declaring logging complete: - [ ] All service methods log entry with parameters - [ ] All service methods log exit with results - [ ] All errors logged with full context and exc_info=True - [ ] All decision points logged (if/else branches) - [ ] All data transformations logged - [ ] No sensitive data (passwords, tokens) in logs - [ ] User context included (username, user_id) - [ ] Operation context included (what, why, when) - [ ] Log levels appropriate (DEBUG/INFO/WARNING/ERROR) - [ ] File handler configured with rotation ## Log Level Guidelines ### DEBUG - Detailed flow control - Type checking - Internal state - Loop iterations - Data structure contents ### INFO - Method entry/exit - Configuration loaded - Major processing steps - Results and outcomes - User actions ### WARNING - Concerning but recoverable conditions - Substitutions and fallbacks - Fallback usage - Data quality issues - Deprecated feature usage ### ERROR - Failures requiring attention - Unrecoverable conditions - Exceptions - Data corruption - External service failures ## Informative Logging Checklist Every log message should answer: - Who: Which user/agent triggered the action? - What: What operation was performed? - Why: Why did it happen (intent, rule, logic)? - Where: Which class/method/line? - When: Timestamp (automatic) - How: With what parameters/data? - Result**: What was the outcome? ## Example: Complete Logging Pattern ```python import logging logger = logging.getLogger(__name__) class WorkflowService: @staticmethod def update_workflow(workflow_id: int, updates: dict, user): """ Update workflow with comprehensive logging. :param workflow_id: Workflow ID. Example: 42 :param updates: Field updates. Example: {"name": "New Name"} :param user: User making changes. Example: User(id=1) :return: Updated workflow """ # Entry logging logger.info( f"Updating workflow: id={workflow_id}, " f"fields={list(updates.keys())}, " f"user={user.username} (id={user.id})" ) try: # Fetch workflow workflow = Workflow.objects.get(id=workflow_id) logger.debug( f"Workflow loaded: id={workflow_id}, " f"current_name={workflow.name!r}, " f"status={workflow.status}" ) # Validate permissions if workflow.playbook.author != user: logger.warning( f"Workflow update denied: user {user.username} " f"not authorized for workflow {workflow_id}" ) raise PermissionError("Not authorized") # Apply updates for field, value in updates.items(): old_value = getattr(workflow, field) setattr(workflow, field, value) logger.info( f"Workflow {workflow_id} field updated: " f"{field}: {old_value!r} -> {value!r}" ) workflow.save() # Success logging logger.info( f"Workflow updated successfully: id={workflow_id}, " f"updated_fields={list(updates.keys())}, " f"user={user.username}" ) return workflow except Workflow.DoesNotExist: logger.error( f"Workflow update failed: workflow not found. " f"id={workflow_id}, user={user.username}" ) raise except Exception as e: logger.error( f"Workflow update failed: {type(e).__name__}: {e}. " f"Context: id={workflow_id}, updates={updates}, " f"user={user.username}", exc_info=True ) raise ```
Test Trophy Architecture	Test Strategy & Design	testing-trophy, integration-testing	Junior Edda	Read the 'Test Trophy Architecture' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: Test Strategy & Design Technology stack: testing-trophy, integration-testing # Skill: Test Trophy Architecture Capability Domain: TEST_STRATEGY Technology Stack: pytest+behave ## Overview Integration-first testing philosophy replacing the traditional test pyramid. The "trophy" shape reflects where we invest most: thick integration tests in the middle, thin unit tests at the base, acceptance tests above, and selective E2E at the top. ## The Test Trophy Model ``` ╱╲ E2E (selective, slow, staging only) ╱────╲ Acceptance Tests (behave, BDD .features) ╱════════╲ INTEGRATION TESTS (main bet, no mocking) ╱──────────╲ Unit Tests (thin, only where isolation helps) ════════════════ Static Analysis (linting, type checks) ``` ## Why Not the Pyramid? 1. Unit tests have limited value: Testing `model.save()` returns OK tells us nothing about whether data persisted. 2. Acceptance tests are expensive: Real browser, slow, flaky. 3. Integration tests are the sweet spot: Real objects, real connections, real data. Fast enough for CI, thorough enough to catch real bugs. ## When Unit Tests ARE Valuable - Custom QuerySet methods with complex filtering logic - Pure utility/helper functions with interesting edge cases - Business logic methods that do computation (not just DB operations) ## When Unit Tests ARE NOT Valuable - Default Model CRUD - Auto-generated admin views - Framework behavior - Anything that requires mocking to test in isolation ## Agent test lanes (when SAO §17 applies) When the project has in-app LLM agents, extend the Trophy with four agent lanes — still integration-first, still no domain mocks: \| Lane \| Trophy layer \| CI gate \| Mock seam \| \|------\|--------------\|---------\|-----------\| \| 1 Control-plane proofs \| Integration (thick) \| PR when `AGENTS_ENABLED=true` \| CAP-004 ScriptedLLM only \| \| 2 Deterministic shell \| Integration (thick) \| PR (normal integration) \| None — no LLM \| \| 3 Live contract eval \| Integration / contract \| Nightly / optional CD \| Live provider, temp=0 \| \| 4 Task performance quality \| Eval overlay \| Promotion band \| Live provider + golden oracle \| Placement: - Lanes 1–2 are part of the integration band — same real DB/services discipline as the Trophy main bet. - Lane 3 is a contract eval overlay — schema and response bounds, not merge-blocking flake. - Lane 4 is outside PR merge — TASK-* golden tasks; regression vs last certified band. Do not move agent orchestration proofs to unit tests or Behave AT. User-visible AT stays in the acceptance band; PRF-* control-plane proofs stay in lane 1 pytest (`@agent_proof`). See skill Agent Integration Proof Patterns (lane 1–2) and Agent Task Eval (lane 4).
Write Gherkin Feature Files	BDD_AUTHORING	Gherkin + Playwright + pytest-bdd	Junior Edda	Read the 'Write Gherkin Feature Files' skill from playbook 'Junior Edda'. Apply its guidance when assisting me. Capability domain: BDD_AUTHORING Technology stack: Gherkin + Playwright + pytest-bdd # Skill: Write Gherkin Feature Files Capability Domain: BDD_AUTHORING Technology Stack: Gherkin + Playwright + pytest-bdd ## Overview Gherkin `.feature` files are the single source of truth for acceptance criteria. They are not documentation — they are executable tests. Every scenario must be specific enough that an automated test runner can determine PASS or FAIL without human interpretation. This skill covers two non-negotiable principles and the patterns that enforce them. --- ## Principle 1 — Scenarios Must Be Executable Tests A scenario is a good test when a developer who has never spoken to you can implement it from the Gherkin alone and get the same result as you intended. ### The Test-Readiness Checklist Before committing a scenario, verify: \| Check \| Question \| Fail signal \| \|-------\|----------\|-------------\| \| Concrete data \| Does every Given/When/Then use real names, real values, real counts? \| "some playbooks", "enters details", "valid data" \| \| Specific selector \| Does every interaction reference the exact button label or `data-testid`? \| "clicks the button", "uses the action" \| \| Verifiable assertion \| Can the Then be checked by `assert element.text == '...'`? \| "page updates", "something happens" \| \| Single behaviour \| Does the scenario test exactly one thing? \| Scenario with 4 Whens and 6 Thens \| \| State independence \| Can it run in any order without depending on prior test state? \| Given that depends on another scenario's outcome \| ### Pull Data from `user_journey.md` `docs/features/user_journey.md` defines the canonical personas (Maria Rodriguez, Mike Chen) and all example entity names. Always use those names — never invent generic placeholders. Anti-pattern (untestable): ```gherkin Scenario: Create activity successfully Given Maria is on the create activity form When she enters a name and description And she creates the activity Then the activity is created ``` Good pattern (executable test): ```gherkin Scenario: FOB-ACTIVITIES-CREATE_ACTIVITY-02 Create activity successfully Given Maria is on the create activity form for workflow "Component Development" When she enters "Setup component structure" in Name And she enters "Create folder structure and base files" in Description And she clicks [Create Activity] Then the activity "Setup component structure" appears in the activity list And she sees success notification "Activity created successfully" And she is redirected to FOB-ACTIVITIES-VIEW_ACTIVITY-1 ``` Key differences: - Entity name comes from user_journey.md ("Component Development", "Setup component structure") - Button references exact label in brackets: `[Create Activity]` - Then assertions name the exact element and exact text - Then includes navigation assertion (which screen) ### Counts and Quantities Must Be Concrete Anti-pattern: `Given she has multiple playbooks` Good pattern: `Given Maria has 3 playbooks in her FOB:` (followed by a data table) Anti-pattern: `Then she sees all playbooks` Good pattern: `Then the header shows "Playbooks (3)"` and `And she sees all 3 playbooks in the table` ### Use Data Tables for Multi-Row Setup ```gherkin Given Maria has 3 playbooks in her FOB: \| name \| author \| version \| status \| \| React Frontend Development \| Mike Chen \| v1.2 \| Active \| \| UX Research Methodology \| Maria Rodriguez \| v2.1 \| Active \| \| Design System Patterns \| Community \| v1.0 \| Disabled \| ``` Never say "she has a playbook" when you can give its full identity. The test framework sets up exactly this data — vague rows produce unpredictable fixtures. ### Use `Scenario Outline` for Parametric Cases When the same flow runs for N values (status filter, column sort), avoid duplicating scenarios: ```gherkin Scenario Outline: FOB-PLAYBOOKS-LIST+FIND-10 Sort by different columns Given Maria is on the playbooks list page When she clicks the "<column>" column header Then playbooks are sorted by "<column>" in ascending order Examples: \| column \| \| Author \| \| Version \| \| Status \| \| Last Modified \| ``` --- ## Principle 2 — Unified Step Vocabulary Every team member and every automated step definition uses the same English phrase for the same UI gesture. Fragmented synonyms mean duplicate step definitions and inconsistent tests. ### Canonical Step Dictionary #### Navigation & Entry Points \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `she clicks "Playbooks" in the main navigation` \| presses, taps, selects from nav, uses the nav link \| \| `she is on FOB-{ENTITY}-LIST+FIND-1` \| she visits, she navigates to, she opens the page \| \| `she is redirected to FOB-{ENTITY}-VIEW_{ENTITY}-1` \| she goes to, she lands on, she ends up at \| #### Button Interactions \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `she clicks [Create New Playbook]` \| presses [Create...], taps [Create...], engages [Create...], uses the create button \| \| `she clicks [Save]` \| submits, confirms, applies \| \| `she clicks [Cancel]` \| dismisses, aborts, closes \| \| `she clicks [Delete]` \| removes, destroys \| \| `she clicks [Edit]` \| modifies, updates, opens edit \| \| `she clicks [View]` \| opens, inspects, reads \| \| `she opens the Actions menu for "{name}"` \| she right-clicks, she uses the kebab, she accesses actions \| Rule: always use square brackets `[Label]` for button references, matching the exact label in the UI. #### Form Field Interactions \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `she enters "{value}" in {Field Name}` \| types in, fills in, inputs, puts \| \| `she selects "{value}" from the {Field} filter` \| picks, chooses, uses filter \| \| `she selects "{value}" from {Field} dropdown` \| picks, chooses \| \| `she leaves {Field} empty` \| does not fill, skips, omits \| \| `she clears {Field}` \| empties, removes text from \| #### Search & Filter \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `she enters "{query}" in the search box` \| types in search, uses search field, searches for \| \| `she clicks [Clear Filters]` \| resets, removes filters \| #### Assertions \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `she sees "{exact text}"` \| text appears, she notices, page shows \| \| `she sees success notification "{exact text}"` \| success message appears, toast shows \| \| `she sees validation error "{exact text}"` \| error appears, field is invalid \| \| `the header shows "{Entity} ({N})"` \| count is shown, number appears \| \| `{Entity} "{name}" appears in the {list/table}` \| she can see it, it is listed \| \| `{Entity} "{name}" is not in the {list/table}` \| it is gone, it disappears, it is removed \| \| `the [Button] is disabled` \| button is grayed out, button cannot be clicked \| \| `a tooltip shows "{exact text}"` \| tooltip appears, tooltip says, hint text \| #### Modal / Dialog \| Canonical Phrase \| Do NOT Use \| \|-----------------\|------------\| \| `the {FOB-ENTITY-DELETE_ENTITY-1} modal appears` \| a dialog pops up, the confirmation box shows \| \| `she confirms` \| she agrees, she accepts (use only inside a modal context) \| \| `she sees "Discard changes?" confirmation` \| a prompt appears \| --- ## Standard Scenario Coverage per Screen For every screen (CRUDLF operation), cover these scenario groups in order: 1. Entry navigation — how the user reaches this screen (from LIST, from detail, from nav) 2. Happy path — successful operation with concrete data from user_journey.md 3. Required field validation — every required field, one scenario per field (or `Scenario Outline`) 4. Optional fields — verify they save correctly or can be left empty 5. Cancel / discard — user abandons the form, no data is persisted 6. Edge cases — empty state, max length, special characters, duplicate names 7. Permission / ownership — actions unavailable to non-owners 8. Navbar integration (last section, marked with comment) — link visible, active state --- ## File Naming & Header Convention ``` docs/features/act-{N}-{entity}/{entity}-{operation}.feature ``` Header template: ```gherkin Feature: FOB-{ENTITY}-{OPERATION}-1 {Human Readable Title} As a {persona from user_journey.md} I want to {goal} So that {benefit} Background: Given {persona} is authenticated in FOB And she {is on / owns / has set up} {specific context} ``` Scenario IDs: ``` FOB-{ENTITY}-{OPERATION}-{NN} (zero-padded: 01, 02, 03 ...) ``` --- ## Anti-Pattern Reference Card \| Anti-Pattern \| Why Bad \| Fix \| \|-------------\|---------\|-----\| \| `she enters valid data` \| Cannot automate — "valid" is undefined \| Name every field with its exact value \| \| `she clicks the button` \| Which button? Multiple may exist \| `she clicks [Create Skill]` \| \| `the page updates` \| No assertion possible \| `the header shows "Skills (4)"` \| \| `given some skills exist` \| Test fixture is non-deterministic \| Provide a full data table \| \| `she performs the action` \| Action is ambiguous \| Use exact click step \| \| `it works correctly` \| Tautology — tests nothing \| State the exact observable outcome \| \| `she can see the form` \| Vague — what form? what state? \| `she is on FOB-SKILLS-CREATE_SKILL-1` and `the form shows "Create Skill in {playbook}"` \| --- ## Quick Self-Review Before Committing Read each scenario aloud and ask: 1. Could a junior developer write the Playwright test from this Gherkin alone? → If no, add data. 2. Does every step use a word from the canonical dictionary? → If no, rename the step. 3. Does every Then contain an exact string or exact count to assert? → If no, add specificity. 4. Would this scenario still pass if the wrong entity was created? → If yes, add identity assertions. 5. Is there a scenario testing what happens when the operation FAILS? → Add validation/error scenarios.
Gap Analysis	Quality Assurance	—	Playbook for Playbooks
Ontology Mapping	Knowledge Engineering	—	Playbook for Playbooks
Semantic Reading	Knowledge Extraction	—	Playbook for Playbooks
Zero-Context Readability	—	—	Playbook for Playbooks	Read the 'Zero-Context Readability' skill from playbook 'Playbook for Playbooks'. Apply its guidance when assisting me. Judging whether an activity packet is executable by a capable intern or coding agent who has never seen this domain. The packet is the activity name, guidance, and whatever that activity already links (skills, artifacts, rules, agent) — nothing else. Pass: they can tell what to do, or at least find pointers to the pieces they must assemble. Fail: they need an oral briefing, hidden files, author memory, or the Extraction Worksheet to start. Distinct from Gap Analysis: Gap Analysis finds missing schema entities (no agent, unlinked artifact). This skill finds missing pointers — guidance that only makes sense if you already know the domain. Capability domain: Quality Assurance.
AST Parsing and Data Flow Analysis	Program Analysis	—	Program Graphs for Code Analysis
Gated Graph Neural Network Implementation	Deep Learning	TensorFlow	Program Graphs for Code Analysis	Read the 'Gated Graph Neural Network Implementation' skill from playbook 'Program Graphs for Code Analysis'. Apply its guidance when assisting me. Capability domain: Deep Learning Technology stack: TensorFlow Implementing GGNNs with sparse tensor representations for efficient batching over large, diverse graphs. Includes message passing, GRU state updates, and multi-threaded minibatch construction.
Subtoken Embedding	NLP / Code Representation	—	Program Graphs for Code Analysis