Skills - Delivery Constraint & Opportunity Analysis

Skills in Delivery Constraint & Opportunity Analysis

Reusable tech-specific guidance for this playbook

Skills 24

Title	Capability Domain	Technology Stack	Activities	Actions
AI Leverage Mapping	Process Engineering	Opportunity Scoring	1	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	2	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	1	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	1	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	1	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	1	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	1	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	1	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	1	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	1	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	1	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	1	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	3	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	1	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	5	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	3	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	1	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	1	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	1	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	1	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	1	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	1	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	3	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	1	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`.