Skills

Title	Capability Domain	Technology Stack	Playbook	Actions
AI Leverage Mapping	Process Engineering	Opportunity Scoring	Delivery Constraint & Opportunity Analysis	Read the 'AI Leverage Mapping' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Process Engineering Technology stack: Opportunity Scoring # Skill: AI Leverage Mapping Capability Domain: Process Engineering Technology Stack: Opportunity Scoring ## Purpose Say where AI could cut impact, not which agents to build. ## File intern fills `streamlit/data/ai_opportunities.yaml` columns: `id`, `opportunity_name`, `stage`, `ai_can_help` (yes/no/unknown), `effort_size` (S/M/L/XL), `expected_gain`, `plot_x`, `plot_y`. Quadrant axes: X = `effort_size` (S–XL), Y = `expected_gain`. Same `id` values as swimlane badges. TSY does not re-query Athena for this plot. ## Recipe 1. Start from the Cost of Delay Ranking. Ignore low-impact stages. 2. For each remaining box, score independently: - AI-can-help? yes / no / unknown (can GenAI shorten touch or wait?) - Implementation effort S / M / L / XL 3. Low-hanging fruit = high impact AND AI-yes AND low effort. 4. Plot expected efficiency gain vs effort. Cells are opportunity names (e.g. "PR review wait"), never product names (no Code Review Agent, no Copilot rollout plan). 5. Write AI Opportunity Prioritization Matrix into that YAML. Overlay numbered badges on high-impact AI-yes swimlane cards; gray = no/unknown. ## Pitfalls - Recommending AI on a cheap stage because it is easy. - Treating this matrix as an agent backlog.
Athena SQL Querying	Analytics	Amazon Athena	Delivery Constraint & Opportunity Analysis	Read the 'Athena SQL Querying' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Technology stack: Amazon Athena # Skill: Athena SQL Querying Capability Domain: Analytics Technology Stack: Amazon Athena Linked Activities: Present the Catalog via Athena ## Recipe 1. One workgroup: Scope Contract `athena_workgroup` (default `ops-lake-analysts`), `EnforceWorkGroupConfiguration` on, scan cap 5GB to start. 2. Glue crawler tables are the contract views (`github_issues`, …). Named Athena queries are proofs (LIMIT 10), not a second catalog. `scripts/create_athena_views.py` after crawlers READY; skip views with no Glue table. 3. Backfill envelope is `{backfill, kind, repo, payload: {…}}`. Query `json_extract_scalar(raw_json, '$.payload.number')`, `$.payload.closed_at`, `$.payload.state` — not top-level GitHub fields. Prefer the snapshot that has `closed_at` when deduping by issue number. 4. Query results → athena-results bucket, 7-day lifecycle. 5. Always filter on `source` / `dt`. `SELECT ` on an unpartitioned scan blows the cap. ## Pitfalls - AWS login refresh is not Athena AccessDenied.* Local Jupyter/`awswrangler` can fail with `AccessDeniedException` on `CreateOAuth2Token`, then `LoginRefreshRequired`: "The refresh token has expired" / "Please reauthenticate using `aws login`". Wrangler never reached `StartQueryExecution`. This is credential session expiry, not lake IAM / workgroup deny. Procedure: (1) terminal `aws login` (or this org's equivalent `aws sso login`); (2) confirm `aws sts get-caller-identity` matches `docs/lake-scope-contract.yaml` `aws_account` (live opsdl: `411113550285`); (3) Restart the Jupyter kernel, then Restart & Run All — boto3 clients in a running kernel keep the dead token; (4) the login credential provider also needs `pip install 'botocore[crt]'` (opsdl `requirements-eda.txt`). - Treating crawler tables as incomplete until CREATE VIEW — the table name already matches the contract view. - Querying `$.number` instead of `$.payload.number` on backfill rows. - Shipping `gitlab_commits` as a default when the contract is GitHub-only. - Correlated EXISTS/UNNEST subqueries in Athena (feature filters belong in Python after the SQL returns).
AWS CDK Infrastructure as Code	Infrastructure as Code	AWS CDK (Python default), CloudFormation	Delivery Constraint & Opportunity Analysis	Read the 'AWS CDK Infrastructure as Code' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Infrastructure as Code Technology stack: AWS CDK (Python default), CloudFormation # Skill: AWS CDK Infrastructure as Code Capability Domain: Infrastructure as Code Technology Stack: AWS CDK (Python default), CloudFormation Linked Activities: Model the Data Lake as CDK Stacks ## Language Greenfield lake repo: Python (`aws-cdk-lib`, pytest). TypeScript only if the host repo is already TypeScript. Do not mix. ## Recipe 1. Read `docs/lake-scope-contract.yaml`. Stacks instantiate only `sources` and `views` listed there. 2. Layout in the starter kit (`https://github.com/FeatureFactory-io/ops-lake-starter`): `infra/app.py`, `infra/ops_lake/deploy_stack.py`, `ingestion_stack.py`, `catalog_stack.py`, `eda_stack.py`, `scope.py`. Customize from the filled contract; do not scaffold empty stacks. 3. Four stacks: - `DeployStack` (`OpsLakeDeploy`): GitHub (or GitLab) OIDC provider + deploy IAM role. Trust both `sub` patterns (name-only and ID-qualified). Output `DeployRoleArn`. - `IngestionStack`: scoped ingestion Lambdas (`GithubWebhookFn`, `GithubBackfillFn`, `GithubProjectsPollFn` if github scoped), HTTP API, DynamoDB cursor table, raw/curated/athena-results buckets, SQS buffer, `ParquetTransformFn`. `GithubBackfillFn` timeout 10 min / 1024 MB. - `CatalogStack`: Glue database, one crawler per `views` entry with daily EventBridge schedule `cron(0 6 * * ? )`, Athena workgroup (5GB scan cap), named preview queries. - `EdaStack`: Streamlit mart on ECS Fargate + ALB* (not App Runner — WebSockets unsupported). Image `linux/amd64`. Task role: Athena + Glue GetTables + `curated_bucket.grant_read` + Athena results read/write. 4. Bucket encryption: `s3.BucketEncryption.KMS_MANAGED` (SSE-KMS) and `bucket_key_enabled=True` (S3 Bucket Keys). Do not attach a customer-managed `kms.Key` to buckets that also have S3→SQS notifications — CloudFormation hits `LakeKey -> RawBucket -> LakeKey`. Without Bucket Keys, every PutObject/GetObject is a KMS request; one-file-per-event Parquet plus Glue/Athena reads burns the 20k always-free KMS requests in a single backfill (recapture X-15, 2026-09-15). Bucket Keys apply to new objects only. 5. pytest: `tests/unit/test_scope_contract.py`, `test_deploy_stack.py`, `test_ingestion_stack.py`, `test_catalog_stack.py`, `test_eda_stack.py`. Use CDK context `skip_bundling` for synth tests without Docker. Must be green before CI deploy. Assert `BucketKeyEnabled` is true on all three lake buckets. Copy-this tests stay in the starter kit. 6. `cdk deploy` from a laptop is bootstrap + one sandbox mint of OpsLakeDeploy only. Shared env is GHA/`cdk deploy --all`. ## Copy-this tests `Template.from_stack` on IngestionStack: 3 buckets, each `SSEAlgorithm: aws:kms` with `BucketKeyEnabled: true`, `GithubWebhook` present, `Gitlab`/`Jira` absent. CatalogStack: Glue database name from contract, crawler count == len(views), Athena workgroup name from contract. DeployStack: OIDC provider + IAM role. EdaStack: Fargate service + ALB, no App Runner. ## Pitfalls - Modeling GitlabWebhookFn / JiraPollFn when `sources: [github]`. - Customer-managed KMS key shared by bucket + SQS notification (CFN cycle). - SSE-KMS without S3 Bucket Keys (`bucket_key_enabled=False`) — KMS Free Tier gone in one backfill morning. - `cdk deploy` from a laptop to a shared account after the OIDC role exists. - Putting Streamlit on App Runner (blank skeleton; `/_stcore/stream` 403). - Scaffolding empty `infra/` instead of customizing the starter kit clone.
AWS Glue Cataloging	Data Engineering	AWS Glue, Glue Crawlers, Hive Metastore	Delivery Constraint & Opportunity Analysis	Read the 'AWS Glue Cataloging' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Engineering Technology stack: AWS Glue, Glue Crawlers, Hive Metastore # Skill: AWS Glue Cataloging Capability Domain: Data Engineering Technology Stack: AWS Glue, Glue Crawlers, Hive Metastore Linked Activities: Catalog with AWS Glue ## Recipe 1. One database: Scope Contract `athena_database` (default `ops_catalog`). 2. One crawler per `views` entry, target `s3://{curated}/{table}/` (partition subdirs `source=`). Names like `{table}_crawler`. 3. Schedule: daily EventBridge `cron(0 6 * * ? )` plus* a one-shot start from populate-lake after Parquet sync. Do not trigger a crawler per S3 object. 4. Built-in Parquet classifier. Custom classifier only if auto-detect fails. 5. Define crawlers in CatalogStack. No console-created crawlers. 6. After populate-lake, wait until each crawler State=READY, then Athena proof. ## Escalate Schema-drift that changes an existing column type — Operations Analyst before apply. ## Pitfalls - Crawlers for `gitlab_` / `jira_` when those views are not in the contract. - Per-object crawler triggers (cost + race with incomplete Parquet). - Duplicate `source` columns from Parquet body + partition (fix in ParquetTransformFn first).
Cycle Impact Scoring	Process Engineering	Cost of Delay, Value Stream Accounting	Delivery Constraint & Opportunity Analysis	Read the 'Cycle Impact Scoring' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Process Engineering Technology stack: Cost of Delay, Value Stream Accounting # Skill: Cycle Impact Scoring Capability Domain: Process Engineering Technology Stack: Cost of Delay, Value Stream Accounting ## Formula `wall_clock = touch_time + wait_time` (elapsed; hours or business days, labeled) `effort = people_in_role × touch_time` (load, not elapsed) `impact = effort + (people_downstream × wait_time)` Rank stages and handoffs by impact, not by p90 wall-clock alone. Keep the Theory-of-Constraints #1 visible so a cheap stage cannot outrank a real bottleneck. ## Files intern fills (starter clone) - `streamlit/data/role_capacity.yaml` — columns: `stage`, `role`, `people_in_role`, `people_downstream`, `assumed_or_measured`, `who_said_so` - `streamlit/data/cost_of_delay.yaml` — columns: `stage`, `touch_hours`, `wait_hours`, `wall_clock_hours`, `effort`, `impact`, `toc_rank_1`, `assumed_or_measured`, `query_execution_id` - SQL: `sql/stage_touch_wait.sql` placeholders `{database}`, `{view}`, `$.payload.` Wall-clock / effort / impact on the swimlane are these YAML fields. Do not re-query Athena when drawing TSY slides. ## Recipe 1. Split each stage's wall-clock into touch time* (active work between events) and wait time (idle gaps). Wall-clock comes from catalog events (issue → PR → CI → merge → deploy). Never treat wall-clock as effort. 2. When Jira `status_segments` exist, a stage's touch/wait may be measured from those segments. Issue lead and cycle (business days; skill Jira Flow Extract) are supporting clocks — they do not replace this impact formula. 3. Headcount is the Role Capacity Assumptions table: people in this role, people downstream. Do not infer headcount from unique Git authors. 4. Label every number measured or assumed. 5. Join work items on issue/PR number (`Closes #N`), never timestamps or `repo` alone. 6. Write Cost of Delay Ranking (query text + QueryExecutionId where measured) and Delivery Cycle Reconstruction (swimlane with three metrics per card: effort, wall-clock, impact). 7. Optional look-until-trusted charts: skill Metric Render Catalog. Do not promote those charts to the #1 ranking. ## Pitfalls - Ranking by duration only, ignoring how many people wait. - Using unique authors as team size. - Putting assumed numbers next to measured ones without a label. - Equating issue lead/cycle business days with merge-request wall-clock hours.
Data Storytelling and Dashboard Design	Analytics Communication	Narrative structure	Delivery Constraint & Opportunity Analysis	Read the 'Data Storytelling and Dashboard Design' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Narrative structure # Skill: Data Storytelling and Dashboard Design Capability Domain: Analytics Communication Technology Stack: Narrative structure ## Purpose Plan the story. Do not pick a BI product here. Interpret proven findings — do not re-extract. Do not re-classify Action Register cause tags. ## Template Fill `docs/analysis/narrative-outline.md`. YAML numbers live in `streamlit/data/`. ## Recipe 1. Big-picture first: reconstructed delivery cycle (effort, wall-clock, impact on every stage) before any stage section. Renderer: `streamlit/pages/0_Delivery_Cycle.py` / `cycle_figure`. 2. Then the opportunity quadrant (`1_Opportunity_Quadrant.py`). Opportunity names, not agents. 3. Then the deficiency register (`2_Deficiency_Register.py`): finding + eliminate/automate/delegate + dE/dK/dI + receiving playbook. Copy CAS. Do not invent tags. - dE + automate/delegate → AI SDLC as receiver. - Other dE → process/tooling owners (not AI SDLC). - dK → Team Upskill Engine as receiver of candidates (stage, clock, unit, n, role). Do not outline modules. - dI → staffing / selection. 4. Then one section per stage in flow order. Promoted EDA ids from `promoted_eda.yaml` or none. 5. Cap visuals at one per finding. 6. Name which presentation skill Present Findings will use. Jupyter = `notebooks/published-findings.ipynb`. 7. If Streamlit or Jupyter: list starter mart tabs (Commits, Work items, Changes, Pipelines, Load, Defects, Sprints) as drill-down. Skip missing views. Formulas: skill Present Findings with Streamlit → Starter mart tabs. ## Clocks (never equate) - Issue lead / cycle (if Jira views exist): business days. Skill Jira Flow Extract. - MR / PR cycle: wall-clock hours, created → merged. - Label the unit. Do not plot both clocks on one unlabeled axis. ## KPI aggregation Prefer per-item median + n. A mean of daily averages is unweighted by volume. ## Three lenses Flow, speed, people — in stage detail and tabs, not as the opening slide. ## Contributors commit author ≠ work-item author ≠ integrator ≠ assigned reviewer. Reviewer counts are assignments, not approvals. Load signals are risk, not a score. ## Pitfalls - A finding without its Action Register decision is trivia. - Opening with a starter tab or Feature Cycle Time. - Re-tagging dE/dK/dI, or presenting dK rows as a curriculum.
EDA with Pandas and Jupyter	Data Science	Python, Pandas, Jupyter, Plotly	Delivery Constraint & Opportunity Analysis	Read the 'EDA with Pandas and Jupyter' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Science Technology stack: Python, Pandas, Jupyter, Plotly # Skill: EDA with Pandas and Jupyter Capability Domain: Data Science Technology Stack: Python, Pandas, Jupyter, Plotly Linked Activities: EDA with Pandas and Jupyter ## Recipe 1. Pull via `awswrangler.athena.read_sql_query(sql, database="ops_catalog", workgroup="ops-lake-analysts")` — not a raw boto3 polling loop; awswrangler handles pagination and polling. 2. Pin the query text as a literal string in the notebook's first cell, and record the Athena `QueryExecutionId` in a markdown cell — that's what makes a finding reproducible against a catalog that keeps growing. 3. Classify the notebook's own question in a markdown cell up front — describe, classify, or predict — the acceptable rigor bar differs: describe needs clean summary stats; predict needs a held-out validation split and an explicit baseline to beat. 4. Standard opening cells, every notebook: `df.info()`, null-rate per column, duplicate-check on the join key (issue key / PR number) — most "surprising" operational-data findings turn out to be a duplicate-row bug. ## Pitfalls - AWS login refresh is not Athena AccessDenied. Local Jupyter/`awswrangler` can fail with `AccessDeniedException` on `CreateOAuth2Token`, then `LoginRefreshRequired`: "The refresh token has expired" / "Please reauthenticate using `aws login`". Wrangler never reached `StartQueryExecution`. This is credential session expiry, not lake IAM / workgroup deny. Procedure: (1) terminal `aws login` (or this org's equivalent `aws sso login`); (2) confirm `aws sts get-caller-identity` matches `docs/lake-scope-contract.yaml` `aws_account` (live opsdl: `411113550285`); (3) Restart the Jupyter kernel, then Restart & Run All — boto3 clients in a running kernel keep the dead token; (4) the login credential provider also needs `pip install 'botocore[crt]'` (opsdl `requirements-eda.txt`). - Re-running cells out of order and trusting the result is the most common way a notebook becomes unreproducible — Restart & Run All before treating any finding as final.
EDA with Streamlit Data Mart	Business Analytics	Streamlit, ECS Fargate, ALB, Athena	Delivery Constraint & Opportunity Analysis	Read the 'EDA with Streamlit Data Mart' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Business Analytics Technology stack: Streamlit, ECS Fargate, ALB, Athena # Skill: EDA with Streamlit Data Mart Capability Domain: Business Analytics Technology Stack: Streamlit, ECS Fargate, ALB, Athena Linked Activities: EDA with Streamlit Data Mart (ECS Fargate + ALB) ## Skip when (QuickSight) No QuickSight subscription. Do not lead STEP 4 with QuickSight. Optional later: Athena data source, SPICE refresh ≤ crawler cadence, anomaly detection only on validated metrics. ## Recipe (Streamlit — the proven path) 1. Code lives in `streamlit/` in the lake repo. CDK `EdaStack` builds `streamlit/Dockerfile` as `linux/amd64` and runs ECS Fargate behind an ALB. Never App Runner (no WebSockets; blank skeleton). 2. Dockerfile must `COPY .py .` and `COPY pages pages/`. Missing `glue_catalog.py` crashed production (`ModuleNotFoundError`). 3. List Glue tables with boto3 paginated `GetTables` (`streamlit/glue_catalog.py`). Do not* use `wr.catalog.tables` (incomplete list / default limit). Catalog cache TTL ≤ 60s. 4. Task role: Athena start/get, Glue GetTables, `curated_bucket.grant_read` (ListBucket deny → Athena PERMISSION_DENIED), Athena-results read/write. Prove with IAM simulate in `deploy.yml`. 5. `.streamlit/config.toml`: disable CORS/XSRF as needed behind ALB; websocket compression off if the ALB flakes. 6. Baseline #1 — Feature Cycle Time (`pages/1_Feature_Cycle_Time.py` + `cycle_time.py`): - Big picture first: median total hours, WoW % last 12 weeks, features completed. - Line chart of median total by completion week; stacked bars Plan/Build/Test/Finalize; WoW table; project/repo filter. - Query `$.payload.`; join issues to PRs on `Closes #N` / `#N` in body, never timestamps alone. - This page is a look-until-trusted check, not the Tell the Data Story opening visual (that remains the reconstructed cycle swimlane). 7. Lake Explorer page: sample contract views for debugging. 8. Additional look-until-trusted pages: follow skill Metric Render Catalog*. Only render families whose contract views exist. KPI strips use inverse delta when lower is better. Prefer per-item median + n over a mean of daily averages. ## Pitfalls - App Runner for Streamlit. - Docker COPY only `app.py`. - `wr.catalog.tables` hiding views that exist in Glue. - Task role without curated-bucket ListBucket. - Feature filter that only accepts GitHub label `Feature` — org work uses `enhancement`, `status-done`, `W27:`, `[mimir:mcp]`, `BPE-01`. - Leading the mart home page with Feature Cycle Time instead of the reconstructed cycle when Present Findings uses Streamlit. - Mixing issue lead/cycle (business days) with MR created→merged (hours) on one sparkline without labeling units.
Eliminate/Automate/Delegate Triage	Process Engineering	AWS Lambda, Guardrails, LLM Agents	Delivery Constraint & Opportunity Analysis	Read the 'Eliminate/Automate/Delegate Triage' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Process Engineering Technology stack: AWS Lambda, Guardrails, LLM Agents # Skill: Eliminate/Automate/Delegate Triage Capability Domain: Process Engineering Technology Stack: AWS Lambda, Guardrails, LLM Agents ## Recipe 1. Work the Action Register (one row per constraint from the Cost of Delay Ranking) in impact order — don't fill "automate" before answering "can this step be removed" in writing. 2. Eliminate if the step is stale policy, a duplicate check, or pure handoff queue with no work. 3. Automate if mechanical and safe to retry. Default: one Lambda plus one Guardrail. 4. Delegate only if judgment remains that a Guardrail cannot encode. Write the agent's scope in the same row. Do not invent an agent catalog from the AI matrix. 5. The AI Opportunity Prioritization Matrix may mark where automate/delegate could apply. It never skips eliminate. 6. On the same row, tag cause layers and a route. A constraint may carry more than one tag (environment and knowledge and individual). Classification is not disposal — keep every applicable tag. ## Cause tags - dE (environment): tool, data, process, incentive, time, or authority. Default owner is process/tooling — not a course. - dK (knowledge/skill): people do not know or cannot yet do the work. Trainable or selectable; not a Lambda. - dI (individual): selection, capacity, or motivation. Not a lesson and not a bot. "People doing it wrong" is not automatically dK. If they know the right move and the environment punishes it, that slice is still dE. If they will not or cannot, that slice is dI. ## Routes (receiving playbook / owner) Write one route per tag on the row. Do not invent a second register. \| Tag + decision \| Route \| \|----------------\|-------\| \| dE + eliminate \| Drop the step. No receiving playbook. \| \| dE + process/tooling change (policy, required check, incentive, buy/configure a tool) \| Process/tooling owners. Not AI SDLC by default. \| \| dE + automate or delegate (step must stay; encode or hand to an agent) \| AI SDLC candidate only. \| \| dK \| Team Upskill Engine input: ranked, evidenced gap candidates (stage, clock, unit, n, role). TUE still builds Areas of Performance, master-performer patterns, and evidence scoring. This playbook does not author modules. \| \| dI \| Staffing / selection. Out of both AI SDLC and Team Upskill Engine curriculum. \| ## Row contract Each Action Register row records: finding, eliminate/automate/delegate decision + rationale, cause tags (multi), route per tag, and the evidence pointer (clock, unit, sample size). ## Escalate - #1 impact constraint where eliminate and automate are both ruled out — flow redesign, not a tool. ## Pitfalls - Reaching for automation or an agent before ruling out elimination. - Treating the AI matrix as an implementation backlog. - Mapping every dE row to AI SDLC. - Authoring Team Upskill Engine modules or a Roles & Performance Map here. - Forcing a single cause tag on a mixed bottleneck.
GitHub Actions CI/CD	DevOps / CI-CD	GitHub Actions, OIDC	Delivery Constraint & Opportunity Analysis	Read the 'GitHub Actions CI/CD' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: DevOps / CI-CD Technology stack: GitHub Actions, OIDC # Skill: GitHub Actions CI/CD Capability Domain: DevOps / CI-CD Technology Stack: GitHub Actions, OIDC Linked Activities: Deploy via GitHub Actions ## Skip when Lake Scope Contract `ci` is not `github_actions`. ## Recipe 1. Workflows already live in the starter kit: `.github/workflows/deploy.yml` on push to `main` (and `workflow_dispatch`). `permissions: { id-token: write, contents: read }`. Do not invent a second pipeline in the clone. 2. Assume AWS role via `aws-actions/configure-aws-credentials` with OIDC. No `AWS_ACCESS_KEY_ID` secret. 3. Steps: pytest (`pandas` in root `requirements.txt` if Streamlit unit tests import it) → `cdk deploy --all --require-approval never`. Print stack outputs to `$GITHUB_STEP_SUMMARY`. IAM `simulate-principal-policy` smoke test that the Streamlit task role can `s3:ListBucket`/`s3:GetObject` on the curated bucket. 4. OIDC trust — both `sub` shapes. GitHub Actions ID tokens often emit `repo:{org}@{ORG_ID}/{repo}@{REPO_ID}:ref:refs/heads/main`, not only `repo:{org}/{repo}:`. `DeployStack` must allow both. Template: starter `infra/ops_lake/deploy_stack.py`. 5. Chicken-and-egg:* laptop `cdk bootstrap` then one sandbox `cdk deploy OpsLakeDeploy` (or `--all`) to mint `DeployRoleArn`. Put that ARN in repo secret `AWS_DEPLOY_ROLE_ARN`. Thereafter shared env is GHA only. 6. A second workflow `populate-lake.yml` (STEP 2) fills data — do not confuse it with deploy. Secret for GitHub API: `OPSLAKE_GITHUB_PAT` (scopes `repo`, `read:org`). Never name a repo secret `GITHUB_` — GitHub rejects that prefix. Template: starter `.github/workflows/populate-lake.yml`. ## Copy-this: IAM trust conditions (DeployStack) Trust `token.actions.githubusercontent.com` with: - `sub` like `repo:{org}/{lake_repo}:` and - `sub` like `repo:{org}@/{lake_repo}@:` - `aud` = `sts.amazonaws.com` ## Pitfalls - Trusting only `repo:org/repo:` — AssumeRoleWithWebIdentity fails on ID-qualified `sub`. - Naming secrets `GITHUB_TOKEN` / `GITHUB_PAT`. - Triggering deploy on every branch. - Standing up GitLab CI in the same account. - Laptop `cdk deploy` to the shared account after OIDC exists.
GitLab CI/CD	DevOps / CI-CD	GitLab CI, id_tokens OIDC	Delivery Constraint & Opportunity Analysis	Read the 'GitLab CI/CD' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: DevOps / CI-CD Technology stack: GitLab CI, id_tokens OIDC # Skill: GitLab CI/CD Capability Domain: DevOps / CI-CD Technology Stack: GitLab CI, id_tokens OIDC Linked Activities: Deploy via GitLab CI ## When to use Lake Scope Contract `ci` is `gitlab_ci`. Skip this skill if the lake repo lives on GitHub. ## Copy-this Starter file: `.gitlab-ci.yml.example` in `https://github.com/FeatureFactory-io/ops-lake-starter`. Copy to `.gitlab-ci.yml` only if `ci: gitlab_ci`. Do not also keep a live GitHub `deploy.yml` against the same AWS account. ## Chicken-and-egg (parity with GitHub Actions) 1. Laptop, same region as the contract: `cdk bootstrap` then one `cdk deploy OpsLakeDeploy` to mint the GitLab OIDC IAM role. Read `DeployRoleArn` from stack outputs. 2. GitLab project → Settings → CI/CD → Variables → `AWS_DEPLOY_ROLE_ARN` (masked). Never `AWS_ACCESS_KEY_ID`. 3. Trust `aud` = `https://gitlab.com` (or this GitLab instance URL) and the project `sub` (`project_path:{group}/{project}:ref_type:branch:ref:main`). 4. After that, never `cdk deploy` a shared env from a laptop. ## Recipe 1. `.gitlab-ci.yml`: a `deploy` stage with `rules: if: $CI_COMMIT_BRANCH == "main"`, using GitLab's `id_tokens` block to mint an OIDC token and assume an AWS role — no `AWS_ACCESS_KEY_ID` CI/CD variable. 2. `id_tokens`: ```yaml id_tokens: GITLAB_OIDC_TOKEN: aud: https://gitlab.com ``` Then `aws sts assume-role-with-web-identity --role-arn $AWS_DEPLOY_ROLE_ARN --role-session-name gitlab-deploy --web-identity-token $GITLAB_OIDC_TOKEN --duration-seconds 3600`. 3. Steps: pytest → `cdk synth` → `cdk diff` → `cdk deploy --require-approval never`, with `when: manual` in front of the production deploy job. Fail the job if `cdk diff` is not empty and you have not approved the manual job — do not invent a line-count number. 4. Register a GitLab Environment (`production`) against the deploy job so GitLab's environment view shows current deployment state. 5. After first pipeline, record `DeployRoleArn`, webhook URL, `StreamlitMartUrl` in `docs/deploy-manifest.yaml`. 6. Prove: a `main` pipeline log shows `AssumedRole` / successful `cdk deploy`, not an AccessKey login. ## Pitfalls - This and GitHub Actions CI/CD are alternative paths to the same outcome — running both against the same AWS account invites split-brain deploys; pick the one matching where the repo actually lives, don't stand up the other "just in case." - Skipping the laptop mint: GitLab OIDC cannot assume a role that does not exist yet.
Huginn Browser Automation	Automation	Huginn, Browser Automation	Delivery Constraint & Opportunity Analysis	Read the 'Huginn Browser Automation' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Automation Technology stack: Huginn, Browser Automation # Skill: Huginn Browser Automation Capability Domain: Automation Technology Stack: Huginn, Browser Automation Linked Activities: Configure Huginn for Automated Reporting ## Recipe 1. Check `../huginn` for an existing Agent/Scenario close to what's needed before creating one from scratch — most refresh-on-a-schedule needs already have a near-identical precedent there. 2. Configure through the Huginn web UI: create/update the Agent, set its schedule, wire it into the target Scenario. Record the Agent's name and purpose in this playbook's own notes, not just in Huginn — there's no IaC diff to review later. 3. Trigger the Agent's dry-run/"run now" action once before trusting its schedule — Huginn Agents fail silently on a schedule if a dependency (an API token, an upstream Agent) breaks. ## Pitfalls - This whole activity is a flagged stopgap: don't let a manually-configured Agent quietly become permanent infrastructure — note it as a future-MCP-connector candidate every time it's touched.
Jira Flow Extract	Data Engineering	Jira REST, JQL, Changelog	Delivery Constraint & Opportunity Analysis	Read the 'Jira Flow Extract' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Engineering Technology stack: Jira REST, JQL, Changelog # Skill: Jira Flow Extract Capability Domain: Data Engineering Technology Stack: Jira REST, JQL, Changelog ## When to use Scope Contract `sources` includes `jira`. Skip entirely when it does not. This skill is the extract contract for issue lead time and cycle time. Webhook-only or snapshot-only pulls are not enough. ## What to persist (minimum) 1. Issue snapshot per key: issue type, current status, assignee, `created`, `updated`, and `resolutiondate` stored as `closed_at`. Unresolved issues have a null `closed_at`. 2. Status timeline: one row per contiguous visit to a status (`status`, `entered_at`, `exited_at`). The last segment stays open (`exited_at` null). 3. Watermark: last `updatedDate` (or equivalent cursor) so incremental pulls refresh both snapshot and timeline. Optional fields (team, sprint, story points) may land in the same snapshot. They are not the clock for lead or cycle. Suggested contract views when `jira` is scoped: `jira_issues`, `jira_status_segments`. Derive names as `{source}_{entity}` per the Scope Contract. Do not invent a third clock table. ## Extraction recipe 1. Scope JQL to a parameterized project key (or keys listed in the contract). Never unbounded JQL — Cloud rejects it. When no watermark exists, default a bounded `updatedDate` window (for example 365 days), then page forward. 2. Incremental: `project = {KEY} AND updatedDate >= '{watermark}' ORDER BY updated ASC`. 3. Cloud: cursor pagination (`enhanced_search_issues` / `nextPageToken`). Server / Data Center: `startAt` offset. Page size about 100. 4. Request `expand=changelog` on the search, or fetch changelog per issue. Keep items where `field == status`. Sort histories by `created`. 5. Build segments: - Initial status = `fromString` of the first status change, else the current status name. - First segment `entered_at` = issue `created`. - Each status change closes the prior segment (`exited_at` = change time) and opens the next. - Final segment has `exited_at` null. 6. Normalize all timestamps to UTC and store them consistently (all naive UTC or all UTC-aware — pick one). 7. Write unmodified JSON to the raw prefix, then Parquet as the next BPE activity. Omit Hive partition keys (`source`, `dt`) from the Parquet body. ## Lead time vs cycle time (compute from the extract) Do this in SQL or the transform. Do not re-hit Jira at analysis time for the clock. \| Metric \| Start \| End \| Unit \| Cohort \| \|--------\|--------\|-----\|------\|--------\| \| Lead time \| issue `created` \| `resolutiondate` (`closed_at`) \| business days (Mon–Fri, fractional) \| issues resolved in the window \| \| Cycle time \| earliest `entered_at` whose status is in the configured Started set \| same `closed_at` \| same business-day clock \| same cohort, only if Started was entered \| Business days: elapsed Mon–Fri only; include partial days by second overlap; return 0 when end ≤ start. Started is a contract parameter, not a hardcoded display name. Record status names or IDs in the Scope Contract (example convention: case-insensitive `In Progress`). Teams that work in `In Development` or `Active` must map those names. A single hard-coded string will silently drop most of the cohort. ## Rules - Done for these clocks is `resolutiondate`, not “last transition to Done”. Those timestamps can diverge. - Cycle start is the first Started entry, not the last stint, not the sum of active segments. Reopens do not reset the clock under this definition. - Issues that never entered Started are excluded from cycle (not scored as zero). - Time-in-status / journey charts may use calendar hours. Do not mix that unit with lead/cycle business days. - Incremental sync only refreshes issues with `updated >= watermark`. Old tickets need a periodic bounded backfill. - Sprint report / velocity snapshots (Agile board reports) are a parallel track. Never use them as the lead/cycle clock. ## Pitfalls - Search `expand=changelog` can truncate long histories. For accurate cycle time, paginate `GET /issue/{key}/changelog` on high-churn issues. - Cloud `search_issues` with `startAt` is deprecated — use cursor search. - Treating current status as the whole timeline (no changelog) makes cycle time a guess. - Using calendar days for lead/cycle KPIs while journey uses hours, then comparing the numbers. - Inferring “started” from the first non-backlog column without writing the Started set in the contract.
MCP-Driven Conversational Analytics	AI Tooling	Model Context Protocol, Claude Desktop	Delivery Constraint & Opportunity Analysis	Read the 'MCP-Driven Conversational Analytics' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: AI Tooling Technology stack: Model Context Protocol, Claude Desktop # Skill: MCP-Driven Conversational Analytics Capability Domain: AI Tooling Technology Stack: Model Context Protocol, Claude Desktop Linked Activities: EDA with MCP and Claude Desktop ## Recipe 1. MCP server exposes Athena query execution against workgroup `ops-lake-analysts`, scoped to the contract `views` in `ops_catalog` only — never grant it raw-table or cross-database access. There is no fixed set of four GitLab/Jira views. 2. Ask the question in plain language; before trusting the answer, read back the SQL the assistant ran — an unread query is an unverified claim. Use `$.payload.*` on backfill rows. 3. Use this track first for "what changed" and "does X still hold" questions — then move anything that will inform a real decision into the Pandas/Jupyter track. 4. Write every finding worth keeping into the Claude Desktop MCP Findings Notes artifact in the same session. ## Escalate - Any request to grant this connector write access, or access beyond the contract views — Data Platform Engineer first. ## Pitfalls - Treating a conversational answer as final rather than a hypothesis.
Metric Render Catalog	Analytics Communication	Athena, Streamlit, Jupyter	Delivery Constraint & Opportunity Analysis	Read the 'Metric Render Catalog' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Athena, Streamlit, Jupyter # Skill: Metric Render Catalog Capability Domain: Analytics Communication Technology Stack: Athena, Streamlit, Jupyter ## Purpose A portable list of ready-made metrics and how to render them. Use during Look until Trusted and mart pages. This catalog does not replace Cost of Delay / impact scoring (`people × touch + downstream × wait`). The reconstructed cycle remains the opening visual for Tell the Data Story. ## When a view is missing Only chart metrics whose contract `views` exist. Do not invent joins across sources without an explicit key (issue key, PR number, commit SHA). ## Starter mart tabs (Streamlit) When Present Findings uses Streamlit, instantiate the tab pack in skill Present Findings with Streamlit. Skip a tab whose required views are absent. Map families → tabs: \| Tab \| Families on that tab \| \|-----\|----------------------\| \| Commits \| VCS velocity \| \| Work items \| Issue flow \| \| Changes \| Merge-request / pull-request flow \| \| Pipelines \| CI health \| \| Load \| Load signals \| \| Defects \| Defect flow \| \| Sprints \| Sprint planning \| Those tabs are drill-down. They are not the stakeholder opening visual. ## Metric families ### Issue flow (Jira views, if scoped) - Closed / day, touched / day (resolved vs updated). - Lead time: business days `created` → `resolutiondate`; cohort = resolved in window. Show count, avg, median, min, max. - Cycle time: business days first Started segment → `resolutiondate`; exclude never-started. Same distribution stats. - Time-in-status: calendar hours per status (open segment ends at now). Journey strip, not a Pulse KPI. Definitions: skill Jira Flow Extract. ### VCS velocity (commit views) - Commits / day, active authors, author share, conventional-commit type mix if messages follow that convention. ### Merge-request / pull-request flow - Opened / merged / day. - MR cycle: wall-clock hours `created` → `merged` (merged in window). Median, mean, min, max, n. - Optional source-branch → trunk band (avg + min/max) when a branch convention is in the contract. - Integrator vs reviewer series are separate roles (assignments ≠ approvals). ### CI health (workflow / pipeline views) - Failure rate, status-by-day stack, duration trend, top failing jobs or reasons. ### Sprint planning (only if Agile snapshots were extracted) - Completed points, committed vs delivered, rolling average, unestimated share. Separate from issue lead/cycle. Do not use sprint reports as the flow clock. ### Defect flow (bug/defect types if present) - Opened vs closed, time-to-target-status, open-age buckets. ### Load signals (commit timestamps) - Long-day / weekend session share. Risk indicators, not performance scores. ## Render pairings \| Pattern \| Best render \| Notes \| \|---------\|-------------\|--------\| \| KPI strip \| 4–6 period deltas \| Inverse color when lower is better (lead/cycle, failure %, age) \| \| Daily throughput \| labeled bar or area \| Zero-fill missing days \| \| Duration trend \| line + points \| Hours or days; optional min–max band \| \| Part-to-whole \| donut \| Author share, failure reasons \| \| Ranked people or jobs \| horizontal bar \| Integrators, reviewers, failing jobs \| \| Workflow wait \| single-row stacked H-bar \| Time-in-status, left-to-right by configured workflow order \| \| Drill-down \| table + deep link \| Always show sample size n \| ## Shared UX - Windows: 7 / 14 / 30 calendar days (or closed-sprint count for sprint metrics). - Period-over-period: fetch `2 × window` and split, or use an explicit prior offset. - Empty states: say "no resolved issues in window" (or equivalent). Do not draw a zero cycle as if work happened. - Feature-path / single-stage charts are look-until-trusted checks, not the stakeholder opening visual. ## Pitfalls - Equating issue lead/cycle (business days) with MR created→merged (hours). - Using the mean of daily averages as the exec KPI (unweighted by volume). Prefer per-item median + n. - Hard-coding one project's status order or issue-type list in this catalog. - Ranking impact by p90 duration alone (that is Cycle Impact Scoring's job). - Treating the starter tab list as the opening story.
Populate the Lake	Data Engineering	GitHub Actions, Lambda, Glue, Athena	Delivery Constraint & Opportunity Analysis	Read the 'Populate the Lake' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Engineering Technology stack: GitHub Actions, Lambda, Glue, Athena # Skill: Populate the Lake Capability Domain: Data Engineering Technology Stack: GitHub Actions, Lambda, Glue, Athena Linked Activities: Backfill Historical GitHub Events, Catalog with AWS Glue, Present the Catalog via Athena ## When to use After STEP 1 GHA has deployed stacks. Webhooks only catch the future. Constraint analysis and cycle-time EDA need closed/merged history. ## Recipe 1. Repo secret `OPSLAKE_GITHUB_PAT` (`repo`, `read:org`). Never `GITHUB_`. 2. Workflow `.github/workflows/populate-lake.yml` (`workflow_dispatch` + daily cron). Template: starter kit `.github/workflows/populate-lake.yml` (`https://github.com/FeatureFactory-io/ops-lake-starter/blob/main/.github/workflows/populate-lake.yml`). 3. Job steps (in order): - Sync PAT into Secrets Manager `ops-lake/github-api-token`. - Optionally reset Glue tables + curated prefixes when re-crawling a broken catalog. - Invoke `GithubBackfillFn` with `--invocation-type Event` (async). Sync CLI invoke times out ~3 minutes; the function needs up to 10 minutes. - Poll CloudWatch `/aws/lambda/GithubBackfillFn` for `GithubBackfillFn written=N` with N>0. - Run `scripts/sync_raw_to_curated.py` to batch-invoke `ParquetTransformFn` (do not wait on SQS). - Start each `{view}_crawler`; wait until State=READY. - `scripts/create_athena_views.py` — LIMIT 10 proof per contract view; skip views with no Glue table. 4. Do not* run these scripts from a laptop against the shared account. ## Pitfalls - GitHub issues/pulls API defaults to `state=open`. Without `state=all` the lake has zero closed issues and cycle time is empty. - Waiting on SQS after a bulk backfill — invoke the transform Lambda directly.
Present Findings with Jupyter	Analytics Communication	Jupyter, Plotly	Delivery Constraint & Opportunity Analysis	Read the 'Present Findings with Jupyter' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Jupyter, Plotly # Skill: Present Findings with Jupyter Capability Domain: Analytics Communication Technology Stack: Jupyter, Plotly ## When to use Insights Communicator picked Jupyter as the story surface. ## Template Open starter (and live lake) `notebooks/published-findings.ipynb`. Kernel: repo `.venv` via `python -m ipykernel install --user --name opsdl --display-name "Python (opsdl .venv)"`. Select Python (opsdl .venv). Notebook root = lake repo so `streamlit/data` resolves. Restart & Run All. Do not start a blank notebook. ## Recipe (this order) 1. Delivery cycle — all BizDevTestSecOps stages. Each card shows effort (`people_in_role × touch_time`), wall-clock (touch + wait), and impact (effort + people_downstream × wait). Measured vs assumed labels. YAML: `streamlit/data/cost_of_delay.yaml` + `role_capacity.yaml`. Renderer: `streamlit/story_visuals.py` → `cycle_figure`. 2. Opportunity quadrant — expected efficiency gain vs implementation effort S–XL. Low hanging fruit = high impact AND AI-yes AND low effort. Cells are opportunity names, not agents. YAML: `streamlit/data/ai_opportunities.yaml` → `quadrant_figure`. 3. Deficiency register — Action Register table plus overlapping dE / dK / dI (multi-tag) and routes. Copy CAS triage; do not re-classify. - dE + eliminate → drop - dE + process/tooling → process/tooling owners (not AI SDLC) - dE + automate or delegate → AI SDLC candidate only - dK → Team Upskill Engine input (stage, clock, unit, n, role). Do not author modules. - dI → staffing / selection YAML: `streamlit/data/action_register.yaml`. Skill Eliminate/Automate/Delegate Triage → Cause tags / Routes. 4. Promoted stage detail — only `streamlit/data/promoted_eda.yaml` rows. Empty file (`rows: []`) is still correct until activity Look until Trusted promotes survivors. The two opening visuals plus the register still satisfy the TSY floor. Do not dump Metric Render Catalog. Do not treat empty promoted-eda as a bug. 5. Starter mart tabs (drill-down, never first). Skip-when is for missing views; if the view exists, run Athena (shared `streamlit/tab_athena.py`), pin `QueryExecutionId`, empty cohort names the window. Do not leave `print("Instantiate: …")` as the tab body. Compute notes live on skill Present Findings with Streamlit → Starter mart tabs — do not invent a second formula. Order: Commits, Work items, Changes, Pipelines, Load, Defects, Sprints. Median + n. Never mix issue lead/cycle (business days) with MR hours. Live GitHub-only lake (opsdl): instantiate Commits, Work items (volume only — omit lead/cycle without `jira_status_segments`), Changes (MR hours, not issue days), Pipelines (top failing = workflow name; job-level extract is not in the lake), Load (risk signal). Skip Defects and Sprints unless those views exist. 6. Pin Athena `QueryExecutionId` in markdown for any measured number. Numbers come from ranking YAML, not a fresh extract. ## Pitfalls - AWS login refresh is not Athena AccessDenied. Local Jupyter/`awswrangler` can fail with `AccessDeniedException` on `CreateOAuth2Token`, then `LoginRefreshRequired`: "The refresh token has expired" / "Please reauthenticate using `aws login`". Wrangler never reached `StartQueryExecution`. This is credential session expiry, not lake IAM / workgroup deny. Procedure: (1) terminal `aws login` (or this org's equivalent `aws sso login`); (2) confirm `aws sts get-caller-identity` matches `docs/lake-scope-contract.yaml` `aws_account` (live opsdl: `411113550285`); (3) Restart the Jupyter kernel, then Restart & Run All — boto3 clients in a running kernel keep the dead token; (4) the login credential provider also needs `pip install 'botocore[crt]'` (opsdl `requirements-eda.txt`). - Mart tabs must query Athena when contract views exist. Skip-when is for missing views. If the view exists, run Athena (shared `streamlit/tab_athena.py`), pin `QueryExecutionId`, empty cohort names the window. Do not leave `print("Instantiate: …")` as the tab body. - `streamlit/data/promoted_eda.yaml` `rows: []` is still correct until activity 398 promotes Look-until-Trusted survivors. TSY floor is still cycle + quadrant + deficiency register. Do not dump Metric Render Catalog. Do not treat empty promoted-eda as a bug in activity 254. - Opening with a tab, Feature Cycle Time, or a contributor leaderboard. - Exclusive pie of causes (tags overlap). - Turning dK rows into a curriculum. - Agent / Copilot product names on the quadrant.
Present Findings with Power BI	Analytics Communication	Microsoft Power BI	Delivery Constraint & Opportunity Analysis	Read the 'Present Findings with Power BI' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Microsoft Power BI # Skill: Present Findings with Power BI Capability Domain: Analytics Communication Technology Stack: Microsoft Power BI ## Skip when The org has no Power BI tenant. Do not add Power BI to CDK. ## Recipe 1. Same narrative: reconstructed cycle first, then impact/AI matrix, then stage detail. 2. Connect to the already-queryable catalog if the org already has a PBI Athena/Glue connector; otherwise skip. 3. Publish from proven ranking artifacts, not from a new exploration. ## Pitfalls - Introducing a new BI product to tell this story. - Re-deriving impact numbers inside PBI.
Present Findings with QuickSight	Analytics Communication	Amazon QuickSight	Delivery Constraint & Opportunity Analysis	Read the 'Present Findings with QuickSight' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Amazon QuickSight # Skill: Present Findings with QuickSight Capability Domain: Analytics Communication Technology Stack: Amazon QuickSight ## Skip when No QuickSight subscription. Do not block Tell the Data Story on QuickSight. ## Recipe 1. Same narrative as other presentation skills: reconstructed cycle first, then impact/AI matrix, then stage detail. 2. Athena data source; SPICE refresh ≤ crawler cadence. 3. Publish from proven ranking artifacts, not from a new exploration. ## Pitfalls - Leading the story with QuickSight when the Streamlit mart already exists and was chosen. - Standing up QuickSight in CDK. This skill uses an existing subscription only.
Present Findings with Streamlit	Analytics Communication	Streamlit, ECS Fargate, ALB	Delivery Constraint & Opportunity Analysis	Read the 'Present Findings with Streamlit' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Analytics Communication Technology stack: Streamlit, ECS Fargate, ALB # Skill: Present Findings with Streamlit Capability Domain: Analytics Communication Technology Stack: Streamlit, ECS Fargate, ALB ## When to use Insights Communicator picked the existing mart as the story surface. ## Templates (starter + live lake) Do not scaffold empty pages. Customize: - `streamlit/pages/0_Delivery_Cycle.py` — effort / wall-clock / impact - `streamlit/pages/1_Opportunity_Quadrant.py` - `streamlit/pages/2_Deficiency_Register.py` — dE/dK/dI - `streamlit/pages/3_Stage_Detail.py` — `promoted_eda.yaml` only - Tabs `4_Commits.py` … `10_Sprints.py` (skip-when in `tab_pages.py`) - YAML in `streamlit/data/` - Dockerfile must `COPY data data/` Look-until-trusted: `11_Feature_Cycle_Time.py`, `12_Lake_Explorer.py` — never first. ## Recipe 1. Pages on the ECS+ALB mart (never App Runner): reconstructed-cycle swimlane first (three metrics), then the opportunity quadrant, then the deficiency register (Action Register table: finding + decision + dE/dK/dI + receiver), then stage detail. 2. Numbers, tags, and routes come from `streamlit/data/.yaml`, not a fresh EDA and not a new classification. Receivers are named only: AI SDLC* (dE automate/delegate), process/tooling (other dE), Team Upskill Engine (dK candidates), staffing (dI). Do not author modules on the mart. 3. After the story pages, instantiate the Starter mart tabs below. A tab is a drill-down, not the opening visual. Skip via `tab_is_skipped` against contract views. 4. Stage-detail and tab charts use skill Metric Render Catalog pairings. Label units. Issue lead/cycle (business days) and MR cycle (hours) stay on separate charts. 5. Contributor charts: name the role (author / integrator / reviewer). Show n. Do not treat assignment counts as approvals. 6. Exec duration KPIs: median + n. Do not caption a mean of daily averages as "the" cycle time. 7. Browser-verify the story path end to end (cycle → quadrant → register → a stage), then each tab that was instantiated. A loading-skeleton screenshot is not verification. ## Starter mart tabs A portable inventory. Skip a tab when every required Scope Contract `view` for that tab is absent. Do not invent joins across sources without an explicit key (issue key, change number, commit SHA). Do not hard-code a tenant, board, repo, project key, or status list — read those from the contract. Skip-when vs query. Skip-when is for missing views. If the view exists, run Athena (shared `streamlit/tab_athena.py`), pin `QueryExecutionId`, empty cohort names the window. Do not leave `print("Instantiate: …")` as the tab body. Live GitHub-only lake (opsdl). Instantiate Commits, Work items (volume only — omit lead/cycle without `jira_status_segments`), Changes (MR hours, not issue days), Pipelines (top failing = workflow name; job-level extract is not in the lake), Load (risk signal). Skip Defects and Sprints unless those views exist. Shared rules (all tabs) - Windows: 7 / 14 / 30 calendar days (sprint tab may use closed-sprint count instead). - Period-over-period: fetch `2 × window` and split, or use an explicit prior offset. Inverse color when lower is better. - Zero-fill missing calendar days on daily series. Empty state: say what cohort is empty (“no resolved work items in window”). Do not draw a zero duration as if work finished. - Duration KPIs: per-item median + n (optionally min/max). A mean of daily averages is unweighted by volume. - Definitions for issue clocks: skill Jira Flow Extract. Render pairings: skill Metric Render Catalog. ### Tab: Commits Required views. Commit / author facts from the VCS extract. Skip when. No commit view is scoped. \| Metric \| Compute \| \|--------\|---------\| \| Commits / day \| Count commit rows with `committed_at` (or equivalent) in the day. Zero-fill the window. \| \| Active authors \| Distinct author identities in the window (use the contract identity key, not display name alone). \| \| Author share \| Author commit count / window commit count. Donut or ranked bar. \| \| Type mix \| If messages follow a conventional-commit convention, bucket by type prefix; otherwise omit. \| Do not treat commit volume as delivery of a change. Bots: apply the contract filter; do not guess. ### Tab: Work items Required views. Issue facts plus changelog-derived status segments (skill Jira Flow Extract). Skip when. No issue view is scoped. If segments are missing, show volume KPIs only — omit lead, cycle, and time-in-status. \| Metric \| Compute \| \|--------\|---------\| \| Closed / day \| Count items with `resolutiondate` on that calendar day. \| \| Touched / day \| Count items with `updated` on that calendar day (not a substitute for closed). \| \| Lead time \| Cohort = resolved in window. Business days `created` → `resolutiondate`. Show count, avg, median, min, max. \| \| Cycle time \| Same cohort, exclude never-started. Business days first Started segment → `resolutiondate`. Started set is parameterized (contract / workflow), not a hardcoded name. \| \| Time-in-status \| Calendar hours per status; the open segment ends at now. Journey strip in configured workflow order — not a Pulse KPI. \| Do not use board sprint reports as this clock. Do not plot lead/cycle on the same unlabeled axis as MR hours. ### Tab: Changes Required views. Merge-request or pull-request facts (opened, merged, timestamps, actors). Skip when. No MR/PR view is scoped. \| Metric \| Compute \| \|--------\|---------\| \| Opened / day \| Count changes with `created_at` on that day. \| \| Merged / day \| Count changes with `merged_at` on that day. \| \| MR / PR cycle \| Cohort = merged in window. Wall-clock hours `created_at` → `merged_at`. Median, mean, min, max, n. \| \| Source → trunk band \| Optional. When the contract names a trunk / default-branch convention, group cycle by source-branch pattern; show avg + min/max. Omit if no convention is recorded. \| \| Integrators \| Distinct merge-clicker (or merge-commit author) counts. Label the role integrator. \| \| Reviewers \| Assigned-reviewer counts. Assignments, not approvals. Empty series usually means the extract never stored assignees. \| Author of the change ≠ integrator ≠ assigned reviewer. Do not combine those counts into one “contributor” bar. ### Tab: Pipelines Required views. Workflow / pipeline / job runs. Skip when. No CI view is scoped. \| Metric \| Compute \| \|--------\|---------\| \| Failure rate \| Failed runs / all terminal runs in the window (exclude cancelled if the contract says to). Inverse KPI color. \| \| Status-by-day \| Stacked counts of terminal status per calendar day. Zero-fill days. \| \| Duration trend \| Per-run duration (start → terminal). Line of daily median or p50; optional min–max. Label the unit. \| \| Top failing jobs or reasons \| Rank by failure count in the window. Horizontal bar. On a GitHub-only lake, top failing = workflow name; job-level extract is not in the lake. \| Do not treat a red pipeline as a work-item cycle-time input. ### Tab: Load Required views. Commit timestamps (same commit view as Commits is enough). Skip when. No commit timestamps are scoped. \| Metric \| Compute \| \|--------\|---------\| \| Long-day share \| Sessions (or commit clusters) whose local span exceeds the contract long-day threshold; share of authors or of sessions. \| \| Weekend share \| Commits (or sessions) on the contract weekend definition. \| \| Names under load \| Rank identities by long-day / weekend volume. Risk signal only. \| Caption as a risk signal, not a performance score. Do not open the mart on this tab. ### Tab: Defects Required views. Work items typed as bug/defect or an equivalent defect view in the contract. Skip when. The scoped issue types / views do not distinguish defects. \| Metric \| Compute \| \|--------\|---------\| \| Opened vs closed \| Created vs resolved counts in the window (daily or totals). \| \| Time-to-target-status \| Business days or hours from created (or first Seen) to the contract target status (e.g. Done). Parameterize the target; do not hard-code it here. \| \| Open-age buckets \| Still-open items: now − created (or now − first Seen), bucketed. Inverse color on aging KPIs. \| Same clock rules as Work items when using issue timestamps. Do not mix with MR hours. ### Tab: Sprints Required views. Agile sprint snapshots (committed vs completed points, dates). Skip when. No sprint snapshot was extracted. A board name in Jira is not enough — you need snapshot rows. \| Metric \| Compute \| \|--------\|---------\| \| Completed points \| Sum of completed (or delivered) points on closed sprints in the lookback. \| \| Committed vs delivered \| Side-by-side per closed sprint. \| \| Rolling average \| Mean completed points over the last N closed sprints (N from the window control). \| \| Unestimated share \| Items without points / items in the sprint snapshot. \| Separate from issue lead/cycle. Do not use sprint reports as the flow clock. ## Story vs tabs The reconstructed delivery cycle (all stages, effort / wall-clock / impact) is the opening story page. Next: opportunity quadrant, then the deficiency register, then stage detail. The register is not a starter tab. Tabs are look-until-trusted and stakeholder drill-down. Do not reorder the mart so Commits or Changes loads first. ## Pitfalls - Mart tabs must query Athena when contract views exist. Skip-when is for missing views. If the view exists, run Athena (shared `streamlit/tab_athena.py`), pin `QueryExecutionId`, empty cohort names the window. Do not leave `print("Instantiate: …")` as the tab body. - `streamlit/data/promoted_eda.yaml` `rows: []` is still correct until activity 398 promotes Look-until-Trusted survivors. TSY floor is still cycle + quadrant + deficiency register. Do not dump Metric Render Catalog. Do not treat empty promoted-eda as a bug in activity 254. - Leading with Feature Cycle Time detail instead of the reconstructed cycle. - Implementing new agent products on the dashboard. - A contributor leaderboard as the first screen. - Mixing clocks or omitting sample size. - Instantiating a tab whose contract views do not exist. - Hard-coding one tenant's repos, boards, issue types, or status names into the mart. - Re-tagging dE/dK/dI or turning dK rows into lesson outlines.
S3 Data Partitioning and Compression	Data Engineering	Amazon S3, Apache Parquet	Delivery Constraint & Opportunity Analysis	Read the 'S3 Data Partitioning and Compression' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Engineering Technology stack: Amazon S3, Apache Parquet # Skill: S3 Data Partitioning and Compression Capability Domain: Data Engineering Technology Stack: Amazon S3, Apache Parquet Linked Activities: Store Compressed and Partitioned in S3 ## Canonical layout - Raw: `s3://{raw}/{source}/{yyyy}/{mm}/{dd}/{event-id}.json` - Curated: `s3://{curated}/{table}/source={source}/dt={yyyy-mm-dd}/part-{uuid}.parquet` - `{table}` ∈ Scope Contract `views`. Two buckets. Never a single `s3://ops-lake/source=gitlab/dt=` layout. ## Recipe 1. `ParquetTransformFn` on ObjectCreated under raw prefix. Write Parquet with pyarrow bundled in the Lambda asset — not awswrangler (layer size / synth Docker). Unit synth uses CDK context `skip_bundling`. 2. Map GitHub event types onto contract tables (`push` → `github_commits`, `pull_request` → `github_pull_requests`, `issues` → `github_issues`, `workflow_run` → `github_workflow_runs`; backfill `kind` `commits`/`pulls`/`issues`/`workflow_runs`). Projects v2 via GraphQL poller → `github_project_items` when that poller is real. 3. Omit partition keys from the Parquet body. `source` and `dt` live only in the S3 path. Duplicating `source` in the file makes Glue report duplicate columns. 4. SQS buffer for webhooks. After backfill, do not wait on SQS — `scripts/sync_raw_to_curated.py` batch-invokes `ParquetTransformFn`. 5. If compression <5x vs JSON, stop and fix schema. 6. Lake buckets are SSE-KMS with S3 Bucket Keys (`bucket_key_enabled=True` in IngestionStack). Glue crawlers and Athena GetObject every Parquet part; without Bucket Keys those reads are KMS `Decrypt` per file. ## Pitfalls - One Parquet file per webhook event (webhook path). - SSE-KMS without S3 Bucket Keys — one-file-per-event plus crawler/Athena reads burns the 20k KMS Free Tier in hours. - `source` both as Hive partition and Parquet column. - Partitioning finer than `dt` without a query need.
Scope the Operations Lake	Discovery	YAML, GitHub CLI, AWS STS	Delivery Constraint & Opportunity Analysis	Read the 'Scope the Operations Lake' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Discovery Technology stack: YAML, GitHub CLI, AWS STS # Skill: Scope the Operations Lake Capability Domain: Discovery Technology Stack: YAML, GitHub CLI, AWS STS Linked Activities: Scope Sources, Org, and Environment ## When to use First activity of STEP 1. Do not model CDK stacks until `docs/lake-scope-contract.yaml` exists. ## Recipe 1. Clone https://github.com/FeatureFactory-io/ops-lake-starter (GitHub → Use this template). Do not invent `infra/` and do not copy the live `opsdl` lake. The clone already has `docs/lake-scope-contract.yaml` plus the four CDK stacks and GHA workflows. 2. Identify the host of the lake repo and the source systems that actually exist (github, gitlab, jira). Never add a source "just in case". 3. For a GitHub org, default entities are: `commits`, `pull_requests`, `issues`, `workflow_runs`, `project_items`. Drop any the org does not use. List org repos (`gh api orgs/{org}/repos`) and Projects v2 (`gh api graphql` organization.projectsV2). 4. Set `ci` to exactly one of `github_actions` \| `gitlab_ci` matching `host`. XOR. 5. Record `aws_account` from `aws sts get-caller-identity`, `aws_region`, `env` (`sandbox`\|`dev`\|`staging`\|`prod`), `lake_name`. 6. Record `lake_repo` (short name of the lake git repo; rename from `ops-lake-starter` if the clone is named differently) and `oidc_sub`. GitHub OIDC tokens use two `sub` shapes; DeployStack must trust both (see GitHub Actions CI/CD skill). 7. Derive Athena view names as `{source}_{entity}`. That list is the catalog contract later activities must implement. There is no fixed set of four GitLab/Jira views. 8. Fill the file below in the clone. Stop. The next activity is Model the Data Lake as CDK Stacks. 9. If `jira` is in `sources`, add the Jira flow keys below and follow skill Jira Flow Extract. Omit the whole block when jira is not scoped. ## Copy-this: `docs/lake-scope-contract.yaml` Template lives in the starter kit. Fill, do not invent from scratch: ```yaml org: YOUR_ORG # GitHub org, GitLab group, or company host: github # github \| gitlab sources: [github] # subset of: github, gitlab, jira github_entities: # omit this key if github not in sources - commits - pull_requests - issues - workflow_runs - project_items github_projects: [] # fill from Projects v2; empty if none repos: [] # org repo names in scope ci: github_actions # github_actions XOR gitlab_ci lake_repo: ops-lake-starter # git repo that hosts the CDK app # Trust both name-only and ID-qualified GitHub OIDC subs (see DeployStack). oidc_sub: repo:YOUR_ORG/ops-lake-starter:* aws_account: "000000000000" aws_region: us-east-1 env: sandbox # sandbox \| dev \| staging \| prod lake_name: ops-lake athena_database: ops_catalog athena_workgroup: ops-lake-analysts views: # derived; STEP 2 must create exactly these - github_commits - github_pull_requests - github_issues - github_workflow_runs - github_project_items buckets: raw: ops-lake-raw-{account_suffix} curated: ops-lake-curated-{account_suffix} athena_results: ops-lake-athena-results-{account_suffix} paths: raw: "s3://{raw}/{source}/{yyyy}/{mm}/{dd}/{event-id}.json" curated: "s3://{curated}/{table}/source={source}/dt={yyyy-mm-dd}/part-{uuid}.parquet" secrets: github_webhook: ops-lake/github-webhook-secret github_api_token: ops-lake/github-api-token ``` ## Jira flow keys (only when `jira` is in `sources`) Add these keys; extend `views` and `secrets`. Do not add them for a GitHub-only lake. ```yaml jira_project_keys: [] # parameterized JQL project keys; never unbounded jira_entities: - issues - status_segments started_statuses: # cycle-time start set (names or IDs) - In Progress # example convention only — replace with this org's Started statuses jira_edition: cloud # cloud \| server secrets: jira_api_token: ops-lake/jira-api-token # Also add to views: # - jira_issues # - jira_status_segments ``` Lead time = `created` → `resolutiondate` (business days). Cycle time = first `started_statuses` entry → `resolutiondate`. See Jira Flow Extract. ## Done when - Starter kit cloned (not opsdl). - File exists and `views` is non-empty. - `ci` is exactly one value. - `sources` lists only systems this org has. - `lake_repo`, `oidc_sub`, and secret names are filled. - If `jira` is scoped: `jira_project_keys`, `started_statuses`, and jira views are filled. ## Pitfalls - Hard-coding `gitlab_commits` / `jira_issue_transitions` for a GitHub-only org. - Standing up both GitHub Actions and GitLab CI against the same account. - Naming a GitHub Actions repo secret `GITHUB_*` — GitHub rejects that prefix. Use `OPSLAKE_GITHUB_PAT` and `AWS_DEPLOY_ROLE_ARN`. - Publishing or cloning the live `opsdl` lake as the template (real org, account, PAT, findings). - Scoping `jira` without a Started status set or without `status_segments` — cycle time will be empty or invented.
Serverless Data Ingestion	Data Engineering	AWS CDK, Lambda, EventBridge, API Gateway, Kinesis Firehose	Delivery Constraint & Opportunity Analysis	Read the 'Serverless Data Ingestion' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Data Engineering Technology stack: AWS CDK, Lambda, EventBridge, API Gateway, Kinesis Firehose # Skill: Serverless Data Ingestion Capability Domain: Data Engineering Technology Stack: AWS CDK, Lambda, EventBridge, API Gateway Linked Activities: Stand Up Serverless Ingestion from Scoped Sources, Backfill Historical GitHub Events, Backfill Historical Jira Issues and Status History ## Recipe 1. Read Scope Contract `sources`. Implement one Lambda per listed source. Do not implement the others. 2. GitHub (if scoped): `GithubWebhookFn` on HTTP API `/webhooks/github`. Verify `X-Hub-Signature-256` against Secrets Manager `ops-lake/github-webhook-secret`. Return 200; SQS for slow writes. 3. GitHub history (required for cycle time): `GithubBackfillFn` — issues and pulls with `state=all`, `per_page=100`, paginate Link headers. Wrap `{backfill, kind, repo, payload}`. Template: `infra/lambdas/github_backfill.py`. Timeout 10 min / 1024 MB. Invoke async from populate-lake. 4. GitLab (if scoped): `GitlabWebhookFn` on `/webhooks/gitlab`, `X-Gitlab-Token` vs `ops-lake/gitlab-webhook-secret`. 5. Jira (if scoped): `JiraPollFn` EventBridge `rate(5 minutes)`, cursor in DynamoDB `ops-lake-ingestion-cursors` PK `source`. This poller is not the lead/cycle extract. Historical issues, changelog status segments, parameterized Started set, and business-day lead/cycle live in skill Jira Flow Extract and activity Backfill Historical Jira Issues and Status History. Implement that path whenever `jira` is in `sources` and STEP 3/4 will score issue flow time. 6. Write unmodified JSON to `s3://{raw}/{source}/{yyyy}/{mm}/{dd}/{event-id}.json`. Parquet is the next activity. 7. `GithubProjectsPollFn` is a heartbeat until GraphQL pagination ships. Do not treat `github_project_items` as a populated Projects v2 feed. ## Copy-this: `infra/lambdas/github_webhook.py` Handler: verify HMAC, parse GitHub event, put JSON to raw bucket with key `{source}/yyyy/mm/dd/{delivery-id}.json`, return 200. Dedupe downstream on event id; do not reject redeliveries. ## Escalate - Payload > API Gateway 10MB. - Jira rate-limit twice in one day → raise interval, do not swallow. ## Pitfalls - Creating Jira/GitLab functions for a GitHub-only contract. - Fetching GitHub issues without `state=all` (default is open-only). - Treating a Jira current-status poll as cycle time (no changelog timeline, no `resolutiondate`).
Value Stream and Constraint Analysis	Process Engineering	Theory of Constraints, DevOps Three Ways	Delivery Constraint & Opportunity Analysis	Read the 'Value Stream and Constraint Analysis' skill from playbook 'Delivery Constraint & Opportunity Analysis'. Apply its guidance when assisting me. Capability domain: Process Engineering Technology stack: Theory of Constraints, DevOps Three Ways # Skill: Value Stream and Constraint Analysis Capability Domain: Process Engineering Technology Stack: Theory of Constraints, DevOps Three Ways ## Recipe 1. Read Scope Contract `views`. Anchor the five stages to those events, not a hardcoded GitLab/Jira set. 2. GitHub-org default join key: issue number / PR number / project item content (never timestamp proximity). - Biz: `github_issues` opened (Projects v2 `github_project_items` only after the GraphQL poller is real). - Dev: `github_pull_requests` opened → merged; commits in window. - Test: `github_workflow_runs` start → first `conclusion=success`. - Sec: security-gate job inside that run, or a dedicated scan workflow. - Ops: deploy `github_workflow_runs` start → complete. 3. If gitlab/jira views exist in the contract, use those events instead/in addition — do not invent joins across sources without an explicit key. 4. Feature-type issues (cycle-time cohort), not "every GitHub issue": - Include: labels `feature`, `enhancement`, `status-done`; titles `W\d+:`, `DIAGRAM W\d+:`, `[area:tool]`, `BPE-\d+` / `MIN-\d+` / `DSP-\d+` / `DTA-\d+`, scenario `LOG1.1:`. - Exclude: plain `bug` with none of those signals. - Classify in Python after Athena returns rows. 5. Hand off ranking to skill Cycle Impact Scoring (people×touch + downstream×wait). This skill maps stages; it does not rank by p90 alone. ## Pitfalls - Joining on timestamp proximity or on `repo` only. - Ranking with GitLab pipeline data when the lake only has GitHub views. - Empty cycle time because backfill used default `state=open`.
Analytical Pattern Recognition	Chart Design / Interpretation	—	EDA with Python, Pandas and Jupyter
Chart-Type Selection per Analysis Type	Chart Design	—	EDA with Python, Pandas and Jupyter
Data Analysis Sequencing	Problem Framing	—	EDA with Python, Pandas and Jupyter
Data Combination (Merge/Join/Concat)	Data Integration	pandas	EDA with Python, Pandas and Jupyter
Data Quality Assessment	Data Readiness	—	EDA with Python, Pandas and Jupyter
Descriptive Statistics and Ranking	Exploratory Analysis	pandas, numpy	EDA with Python, Pandas and Jupyter
Ensemble Modeling and Feature Importance	Predictive Modeling	scikit-learn	EDA with Python, Pandas and Jupyter
Feature Engineering and Transformation	Feature Engineering	pandas	EDA with Python, Pandas and Jupyter
Jupyter Notebook Storytelling	Communication	Jupyter	EDA with Python, Pandas and Jupyter
Missing Data Handling	Data Cleaning	pandas	EDA with Python, Pandas and Jupyter
Over-Plotting and Clutter Mitigation	Chart Construction	—	EDA with Python, Pandas and Jupyter
Pandas Data Structure Manipulation	Tabular Data Engineering	pandas, numpy	EDA with Python, Pandas and Jupyter
Plotly Visualization Engineering	Visualization Implementation	Plotly (plotly.express, graph_objects)	EDA with Python, Pandas and Jupyter
Predictive Experiment Design and Model Validation	Machine Learning Methodology	scikit-learn	EDA with Python, Pandas and Jupyter
Quantitative Scale and Reference-Line Design	Chart Design	—	EDA with Python, Pandas and Jupyter
Regression and Classification Modeling	Predictive Modeling	scikit-learn	EDA with Python, Pandas and Jupyter
Statistical Measures and Correlation Analysis	Statistics	scipy, pandas	EDA with Python, Pandas and Jupyter
Trellis and Multi-View Layout Design	Storybook Layout	—	EDA with Python, Pandas and Jupyter
Unsupervised Clustering	Predictive/Exploratory Modeling	scikit-learn	EDA with Python, Pandas and Jupyter
Visual Perception Literacy	Chart Design	—	EDA with Python, Pandas and Jupyter
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