@geraldmaron/construct 1.0.0

package/skills/roles/data-engineer.pipeline.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-engineer.pipeline.md — Anti-pattern guidance for the Data-engineer.pipeline (pipeline) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-engineer.pipeline (pipeline) domain and counter-moves to avoid them.
+Applies to: cx-data-engineer.
+-->
+---
+role: data-engineer.pipeline
+applies_to: [cx-data-engineer]
+inherits: engineer.data
+version: 1
+---
+# Data Pipeline Engineer Overlay
+
+Additional failure modes on top of the data engineer core.
+
+### 1. Non-idempotent jobs
+**Symptom**: reruns duplicate records, skip records, or mutate state unpredictably.
+**Why it fails**: retries and backfills are normal operations, not edge cases.
+**Counter-move**: design idempotency keys, checkpoints, replay windows, and deduplication rules.
+
+### 2. Hidden failure states
+**Symptom**: jobs fail silently or require manual log archaeology.
+**Why it fails**: data consumers keep making decisions from stale or partial data.
+**Counter-move**: add freshness, volume, schema, latency, and error-rate monitors with owners.
+
+### 3. Contract drift
+**Symptom**: upstream fields change without downstream tests failing.
+**Why it fails**: data breaks at the consumer boundary.
+**Counter-move**: publish contracts and run compatibility checks before deploy.
+
+## Self-check before shipping
+- [ ] Reruns, retries, and backfills are idempotent
+- [ ] Freshness, volume, schema, latency, and error monitors exist
+- [ ] Data contracts and compatibility tests are present
+- [ ] Ownership and runbook are clear

package/skills/roles/data-engineer.vector-retrieval.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-engineer.vector-retrieval.md — Anti-pattern guidance for the Data-engineer.vector-retrieval (vector retrieval) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-engineer.vector-retrieval (vector retrieval) domain and counter-moves to avoid them.
+Applies to: cx-data-engineer, cx-ai-engineer.
+-->
+---
+role: data-engineer.vector-retrieval
+applies_to: [cx-data-engineer, cx-ai-engineer]
+inherits: engineer.data
+version: 1
+---
+# Vector Retrieval Engineer Overlay
+
+Additional failure modes on top of the data engineer core.
+
+### 1. Embeddings without lifecycle
+**Symptom**: documents are embedded once with no freshness, deletion, or re-indexing policy.
+**Why it fails**: retrieval serves stale or unauthorized context.
+**Counter-move**: define ingestion, chunking, metadata, freshness, deletion, and re-indexing rules.
+
+### 2. Similarity score as truth
+**Symptom**: the system trusts nearest neighbors without source filtering or confidence thresholds.
+**Why it fails**: plausible retrieval can be wrong, stale, or cross-tenant.
+**Counter-move**: combine vector search with metadata filters, SQL/file provenance, score thresholds, and citations.
+
+### 3. No retrieval evaluation
+**Symptom**: retrieval is judged from a few manual searches.
+**Why it fails**: recall and precision regress silently as the corpus changes.
+**Counter-move**: maintain query sets, expected documents, precision/recall checks, and latency budgets.
+
+## Self-check before shipping
+- [ ] Ingestion, chunking, metadata, deletion, and re-indexing are specified
+- [ ] Retrieval enforces ACL, tenant, and freshness filters
+- [ ] Results include source provenance and confidence handling
+- [ ] Retrieval evals cover precision, recall, and latency

package/skills/roles/data-engineer.warehouse.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-engineer.warehouse.md — Anti-pattern guidance for the Data-engineer.warehouse (warehouse) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-engineer.warehouse (warehouse) domain and counter-moves to avoid them.
+Applies to: cx-data-engineer.
+-->
+---
+role: data-engineer.warehouse
+applies_to: [cx-data-engineer]
+inherits: engineer.data
+version: 1
+---
+# Warehouse Engineer Overlay
+
+Additional failure modes on top of the data engineer core.
+
+### 1. Modeling for the first question
+**Symptom**: tables answer one dashboard but cannot support future slicing or audit.
+**Why it fails**: warehouse models become brittle semantic traps.
+**Counter-move**: define grains, dimensions, facts, slowly changing attributes, and ownership.
+
+### 2. Semantic duplication
+**Symptom**: the same metric exists in several SQL files with different filters.
+**Why it fails**: teams argue over numbers instead of decisions.
+**Counter-move**: centralize metric definitions and document denominator, exclusions, and freshness.
+
+### 3. Cost ignored
+**Symptom**: transformations are correct but expensive or slow at production volume.
+**Why it fails**: analytics reliability includes cost and latency.
+**Counter-move**: design partitions, clustering, incremental models, and retention explicitly.
+
+## Self-check before shipping
+- [ ] Grain, dimensions, facts, and ownership are documented
+- [ ] Metrics are centralized with denominators and exclusions
+- [ ] Incremental strategy, partitions, and retention are defined
+- [ ] Cost and latency are acceptable at expected volume

package/skills/roles/debugger.md

@@ -0,0 +1,68 @@
+<!--
+skills/roles/debugger.md — Anti-pattern guidance for the Debugger role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the debugger domain and counter-moves to avoid them.
+Applies to: cx-debugger.
+-->
+---
+role: debugger
+applies_to: [cx-debugger]
+inherits: null
+version: 1
+---
+# Debugger — Role guidance
+
+Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+
+
+### 1. Fixing the symptom
+**Symptom**: the patch makes the test pass or the error disappear without a clear statement of why it was happening.
+**Why it fails**: the cause re-emerges elsewhere, often with more blast radius than the original.
+**Counter-move**: explain the cause in one sentence before writing the fix. If you cannot, you are still debugging.
+
+### 2. Untested assumption
+**Symptom**: "it must be the cache" or "probably a race" stated as fact, never verified.
+**Why it fails**: the investigation follows the assumption down a dead end; the real cause escapes notice.
+**Counter-move**: for each hypothesis, name the experiment that would disprove it. Run the experiment before acting.
+
+### 3. Skipping reproduction
+**Symptom**: fix proposed based on a stack trace or a bug report, without reproducing the failure locally.
+**Why it fails**: the fix targets the author's mental model, not the actual failure. Often does not fix the bug.
+**Counter-move**: reproduce the failure. Confirm the fix makes the reproduction stop. Preserve the reproduction as a regression test.
+
+### 4. Noise-driven debugging
+**Symptom**: randomly adding logs, retries, or sleep() until the symptom goes away.
+**Why it fails**: the bug is masked, not fixed. The masked bug resurfaces later, worse.
+**Counter-move**: form a hypothesis. Add one targeted log or breakpoint that would confirm or deny it. Iterate.
+
+### 5. Believing the first error
+**Symptom**: acting on the first error in the log as the cause, when it is actually the downstream effect of something earlier.
+**Why it fails**: fixes the surface failure; leaves the upstream bug intact.
+**Counter-move**: read the log from the top. Find the earliest anomaly. Work forward from there.
+
+### 6. Scope leakage
+**Symptom**: the debugging session turns into a refactor, a cleanup, and a style pass.
+**Why it fails**: the fix is bundled with unrelated changes; reviewers cannot isolate the bug fix; regressions become harder to bisect.
+**Counter-move**: land the fix as a narrow diff. Bank any cleanup for a separate PR.
+
+### 7. Giving up at "intermittent"
+**Symptom**: a failure labeled "flaky" or "intermittent" and set aside without investigation.
+**Why it fails**: intermittent failures signal race conditions, timing dependencies, or resource leaks that will eventually cause a production incident.
+**Counter-move**: investigate every intermittent failure. Either find the race or isolate the environmental dependency.
+
+### 8. No regression test
+**Symptom**: the bug is fixed but no test is added that would have caught it.
+**Why it fails**: the same bug returns in six months, silently.
+**Counter-move**: add a test that fails against the broken code and passes against the fix. Keep it.
+
+## Self-check before shipping
+
+- [ ] Cause stated in one sentence before the fix
+- [ ] Each hypothesis tested before acting on it
+- [ ] Failure reproduced locally and reproduction preserved as a test
+- [ ] No speculative logs, retries, or sleeps in the fix
+- [ ] Earliest anomaly in the log is the starting point
+- [ ] Diff is narrow — fix only, no drive-bys
+- [ ] Intermittent failures investigated, not shelved
+- [ ] Regression test added alongside the fix

package/skills/roles/designer.accessibility.md

@@ -0,0 +1,43 @@
+<!--
+skills/roles/designer.accessibility.md — Anti-pattern guidance for the Designer.accessibility (accessibility) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the designer.accessibility (accessibility) domain and counter-moves to avoid them.
+Applies to: cx-accessibility.
+-->
+---
+role: designer.accessibility
+applies_to: [cx-accessibility]
+inherits: designer
+version: 1
+---
+# Accessibility Overlay
+
+Additional failure modes on top of the designer core.
+
+
+### 1. Accessibility as visual-only
+**Symptom**: focusing on color contrast and font size; ignoring keyboard navigation, screen readers, and motion.
+**Why it fails**: many users are blocked on surfaces the designer never tested.
+**Counter-move**: for every component, check keyboard-only path, screen-reader output, and reduced-motion behavior.
+
+### 2. ARIA as patch
+**Symptom**: sprinkling `aria-label`, `role=button` onto non-semantic markup to "make it accessible."
+**Why it fails**: ARIA is a override for semantic HTML, not a replacement; mis-applied ARIA reduces accessibility.
+**Counter-move**: use semantic elements first. Add ARIA only where semantics are insufficient and the override is correct.
+
+### 3. Automated-only compliance
+**Symptom**: passing axe/Lighthouse then declaring the surface accessible.
+**Why it fails**: automated tools catch ~30% of WCAG issues. Real barriers (focus order, meaningful labels, logical flow) pass automated checks while being unusable.
+**Counter-move**: combine automated scan with manual keyboard + screen-reader test. Document both.
+
+### 4. Motion without controls
+**Symptom**: scroll-triggered animations, auto-playing video, parallax effects with no reduce-motion path.
+**Why it fails**: triggers vestibular disorders; drives users away.
+**Counter-move**: honor `prefers-reduced-motion`. Provide pause controls for any auto-playing content.
+
+## Self-check before shipping
+- [ ] Keyboard-only path tested for every interactive element
+- [ ] Screen-reader output verified
+- [ ] Semantic HTML first; ARIA only where needed
+- [ ] Reduced-motion path exists and is tested

package/skills/roles/designer.md

@@ -0,0 +1,68 @@
+<!--
+skills/roles/designer.md — Anti-pattern guidance for the Designer role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the designer domain and counter-moves to avoid them.
+Applies to: cx-designer, cx-accessibility.
+-->
+---
+role: designer
+applies_to: [cx-designer, cx-accessibility]
+inherits: null
+version: 1
+---
+# Designer — Role guidance
+
+Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+
+
+### 1. Template defaults
+**Symptom**: the design looks like an unmodified Tailwind, shadcn, or Material page — centered hero, gradient blob, uniform card grid, one accent color.
+**Why it fails**: nothing about the output communicates product intent. It could be any app.
+**Counter-move**: pick an explicit visual direction before designing. Commit to typography, color, and layout choices specific to the product.
+
+### 2. Empty states as afterthought
+**Symptom**: empty, loading, and error states are absent from the design or shown as a single spinner.
+**Why it fails**: most users encounter the empty state first. A bad one signals the product is broken before it has started.
+**Counter-move**: design empty, loading, error, and end-of-list states as first-class screens. Each should teach the user what to do next.
+
+### 3. Hover-only affordances
+**Symptom**: primary actions are revealed only on hover, with no touch equivalent and no visible cue before the user hovers.
+**Why it fails**: unusable on touch devices; discoverability collapses on desktop too.
+**Counter-move**: primary actions are visible at rest. Hover can enhance, never gate.
+
+### 4. Accessibility bolted on
+**Symptom**: contrast, focus rings, keyboard paths, screen reader labels addressed only when a reviewer flags them.
+**Why it fails**: accessibility fixes late in the cycle are expensive and incomplete; some users get a worse product.
+**Counter-move**: treat contrast ratios, keyboard navigation order, and semantic structure as acceptance criteria, not polish.
+
+### 5. Uniform emphasis
+**Symptom**: every card, section, and action is rendered at the same visual weight.
+**Why it fails**: the user cannot tell what matters. Attention fails; scanning fails.
+**Counter-move**: use hierarchy — scale, weight, color, spacing — to express importance. One primary action per view.
+
+### 6. Motion for motion's sake
+**Symptom**: decorative transitions, parallax, and animated backgrounds that do not clarify flow or state.
+**Why it fails**: slows the interaction, distracts from content, fails reduced-motion preferences.
+**Counter-move**: motion should clarify — state change, origin-destination, or loading progress. Respect `prefers-reduced-motion`.
+
+### 7. Desktop-first, responsive later
+**Symptom**: the design is mocked at 1440, then "responsive breakpoints" are annotated as an afterthought.
+**Why it fails**: the mobile experience becomes a compressed desktop, not a designed experience.
+**Counter-move**: design the constrained view first. Expansion to larger viewports is additive, not reductive.
+
+### 8. Invisible system
+**Symptom**: every screen reinvents spacing, radius, shadow, and color values.
+**Why it fails**: the product feels inconsistent even when individual screens are fine. Engineering cannot implement cleanly.
+**Counter-move**: name the tokens — space, color, type, radius, motion — before designing. Use them.
+
+## Self-check before shipping
+
+- [ ] Visual direction is explicit, not default
+- [ ] Empty / loading / error states designed as first-class
+- [ ] Primary actions visible at rest, not hover-gated
+- [ ] Contrast, focus, keyboard order, semantic structure specified
+- [ ] One primary action per view; hierarchy expresses importance
+- [ ] Motion clarifies state; reduced-motion alternative specified
+- [ ] Smallest viewport designed first
+- [ ] Design tokens named and reused

package/skills/roles/engineer.ai.md

@@ -0,0 +1,49 @@
+<!--
+skills/roles/engineer.ai.md — Anti-pattern guidance for the Engineer.ai (ai) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the engineer.ai (ai) domain and counter-moves to avoid them.
+Applies to: cx-ai-engineer.
+-->
+---
+role: engineer.ai
+applies_to: [cx-ai-engineer]
+inherits: engineer
+version: 1
+---
+# AI Engineer Overlay
+
+Additional failure modes on top of the engineer core. Check your draft against each.
+
+
+### 1. Prompt tuning without evals
+**Symptom**: iterating on system prompts by eyeballing a handful of outputs.
+**Why it fails**: changes that look better on one example regress on three others you didn't look at.
+**Counter-move**: build a minimum eval set (10+ cases with expected shape) before editing prompts. Diff eval scores, not vibes.
+
+### 2. Silent model swaps
+**Symptom**: changing the model name in config without re-running evals or updating the system prompt.
+**Why it fails**: model families interpret instructions differently; what passed on Opus 4.7 may loop on Haiku 4.5.
+**Counter-move**: re-run evals on any model change. Pin the model ID in code, not just config.
+
+### 3. Context bloat
+**Symptom**: stuffing everything retrievable into the prompt because "more context is better."
+**Why it fails**: burns tokens, buries the instruction, and the model attends to noise. Cost scales linearly, quality does not.
+**Counter-move**: measure tokens per turn. Cut anything that doesn't change the output.
+
+### 4. Tool-use without guardrails
+**Symptom**: giving the model access to a tool with no schema validation or output shape checks.
+**Why it fails**: models produce plausible-but-malformed tool calls, which downstream code swallows or mis-routes.
+**Counter-move**: validate tool inputs and outputs at the boundary. Fail loud on schema violation.
+
+### 5. Treating the model as deterministic
+**Symptom**: writing code that assumes a specific token, phrase, or structure will come back every time.
+**Why it fails**: non-zero temperature varies; even temp=0 drifts across model versions.
+**Counter-move**: parse liberally, validate strictly. Treat outputs as probabilistic and always have a fallback path.
+
+## Self-check before shipping
+- [ ] Eval set exists and regressions are checked
+- [ ] Model ID is pinned; evals re-run on any model change
+- [ ] Prompt token count is measured and justified
+- [ ] Tool inputs/outputs validated at the boundary
+- [ ] No code path assumes exact output strings

package/skills/roles/engineer.data.md

@@ -0,0 +1,49 @@
+<!--
+skills/roles/engineer.data.md — Anti-pattern guidance for the Engineer.data (data) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the engineer.data (data) domain and counter-moves to avoid them.
+Applies to: cx-data-engineer.
+-->
+---
+role: engineer.data
+applies_to: [cx-data-engineer]
+inherits: engineer
+version: 1
+---
+# Data Engineer Overlay
+
+Additional failure modes on top of the engineer core.
+
+
+### 1. Pipeline without data contracts
+**Symptom**: producers and consumers agree only on column names, not on types, nullability, or semantics.
+**Why it fails**: a silent upstream change corrupts everything downstream. Bad data is invisible until someone notices a broken dashboard.
+**Counter-move**: define the contract (schema + nullability + units + primary-key semantics) and assert it at the pipeline boundary.
+
+### 2. No idempotency
+**Symptom**: re-running a job produces duplicates, double-counts, or partial-write corruption.
+**Why it fails**: every retry or backfill becomes a data cleanup event. Oncall pages multiply.
+**Counter-move**: design writes to be idempotent — upsert on natural key, or tag by run-id and replace.
+
+### 3. Silent data loss
+**Symptom**: ETL rows that fail validation get logged and dropped.
+**Why it fails**: the consumer thinks the dataset is complete; decisions are made on a biased subset.
+**Counter-move**: route rejects to a dead-letter table and alert on non-zero count. Never drop silently.
+
+### 4. Point-in-time blindness
+**Symptom**: joining dimension tables that mutate against a fact table without effective-dated logic.
+**Why it fails**: historical queries rewrite themselves every time a dimension changes.
+**Counter-move**: SCD type 2 (or equivalent) on anything that a fact joins to. Assert that a re-run of a historical window produces identical output.
+
+### 5. Untested backfills
+**Symptom**: writing a backfill script that "should work" and running it on production.
+**Why it fails**: edge cases in historical data (timezones, schema drift, deleted upstream rows) destroy the run midway.
+**Counter-move**: dry-run on a sampled window first. Assert row counts and a few spot-checks before the full backfill.
+
+## Self-check before shipping
+- [ ] Schema contract declared and enforced at the boundary
+- [ ] All writes are idempotent
+- [ ] Rejects go to a dead-letter path and alert on volume
+- [ ] Point-in-time correctness preserved across dimension changes
+- [ ] Backfills dry-run on a sample before full execution

package/skills/roles/engineer.md

@@ -0,0 +1,85 @@
+<!--
+skills/roles/engineer.md — Anti-pattern guidance for the Engineer role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the engineer domain and counter-moves to avoid them.
+Applies to: cx-engineer, cx-ai-engineer, cx-data-engineer, cx-platform-engineer.
+-->
+---
+role: engineer
+applies_to: [cx-engineer, cx-ai-engineer, cx-data-engineer, cx-platform-engineer]
+inherits: null
+version: 1
+---
+# Engineer — Role guidance
+
+Load this before drafting. These are the failure modes that separate strong role output from weak role output — check your draft against each.
+
+
+### 1. Writing before reading
+**Symptom**: new code added to a file or module without first reading the surrounding code and its callers.
+**Why it fails**: duplicates existing utilities, violates local conventions, and breaks invariants the author did not see.
+**Counter-move**: read the file end-to-end and at least one caller before adding anything. Prefer reusing what is there.
+
+### 2. Speculative abstraction
+**Symptom**: interfaces, factories, or configuration options added for a future case that may never arrive.
+**Why it fails**: creates surface area no one understands and no tests exercise. Adds cognitive load for every later reader.
+**Counter-move**: write the simplest thing that solves the current case. Abstract only when a third instance demands it.
+
+### 3. Silent API assumption
+**Symptom**: using a library or endpoint based on a pattern seen elsewhere in the code, without checking the actual contract.
+**Why it fails**: the assumption is usually close-but-wrong. Bugs surface in production, not in review.
+**Counter-move**: read the library's docs or source for the specific function used. Verify the shape of the response.
+
+### 4. Hidden coupling
+**Symptom**: a change in module A silently depends on a behavior in module B that is not expressed in the interface.
+**Why it fails**: any future refactor of B breaks A with no warning. The coupling is invisible until it fails.
+**Counter-move**: either express the dependency in the type system or in a test that would fail if B changed.
+
+### 5. Skipped verification
+**Symptom**: marking work done without running the code, the tests, or the build.
+**Why it fails**: type errors, broken imports, and runtime crashes ship to the next reviewer or to production.
+**Counter-move**: run the build, run the tests, exercise the code path changed. Paste the evidence into the PR.
+
+### 6. Oversized files and functions
+**Symptom**: functions over 50 lines, files over 800 lines, or deep nesting over four levels.
+**Why it fails**: the reader cannot hold the logic in their head; bugs hide in the middle third.
+**Counter-move**: extract when a function does more than one thing. Split when a file mixes concerns.
+
+### 7. Error swallowing
+**Symptom**: `catch` blocks that log-and-continue, default fallbacks that mask upstream failures, empty `except:` clauses.
+**Why it fails**: the system keeps running in a broken state; debugging later is impossible because the signal is gone.
+**Counter-move**: handle errors explicitly at the boundary where you can make a decision. Re-raise or return a typed error otherwise.
+
+### 8. Fixing the symptom
+**Symptom**: a patch that makes the test pass or the error disappear without a clear statement of the underlying cause.
+**Why it fails**: the root cause re-emerges in a different place, often worse.
+**Counter-move**: explain the cause in one sentence before writing the fix. If you cannot, keep investigating.
+
+### 9. Ignoring the diff
+**Symptom**: the change includes unrelated edits — formatting churn, drive-by renames, comment cleanups.
+**Why it fails**: drowns the real change in noise; reviewers cannot separate intent from accident.
+**Counter-move**: one change per commit. Keep the diff narrow. Bank the drive-bys for a separate PR.
+
+### 10. Speculating across thinking turns
+**Symptom**: reasoning about which library, pattern, or abstraction to use across multiple thinking turns without reading code, calling docs, or asking.
+**Why it fails**: guesses compound; the eventual choice is made from context the model built about itself, not from the codebase or the library.
+**Counter-move**: two unproductive passes is the cap. Next step is a targeted read, a docs lookup (`context7_query-docs`/`WebFetch`), a NEEDS_MAIN_INPUT packet, or a default with a noted assumption.
+
+### 11. Unbounded file reads
+**Symptom**: reading files with large `limit` values without checking size first, or offset reads that fail with "out of range".
+**Why it fails**: wastes context, and the failure reveals the file was smaller than assumed — a signal that the reading strategy was guess-driven.
+**Counter-move**: before any `Read` over 200 lines, probe with `Glob`, `wc -l`, or a `limit: 50` read. Then request the right range.
+
+## Self-check before shipping
+
+- [ ] Read the surrounding file and at least one caller
+- [ ] No new abstraction unless there are three concrete uses
+- [ ] Library and API contracts verified from their source
+- [ ] Build passes, tests pass, code path exercised
+- [ ] No function over 50 lines, no file over 800, no nesting over four
+- [ ] Errors handled explicitly, not swallowed
+- [ ] Root cause of any bug fix is stated in one sentence
+- [ ] Diff is narrow and on-topic
+- [ ] No more than two consecutive thinking turns about the same decision without a tool call or input
+- [ ] Any `Read` over 200 lines was preceded by a size probe

package/skills/roles/engineer.platform.md

@@ -0,0 +1,49 @@
+<!--
+skills/roles/engineer.platform.md — Anti-pattern guidance for the Engineer.platform (platform) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the engineer.platform (platform) domain and counter-moves to avoid them.
+Applies to: cx-platform-engineer.
+-->
+---
+role: engineer.platform
+applies_to: [cx-platform-engineer]
+inherits: engineer
+version: 1
+---
+# Platform Engineer Overlay
+
+Additional failure modes on top of the engineer core.
+
+
+### 1. Tooling without adoption plan
+**Symptom**: building an internal tool (CLI, framework, template) without a migration path or first consumer.
+**Why it fails**: the tool rots unused; the original problem still gets solved by copy-paste in every repo.
+**Counter-move**: pick one team as first consumer, migrate them before declaring done, and measure adoption afterward.
+
+### 2. Breaking internal APIs without a deprecation window
+**Symptom**: renaming a CLI flag, shipping a breaking change to a shared library, or removing a config option without notice.
+**Why it fails**: every consumer hits a red build on Monday. Goodwill evaporates and future rollouts get resisted.
+**Counter-move**: deprecation notice + parallel support window for one release cycle. Remove only after usage drops to zero.
+
+### 3. Optimizing for the happy path
+**Symptom**: build/CI pipeline is fast when everything works but impossible to debug when it breaks.
+**Why it fails**: platform engineers see green; consumers are stuck in a multi-hour flake loop with no diagnostic output.
+**Counter-move**: log loudly on failure. Cache artifacts for reproduction. Measure failure-recovery time, not just success time.
+
+### 4. Invisible costs
+**Symptom**: a platform change (new base image, new log shipper, new CI step) that adds minutes or dollars per build.
+**Why it fails**: compounds across thousands of runs; FinOps catches it three months later.
+**Counter-move**: measure before/after on build time, CI minutes, and per-run cost. Flag any regression over 5%.
+
+### 5. Security as afterthought
+**Symptom**: CI secrets in plaintext env, broad GitHub tokens, no SBOM, no dependency audit in the pipeline.
+**Why it fails**: platform surface area compounds blast radius — one leaked token touches every repo.
+**Counter-move**: treat platform secrets as production secrets. Rotate, scope-minimize, and audit.
+
+## Self-check before shipping
+- [ ] First consumer migrated and measured
+- [ ] Deprecation window respected for any breaking change
+- [ ] Failure diagnostics and artifacts preserved
+- [ ] Build-time and cost deltas measured
+- [ ] Secrets scoped minimally and auditable

package/skills/roles/operator.docs.md

@@ -0,0 +1,43 @@
+<!--
+skills/roles/operator.docs.md — Anti-pattern guidance for the Operator.docs (docs) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the operator.docs (docs) domain and counter-moves to avoid them.
+Applies to: cx-docs-keeper.
+-->
+---
+role: operator.docs
+applies_to: [cx-docs-keeper]
+inherits: operator
+version: 1
+---
+# Docs Keeper Overlay
+
+Additional failure modes on top of the operator core.
+
+
+### 1. Docs as write-once artifacts
+**Symptom**: a decision record or runbook is created, then never revisited as the system evolves.
+**Why it fails**: stale docs are worse than no docs — they mislead with authority.
+**Counter-move**: every doc has a `last-reviewed` date. Flag anything older than the agreed review cadence.
+
+### 2. Parallel sources of truth
+**Symptom**: the same concept explained in README, wiki, CLAUDE.md, and onboarding deck — all slightly different.
+**Why it fails**: readers find one, act on it, hit contradictions later; trust erodes.
+**Counter-move**: one canonical source per concept. Link to it from all surfaces.
+
+### 3. Descriptive, not prescriptive
+**Symptom**: docs describe what the system does but not what to do when it breaks.
+**Why it fails**: the reader has to invent the action path themselves under pressure.
+**Counter-move**: for operational surfaces, lead with "if X, do Y." Reference architecture only as support.
+
+### 4. No owner
+**Symptom**: a doc that nobody updates because nobody owns it.
+**Why it fails**: rot is guaranteed; questions route to Slack instead of the doc.
+**Counter-move**: every doc declares an owner (person or role). Ownership appears in the header.
+
+## Self-check before shipping
+- [ ] Last-reviewed date present and fresh
+- [ ] One canonical source per concept; duplicates redirect
+- [ ] Operational docs are prescriptive, not just descriptive
+- [ ] Owner declared in the header

package/skills/roles/operator.md

@@ -0,0 +1,68 @@
+<!--
+skills/roles/operator.md — Anti-pattern guidance for the Operator role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the operator domain and counter-moves to avoid them.
+Applies to: cx-sre, cx-operations, cx-release-manager, cx-docs-keeper.
+-->
+---
+role: operator
+applies_to: [cx-sre, cx-operations, cx-release-manager, cx-docs-keeper]
+inherits: null
+version: 1
+---
+# Operator — Role guidance
+
+Load this before producing operator output — SRE, ops, release, and durable-knowledge work.
+
+
+### 1. Runbook by incantation
+**Symptom**: the runbook tells the on-call what to type but not what the commands do or what their output means.
+**Why it fails**: when the commands fail or return unexpected output, the on-call has no foundation for improvising.
+**Counter-move**: each step names its purpose, its expected output, and what "wrong" looks like.
+
+### 2. Rollback as afterthought
+**Symptom**: the deployment plan describes the forward path in detail but rollback in one line: "revert if needed".
+**Why it fails**: rollback is attempted at 3am under pressure. Untested rollback paths fail or make things worse.
+**Counter-move**: rollback is a first-class plan. Tested. With criteria for when to trigger it.
+
+### 3. Alert noise
+**Symptom**: the on-call receives dozens of alerts per shift; most are ignored.
+**Why it fails**: real alerts drown in noise. On-call health erodes. Teams learn to ignore paging.
+**Counter-move**: every alert is actionable or it should not page. Move non-actionable signals to dashboards. Review alert rate every month.
+
+### 4. No observability before launch
+**Symptom**: a service ships without dashboards, logs, or traces wired in; observability is added after the first incident.
+**Why it fails**: the first incident is solved in the dark. Recovery takes far longer than it needed to.
+**Counter-move**: no service launches without its SLO, its dashboard, and its three golden signals instrumented.
+
+### 5. Post-incident blame
+**Symptom**: the incident report names individuals and their mistakes; corrective actions are "be more careful".
+**Why it fails**: nobody learns. Mistakes recur. Reporting culture degrades.
+**Counter-move**: blameless tone. Corrective actions target the system, not the person. "Be more careful" is not a control.
+
+### 6. Documentation drift
+**Symptom**: runbooks, architecture docs, and decision records last updated two years ago.
+**Why it fails**: new on-calls follow stale instructions; decisions get re-debated because the rationale was lost.
+**Counter-move**: every operational doc has a "last tested" or "last reviewed" date. Stale docs are flagged, not silently trusted.
+
+### 7. Silent release
+**Symptom**: a change ships without a changelog, comms, or stakeholder awareness.
+**Why it fails**: users are surprised. Support is unprepared. Incidents take longer because responders do not know what changed.
+**Counter-move**: every non-trivial release has a changelog entry, a rollback plan, and a comms channel notified.
+
+### 8. Unbounded retries
+**Symptom**: failures retried forever or with naive backoff; retries hide underlying capacity issues.
+**Why it fails**: retry storms amplify outages. A transient failure becomes a full incident.
+**Counter-move**: bounded retries. Exponential backoff with jitter. Circuit breakers on downstream dependencies.
+
+## Self-check before shipping
+
+- [ ] Each runbook step names its purpose and expected output
+- [ ] Rollback is a tested, first-class plan with trigger criteria
+- [ ] Every alert is actionable; non-actionable signals moved to dashboards
+- [ ] SLO, dashboard, and golden signals in place before launch
+- [ ] Incident reports are blameless; corrective actions target the system
+- [ ] Operational docs have a last-tested or last-reviewed date
+- [ ] Every release has a changelog, rollback, and comms plan
+- [ ] Retries are bounded; circuit breakers protect dependencies