@geraldmaron/construct 1.0.0

package/skills/devops/incident-response.md

@@ -0,0 +1,167 @@
+<!--
+skills/devops/incident-response.md — Incident Response — | Sev | User impact | Response time | Example |
+
+## Severity Levels | Sev | User impact | Response time | Example |
+-->
+# Incident Response
+
+## Severity Levels
+
+| Sev | User impact | Response time | Example |
+|---|---|---|---|
+| **P0** | Total outage, data loss, security breach | Immediate (< 5 min) | Production DB down, credentials leaked |
+| **P1** | Major feature broken for all users | < 15 min | Auth service down, checkout failing |
+| **P2** | Significant degradation, partial outage | < 1 hour | Elevated error rate, slow responses |
+| **P3** | Minor impact, workaround available | Best effort / next business day | Single user affected, cosmetic |
+
+Define severity in your runbook and assign it early — it determines escalation and comms cadence.
+
+## The Response Loop
+
+```
+Detect → Declare → Triage → Mitigate → Resolve → Post-mortem
+```
+
+### Detect
+
+Alert sources: Prometheus/Grafana alerting, Datadog, PagerDuty, user reports, on-call rotation.
+
+Healthy detection requires:
+- Symptom-based alerts (error rate, latency p99, availability) not just cause-based
+- Alert fatigue prevention: alert on SLO burn rate, not raw thresholds
+- Clear escalation paths: who gets paged first, who is backup
+
+### Declare
+
+Declare an incident early, even if uncertain. It is easier to downgrade than to delay comms.
+
+1. Create incident channel: `#incident-YYYY-MM-DD-brief-description`
+2. Assign **Incident Commander (IC)** — one person owns the call and all decisions
+3. Assign **Scribe** — records timeline, decisions, actions in real time
+4. Assign **Comms Lead** — status page updates and stakeholder notifications
+
+### Triage
+
+IC asks: **"What is the user impact and is it getting better or worse?"**
+
+```
+1. Confirm the alert is real (not a monitoring fluke)
+2. Bound the blast radius — how many users? Which regions?
+3. Identify the change vector — what deployed recently?
+4. Establish a working hypothesis
+```
+
+Use `git log --since="2 hours ago"` and deployment logs to find the change vector.
+
+### Mitigate (not root cause — stop the bleeding first)
+
+Mitigation options in priority order:
+1. **Rollback** — fastest if a recent deploy is the cause
+2. **Feature flag off** — disable the failing feature
+3. **Traffic shift** — route to a healthy region or canary
+4. **Scale up** — if resource exhaustion is the cause
+5. **Restart** — for stuck processes (last resort — often hides root cause)
+
+Do NOT wait for a perfect fix. Mitigate first, fix properly after users are unblocked.
+
+### Resolve
+
+Incident is resolved when:
+- User impact returns to baseline
+- Monitoring shows healthy signals for ≥ 15 minutes
+- A clear path to permanent fix is identified
+
+Close the incident channel. Update the status page. Send resolution notification to stakeholders.
+
+## Communication During the Incident
+
+### Status page cadence
+
+| Phase | Cadence |
+|---|---|
+| P0/P1 active | Every 15 minutes |
+| P2 active | Every 30–60 minutes |
+| Resolved | One final update with summary |
+
+Status updates must include: what is impacted, what we know, what we are doing, when the next update is.
+
+```
+[INVESTIGATING] We are seeing elevated error rates on the checkout service.
+Impact: ~30% of checkout attempts are failing.
+We are investigating and will provide an update in 15 minutes.
+```
+
+### Internal Slack cadence
+
+IC posts to the incident channel:
+- Current hypothesis
+- Actions being taken and by whom
+- Decisions made
+- New findings
+
+Scribe captures everything in the timeline doc.
+
+## Post-Mortem (Blameless)
+
+Write the post-mortem within 48 hours while memory is fresh.
+
+### Required sections
+
+1. **Summary** — 3-sentence description of what happened, impact, and resolution
+2. **Timeline** — chronological log with timestamps
+3. **Root cause(s)** — use 5-whys to reach systemic causes, not surface symptoms
+4. **Contributing factors** — process/tooling gaps that allowed the issue
+5. **What went well** — detection worked, rollback was fast, etc.
+6. **Action items** — concrete, assigned, time-bounded; not vague recommendations
+
+### 5-Whys example
+
+```
+User impact: checkout error rate 30%
+Why? → Payment service returning 500s
+Why? → DB connection pool exhausted
+Why? → Query added in yesterday's deploy was unindexed and slow
+Why? → No query performance review in the PR process
+Why? → We have no policy requiring EXPLAIN ANALYZE on new queries
+
+Action: Add query plan check to PR template + CI gate for slow queries
+```
+
+### Blameless culture
+
+The post-mortem finds systemic failures, not individual errors. A person took an action that made sense given the information and tools available at the time — the question is why the system allowed that action to cause an outage.
+
+## Runbook Template
+
+Every on-call service should have a runbook per alert type:
+
+```markdown
+# Alert: HighPaymentErrorRate
+
+## What this means
+The fraction of payment attempts returning 5xx has exceeded 5% for 5 minutes.
+
+## Immediate checks
+1. `kubectl logs -n payments -l app=payment-svc --tail=100`
+2. Check Grafana → Payments dashboard → DB connection pool utilization
+3. Check recent deploys: `kubectl rollout history deployment/payment-svc`
+
+## Mitigation options
+- If deploy-related: `kubectl rollout undo deployment/payment-svc`
+- If DB-related: page DBA on-call; check slow query log
+
+## Escalation
+If unresolved after 20 min: escalate to on-call lead.
+```
+
+## Tools Reference
+
+| Need | Tool |
+|---|---|
+| Alerting | PagerDuty, OpsGenie |
+| Dashboards | Grafana, Datadog |
+| Log search | Loki, Datadog Logs, CloudWatch |
+| Trace analysis | Jaeger, Tempo, Datadog APM |
+| Status page | Statuspage.io, Atlassian Status |
+| Incident management | Incident.io, FireHydrant, PagerDuty IR |
+| Post-mortem tracking | Linear, Jira, Notion |

package/skills/devops/monorepo.md

@@ -0,0 +1,87 @@
+<!--
+skills/devops/monorepo.md — Monorepo — Use this skill when selecting monorepo tooling, structuring packages, or optimiz
+
+Use this skill when selecting monorepo tooling, structuring packages, or optimizing affected-only builds. ## Tool Selection
+-->
+# Monorepo
+
+Use this skill when selecting monorepo tooling, structuring packages, or optimizing affected-only builds.
+
+## Tool Selection
+
+| Tool | Best For | When NOT to Use | Overhead |
+|---|---|---|---|
+| pnpm workspaces | Simple multi-package repos, shared deps, no task orchestration | Complex task graphs, build caching requirements | Minimal |
+| Turborepo | Medium complexity, build/test caching critical, TypeScript/JS-first, works on pnpm/yarn/npm | Polyglot repos with non-JS build systems | Low |
+| Nx | Large orgs, polyglot, code generation, fine-grained ownership, plugin ecosystem | Small teams or repos where Nx's concepts add more friction than value | Medium–High |
+| Bazel | 10k+ files, strict reproducibility, polyglot, hermetic builds | Any team without a dedicated Bazel expert; startup cost is high | Very High |
+
+Start with pnpm workspaces. Add Turborepo when caching becomes valuable. Reach for Nx only when you need its generator, constraint, or ownership systems.
+
+## Repository Layout
+
+```
+apps/
+  web/          # deployable applications
+  api/
+packages/
+  shared/       # shared types, utilities consumed by multiple apps or packages
+  ui/           # component library
+  config/       # shared eslint, tsconfig, prettier configs
+  billing/      # domain packages — business logic with no UI
+  auth/
+```
+
+Keep `apps/` for deployable surfaces and `packages/` for everything importable. Never put deployable entrypoints inside `packages/`. Config packages (`packages/config/`) centralise tooling setup — each app/package extends rather than duplicates.
+
+## Package Boundaries
+
+- One package per domain or product surface (`packages/billing`, `packages/auth`, `apps/web`, `apps/api`).
+- Place shared utilities in `packages/utils` or `packages/shared` — never in an app package.
+- Never import directly from one `apps/` package to another `apps/` package; extract shared code to `packages/`.
+- Each package exposes its public API through a single `index.ts` barrel file; internal modules are private.
+- Enforce boundaries with Nx `@nrwl/enforce-module-boundaries` lint rules or ESLint's `import/no-restricted-paths`.
+
+## Affected-only Builds
+
+Turborepo:
+```bash
+turbo run build --filter=[HEAD^1]
+turbo run test --filter=[HEAD^1]...
+```
+
+Nx:
+```bash
+nx affected --target=build --base=origin/main
+nx affected --target=test --base=origin/main
+```
+
+Both tools build a change graph from the dependency tree. A change to `packages/utils` marks every downstream package as affected. Only affected packages run in CI — unaffected packages use cached results.
+
+CI integration: set `--base` to the merge base of the PR branch (`origin/main` or `$(git merge-base HEAD origin/main)`), not `HEAD^1`, to correctly identify all changed files in the PR.
+
+## Dependency Management
+
+- Use the workspace protocol in pnpm (`workspace:*`) to reference local packages; this guarantees the local version is always used.
+- Never duplicate a dependency version across packages unless there is an explicit version conflict. Use a single lock file at the repo root.
+- Align peer dependencies across all packages; mismatched React or TypeScript versions produce hard-to-diagnose errors.
+- Use `pnpm why <package>` to trace why a transitive dep is installed before removing it.
+- Run `pnpm dedupe` after bulk upgrades to collapse duplicate transitive versions.
+
+## Versioning Strategies
+
+| Strategy | Tool | When to Use |
+|---|---|---|
+| Fixed (all packages same version) | Lerna (`--unified`), Nx Release | Libraries published together; consumers always upgrade the full suite |
+| Independent (each package versioned separately) | Changesets, Lerna (`--independent`) | Packages released on different cadences; consumers pick and choose |
+
+Changesets workflow: developers add a changeset file (`pnpm changeset`) describing the change and bump type; CI applies changesets and publishes on merge to main. This keeps version decisions in PRs rather than as a post-merge step.
+
+Generate changelogs automatically from changeset files; do not write changelogs manually.
+
+## CI Optimization
+
+- Cache `.turbo` or Nx's default cache directory (`node_modules/.cache/nx`) between CI runs, keyed to the lock file hash.
+- Enable remote caching (Turborepo Remote Cache, Nx Cloud) for team environments — local caches do not transfer between CI runners.
+- Run `turbo prune --scope=<app>` to generate a minimal lockfile subset for Docker builds of individual apps.
+- Gate PR merges on `affected` tests, not the full suite, to keep CI under 10 minutes for large repos.

package/skills/devops/observability.md

@@ -0,0 +1,103 @@
+<!--
+skills/devops/observability.md — Observability — Use this skill when designing logging, tracing, metrics, or alerting systems.
+
+Use this skill when designing logging, tracing, metrics, or alerting systems. ## Three Pillars
+-->
+# Observability
+
+Use this skill when designing logging, tracing, metrics, or alerting systems.
+
+## Three Pillars
+
+### Logs
+- Structured format (JSON) with consistent field names
+- Required fields: timestamp, level, service, request_id, message
+- Levels: DEBUG (development only), INFO (normal operations), WARN (unexpected but handled), ERROR (failures requiring attention)
+- Never log secrets, passwords, tokens, or full PII
+- Correlate logs with trace IDs for request-level debugging
+- Centralize logs: ELK, Loki, CloudWatch, Datadog
+
+### Metrics
+- USE method for resources: Utilization, Saturation, Errors
+- RED method for services: Rate, Errors, Duration
+- Four golden signals: latency, traffic, errors, saturation
+- Use histograms for latency (not averages)
+- Label dimensions: service, endpoint, status_code, environment
+- Keep cardinality manageable; avoid high-cardinality labels
+
+### Traces
+- Distributed tracing across service boundaries
+- Propagate trace context via headers (W3C Trace Context or B3)
+- Instrument: HTTP clients/servers, database queries, message queue operations
+- Sample in production: 1-10% for high-traffic services, 100% for low-traffic
+- Record: span name, duration, status, attributes, parent span
+
+## Instrumentation
+
+### What to Instrument
+- Every inbound request (HTTP, gRPC, message consumer)
+- Every outbound call (database, cache, external API, queue publish)
+- Business events: signup, purchase, error recovery
+- Background jobs: start, complete, fail
+
+### How to Instrument
+- Use OpenTelemetry for vendor-neutral instrumentation
+- Auto-instrumentation for frameworks and libraries when available
+- Custom spans for business-critical code paths
+- Baggage for cross-service context (tenant ID, feature flags)
+
+## Alerting
+
+### Alert Design
+- Alert on symptoms (error rate, latency), not causes (CPU, memory)
+- Use burn rate alerts for SLO-based monitoring
+- Page for user-impacting issues; ticket for non-urgent
+- Every alert must have a runbook link
+- Test alerts regularly; unused alerts should be deleted
+
+### Severity Levels
+
+| Level | Response Time | Example |
+|---|---|---|
+| Critical (page) | <15 min | Service down, data loss risk |
+| High (page) | <1 hour | Error rate >5%, SLO breach |
+| Medium (ticket) | <24 hours | Elevated latency, disk >80% |
+| Low (ticket) | <1 week | Dependency deprecation, minor anomaly |
+
+### Anti-Patterns
+- Alerting on every metric threshold (alert fatigue)
+- Alerts without runbooks (responder does not know what to do)
+- Alerts that always fire (desensitization)
+- No owner assigned to an alert
+
+## SLOs
+
+- Define SLIs: the metric that represents user experience (availability, latency, correctness)
+- Set SLO target: e.g., 99.9% of requests complete in <300ms
+- Calculate error budget: 100% - SLO = acceptable failures per period
+- Alert when error budget burn rate exceeds threshold
+- Review SLOs quarterly; adjust based on business needs and reliability data
+
+## Dashboards
+
+### Principles
+- One overview dashboard per service
+- Top section: SLO status, error budget remaining
+- Middle section: traffic, latency (p50, p95, p99), error rate
+- Bottom section: resource utilization, dependency health
+- Drill-down dashboards for specific subsystems
+- Avoid vanity metrics; every panel should inform a decision
+
+### Tools
+- Grafana for open-source metric visualization
+- Datadog, New Relic, or Honeycomb for managed observability
+- PagerDuty or Opsgenie for alert routing and escalation
+
+## Incident Investigation Flow
+
+1. Check SLO dashboard for affected services
+2. Inspect error rate and latency spikes for timing
+3. Filter traces by error status in the time window
+4. Read logs correlated with failing trace IDs
+5. Identify the root service and operation
+6. Check recent deployments and configuration changes

package/skills/devops/performance.md

@@ -0,0 +1,104 @@
+<!--
+skills/devops/performance.md — Performance Engineering — Use this skill when profiling, load testing, or optimizing application and infra
+
+Use this skill when profiling, load testing, or optimizing application and infrastructure performance. ## Performance Targets
+-->
+# Performance Engineering
+
+Use this skill when profiling, load testing, or optimizing application and infrastructure performance.
+
+## Performance Targets
+
+Define targets before optimizing. Measure against real user experience.
+
+| Metric | Web Target | API Target |
+|---|---|---|
+| p50 latency | <200ms | <50ms |
+| p95 latency | <1s | <200ms |
+| p99 latency | <3s | <500ms |
+| Throughput | - | Define per endpoint |
+| Error rate | <0.1% | <0.1% |
+
+## Profiling
+
+### Application Profiling
+- CPU profiling: identify hot functions and call paths
+- Memory profiling: find leaks, excessive allocations, and retention
+- Trace profiling: follow requests across service boundaries
+- Flame graphs for visual analysis of CPU and memory usage
+- Profile in production or with production-like data; synthetic benchmarks mislead
+
+### Database Profiling
+- Slow query log (threshold: 100ms)
+- EXPLAIN ANALYZE on suspect queries
+- Index usage statistics
+- Connection pool utilization
+- Lock contention and wait events
+
+### Network Profiling
+- DNS resolution time
+- TLS handshake time
+- Time to first byte (TTFB)
+- Payload size and compression effectiveness
+- Connection reuse and keep-alive behavior
+
+## Load Testing
+
+### Types
+- **Smoke**: minimal load to verify the system works (1-5 users)
+- **Load**: expected production traffic to establish baseline
+- **Stress**: beyond expected traffic to find the breaking point
+- **Soak**: sustained load for hours to find leaks and degradation
+- **Spike**: sudden traffic burst to test auto-scaling and recovery
+
+### Tools
+- k6, Gatling, Locust, Artillery, or JMeter
+- Script realistic user journeys, not just single endpoints
+- Ramp up gradually; sudden jumps obscure bottleneck identification
+- Run against an environment isolated from production
+- Collect metrics from application, database, and infrastructure during tests
+
+### Analysis
+- Identify the bottleneck: CPU, memory, I/O, network, database, external service
+- Fix one bottleneck at a time; re-measure after each fix
+- Document baseline metrics before optimization
+- Compare before and after with statistical significance
+
+## Optimization Techniques
+
+### Application
+- Cache expensive computations and repeated queries
+- Use connection pooling for databases and HTTP clients
+- Batch operations instead of sequential calls
+- Async processing for non-blocking work
+- Precompute and materialize frequently accessed derived data
+
+### Database
+- Optimize queries before adding hardware
+- Add indexes for slow queries (EXPLAIN first)
+- Use read replicas for read-heavy workloads
+- Partition large tables by time or tenant
+- Archive old data to reduce active dataset size
+
+### Infrastructure
+- Right-size instances based on actual utilization
+- Auto-scale based on leading indicators (queue depth, CPU trend)
+- Use CDN for static content and cacheable API responses
+- Place compute close to data to reduce network latency
+- Compress responses (gzip, brotli, zstd)
+
+## Monitoring for Performance
+
+- Track p50, p95, p99 latency per endpoint
+- Monitor error rate alongside latency
+- Set SLOs and alert on burn rate, not individual breaches
+- Dashboard: latency, throughput, error rate, saturation (CPU, memory, connections)
+- Compare metrics week-over-week to detect gradual degradation
+
+## Anti-Patterns
+
+- Optimizing without profiling (guessing the bottleneck)
+- Premature optimization of code that runs rarely
+- Caching without invalidation strategy
+- Adding resources instead of fixing the root cause
+- Micro-benchmarks that do not reflect production workloads

package/skills/devops/testing.md

@@ -0,0 +1,104 @@
+<!--
+skills/devops/testing.md — Testing Strategy — Use this skill when planning test coverage, selecting test types, or establishin
+
+Use this skill when planning test coverage, selecting test types, or establishing testing practices. ## Test Pyramid
+-->
+# Testing Strategy
+
+Use this skill when planning test coverage, selecting test types, or establishing testing practices.
+
+## Test Pyramid
+
+### Unit Tests (70%)
+- Test individual functions, methods, and classes in isolation
+- Fast: entire suite runs in seconds
+- Mock external dependencies (database, network, file system)
+- One assertion per test when practical
+- Name tests for the behavior they verify
+
+### Integration Tests (20%)
+- Test interactions between components
+- Use real databases (Docker containers) when practical
+- Test API endpoints end-to-end within the service
+- Verify serialization, query behavior, and error propagation
+- Slower than unit tests; run in CI, not necessarily on every save
+
+### End-to-End Tests (10%)
+- Test critical user flows through the full system
+- Use browser automation (Playwright, Cypress) for web
+- Cover the happy path and the most important error paths
+- Flaky by nature; invest in deterministic waits and stable selectors
+- Run in CI; gate deployment on these passing
+
+## Test Structure (AAA)
+
+```
+Arrange: set up preconditions and inputs
+Act: execute the behavior under test
+Assert: verify the expected outcome
+```
+
+- One act per test
+- Minimize arrangement; use factories or fixtures
+- Assertions should be specific and descriptive
+
+## Coverage Targets
+
+| Category | Minimum | Target |
+|---|---|---|
+| Overall | 80% | 90% |
+| Critical paths | 95% | 100% |
+| Utility functions | 90% | 95% |
+| Error handling | 80% | 90% |
+
+- Measure branch coverage, not just line coverage
+- Coverage is a floor, not a ceiling; high coverage does not guarantee quality
+- Uncovered code should have documented justification
+
+## Test Naming
+
+Use descriptive names that explain the scenario:
+- `returns empty array when no results match`
+- `throws validation error when email is missing`
+- `retries three times before failing`
+
+Avoid: `test1`, `testCreate`, `it works`
+
+## Mocking Guidelines
+
+- Mock external dependencies, not internal implementation
+- Prefer fakes (in-memory database) over mocks when practical
+- Verify mock interactions only when the interaction itself is the behavior
+- Reset mocks between tests to prevent state leakage
+- Avoid mocking what you do not own; use integration tests instead
+
+## Test Data
+
+- Use factories or builders for test data creation
+- Randomize non-essential fields to catch hidden dependencies
+- Use realistic data shapes and sizes
+- Clean up test data after each test or use transactions with rollback
+- Never use production data in tests
+
+## Flaky Test Management
+
+- Quarantine flaky tests immediately; do not let them erode CI trust
+- Fix or delete within one sprint
+- Common causes: timing, shared state, external dependencies, race conditions
+- Use retry as a diagnostic tool, not a fix
+
+## Performance Testing
+
+- Load test: expected traffic for baseline
+- Stress test: beyond expected traffic to find breaking point
+- Soak test: sustained load to find memory leaks and resource exhaustion
+- Benchmark critical paths with repeatable measurements
+- Automate performance regression detection in CI
+
+## Security Testing
+
+- SAST: static analysis in CI on every commit
+- DAST: dynamic scanning against staging environment
+- Dependency scanning: `audit` commands in CI
+- Penetration testing: quarterly or after major changes
+- See `skills/security/pentest.md` for detailed web testing guidance

package/skills/docs/adr-workflow.md

@@ -0,0 +1,32 @@
+<!--
+skills/docs/adr-workflow.md — Workflow for recording an architectural decision as an ADR.
+
+Triggered when cx-architect finalizes a design or a technology choice is made. Writes a
+full ADR to docs/adr/ using the shipped template (user-overridable via .cx/templates/docs/adr.md)
+and a shorter entry to .cx/decisions/ for session context.
+-->
+# ADR Workflow
+
+Use when: an architectural decision is made that affects the system structure, data model, API contracts, or technology choices.
+
+## Trigger automatically when
+- cx-architect finalizes a design
+- A technology is selected over alternatives
+- A pattern is established that should be followed project-wide
+- A previous decision is reversed or superseded
+
+## Steps
+
+1. **cx-architect** or **cx-engineer** identifies the decision
+2. **Write to `docs/adr/ADR-{NNN}-{slug}.md`** using the template from `get_template("adr")` — resolves `.cx/templates/docs/adr.md` (override) then `templates/docs/adr.md` (shipped)
+   - NNN = next sequential number (check existing files)
+3. **Also write a shorter entry to `.cx/decisions/`** for session context
+4. **cx-docs-keeper** updates `.cx/context.md` Architecture Notes with a one-line summary and link
+
+## File naming
+- `docs/adr/ADR-001-use-postgres-over-mysql.md`
+- `docs/adr/ADR-002-jwt-auth-strategy.md`
+
+## Cross-referencing
+- If this ADR supersedes another: update the old ADR's status field
+- If this ADR depends on another: add a References link

package/skills/docs/backlog-proposal-workflow.md

@@ -0,0 +1,19 @@
+<!--
+skills/docs/backlog-proposal-workflow.md — Approval-gated issue tracker proposals.
+-->
+# Backlog Proposal Workflow
+
+Use when: product evidence should create or update Jira, Linear, GitHub Issues, or another tracker.
+
+## Steps
+
+1. Load source evidence, evidence brief, PRD, or signal brief.
+2. Search existing tracker context if an MCP is configured; otherwise search local docs and product-intel artifacts.
+3. Create `.cx/product-intel/backlog-proposals/{date}-{slug}.md` with `get_template("backlog-proposal")`.
+4. Include duplicate/conflict analysis and exact proposed writes.
+5. Return `NEEDS_MAIN_INPUT` for approval before any external write.
+6. After approval, apply changes and update the proposal's application log.
+
+## Rules
+
+Never write externally from weak evidence without making the risk explicit. Never create duplicate issues when an existing issue can be updated.

package/skills/docs/customer-profile-workflow.md

@@ -0,0 +1,22 @@
+<!--
+skills/docs/customer-profile-workflow.md — Maintain durable customer/account memory for Product Intelligence.
+-->
+# Customer Profile Workflow
+
+Use when: customer evidence should update durable product memory.
+
+## Steps
+
+1. Load the existing customer profile from `.cx/product-intel/customer-profiles/` if present.
+2. Read the new source evidence.
+3. Add new facts, asks, pain points, contacts, product areas, and evidence links.
+4. Preserve historical entries. Do not delete or rewrite prior history without explicit approval.
+5. Save with `get_template("customer-profile")`.
+
+## Rules
+
+Profiles are product memory, not CRM records. Keep only information needed for product decisions. Mark uncertain facts as uncertain and cite the source.
+
+## Retrieval
+
+Customer profiles are indexed by hybrid retrieval. Future PRDs, PRFAQs, evidence briefs, and backlog proposals should search them before drafting.

package/skills/docs/evidence-ingest-workflow.md

@@ -0,0 +1,23 @@
+<!--
+skills/docs/evidence-ingest-workflow.md — Normalize raw product evidence into Construct product-intel artifacts.
+-->
+# Evidence Ingest Workflow
+
+Use when: the user pastes customer notes, Slack threads, support tickets, sales notes, research snippets, RFCs, analytics summaries, or competitor signals.
+
+## Steps
+
+1. Identify the source type and date.
+2. Extract source metadata: customer, actor, product area, channel, linked issue, and confidence.
+3. Save raw or lightly normalized source material under `.cx/product-intel/sources/`.
+4. If customer-specific, update or create `.cx/product-intel/customer-profiles/{customer}.md` using `get_template("customer-profile")`.
+5. Create `.cx/product-intel/evidence-briefs/{date}-{slug}.md` using `get_template("evidence-brief")` when the evidence supports a product decision.
+6. If evidence is weak but worth preserving, create a signal brief with `get_template("signal-brief")`.
+
+## Rules
+
+Do not invent customer quotes, names, or issue links. Preserve ambiguity. If source evidence contains personal data, record only the minimum needed for product decisions.
+
+## Storage
+
+Files in `.cx/product-intel/` are indexed by Construct's hybrid retrieval path. Postgres stores them as `product-intel` documents during sync, and the vector layer makes them semantically retrievable for future PRDs and Meta PRDs.