@geraldmaron/construct 1.0.0

package/skills/quality-gates/verify-quality.md

@@ -0,0 +1,93 @@
+<!--
+skills/quality-gates/verify-quality.md — Verify Quality — Use this skill to check code quality, complexity, and maintainability after chan
+
+Use this skill to check code quality, complexity, and maintainability after changes. ## Complexity
+-->
+# Verify Quality
+
+Use this skill to check code quality, complexity, and maintainability after changes.
+
+## Complexity
+
+- [ ] Cyclomatic complexity per function stays below 15
+- [ ] Cognitive complexity per function stays below 20
+- [ ] No function exceeds 50 lines (excluding comments and blank lines)
+- [ ] No file exceeds 800 lines
+- [ ] No nesting deeper than 4 levels; use early returns to flatten
+
+**Severity**: Function >80 lines = High. File >800 lines = High. Nesting >5 = Medium.
+
+## Naming
+
+- [ ] Variables and functions use descriptive, intention-revealing names
+- [ ] Boolean variables use `is`, `has`, `should`, or `can` prefixes
+- [ ] No single-letter variables outside tiny loop counters
+- [ ] No abbreviations unless universally understood (id, url, http)
+- [ ] Types, interfaces, and components use PascalCase
+- [ ] Constants use UPPER_SNAKE_CASE
+
+**Severity**: Misleading name = High. Ambiguous abbreviation = Medium.
+
+## Code Smells
+
+- [ ] No dead code (unreachable branches, unused imports, commented-out blocks)
+- [ ] No magic numbers or strings; extract to named constants
+- [ ] No god objects or god functions that do everything
+- [ ] No feature envy (function that uses another module's data more than its own)
+- [ ] No shotgun surgery pattern (one change requires edits across many files)
+- [ ] No primitive obsession (use domain types instead of raw strings/numbers)
+
+**Severity**: Dead code = Medium. God function = High. Magic number = Low.
+
+## DRY Violations
+
+- [ ] No duplicated logic blocks (3+ lines repeated 2+ times)
+- [ ] Shared patterns extracted into utility functions or modules
+- [ ] No copy-paste drift where cloned code diverged silently
+- [ ] Configuration values defined once and referenced
+
+**Severity**: Exact duplication = Medium. Diverged clone = High.
+
+## Error Handling
+
+- [ ] All error paths handled explicitly; no silent swallowing
+- [ ] Errors include context for debugging (what failed, with what input)
+- [ ] User-facing errors are friendly; developer-facing errors are detailed
+- [ ] Async errors caught (unhandled promise rejections, goroutine panics)
+- [ ] Resource cleanup in finally/defer blocks
+
+**Severity**: Silent swallow = High. Missing async catch = High. No context = Medium.
+
+## Immutability
+
+- [ ] Functions return new values instead of mutating inputs
+- [ ] Collections updated via spread/copy, not in-place mutation
+- [ ] Shared state minimized; prefer local scope
+
+**Severity**: Mutation of shared state = High. Local mutation = Low.
+
+## Type Safety
+
+- [ ] No use of `any` or equivalent escape hatches without justification
+- [ ] Null/undefined handled with type narrowing or optional chaining
+- [ ] Generic types used where they reduce duplication without obscuring intent
+
+**Severity**: Unchecked `any` = Medium. Missing null check = High.
+
+## Readability
+
+- [ ] Functions do one thing and are named for what they do
+- [ ] Control flow is linear and predictable (no spaghetti)
+- [ ] Related code is colocated; unrelated code is separated
+- [ ] Abstractions are justified by actual reuse, not speculation
+
+**Severity**: Tangled control flow = High. Speculative abstraction = Medium.
+
+## Severity Reference
+
+| Level | Meaning | Action |
+|---|---|---|
+| Critical | Correctness risk or architectural violation | Must fix |
+| High | Significant maintainability problem | Should fix |
+| Medium | Quality concern worth addressing | Fix when practical |
+| Low | Style preference or minor suggestion | Optional |

package/skills/quality-gates/verify-security.md

@@ -0,0 +1,95 @@
+<!--
+skills/quality-gates/verify-security.md — Verify Security — Use this skill to scan code for security vulnerabilities before commits or relea
+
+Use this skill to scan code for security vulnerabilities before commits or releases. ## Scan Scope
+-->
+# Verify Security
+
+Use this skill to scan code for security vulnerabilities before commits or releases.
+
+## Scan Scope
+
+Analyze all changed files plus their direct dependencies for the categories below.
+
+## Secrets and Credentials
+
+- [ ] No hardcoded API keys, passwords, tokens, or connection strings
+- [ ] No private keys or certificates committed
+- [ ] `.env` files excluded from version control
+- [ ] Secrets loaded from environment variables or a secret manager
+- [ ] No secrets in logs, error messages, or stack traces
+
+**Severity**: Hardcoded secret = Critical. Secret in logs = High.
+
+## Authentication and Authorization
+
+- [ ] Authentication required on all protected endpoints
+- [ ] Authorization checks enforce least privilege
+- [ ] Session tokens are cryptographically random and expire
+- [ ] Password storage uses bcrypt, scrypt, or argon2 with sufficient rounds
+- [ ] Multi-factor authentication supported where appropriate
+- [ ] No authentication bypass via parameter tampering or path traversal
+
+**Severity**: Auth bypass = Critical. Missing authz check = High. Weak hash = High.
+
+## Injection
+
+- [ ] SQL queries use parameterized statements or an ORM
+- [ ] No string concatenation in queries, commands, or templates
+- [ ] OS command execution uses allowlists, never user input directly
+- [ ] LDAP, XML, and template injection vectors reviewed
+
+**Severity**: SQL/OS injection = Critical. Template injection = High.
+
+## Cross-Site Scripting (XSS)
+
+- [ ] All user-supplied data escaped before rendering in HTML
+- [ ] No use of `innerHTML`, `dangerouslySetInnerHTML`, or `v-html` without sanitization
+- [ ] Content-Security-Policy header configured
+- [ ] Reflected, stored, and DOM-based XSS vectors checked
+
+**Severity**: Stored XSS = Critical. Reflected XSS = High. DOM XSS = High.
+
+## Cross-Site Request Forgery (CSRF)
+
+- [ ] State-changing requests require CSRF tokens
+- [ ] SameSite cookie attribute set to Lax or Strict
+- [ ] Custom headers validated for API endpoints
+
+**Severity**: Missing CSRF on state change = High.
+
+## Dependencies
+
+- [ ] No known CVEs in direct or transitive dependencies
+- [ ] Lock file committed and up to date
+- [ ] No unnecessary dependencies
+- [ ] Audit command run: `npm audit`, `pip audit`, `cargo audit`, or equivalent
+
+**Severity**: Critical CVE = Critical. High CVE = High. Outdated dep = Medium.
+
+## Cryptography
+
+- [ ] TLS 1.2+ enforced for all network communication
+- [ ] No use of MD5, SHA1, DES, or RC4 for security purposes
+- [ ] Random values generated with cryptographic PRNG
+- [ ] Key lengths meet current standards (RSA 2048+, AES 256)
+
+**Severity**: Broken crypto = High. Weak random = High. Deprecated algo = Medium.
+
+## Data Exposure
+
+- [ ] Sensitive fields excluded from API responses and logs
+- [ ] Error messages do not leak internal paths, stack traces, or versions
+- [ ] Debug endpoints disabled in production
+- [ ] Rate limiting on authentication and sensitive endpoints
+
+**Severity**: PII leak = Critical. Stack trace in prod = Medium. Missing rate limit = Medium.
+
+## Severity Reference
+
+| Level | Meaning | Action |
+|---|---|---|
+| Critical | Exploitable vulnerability or data breach risk | Must fix before merge |
+| High | Significant security weakness | Should fix before merge |
+| Medium | Defense-in-depth gap | Fix when practical |
+| Low | Hardening suggestion | Optional |

package/skills/roles/architect.ai-systems.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/architect.ai-systems.md — Anti-pattern guidance for the Architect.ai-systems (ai systems) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect.ai-systems (ai systems) domain and counter-moves to avoid them.
+Applies to: cx-architect.
+-->
+---
+role: architect.ai-systems
+applies_to: [cx-architect]
+inherits: architect
+version: 1
+---
+# AI Systems Architect Overlay
+
+Additional failure modes on top of the architect core.
+
+### 1. Model behavior as an implicit dependency
+**Symptom**: the design depends on a model always following instructions or returning one exact shape.
+**Why it fails**: model behavior changes across versions, providers, prompts, and context.
+**Counter-move**: define output schemas, validation, retries, fallback behavior, and human review boundaries.
+
+### 2. Retrieval without provenance
+**Symptom**: vector search is treated as truth without source attribution, freshness, or permission boundaries.
+**Why it fails**: stale or unauthorized context can become generated output.
+**Counter-move**: design citation, freshness, access control, and re-indexing paths.
+
+### 3. Evals postponed until after launch
+**Symptom**: the ADR names model choice but not the evaluation gate.
+**Why it fails**: quality becomes subjective and regressions become invisible.
+**Counter-move**: require eval suites, golden traces, failure cases, and promotion criteria as part of the architecture.
+
+## Self-check before shipping
+- [ ] Model output schemas and validation paths are explicit
+- [ ] Retrieval has provenance, freshness, ACL, and re-indexing rules
+- [ ] Human review and fallback boundaries are named
+- [ ] Evals and promotion gates are architecture requirements

package/skills/roles/architect.data.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/architect.data.md — Anti-pattern guidance for the Architect.data (data) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect.data (data) domain and counter-moves to avoid them.
+Applies to: cx-architect.
+-->
+---
+role: architect.data
+applies_to: [cx-architect]
+inherits: architect
+version: 1
+---
+# Data Architect Overlay
+
+Additional failure modes on top of the architect core.
+
+### 1. Schema now, migration later
+**Symptom**: the model fits the first implementation but has no migration or backfill plan.
+**Why it fails**: data shape changes are harder to unwind than code shape changes.
+**Counter-move**: define forward/backward migration, backfill safety, and compatibility windows before implementation.
+
+### 2. Query patterns guessed instead of designed
+**Symptom**: indexes, partitions, and materialized views are deferred until performance hurts.
+**Why it fails**: production data volume exposes assumptions hidden by test fixtures.
+**Counter-move**: document expected cardinality, access paths, retention, and latency targets.
+
+### 3. Data quality treated as downstream work
+**Symptom**: contracts cover types but not nullability, freshness, uniqueness, or lineage.
+**Why it fails**: bad data silently becomes product behavior.
+**Counter-move**: include data contracts, quality checks, lineage, and incident response ownership.
+
+## Self-check before shipping
+- [ ] Schema evolution, migrations, and backfills are covered
+- [ ] Cardinality, indexing, retention, and latency assumptions are explicit
+- [ ] Quality checks, lineage, and data ownership are defined
+- [ ] Rollback and repair paths exist for corrupted state

package/skills/roles/architect.enterprise.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/architect.enterprise.md — Anti-pattern guidance for the Architect.enterprise (enterprise) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect.enterprise (enterprise) domain and counter-moves to avoid them.
+Applies to: cx-architect.
+-->
+---
+role: architect.enterprise
+applies_to: [cx-architect]
+inherits: architect
+version: 1
+---
+# Enterprise Architect Overlay
+
+Additional failure modes on top of the architect core.
+
+### 1. Enterprise controls bolted on late
+**Symptom**: SSO, RBAC, audit, retention, and tenant isolation are listed as future work.
+**Why it fails**: enterprise controls change data models, APIs, and operational workflows.
+**Counter-move**: include identity, access, audit, retention, and tenancy in the first architecture pass.
+
+### 2. Procurement requirements treated as non-technical
+**Symptom**: compliance evidence, data residency, SLAs, and admin reporting are not reflected in system design.
+**Why it fails**: sales commitments become engineering emergencies.
+**Counter-move**: translate procurement and compliance needs into explicit technical contracts.
+
+### 3. Single-tenant assumptions hidden in code
+**Symptom**: tenant IDs, limits, and isolation rules are missing from interfaces.
+**Why it fails**: retrofitting tenancy after launch creates security and migration risk.
+**Counter-move**: make tenant context, authorization, quotas, and isolation visible at every boundary.
+
+## Self-check before shipping
+- [ ] SSO, RBAC, audit, retention, and tenant isolation are designed
+- [ ] Data residency, SLA, and evidence requirements are translated into system contracts
+- [ ] Tenant context and authorization are visible in interfaces
+- [ ] Admin reporting and support diagnostics are included

package/skills/roles/architect.integration.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/architect.integration.md — Anti-pattern guidance for the Architect.integration (integration) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect.integration (integration) domain and counter-moves to avoid them.
+Applies to: cx-architect.
+-->
+---
+role: architect.integration
+applies_to: [cx-architect]
+inherits: architect
+version: 1
+---
+# Integration Architect Overlay
+
+Additional failure modes on top of the architect core.
+
+### 1. Designing only the successful exchange
+**Symptom**: the sequence diagram stops after a 200 response.
+**Why it fails**: real integrations fail through retries, partial writes, timeouts, duplicate deliveries, and stale credentials.
+**Counter-move**: document idempotency keys, retry/backoff policy, dead-letter paths, and reconciliation flows.
+
+### 2. Unclear source of truth
+**Symptom**: two systems can update the same entity without conflict rules.
+**Why it fails**: data divergence becomes a support problem that cannot be diagnosed from logs.
+**Counter-move**: name the system of record, conflict strategy, sync direction, and repair workflow.
+
+### 3. Credentials as an implementation detail
+**Symptom**: auth setup, rotation, scopes, and revocation are left to engineering.
+**Why it fails**: integrations become fragile and over-privileged.
+**Counter-move**: define credential lifecycle, least-privilege scopes, secret storage, and audit events.
+
+## Self-check before shipping
+- [ ] Failure modes include retries, duplicates, partial failure, and reconciliation
+- [ ] System of record and conflict resolution are explicit
+- [ ] Credential lifecycle and scopes are designed
+- [ ] Observability covers cross-system correlation IDs

package/skills/roles/architect.md

@@ -0,0 +1,68 @@
+<!--
+skills/roles/architect.md — Anti-pattern guidance for the Architect role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect domain and counter-moves to avoid them.
+Applies to: cx-architect, cx-rd-lead.
+-->
+---
+role: architect
+applies_to: [cx-architect, cx-rd-lead]
+inherits: null
+version: 1
+---
+# Architect — 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. Premature tech choice
+**Symptom**: the design names a specific database, framework, or cloud service before the requirements have been stated.
+**Why it fails**: anchors the team on a tool the problem may not need. Alternatives go unexplored.
+**Counter-move**: state requirements first. Name candidates second. Pick last, with the reason tied to the requirements.
+
+### 2. Decisions without alternatives
+**Symptom**: the doc presents one option as the recommendation with no serious comparison.
+**Why it fails**: reviewers cannot tell whether the decision was made or merely assumed.
+**Counter-move**: document at least two real alternatives with specific reasons each was rejected. A straw-man alternative is worse than none.
+
+### 3. Ignoring operational burden
+**Symptom**: the design optimizes for build-time elegance and ignores who operates the system at 3am.
+**Why it fails**: elegant systems become unmaintainable once they have real users; on-call pays the cost forever.
+**Counter-move**: include an operations section. Who pages, what breaks, how it is observed, how it is rolled back.
+
+### 4. Reversibility blindness
+**Symptom**: no statement of whether the decision is a one-way door (irreversible) or a two-way door (cheap to undo).
+**Why it fails**: one-way doors get the same debate-depth as two-way doors; teams over-deliberate on the reversible and under-deliberate on the permanent.
+**Counter-move**: label every major decision as one-way or two-way and match the evidence burden to it.
+
+### 5. Boundary vagueness
+**Symptom**: modules, services, or teams are drawn with arrows but the contracts — inputs, outputs, failure modes — are not specified.
+**Why it fails**: each team implements its own interpretation; the integration surfaces the gaps in production.
+**Counter-move**: every boundary has a contract. Every contract names its failure modes.
+
+### 6. Scaling for the fantasy case
+**Symptom**: the design is sized for a load that requires 100x of current users, which the business has no plan to reach.
+**Why it fails**: pays today's cost for tomorrow's hypothetical. The hypothetical never arrives, or arrives in a different shape.
+**Counter-move**: size for current load plus the one-year plan. Note the scaling assumption. Revisit when reality deviates.
+
+### 7. Ignoring the migration
+**Symptom**: the design describes the end state but not the path from here to there.
+**Why it fails**: migration is where projects die. "Cut over the weekend" rarely works.
+**Counter-move**: include a migration plan with phases, dual-run strategy, rollback points, and the failure modes of each phase.
+
+### 8. Reinventing over reusing
+**Symptom**: a custom solution for a problem a mature tool already solves, justified by thin differentiation.
+**Why it fails**: the team now owns the maintenance of both the product and a worse version of an existing tool.
+**Counter-move**: survey existing tools honestly. If building, articulate exactly what the existing tools fail to do.
+
+## Self-check before shipping
+
+- [ ] Requirements are stated before tech choices
+- [ ] At least two real alternatives considered and rejected with reasons
+- [ ] Operations section names on-call, observability, rollback
+- [ ] Every major decision labeled one-way or two-way
+- [ ] Every boundary has a specified contract, including failure modes
+- [ ] Scaling assumptions are named and tied to the business plan
+- [ ] Migration path is explicit with phases and rollback points
+- [ ] Build-vs-buy is justified when building

package/skills/roles/architect.platform.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/architect.platform.md — Anti-pattern guidance for the Architect.platform (platform) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the architect.platform (platform) domain and counter-moves to avoid them.
+Applies to: cx-architect.
+-->
+---
+role: architect.platform
+applies_to: [cx-architect]
+inherits: architect
+version: 1
+---
+# Platform Architect Overlay
+
+Additional failure modes on top of the architect core.
+
+### 1. Treating platform APIs as feature internals
+**Symptom**: the design describes a service boundary but not the public contract, compatibility policy, or owner.
+**Why it fails**: downstream teams build against accidental behavior and the platform becomes impossible to change.
+**Counter-move**: specify API versioning, compatibility guarantees, migration paths, tenant boundaries, and contract tests.
+
+### 2. Omitting operational interfaces
+**Symptom**: the ADR covers the happy-path API but not admin actions, audit logs, rate limits, quotas, or diagnostics.
+**Why it fails**: platforms fail through support burden as often as runtime defects.
+**Counter-move**: design the operator surface alongside the developer surface.
+
+### 3. Local optimization over ecosystem fit
+**Symptom**: the solution is clean for one product team but inconsistent with existing platform conventions.
+**Why it fails**: every exception becomes another integration tax.
+**Counter-move**: compare against current platform patterns before introducing a new one.
+
+## Self-check before shipping
+- [ ] Public contracts, owners, versioning, and compatibility guarantees are explicit
+- [ ] Migration, deprecation, and rollback behavior are documented
+- [ ] Admin, audit, quota, and diagnostic surfaces are included
+- [ ] Contract tests and integration acceptance criteria exist

package/skills/roles/data-analyst.experiment.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-analyst.experiment.md — Anti-pattern guidance for the Data-analyst.experiment (experiment) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-analyst.experiment (experiment) domain and counter-moves to avoid them.
+Applies to: cx-data-analyst.
+-->
+---
+role: data-analyst.experiment
+applies_to: [cx-data-analyst]
+inherits: data-analyst
+version: 1
+---
+# Experiment Analyst Overlay
+
+Additional failure modes on top of the data-analyst core.
+
+### 1. Experiment without a decision rule
+**Symptom**: the team plans to "see what happens" after launch.
+**Why it fails**: ambiguous outcomes become arguments instead of decisions.
+**Counter-move**: define hypothesis, primary metric, guardrails, minimum detectable effect, and stop rule.
+
+### 2. Randomization mismatch
+**Symptom**: randomization unit does not match how users experience the product.
+**Why it fails**: contamination and repeated exposure distort the result.
+**Counter-move**: choose user, account, workspace, session, or request-level assignment deliberately.
+
+### 3. Reading results too early
+**Symptom**: decisions are made on partial data because the chart looks convincing.
+**Why it fails**: early peeking inflates false positives.
+**Counter-move**: specify duration, sample size, and analysis plan before the experiment starts.
+
+## Self-check before shipping
+- [ ] Hypothesis, primary metric, guardrails, and stop rule are explicit
+- [ ] Randomization unit matches the product behavior
+- [ ] Sample size and duration are justified
+- [ ] Segmentation and novelty effects are considered

package/skills/roles/data-analyst.md

@@ -0,0 +1,68 @@
+<!--
+skills/roles/data-analyst.md — Anti-pattern guidance for the Data-analyst role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-analyst domain and counter-moves to avoid them.
+Applies to: cx-data-analyst.
+-->
+---
+role: data-analyst
+applies_to: [cx-data-analyst]
+inherits: null
+version: 1
+---
+# Data Analyst — 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. Metric without definition
+**Symptom**: a metric cited without its precise definition — which events, what time window, deduplication rules, filters.
+**Why it fails**: two teams compute "active users" differently. Decisions rest on numbers nobody can reproduce.
+**Counter-move**: name the metric and its SQL-level or event-level definition before any number. Version the definition.
+
+### 2. Vanity over outcome
+**Symptom**: reports lead with impressions, pageviews, clicks — activity disconnected from whether users got value.
+**Why it fails**: rewards teams for moving activity numbers while outcomes stagnate.
+**Counter-move**: tie every vanity metric to an outcome metric. Report both. Lead with the outcome.
+
+### 3. Ignoring data quality
+**Symptom**: analysis assumes the underlying events fire correctly, are deduped, and have consistent schemas.
+**Why it fails**: real pipelines drop, duplicate, and malform events. Analysis without QA produces confident wrong numbers.
+**Counter-move**: run sanity checks — row counts, null rates, distribution shape, schema checks — before analysis. Report data quality alongside findings.
+
+### 4. Correlation as causation
+**Symptom**: "users who did X had higher retention" presented as a reason to make everyone do X.
+**Why it fails**: selection bias, reverse causation, and confounders produce the same pattern. Actions based on it rarely work.
+**Counter-move**: name the alternative explanations. If you want to claim causation, the answer is an experiment.
+
+### 5. p-hacking and post-hoc slicing
+**Symptom**: after seeing the results, the analyst carves the data until a significant effect appears somewhere.
+**Why it fails**: guaranteed to find "effects" that are noise. Decisions based on them do not replicate.
+**Counter-move**: register hypotheses before looking at the data. Distinguish confirmatory from exploratory findings.
+
+### 6. Missing funnel context
+**Symptom**: a conversion rate reported without the volume at each step, or a step-change reported without the broader funnel.
+**Why it fails**: a "20% lift" on a step that 1% of users reach moves nothing. Context collapses.
+**Counter-move**: every rate comes with its denominator and its place in the funnel. Report absolute as well as relative.
+
+### 7. Dashboard as deliverable
+**Symptom**: the analyst builds a dashboard and stops. No interpretation, no recommendation, no action.
+**Why it fails**: stakeholders read numbers without knowing what to do with them; dashboards accumulate but decisions do not.
+**Counter-move**: every analysis ends with interpretation and a recommended action. Dashboards support that, they do not replace it.
+
+### 8. Unreproducible analysis
+**Symptom**: the number came from a notebook on someone's laptop; the query is not saved; the result cannot be regenerated.
+**Why it fails**: the analysis cannot be audited, extended, or re-run against fresh data. Trust erodes when numbers cannot be reproduced.
+**Counter-move**: code in a repo, queries in version control, inputs and outputs documented. A colleague can re-run the analysis tomorrow.
+
+## Self-check before shipping
+
+- [ ] Every metric has a precise, versioned definition
+- [ ] Outcome metrics lead; vanity metrics support or are omitted
+- [ ] Data quality checks run; quality reported with findings
+- [ ] Correlations explicitly separated from causal claims
+- [ ] Hypotheses registered before seeing the data
+- [ ] Rates include denominators and funnel context
+- [ ] Interpretation and recommended action accompany numbers
+- [ ] Analysis is reproducible from version-controlled artifacts

package/skills/roles/data-analyst.product-intelligence.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-analyst.product-intelligence.md — Anti-pattern guidance for the Data-analyst.product-intelligence (product intelligence) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-analyst.product-intelligence (product intelligence) domain and counter-moves to avoid them.
+Applies to: cx-data-analyst, cx-product-manager.
+-->
+---
+role: data-analyst.product-intelligence
+applies_to: [cx-data-analyst, cx-product-manager]
+inherits: data-analyst
+version: 1
+---
+# Product Intelligence Analyst Overlay
+
+Additional failure modes on top of the data-analyst core.
+
+### 1. Anecdotes counted as evidence
+**Symptom**: customer notes are summarized without source count, confidence, or contradiction.
+**Why it fails**: loud examples masquerade as trends.
+**Counter-move**: separate signal, evidence, confidence, counter-evidence, and unresolved questions.
+
+### 2. Qualitative and quantitative data never meet
+**Symptom**: support themes, interviews, telemetry, and roadmap work remain separate artifacts.
+**Why it fails**: PM decisions lack a durable evidence trail.
+**Counter-move**: link customer signals to metrics, segments, affected workflows, and backlog proposals.
+
+### 3. Evidence store ignored
+**Symptom**: new briefs are written without checking prior Product Intelligence artifacts.
+**Why it fails**: teams rediscover the same signal and lose longitudinal context.
+**Counter-move**: query `.cx/product-intel`, `docs/prd`, and `docs/meta-prd` through hybrid search before drafting.
+
+## Self-check before shipping
+- [ ] Evidence count, confidence, and counter-evidence are explicit
+- [ ] Signals link to metrics, segments, and backlog implications
+- [ ] Prior Product Intelligence artifacts were checked
+- [ ] Open questions and collection plan are recorded

package/skills/roles/data-analyst.product.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-analyst.product.md — Anti-pattern guidance for the Data-analyst.product (product) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-analyst.product (product) domain and counter-moves to avoid them.
+Applies to: cx-data-analyst.
+-->
+---
+role: data-analyst.product
+applies_to: [cx-data-analyst]
+inherits: data-analyst
+version: 1
+---
+# Product Analytics Overlay
+
+Additional failure modes on top of the data-analyst core.
+
+### 1. Measuring usage instead of value
+**Symptom**: success is defined as clicks, visits, or feature usage.
+**Why it fails**: users can use a feature without getting value from it.
+**Counter-move**: connect metrics to the user behavior or business outcome the product is meant to change.
+
+### 2. Funnel averages hide segments
+**Symptom**: aggregate conversion improves while an important user segment regresses.
+**Why it fails**: product decisions often affect cohorts differently.
+**Counter-move**: require segmentation by persona, plan, acquisition source, geography, device, or maturity where relevant.
+
+### 3. Instrumentation after launch
+**Symptom**: events are added after users start flowing through the feature.
+**Why it fails**: there is no baseline and no clean before/after comparison.
+**Counter-move**: define event schema, baseline window, and success threshold before release.
+
+## Self-check before shipping
+- [ ] Metrics connect to user value, not raw activity
+- [ ] Baselines and segments are defined
+- [ ] Event schema and properties are specified
+- [ ] Guardrail metrics are included

package/skills/roles/data-analyst.telemetry.md

@@ -0,0 +1,37 @@
+<!--
+skills/roles/data-analyst.telemetry.md — Anti-pattern guidance for the Data-analyst.telemetry (telemetry) role.
+
+Loaded at sync time to inline role-specific failure modes into specialist agent prompts.
+Covers common failure modes for the data-analyst.telemetry (telemetry) domain and counter-moves to avoid them.
+Applies to: cx-data-analyst, cx-sre.
+-->
+---
+role: data-analyst.telemetry
+applies_to: [cx-data-analyst, cx-sre]
+inherits: data-analyst
+version: 1
+---
+# Telemetry Analyst Overlay
+
+Additional failure modes on top of the data-analyst core.
+
+### 1. Observability without an answer path
+**Symptom**: dashboards exist but cannot answer whether a user-facing behavior improved or regressed.
+**Why it fails**: telemetry becomes decorative instead of operational.
+**Counter-move**: tie traces, metrics, logs, and events to concrete questions and decisions.
+
+### 2. Missing denominator
+**Symptom**: counts are reported without exposure, attempts, population, or eligibility.
+**Why it fails**: raw counts move with traffic and hide rate changes.
+**Counter-move**: define numerator, denominator, sampling, and exclusions for every metric.
+
+### 3. Data quality not monitored
+**Symptom**: teams monitor the product but not the telemetry pipeline.
+**Why it fails**: broken instrumentation can look like product behavior.
+**Counter-move**: add freshness, volume, schema, and drop-rate checks.
+
+## Self-check before shipping
+- [ ] Telemetry answers named product or operational questions
+- [ ] Numerators, denominators, and exclusions are defined
+- [ ] Freshness, volume, schema, and drop-rate checks exist
+- [ ] Alerts distinguish product failure from telemetry failure