@geraldmaron/construct 1.0.5 → 1.0.6

package/skills/development/kotlin.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/kotlin.md — Kotlin / Android Development — | Scope | Use when |
+skills/development/kotlin.md (Kotlin / Android Development) | Scope | Use when |
 
 ## Coroutines & Flows ### Coroutine scope discipline
 -->
@@ -14,7 +14,7 @@ skills/development/kotlin.md — Kotlin / Android Development — | Scope | Use
 | `viewModelScope` | ViewModel-bound work; auto-cancelled on clear |
 | `lifecycleScope` | Fragment/Activity-bound; cancelled on destroy |
 | `rememberCoroutineScope()` | Compose-scoped; cancelled on composition exit |
-| `GlobalScope` | Never — uncontrolled lifetime |
+| `GlobalScope` | Never: uncontrolled lifetime |
 
 ```kotlin
 class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
@@ -31,7 +31,7 @@ class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
 
 ### Flow operators
 
-- `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)` — converts cold flow to hot StateFlow for UI consumption
+- `stateIn(scope, SharingStarted.WhileSubscribed(5_000), initial)`: converts cold flow to hot StateFlow for UI consumption
 - `map`, `filter`, `distinctUntilChanged`, `debounce` for transform chains
 - `combine` for merging multiple flows
 - Use `flowOn(Dispatchers.IO)` for upstream CPU/IO work; do not switch dispatchers in the collector
@@ -43,7 +43,7 @@ class ItemViewModel(private val repo: ItemRepository) : ViewModel() {
 | `Dispatchers.Main` | UI updates |
 | `Dispatchers.IO` | Network, disk, database |
 | `Dispatchers.Default` | CPU-intensive work |
-| `Dispatchers.Unconfined` | Rarely — only in tests |
+| `Dispatchers.Unconfined` | Rarely: only in tests |
 
 ## Jetpack Compose
 
@@ -69,7 +69,7 @@ fun ItemList(items: List<Item>, onDelete: (Item) -> Unit) { ... }
 
 - `remember` expensive computations with stable keys
 - `key(id) { ... }` in lazy lists to preserve item identity
-- Avoid unstable lambdas — use `remember { { ... } }` or stable function references
+- Avoid unstable lambdas: use `remember { { ... } }` or stable function references
 - Enable Compose compiler metrics to detect recomposition hot spots
 - Prefer `LazyColumn` over `Column` for variable-length lists
 
@@ -134,7 +134,7 @@ Scoping: `@Singleton` for app-scoped, `@ActivityRetainedScoped` for ViewModel-li
 
 ## Common Pitfalls
 
-- `collect` in `Fragment.onViewCreated` without `repeatOnLifecycle(STARTED)` — causes collection after view destruction
-- `StateFlow.value` reads in tests without collecting — use `turbine` or `runTest { first() }`
-- Leaking `Activity` context into long-lived objects — use `applicationContext`
-- `LazyColumn` with `items(list)` where `list` is `State<List<...>>` causing full recomposition — use `key` param
+- `collect` in `Fragment.onViewCreated` without `repeatOnLifecycle(STARTED)`: causes collection after view destruction
+- `StateFlow.value` reads in tests without collecting: use `turbine` or `runTest { first() }`
+- Leaking `Activity` context into long-lived objects: use `applicationContext`
+- `LazyColumn` with `items(list)` where `list` is `State<List<...>>` causing full recomposition: use `key` param

package/skills/development/mobile-crossplatform.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/mobile-crossplatform.md — Mobile Cross-Platform Development — Before choosing a framework, answer:
+skills/development/mobile-crossplatform.md (Mobile Cross-Platform Development) Before choosing a framework, answer:
 
 ## Decision Framework: Native vs Cross-Platform Before choosing a framework, answer:
 -->
@@ -13,11 +13,11 @@ Before choosing a framework, answer:
 |---|---|---|
 | Platform-specific APIs needed (ARKit, Health, NFC)? | Yes | No |
 | Animation fidelity is a differentiator? | Yes | Partial |
-| Single team, both platforms? | — | Yes |
+| Single team, both platforms? |: | Yes |
 | Heavy use of platform OS widgets? | Yes | No |
-| App is primarily data-display / CRUD? | — | Yes |
-| Existing web team? | — | React Native |
-| Existing Kotlin/Swift team? | Native | — |
+| App is primarily data-display / CRUD? |: | Yes |
+| Existing web team? |: | React Native |
+| Existing Kotlin/Swift team? | Native |: |
 
 ---
 
@@ -42,7 +42,7 @@ Future<List<Item>> items(ItemsRef ref) async {
 
 ### Performance
 
-- `const` constructors everywhere possible — eliminates widget rebuilds
+- `const` constructors everywhere possible: eliminates widget rebuilds
 - `RepaintBoundary` around independently-animated subtrees
 - Profile with Flutter DevTools → CPU flame chart + widget rebuild tracker
 - `ListView.builder` for lazy lists; never `ListView(children: [...])` for long lists
@@ -78,8 +78,8 @@ testWidgets('shows items on load', (tester) async {
 ### New Architecture (React Native 0.74+)
 
 Enable the New Architecture by default on new projects. Key changes:
-- JSI replaces the async bridge — sync native calls
-- Fabric replaces the native renderer — concurrent React features work correctly
+- JSI replaces the async bridge: sync native calls
+- Fabric replaces the native renderer: concurrent React features work correctly
 - TurboModules replace native modules
 
 ### State & logic sharing with web
@@ -130,11 +130,11 @@ export default function ItemScreen() { ... }
 
 ## Common Pitfalls (both frameworks)
 
-- **Deep linking not tested until late** — set up universal links / app links in week 1
-- **Push notifications complexity** — Expo Notifications or Firebase Cloud Messaging; plan for permission states
-- **Over-the-air update strategy** — define what can be OTA vs what requires App Store review
-- **Platform capability divergence** — features available on iOS 17+ may be absent on Android 12; maintain a capability matrix
-- **Code signing automation** — `fastlane match` (iOS) and keystore management (Android) require upfront investment; do it early
+- **Deep linking not tested until late**: set up universal links / app links in week 1
+- **Push notifications complexity**: Expo Notifications or Firebase Cloud Messaging; plan for permission states
+- **Over-the-air update strategy**: define what can be OTA vs what requires App Store review
+- **Platform capability divergence**: features available on iOS 17+ may be absent on Android 12; maintain a capability matrix
+- **Code signing automation**: `fastlane match` (iOS) and keystore management (Android) require upfront investment; do it early
 
 ## When to go native anyway
 

package/skills/development/python.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/python.md — Python Best Practices — Use this skill when writing, reviewing, or debugging Python code.
+skills/development/python.md (Python Best Practices) Use this skill when writing, reviewing, or debugging Python code.
 
 Use this skill when writing, reviewing, or debugging Python code. ## Project Structure
 -->

package/skills/development/rust.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/rust.md — Rust Best Practices — Use this skill when writing, reviewing, or debugging Rust code.
+skills/development/rust.md (Rust Best Practices) Use this skill when writing, reviewing, or debugging Rust code.
 
 Use this skill when writing, reviewing, or debugging Rust code. ## Project Structure
 -->

package/skills/development/shell.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/shell.md — Shell Scripting Best Practices — Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell s
+skills/development/shell.md (Shell Scripting Best Practices) Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell s
 
 Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell scripts. ## Script Header
 -->

package/skills/development/swift.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/swift.md — Swift / iOS Development — Swift 6 enforces data-race safety at compile time. Annotate isolation boundary e
+skills/development/swift.md (Swift / iOS Development) Swift 6 enforces data-race safety at compile time. Annotate isolation boundary e
 
 ## Concurrency (Swift 6 Strict Concurrency) Swift 6 enforces data-race safety at compile time. Annotate isolation boundary explicitly:
 -->
@@ -26,7 +26,7 @@ Key rules:
 - `Sendable` conformance on types crossing isolation boundaries
 - Prefer `async/await` over completion handlers; avoid mixing the two
 
-Common pitfall: `Task { }` inherits the actor context of its caller — do not assume it runs on a background thread.
+Common pitfall: `Task { }` inherits the actor context of its caller: do not assume it runs on a background thread.
 
 ## SwiftUI Patterns
 
@@ -80,7 +80,7 @@ func testFetchReturnsItems() async throws {
 
 ### UI tests
 
-Prefer `XCUITest` for critical flows only — it is slow and flaky. Supplement with snapshot tests (`swift-snapshot-testing`) for visual regression.
+Prefer `XCUITest` for critical flows only: it is slow and flaky. Supplement with snapshot tests (`swift-snapshot-testing`) for visual regression.
 
 ### Test doubles
 
@@ -119,11 +119,11 @@ View → ViewModel (@MainActor) → Repository (actor) → Network/DB
 
 ### The Composable Architecture (TCA)
 
-Use TCA when state fan-out is complex or testability of reducers is a priority. Adds boilerplate — evaluate against team familiarity.
+Use TCA when state fan-out is complex or testability of reducers is a priority. Adds boilerplate: evaluate against team familiarity.
 
 ## Common Pitfalls
 
-- Do not call `@MainActor` methods from synchronous non-main contexts — use `Task { @MainActor in ... }`
+- Do not call `@MainActor` methods from synchronous non-main contexts: use `Task { @MainActor in ... }`
 - Avoid `DispatchQueue.main.async` in new code; use `await MainActor.run { }` instead
-- `@StateObject` vs `@ObservedObject` confusion causes double-initialization bugs — `@StateObject` only at the owner
+- `@StateObject` vs `@ObservedObject` confusion causes double-initialization bugs: `@StateObject` only at the owner
 - `List` with large datasets: use `lazy` loading or pagination; do not load everything into `@State`

package/skills/development/typescript.md

@@ -1,5 +1,5 @@
 <!--
-skills/development/typescript.md — TypeScript Best Practices — Use this skill when writing, reviewing, or debugging TypeScript or JavaScript co
+skills/development/typescript.md (TypeScript Best Practices) Use this skill when writing, reviewing, or debugging TypeScript or JavaScript co
 
 Use this skill when writing, reviewing, or debugging TypeScript or JavaScript code. ## Project Structure
 -->

package/skills/devops/ci-cd.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/ci-cd.md — CI/CD — Use this skill when designing, debugging, or optimizing CI/CD pipelines.
+skills/devops/ci-cd.md (CI/CD) Use this skill when designing, debugging, or optimizing CI/CD pipelines.
 
 Use this skill when designing, debugging, or optimizing CI/CD pipelines. ## Pipeline Stages
 -->
@@ -11,12 +11,12 @@ Use this skill when designing, debugging, or optimizing CI/CD pipelines.
 
 | Stage | Purpose | Tools | Failure Policy |
 |---|---|---|---|
-| Build | Compile, lint, typecheck | tsc, eslint, cargo check, go vet | Fail fast — block all downstream stages |
+| Build | Compile, lint, typecheck | tsc, eslint, cargo check, go vet | Fail fast: block all downstream stages |
 | Test | Unit → integration → e2e | Jest, Pytest, go test, Playwright | Fail on any; parallelize within stage |
 | Security Scan | SAST, dep audit, secrets detection | Semgrep, CodeQL, Trivy, gitleaks | Block on CRITICAL/HIGH; warn on MEDIUM |
 | Deploy | Promote artifact through environments | GitHub Actions, ArgoCD, Helm | Gate on all prior stages passing |
 
-Always run lint and typecheck before tests — they are faster and catch more errors per second of CI time.
+Always run lint and typecheck before tests: they are faster and catch more errors per second of CI time.
 
 ## GitHub Actions
 
@@ -94,14 +94,14 @@ Never auto-deploy to production without a passing security scan and at least one
 
 - Store secrets in the platform's encrypted secret store (GitHub Actions Secrets, GitLab CI Variables).
 - Never hardcode secrets in workflow files or Dockerfiles.
-- Mask secrets in logs — CI platforms do this automatically for registered secrets; verify it works before relying on it.
+- Mask secrets in logs: CI platforms do this automatically for registered secrets; verify it works before relying on it.
 - Rotate any secret immediately after a potential exposure; treat "may have leaked" the same as "did leak".
 - Use OIDC-based short-lived tokens (GitHub OIDC → AWS/GCP/Azure) over long-lived service account keys wherever the cloud provider supports it.
 
 ## Speed Optimization
 
 - Cache dependency layers keyed to lock file hash; a clean install on every run is a CI antipattern.
-- Run lint and typecheck first — they fail fast and cost less than a full test suite.
+- Run lint and typecheck first: they fail fast and cost less than a full test suite.
 - Split slow test suites across workers using matrix or `--shard` flags (Vitest, Jest, Playwright all support sharding).
 - Parallelize independent test files; do not serialize unit tests.
 - In monorepos, run only affected packages: `turbo run test --filter=[HEAD^1]` or `nx affected --target=test`.

package/skills/devops/containerization.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/containerization.md — Containerization — Use this skill when writing Dockerfiles, optimizing image size, or securing cont
+skills/devops/containerization.md (Containerization) Use this skill when writing Dockerfiles, optimizing image size, or securing cont
 
 Use this skill when writing Dockerfiles, optimizing image size, or securing container builds. ## Multi-Stage Builds
 -->
@@ -26,14 +26,14 @@ COPY --from=builder /app/node_modules ./node_modules
 ```
 
 Runtime base image selection:
-- `gcr.io/distroless/nodejs20-debian12` — no shell, no package manager, smallest attack surface for Node.
-- `node:20-alpine` — shell available for debugging; use when distroless breaks scripts.
-- `scratch` — static binaries only (Go, Rust with `musl`).
+- `gcr.io/distroless/nodejs20-debian12`: no shell, no package manager, smallest attack surface for Node.
+- `node:20-alpine`: shell available for debugging; use when distroless breaks scripts.
+- `scratch`: static binaries only (Go, Rust with `musl`).
 - Never use `debian`, `ubuntu`, or `node:20` (Debian-based) as a production runtime base; they carry thousands of unnecessary packages.
 
 ## Layer Caching
 
-Order layers by change frequency — least-changed first:
+Order layers by change frequency: least-changed first:
 
 1. Base OS packages (`RUN apk add ...`)
 2. App dependencies (`COPY package*.json ./` then `RUN npm ci`)
@@ -54,7 +54,7 @@ RUN apk add --no-cache curl git && \
     rm -rf /var/cache/apk/*
 ```
 
-Never put cache cleanup in a separate `RUN` — it creates a new layer that does not reclaim space from the previous layer.
+Never put cache cleanup in a separate `RUN`: it creates a new layer that does not reclaim space from the previous layer.
 
 ## Security
 
@@ -67,7 +67,7 @@ Never put cache cleanup in a separate `RUN` — it creates a new layer that does
 | No `apt-get upgrade` | Pin the base image digest instead; `upgrade` produces non-reproducible layers |
 | Read-only filesystem | Pass `--read-only` at runtime; mount writable tmpfs only for paths that need writes |
 
-Never use `ADD` with a URL — it bypasses layer caching in unpredictable ways and cannot be verified. Use `COPY` for local files and `curl` + checksum verification for remote files.
+Never use `ADD` with a URL: it bypasses layer caching in unpredictable ways and cannot be verified. Use `COPY` for local files and `curl` + checksum verification for remote files.
 
 ## Image Scanning
 
@@ -94,7 +94,7 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
 
 Use an HTTP endpoint for web services. Use a process check (`pgrep`) only for non-HTTP workloads.
 
-Kubernetes uses separate liveness, readiness, and startup probes — configure those in the deployment manifest, not in the Dockerfile. The Docker `HEALTHCHECK` is relevant for `docker run` and Docker Compose only.
+Kubernetes uses separate liveness, readiness, and startup probes: configure those in the deployment manifest, not in the Dockerfile. The Docker `HEALTHCHECK` is relevant for `docker run` and Docker Compose only.
 
 ## Size Optimization
 
@@ -102,5 +102,5 @@ Kubernetes uses separate liveness, readiness, and startup probes — configure t
 - `--no-install-recommends` with `apt-get install` eliminates suggested packages.
 - Always clean package manager caches in the same `RUN` layer as the install command.
 - Use `COPY --chown=app:app` instead of a separate `RUN chown` to avoid a wasted layer.
-- Multi-stage builds remove all build tools, source files, and intermediate artifacts automatically — they are the single highest-impact size reduction technique.
+- Multi-stage builds remove all build tools, source files, and intermediate artifacts automatically: they are the single highest-impact size reduction technique.
 - For Go and Rust, build a statically linked binary (`CGO_ENABLED=0` for Go, `musl` target for Rust) and copy it into `scratch` or distroless for a final image under 20 MB.

package/skills/devops/cost-optimization.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/cost-optimization.md — Cloud Cost Optimization — Use this skill when reducing cloud spend, right-sizing resources, or implementin
+skills/devops/cost-optimization.md (Cloud Cost Optimization) Use this skill when reducing cloud spend, right-sizing resources, or implementin
 
 Use this skill when reducing cloud spend, right-sizing resources, or implementing FinOps practices. ## Cost Visibility
 -->

package/skills/devops/data-engineering.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/data-engineering.md — Data Engineering — 1. **Idempotency**: pipelines can run multiple times without duplicating data
+skills/devops/data-engineering.md (Data Engineering) 1. **Idempotency**: pipelines can run multiple times without duplicating data
 
 ## Core Principles 1. **Idempotency**: pipelines can run multiple times without duplicating data
 -->
@@ -59,7 +59,7 @@ stream = env \
 env.execute("Orders Streaming Pipeline")
 ```
 
-Watermarks define event-time handling for late-arriving events — configure based on source latency SLA.
+Watermarks define event-time handling for late-arriving events: configure based on source latency SLA.
 
 ## Data Modeling
 

package/skills/devops/database.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/database.md — Database Patterns — Use this skill when designing schemas, writing migrations, optimizing queries, o
+skills/devops/database.md (Database Patterns) Use this skill when designing schemas, writing migrations, optimizing queries, o
 
 Use this skill when designing schemas, writing migrations, optimizing queries, or selecting databases. ## Schema Design
 -->

package/skills/devops/dependency-management.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/dependency-management.md — Dependency Management — Use this skill when managing package upgrades, resolving CVEs, or establishing l
+skills/devops/dependency-management.md (Dependency Management) Use this skill when managing package upgrades, resolving CVEs, or establishing l
 
 Use this skill when managing package upgrades, resolving CVEs, or establishing lock file and versioning policy. ## Lock File Hygiene
 -->
@@ -11,7 +11,7 @@ Use this skill when managing package upgrades, resolving CVEs, or establishing l
 
 - Always commit lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `go.sum`, `Cargo.lock`.
 - Never delete and regenerate a lock file without reviewing the full diff; regeneration silently upgrades all transitive dependencies.
-- Review lock file diffs in PRs for unexpected transitive version changes — these are where supply chain attacks hide.
+- Review lock file diffs in PRs for unexpected transitive version changes: these are where supply chain attacks hide.
 - Do not add lock files to `.gitignore`; they are the reproducibility contract for the build.
 - A PR that changes only the lock file (no `package.json` change) warrants careful scrutiny.
 
@@ -22,7 +22,7 @@ Use this skill when managing package upgrades, resolving CVEs, or establishing l
 | Dependabot | Daily/weekly schedule | One PR per package by default; group with `groups:` config | Patch: auto-merge if CI passes. Minor: batch weekly, manual review. Major: manual always. |
 | Renovate | Configurable schedule | Group by ecosystem, semver range, or custom regex via `packageRules` | Auto-merge patch and minor with passing CI; use `stabilityDays: 3` to avoid merging on day of release |
 
-Prefer Renovate for complex repos — its `rangeStrategy`, `grouping`, `stabilityDays`, and `automerge` controls are more expressive than Dependabot's.
+Prefer Renovate for complex repos: its `rangeStrategy`, `grouping`, `stabilityDays`, and `automerge` controls are more expressive than Dependabot's.
 
 Always require CI to pass before any auto-merge. Never auto-merge major version bumps.
 

package/skills/devops/devsecops.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/devsecops.md — DevSecOps — Use this skill when integrating security into CI/CD pipelines, managing supply c
+skills/devops/devsecops.md (DevSecOps) Use this skill when integrating security into CI/CD pipelines, managing supply c
 
 Use this skill when integrating security into CI/CD pipelines, managing supply chain risk, or automating security scanning. ## Pipeline Security Stages
 -->

package/skills/devops/git-workflow.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/git-workflow.md — Git Workflow — Use this skill when establishing branching strategies, commit conventions, or co
+skills/devops/git-workflow.md (Git Workflow) Use this skill when establishing branching strategies, commit conventions, or co
 
 Use this skill when establishing branching strategies, commit conventions, or code integration practices. ## Branching Strategies
 -->

package/skills/devops/incident-response.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/incident-response.md — Incident Response — | Sev | User impact | Response time | Example |
+skills/devops/incident-response.md (Incident Response) | Sev | User impact | Response time | Example |
 
 ## Severity Levels | Sev | User impact | Response time | Example |
 -->
@@ -14,7 +14,7 @@ skills/devops/incident-response.md — Incident Response — | Sev | User impact
 | **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.
+Define severity in your runbook and assign it early: it determines escalation and comms cadence.
 
 ## The Response Loop
 
@@ -36,9 +36,9 @@ Healthy detection requires:
 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
+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
 
@@ -53,14 +53,14 @@ IC asks: **"What is the user impact and is it getting better or worse?"**
 
 Use `git log --since="2 hours ago"` and deployment logs to find the change vector.
 
-### Mitigate (not root cause — stop the bleeding first)
+### 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)
+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.
 
@@ -107,12 +107,12 @@ 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
+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
 
@@ -129,7 +129,7 @@ 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.
+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
 

package/skills/devops/monorepo.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/monorepo.md — Monorepo — Use this skill when selecting monorepo tooling, structuring packages, or optimiz
+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
 -->
@@ -32,12 +32,12 @@ packages/
   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.
+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.
+- 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`.
@@ -56,7 +56,7 @@ 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.
+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.
 
@@ -82,6 +82,6 @@ Generate changelogs automatically from changeset files; do not write changelogs
 ## 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.
+- 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

@@ -1,5 +1,5 @@
 <!--
-skills/devops/observability.md — Observability — Use this skill when designing logging, tracing, metrics, or alerting systems.
+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
 -->

package/skills/devops/performance.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/performance.md — Performance Engineering — Use this skill when profiling, load testing, or optimizing application and infra
+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
 -->

package/skills/devops/testing.md

@@ -1,5 +1,5 @@
 <!--
-skills/devops/testing.md — Testing Strategy — Use this skill when planning test coverage, selecting test types, or establishin
+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
 -->

package/skills/docs/adr-workflow.md

@@ -1,5 +1,5 @@
 <!--
-skills/docs/adr-workflow.md — Workflow for recording an architectural decision as an ADR.
+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)
@@ -18,7 +18,7 @@ Use when: an architectural decision is made that affects the system structure, d
 ## 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)
+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

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

@@ -1,5 +1,5 @@
 <!--
-skills/docs/backlog-proposal-workflow.md — Approval-gated issue tracker proposals.
+skills/docs/backlog-proposal-workflow.md: Approval-gated issue tracker proposals.
 -->
 # Backlog Proposal Workflow
 

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

@@ -1,5 +1,5 @@
 <!--
-skills/docs/customer-profile-workflow.md — Maintain durable customer/account memory for Product Intelligence.
+skills/docs/customer-profile-workflow.md: Maintain durable customer/account memory for Product Intelligence.
 -->
 # Customer Profile Workflow
 

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

@@ -1,5 +1,5 @@
 <!--
-skills/docs/document-ingest-workflow.md — Convert source documents into retrieval-ready markdown artifacts.
+skills/docs/document-ingest-workflow.md: Convert source documents into retrieval-ready markdown artifacts.
 -->
 # Document Ingest Workflow
 

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

@@ -1,5 +1,5 @@
 <!--
-skills/docs/evidence-ingest-workflow.md — Normalize raw product evidence into Construct knowledge artifacts.
+skills/docs/evidence-ingest-workflow.md: Normalize raw product evidence into Construct knowledge artifacts.
 -->
 # Evidence Ingest Workflow