@wazir-dev/cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
package/expertise/quality/performance.md ADDED
@@ -0,0 +1,600 @@
1
+ # Performance Engineering -- Expertise Module
2
+
3
+ > A performance engineer ensures systems meet speed, scalability, and reliability targets across the full stack -- from browser paint to database query to infrastructure capacity.
4
+ > Scope spans defining performance budgets and SLOs, profiling and optimizing frontend/backend/database/network layers, load testing, capacity planning, caching architecture, and continuous performance monitoring in production.
5
+
6
+ ---
7
+
8
+ ## Core Patterns & Conventions
9
+
10
+ ### Performance Budgets & SLOs
11
+
12
+ Performance budgets are hard limits on metrics that block deployment when exceeded. SLOs (Service Level Objectives) are reliability targets derived from SLIs (Service Level Indicators) that define acceptable user experience.
13
+
14
+ **Establishing SLOs:**
15
+
16
+ | Metric | Typical SLO | Measurement |
17
+ |---|---|---|
18
+ | Availability | 99.9% (8.7h downtime/year) | Successful responses / total requests |
19
+ | API latency (p50) | < 100ms | Median response time |
20
+ | API latency (p95) | < 250ms | 95th percentile response time |
21
+ | API latency (p99) | < 500ms | 99th percentile response time |
22
+ | Error rate | < 0.1% | 5xx responses / total responses |
23
+ | Throughput | Varies by service | Requests per second at target latency |
24
+
25
+ **Error budget model:** If your SLO is 99.9% availability over 30 days, your error budget is 0.1% -- roughly 43 minutes of downtime per month. A burn rate > 1.0 means the budget will be exhausted before the window ends. Track burn rate to decide when to freeze deployments vs. ship features.
26
+
27
+ **Performance budget examples (frontend):**
28
+
29
+ - Total JavaScript bundle: < 200 KB gzipped
30
+ - Total page weight: < 1.5 MB on initial load
31
+ - Time to Interactive: < 3.5s on 4G connection
32
+ - Maximum third-party script size: < 50 KB
33
+
34
+ ### Core Web Vitals (CWV)
35
+
36
+ Google's Core Web Vitals are the primary frontend performance metrics, measured at the 75th percentile of real user data.
37
+
38
+ | Metric | Good | Needs Improvement | Poor | What It Measures |
39
+ |---|---|---|---|---|
40
+ | **LCP** (Largest Contentful Paint) | < 2.5s | 2.5s -- 4.0s | > 4.0s | Perceived load speed |
41
+ | **INP** (Interaction to Next Paint) | < 200ms | 200ms -- 500ms | > 500ms | Input responsiveness |
42
+ | **CLS** (Cumulative Layout Shift) | < 0.1 | 0.1 -- 0.25 | > 0.25 | Visual stability |
43
+
44
+ INP replaced FID (First Input Delay) in March 2024. As of 2026, INP remains the most commonly failed Core Web Vital -- 43% of sites fail the 200ms threshold.
45
+
46
+ **LCP optimization checklist:**
47
+ - Preload the LCP image with `<link rel="preload" as="image">`
48
+ - Inline critical CSS, defer non-critical stylesheets
49
+ - Preload fonts with `font-display: swap`
50
+ - Use server-side rendering (SSR) or static generation for above-the-fold content
51
+ - Eliminate render-blocking JavaScript from the `<head>`
52
+
53
+ **INP optimization checklist:**
54
+ - Break long tasks (> 50ms) into smaller chunks using `scheduler.yield()` or `setTimeout`
55
+ - Defer non-critical JavaScript execution
56
+ - Minimize DOM size (target < 1,500 nodes)
57
+ - Use `requestIdleCallback` for low-priority work
58
+ - Debounce/throttle high-frequency event handlers
59
+
60
+ **CLS optimization checklist:**
61
+ - Set explicit `width` and `height` on all images, videos, and iframes
62
+ - Reserve space for ad slots and dynamic content with CSS `aspect-ratio` or `min-height`
63
+ - Use `font-display: optional` or `font-display: swap` with size-adjust
64
+ - Avoid inserting content above existing visible content
65
+
66
+ ### Backend Performance Metrics
67
+
68
+ **Latency percentiles matter more than averages.** An average of 100ms can hide a p99 of 3 seconds. P99 captures the experience of the unluckiest 1% of users -- the tail latency that damages reputation and triggers cascading failures.
69
+
70
+ **Key backend metrics:**
71
+
72
+ | Metric | What It Tells You | Target (typical API) |
73
+ |---|---|---|
74
+ | p50 latency | Median experience | < 100ms |
75
+ | p95 latency | Vast majority experience | < 250ms |
76
+ | p99 latency | Worst reasonable case | < 500ms |
77
+ | Throughput (RPS) | Capacity under load | Service-dependent |
78
+ | Error rate | Reliability signal | < 0.1% |
79
+ | Saturation | Resource utilization | CPU < 70%, memory < 80% |
80
+
81
+ **Apdex score:** A standardized measure of user satisfaction: `(satisfied + tolerating/2) / total`. Target: > 0.9. Satisfied threshold is typically 500ms for web apps.
82
+
83
+ ### Caching Strategies
84
+
85
+ Caching is the single highest-leverage performance optimization. Apply caching in layers, each with different trade-offs.
86
+
87
+ | Pattern | Mechanism | Pros | Cons | Best For |
88
+ |---|---|---|---|---|
89
+ | **Cache-Aside** | App checks cache; on miss, fetches DB, populates cache | Only caches requested data; cache-failure resilient | First request slow; staleness risk | Read-heavy, eventual consistency OK |
90
+ | **Write-Through** | App writes cache + DB simultaneously | Always consistent; no stale reads | Higher write latency; caches unread data | Data read immediately after write |
91
+ | **Write-Behind** | App writes cache only; async flush to DB | Lowest write latency; absorbs spikes | Data loss risk on cache failure | High-write throughput (counters, analytics) |
92
+
93
+ **Caching layer selection:**
94
+
95
+ | Layer | TTL | Scope | Best For |
96
+ |---|---|---|---|
97
+ | **Browser cache** | Minutes to days | Single user | Static assets, API responses with Cache-Control |
98
+ | **CDN** (Cloudflare, CloudFront) | Minutes to hours | All users in region | Static assets, HTML pages, API responses |
99
+ | **Application cache** (Redis, Memcached) | Seconds to hours | All app instances | Session data, computed results, API responses |
100
+ | **Database cache** (query cache, materialized views) | Varies | Database level | Expensive aggregations, repeated queries |
101
+
102
+ **Cache invalidation:** TTL-based (simple, tolerates staleness), event-driven (publish invalidation on mutation), version-based (hash in cache key), tag-based (group entries, invalidate by tag).
103
+
104
+ ### Database Query Optimization
105
+
106
+ 90% of database performance problems come from 10% of queries. Inefficient SQL accounts for 63% of performance issues.
107
+
108
+ **EXPLAIN plan analysis:**
109
+ - Use `EXPLAIN` for quick estimates during development
110
+ - Use `EXPLAIN ANALYZE` for accurate measurements (actually executes the query)
111
+ - Watch for: sequential scans on large tables, nested loop joins on > 100K rows, high row estimates vs. actuals
112
+
113
+ **Index strategy:** Index columns in WHERE/JOIN/ORDER BY/GROUP BY. Use composite indexes (leftmost prefix rule). Avoid over-indexing (slows writes). Use partial indexes for constant-condition filters and covering indexes (INCLUDE) to avoid table lookups.
114
+
115
+ **Query optimization:** Never `SELECT *` in production. Avoid functions on indexed columns in WHERE. Use `EXISTS` over `IN` for correlated subqueries. Replace OFFSET pagination with cursor/keyset. Batch inserts (`INSERT ... VALUES` with multiple rows). Use connection pooling (PgBouncer, HikariCP).
116
+
117
+ **Slow query detection:** PostgreSQL: `pg_stat_statements`, `auto_explain`, `log_min_duration_statement`. MySQL: slow query log, Performance Schema. SQL Server: Query Store, Extended Events.
118
+
119
+ ### Network Optimization
120
+
121
+ **Protocols:** HTTP/2 (multiplexed streams, header compression) for all web traffic. HTTP/3/QUIC (UDP-based, 0-RTT resumption) where CDN supports it.
122
+
123
+ **Compression:** Brotli (`br`) for static assets (20-26% smaller than gzip). Gzip as fallback for dynamic content.
124
+
125
+ **Connections:** Pool database and HTTP client connections. Enable keep-alive. Use `dns-prefetch` and `preconnect` for critical third-party origins. Minimize unique domain count.
126
+
127
+ ### Frontend Performance
128
+
129
+ **Code splitting:** Split by route (each page = own bundle). Dynamic `import()` for below-the-fold components. `loading="lazy"` for below-fold images; `loading="eager"` for LCP image. Preload critical resources with `<link rel="preload">`.
130
+
131
+ **Images:** Serve WebP/AVIF via `<picture>` (30-50% smaller than JPEG/PNG). Use `srcset`/`sizes` for responsive images. Resize server-side. Use image CDNs (Cloudinary, imgix) for on-the-fly optimization.
132
+
133
+ **JavaScript:** Tree-shake (ESM imports, not CJS). `defer`/`async` for non-critical scripts. Web Workers for CPU-intensive tasks. `requestAnimationFrame` for visual updates.
134
+
135
+ **CSS:** Inline critical CSS above the fold. Async-load the rest via `media="print" onload="this.media='all'"`. Purge unused CSS (PurgeCSS, Tailwind JIT).
136
+
137
+ ### API Performance
138
+
139
+ **Pagination:** Cursor-based for large datasets (stable, O(1) seek). Return `next_cursor`; page size 20-100.
140
+
141
+ **N+1 prevention:** GraphQL: DataLoader batches `.load(key)` into `WHERE id IN (...)` -- up to 85% response time reduction. New DataLoader per request. REST: batch endpoints (`POST /batch`).
142
+
143
+ **Response optimization:** `ETag`/`If-None-Match` for 304s. Brotli/gzip compression. Sparse fieldsets (`?fields=id,name`).
144
+
145
+ ### Async Processing
146
+
147
+ **When to go async:** Any operation > 500ms outside the critical response path (email, PDF generation, image processing, analytics, slow third-party calls).
148
+
149
+ **Patterns:** Message queues (RabbitMQ, SQS, Kafka) for decoupling. Background jobs (Celery, Sidekiq, BullMQ) for retry/scheduling. Event-driven architecture for downstream triggers. Webhooks with retry for external notifications.
150
+
151
+ ---
152
+
153
+ ## Anti-Patterns & Pitfalls
154
+
155
+ ### 1. Optimizing Without Profiling
156
+ **Why it is a problem:** Developers guess where bottlenecks are and waste time optimizing code paths that contribute < 1% of total latency. Always profile first, then optimize the measured hotspot. "Premature optimization is the root of all evil" -- Knuth.
157
+
158
+ ### 2. Ignoring Tail Latency (p99/p999)
159
+ **Why it is a problem:** Average latency hides outliers. A service with 50ms average but 5s p99 has 1% of users waiting 100x longer. Tail latency cascades in microservices -- if Service A calls Service B at p99, combined latency explodes. Monitor p95/p99, not just averages.
160
+
161
+ ### 3. N+1 Query Problem
162
+ **Why it is a problem:** Fetching a list of N items and then issuing a separate query for each item's related data produces N+1 database round-trips. Response time grows linearly with data size. Solve with JOINs, DataLoader, or eager loading.
163
+
164
+ ### 4. Missing or Wrong Indexes
165
+ **Why it is a problem:** A missing index on a frequently queried column forces full table scans. On a 10M row table, this turns a 1ms lookup into a 500ms+ scan. Conversely, too many indexes slow writes and waste storage.
166
+
167
+ ### 5. Unbounded Queries
168
+ **Why it is a problem:** `SELECT * FROM orders` with no LIMIT or WHERE clause on a large table returns millions of rows, exhausting memory and blocking connections. Always paginate, always set limits.
169
+
170
+ ### 6. Synchronous Processing in the Request Path
171
+ **Why it is a problem:** Sending emails, generating reports, or calling slow third-party APIs synchronously blocks the response. Users wait for work that does not affect the response they need. Offload to background jobs.
172
+
173
+ ### 7. Cache Stampede (Thundering Herd)
174
+ **Why it is a problem:** When a popular cache key expires, hundreds of concurrent requests all miss the cache simultaneously and hit the database. Use lock-based recomputation (only one request refills cache), probabilistic early expiry, or stale-while-revalidate patterns.
175
+
176
+ ### 8. Over-Caching Without Invalidation Strategy
177
+ **Why it is a problem:** Caching aggressively without a plan for invalidation leads to stale data, user confusion, and hard-to-debug inconsistencies. Every cache entry needs a defined TTL and/or an event-driven invalidation trigger.
178
+
179
+ ### 9. No Connection Pooling
180
+ **Why it is a problem:** Creating a new database connection per request adds 20-50ms of overhead (TCP handshake + TLS + auth). Under load, connection creation overwhelms the database. Use connection pools (PgBouncer, HikariCP, `asyncpg` pool).
181
+
182
+ ### 10. Blocking the Event Loop / Main Thread
183
+ **Why it is a problem:** In Node.js/Python async or browser JavaScript, CPU-intensive synchronous work blocks all other operations. A 100ms synchronous computation blocks 100ms of I/O. Use worker threads, Web Workers, or break into yielding chunks.
184
+
185
+ ### 11. OFFSET-Based Pagination at Scale
186
+ **Why it is a problem:** `OFFSET 100000 LIMIT 20` still scans and discards 100,000 rows. Performance degrades linearly with page depth. Use cursor/keyset pagination instead.
187
+
188
+ ### 12. Not Setting Timeouts
189
+ **Why it is a problem:** Without timeouts, a single slow downstream service can hold connections indefinitely, exhausting the connection pool and cascading failures across the system. Set timeouts on every external call: HTTP, database, cache, queues.
190
+
191
+ ### 13. Loading Everything on Initial Page Load
192
+ **Why it is a problem:** Bundling all JavaScript, CSS, and images into the initial load delays Time to Interactive. Users on mobile/3G connections suffer most. Use code splitting, lazy loading, and progressive enhancement.
193
+
194
+ ### 14. Ignoring Payload Size
195
+ **Why it is a problem:** Returning entire database rows when the client needs two fields wastes bandwidth and serialization time. A 50 KB JSON response that could be 2 KB adds up to gigabytes of wasted transfer daily at scale. Use field selection and projection.
196
+
197
+ ### 15. Testing Only Happy Path Performance
198
+ **Why it is a problem:** Performance at 10 RPS tells you nothing about behavior at 10,000 RPS. Systems exhibit non-linear degradation: latency often spikes exponentially past a saturation point. Test at expected peak, 2x peak, and failure scenarios.
199
+
200
+ ---
201
+
202
+ ## Testing Strategy
203
+
204
+ ### Load Testing Tools
205
+
206
+ | Tool | Language | Protocol Support | Best For |
207
+ |---|---|---|---|
208
+ | **k6** (Grafana) | JavaScript | HTTP, WebSocket, gRPC | Developer-friendly, CI integration |
209
+ | **Locust** | Python | HTTP, custom protocols | Python teams, custom load shapes |
210
+ | **Gatling** | Scala/Java | HTTP, WebSocket, JMS | Enterprise Java, detailed reports |
211
+ | **Artillery** | JavaScript/YAML | HTTP, WebSocket, Socket.io | Quick YAML-based tests, serverless |
212
+ | **JMeter** | Java | HTTP, JDBC, LDAP, FTP | Legacy, protocol variety |
213
+
214
+ ### Load Test Patterns
215
+
216
+ | Pattern | Description | Duration | Purpose |
217
+ |---|---|---|---|
218
+ | **Ramp-up** | Gradually increase VUs 0 to target | 5-10 min ramp | Find latency degradation point |
219
+ | **Stress** | Push 2-5x beyond expected peak | 10-30 min | Find breaking point and failure mode |
220
+ | **Spike** | Sudden jump (50 to 500 VUs in 10s) | 5-15 min | Validate auto-scaling, queue behavior |
221
+ | **Soak** | Moderate load (60-80% capacity) | 4-12 hours | Detect memory leaks, pool exhaustion |
222
+ | **Breakpoint** | Continuously increase until failure | Until crash | Determine absolute max capacity |
223
+
224
+ ### Performance Regression Testing in CI
225
+
226
+ Run baseline k6/Lighthouse on every PR. Define pass/fail thresholds (`http_req_duration{p(95)} < 300ms`). Store historical results to detect trends. Keep CI tests < 10 min; soak tests nightly.
227
+
228
+ ### Synthetic Monitoring vs. RUM
229
+
230
+ **Synthetic monitoring** (Pingdom, Checkly, Datadog Synthetics): Simulated requests from known locations every 1-5 min. Consistent baseline, detects outages 24/7. Does not capture real device/network variance.
231
+
232
+ **Real User Monitoring** (Datadog RUM, SpeedCurve, Sentry): Actual user browsers/devices on every page load. Real-world CWV data. Noisy, requires traffic volume.
233
+
234
+ **Best practice:** Use both. Synthetic for baseline/alerting; RUM for actual user experience.
235
+
236
+ ### Benchmark Methodology
237
+
238
+ **Warm-up:** 2-5 min warm-up before measuring (JIT, cache, pool init). **Repetition:** Run 3+ times; report median and stddev; discard > 2 stddev outliers. **Controlled environment:** Pin instance types/region; disable auto-scaling. **Realistic data:** Use production-like volumes (100 rows tells nothing about 10M).
239
+
240
+ ---
241
+
242
+ ## Performance Considerations (Deep Dive)
243
+
244
+ ### Profiling Tools by Domain
245
+
246
+ | Domain | Tools | Purpose |
247
+ |---|---|---|
248
+ | **Frontend** | Lighthouse, Chrome DevTools Performance, WebPageTest, SpeedCurve | CWV audits, flame charts, filmstrip analysis, continuous RUM |
249
+ | **Backend** | Flamegraphs (async-profiler, py-spy, perf), Datadog APM, New Relic, Jaeger | CPU visualization, distributed tracing, service maps |
250
+ | **Database** | `EXPLAIN ANALYZE`, `pg_stat_statements`, slow query log, pganalyze, Percona PMM | Query plans, top queries by time, continuous analysis |
251
+ | **Infra** | `top`/`htop`, `vmstat`, `iostat`, `perf`, `strace`/`dtrace`, `ss` | CPU, memory, disk I/O, syscalls, network state |
252
+
253
+ ### Memory Leak Detection
254
+
255
+ **Symptoms:** Gradually increasing RSS over hours/days, OOM kills, growing GC pauses.
256
+
257
+ **Approach:** Monitor RSS over time (upward trend = leak). Take heap snapshots at intervals (Chrome DevTools for JS, `jmap` for Java, `tracemalloc` for Python). Compare snapshots -- growing object counts by type reveal the source. Common causes: unclosed connections, caches without eviction, event listener accumulation.
258
+
259
+ ### CPU Profiling Patterns
260
+
261
+ - **Sampling** (~2-5% overhead): Sample call stack periodically. Safe for production. Tools: async-profiler, py-spy, perf.
262
+ - **Instrumentation** (high overhead): Wraps every function. Dev only. Tools: cProfile, JProfiler.
263
+ - **Continuous profiling**: Always-on sampling. Services: Datadog Continuous Profiler, Pyroscope, Google Cloud Profiler.
264
+ - **Flamegraphs**: Wide plateaus = most CPU time. Optimize the widest bars first.
265
+
266
+ ### I/O Optimization
267
+
268
+ Use async I/O (epoll, io_uring, kqueue) over thread-per-connection. Batch small writes to reduce syscall overhead. Memory-mapped files for large sequential reads. Monitor `iowait` with `iostat` -- high values indicate I/O-bound workload.
269
+
270
+ ---
271
+
272
+ ## Security Considerations
273
+
274
+ ### DDoS Protection
275
+
276
+ CDN-level filtering (Cloudflare, AWS Shield, Akamai) absorbs volumetric attacks at the edge. Apply per-IP/per-path rate limits at CDN/load balancer. Use anycast routing to distribute attack traffic. Deploy challenge pages (CAPTCHA/JS) for suspicious patterns.
277
+
278
+ ### Rate Limiting
279
+
280
+ **Token bucket** (sustained rate + burst) for APIs. **Sliding window** for smooth enforcement. Apply per API key, user ID, IP, and endpoint. Return `429 Too Many Requests` with `Retry-After`. Separate limits for reads vs. writes. Enforce at reverse proxy (Nginx, HAProxy, API Gateway) -- not in app code.
281
+
282
+ ### Resource Exhaustion Prevention
283
+
284
+ Max request body size (e.g., 10 MB). Limit concurrent connections per client. GraphQL: depth limits + cost analysis. Timeouts at every layer. Backpressure: reject work when queues exceed capacity rather than buffering unboundedly.
285
+
286
+ ### Timeouts and Circuit Breakers
287
+
288
+ **Timeout hierarchy:** Connection timeout (3s) -> Read/response timeout (10s) -> Total request timeout with retries (30s). Set all three on every external call.
289
+
290
+ **Circuit breaker:** Closed (normal, tracking failures) -> Open (failures > threshold, e.g. 50% in 10s; return fallback immediately) -> Half-Open (after 30s cooldown, probe with few requests; success = close, failure = reopen).
291
+
292
+ ---
293
+
294
+ ## Integration Patterns
295
+
296
+ ### APM Tools Integration
297
+
298
+ | Tool | Key Strength | Agent |
299
+ |---|---|---|
300
+ | **Datadog APM** | Trace/log/metric correlation | `dd-trace` libraries |
301
+ | **New Relic** | Full-stack observability | Language agents (Java, Node, Python, Go, Ruby) |
302
+ | **Dynatrace** | AI root cause analysis (Davis AI) | OneAgent per host |
303
+
304
+ **Common setup:** Install language agent, set service name + environment tags, configure sampling (100% staging, 10-20% production).
305
+
306
+ ### OpenTelemetry for Distributed Tracing
307
+
308
+ OTel is the vendor-neutral standard: `Application --> OTel SDK --> OTel Collector --> Backend (Jaeger/Datadog/New Relic)`.
309
+
310
+ **Best practices:** Use OTel Collector as centralized pipeline (not direct vendor export). Auto-instrumentation agents for 80% coverage. Enrich spans with business context (user ID, order ID). Add attributes at span creation for SDK sampling. Tail-based sampling: keep all error traces, sample 10% of successes. Correlate traces with logs via trace_id/span_id.
311
+
312
+ ### Real User Monitoring (RUM)
313
+
314
+ Inject lightweight JS snippet (< 10 KB). Capture page load timing, CWV, JS errors, interactions. Segment by device, browser, geography, connection speed. Tools: Datadog RUM, SpeedCurve, Sentry Performance.
315
+
316
+ ### CDN Integration
317
+
318
+ | CDN | Strengths | Configuration |
319
+ |---|---|---|
320
+ | **Cloudflare** | DDoS protection, Workers (edge compute), free tier | DNS proxy, page rules, cache rules |
321
+ | **CloudFront** | AWS integration, Lambda@Edge | Origin groups, behaviors, cache policies |
322
+ | **Fastly** | Real-time purging, VCL/Compute@Edge | Instant purge API, edge dictionaries |
323
+
324
+ **CDN cache tips:** `Cache-Control: public, max-age=31536000, immutable` for hashed assets. `s-maxage` for CDN-specific TTL. `Surrogate-Key` (Fastly) or cache tags for purging. `stale-while-revalidate` for background refresh.
325
+
326
+ ### Database Connection Pooling
327
+
328
+ **PgBouncer** (PostgreSQL): Transaction-level pooling; 10K app connections to 50 DB connections. **HikariCP** (JVM): `maximumPoolSize = (core_count * 2) + disk_spindles`. **asyncpg** pool (Python): `min_size=10, max_size=20` starting point. Monitor: active/idle connections, wait time, timeouts. Alert when wait time > 100ms.
329
+
330
+ ---
331
+
332
+ ## DevOps & Deployment
333
+
334
+ ### Performance CI/CD Gates
335
+
336
+ ```yaml
337
+ # Lighthouse CI gate (GitHub Actions)
338
+ - uses: treosh/lighthouse-ci-action@v12
339
+ with:
340
+ urls: "https://staging.example.com/"
341
+ budgetPath: ./lighthouse-budget.json
342
+
343
+ # k6 load test gate
344
+ - run: k6 run --out json=results.json -e BASE_URL=$STAGING_URL tests/load/api-test.js
345
+ env: { K6_THRESHOLDS: '{"http_req_duration{p(95)}":["max<300"]}' }
346
+ ```
347
+
348
+ Fail builds if p95 > 300ms or Lighthouse < 90. Store results historically. Full soak tests nightly.
349
+
350
+ ### Auto-Scaling Strategies
351
+
352
+ | Strategy | Trigger | Best For | Tool |
353
+ |---|---|---|---|
354
+ | **HPA** (Horizontal Pod Autoscaler) | CPU/memory utilization | Stateless web services | Kubernetes built-in |
355
+ | **VPA** (Vertical Pod Autoscaler) | Resource request adjustment | Right-sizing pods | Kubernetes add-on |
356
+ | **KEDA** | Event-driven (queue depth, custom metrics) | Background workers, event consumers | CNCF graduated project |
357
+ | **Lambda concurrency** | Invocation rate | Serverless functions | AWS Lambda |
358
+ | **Target tracking** | Request count per target | Load-balanced services | AWS Auto Scaling |
359
+
360
+ **HPA guidance:** Target 60-70% CPU utilization. `minReplicas` >= 2 for availability. `stabilizationWindowSeconds` prevents flapping (300s default for scale-down). Prefer KEDA for queue-based workloads (scale to zero when idle).
361
+
362
+ ### Blue/Green and Canary for Performance Validation
363
+
364
+ **Canary:** Route 5-10% to new version; compare p95/error rate for 15-30 min before promoting. **Blue/green:** Load test green before switching; instant rollback available. **Feature flags:** Ramp 1% -> 10% -> 50% -> 100%. **Auto-rollback:** If canary p99 exceeds baseline by > 20% or error rate exceeds SLO, rollback within 5 min.
365
+
366
+ ### Performance Monitoring Dashboards (Grafana)
367
+
368
+ **Essential panels:** Request rate (RPS) + error rate overlay. Latency lines (p50/p95/p99). Saturation (CPU, memory, disk I/O, pool utilization). Error budget burn rate. Top 10 slowest endpoints. Deployment markers as vertical annotations.
369
+
370
+ ### Alerting on Performance Degradation
371
+
372
+ **Alert tiers:**
373
+
374
+ | Severity | Condition | Response |
375
+ |---|---|---|
376
+ | **P1 (Page)** | p99 > 5s for 5 min OR error rate > 5% | Immediate on-call response |
377
+ | **P2 (Alert)** | p95 > 500ms for 15 min OR error rate > 1% | Respond within 1 hour |
378
+ | **P3 (Warn)** | p50 > 200ms for 30 min | Investigate during business hours |
379
+ | **P4 (Info)** | Weekly p95 trend increasing > 10% | Review in next sprint planning |
380
+
381
+ **Multi-window alerting:** Use burn-rate alerts (e.g., Google SRE approach): alert when the error budget is being consumed at 14.4x the sustainable rate over a 1-hour window AND 6x over a 6-hour window. This catches both sudden spikes and slow degradation while minimizing false positives.
382
+
383
+ ---
384
+
385
+ ## Decision Trees
386
+
387
+ ### Decision Tree 1: Where Is the Bottleneck?
388
+
389
+ ```
390
+ User reports slowness
391
+ |
392
+ +--> Check DevTools Network tab
393
+ | +--> Large assets / many requests? --> Frontend: optimize images, code split, compress
394
+ | +--> Slow TTFB (> 600ms)? --> Backend bottleneck, check APM:
395
+ | +--> Slow DB queries? --> EXPLAIN ANALYZE, add indexes
396
+ | +--> Slow external APIs? --> Cache, circuit breaker, go async
397
+ | +--> High CPU? --> Flamegraph, optimize algorithm or scale out
398
+ | +--> High memory / GC? --> Heap snapshot, fix leak or upsize
399
+ ```
400
+
401
+ ### Decision Tree 2: Which Caching Layer?
402
+
403
+ ```
404
+ What are you caching?
405
+ |
406
+ +--> Static assets? --> CDN + browser cache (immutable, content-hash filenames)
407
+ +--> HTML pages?
408
+ | +--> Rarely changes? --> CDN, short TTL + purge on publish
409
+ | +--> Personalized? --> Redis with user-keyed entries (no CDN)
410
+ +--> API responses?
411
+ | +--> Same for all users? --> CDN (Surrogate-Key purging)
412
+ | +--> User-specific? --> Redis with user-scoped keys
413
+ | +--> Expensive compute? --> Redis + TTL + background refresh
414
+ +--> DB query results?
415
+ +--> Aggregations? --> Materialized views + periodic refresh
416
+ +--> Repeated queries? --> Redis with query-hash keys
417
+ +--> Hot config rows? --> In-process LRU cache, short TTL
418
+ ```
419
+
420
+ ### Decision Tree 3: Scale Up vs. Scale Out?
421
+
422
+ ```
423
+ System at capacity
424
+ |
425
+ +--> CPU-bound?
426
+ | +--> Parallelizable? --> Scale OUT (more instances)
427
+ | +--> Single-threaded? --> Scale UP (faster CPU) or refactor
428
+ +--> Memory-bound?
429
+ | +--> Fits in larger instance? --> Scale UP
430
+ | +--> Can partition? --> Scale OUT (shard)
431
+ +--> I/O-bound?
432
+ | +--> Disk I/O? --> Scale UP (NVMe) or add read replicas
433
+ | +--> Network I/O? --> Scale OUT behind load balancer
434
+ +--> Connection-bound?
435
+ | +--> Add pooling first, then Scale OUT if still saturated
436
+ +--> General: Stateless = OUT, Stateful = UP then shard. Always optimize first.
437
+ ```
438
+
439
+ ---
440
+
441
+ ## Code Examples
442
+
443
+ ### Example 1: Redis Cache-Aside Pattern (Python / FastAPI)
444
+
445
+ ```python
446
+ import redis.asyncio as redis
447
+ import json
448
+ from fastapi import FastAPI, Depends
449
+
450
+ app = FastAPI()
451
+ cache = redis.Redis(host="localhost", port=6379, decode_responses=True)
452
+
453
+ async def get_user(user_id: int) -> dict:
454
+ # 1. Check cache
455
+ cache_key = f"user:{user_id}"
456
+ cached = await cache.get(cache_key)
457
+ if cached:
458
+ return json.loads(cached)
459
+
460
+ # 2. Cache miss -- fetch from DB
461
+ user = await db.fetch_one("SELECT * FROM users WHERE id = $1", user_id)
462
+ if user:
463
+ # 3. Populate cache with 5-minute TTL
464
+ await cache.set(cache_key, json.dumps(dict(user)), ex=300)
465
+ return dict(user)
466
+
467
+ async def invalidate_user_cache(user_id: int):
468
+ """Call this after any user mutation."""
469
+ await cache.delete(f"user:{user_id}")
470
+ ```
471
+
472
+ ### Example 2: Database Connection Pooling (Node.js / PostgreSQL)
473
+
474
+ ```javascript
475
+ import pg from "pg";
476
+ const pool = new pg.Pool({
477
+ host: process.env.DB_HOST, database: "myapp",
478
+ user: process.env.DB_USER, password: process.env.DB_PASSWORD,
479
+ min: 5, max: 20, // Pool size bounds
480
+ idleTimeoutMillis: 30000, // Close idle after 30s
481
+ connectionTimeoutMillis: 3000, // Fail connect after 3s
482
+ statement_timeout: 10000, // Kill queries > 10s
483
+ });
484
+ pool.on("error", (err) => console.error("Pool error:", err));
485
+
486
+ async function getOrders(userId) {
487
+ const client = await pool.connect();
488
+ try {
489
+ const { rows } = await client.query(
490
+ "SELECT id, total, created_at FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT 20",
491
+ [userId]
492
+ );
493
+ return rows;
494
+ } finally { client.release(); } // Always release back to pool
495
+ }
496
+ ```
497
+
498
+ ### Example 3: k6 Load Test Script with Thresholds
499
+
500
+ ```javascript
501
+ // tests/load/api-test.js
502
+ import http from "k6/http";
503
+ import { check, sleep } from "k6";
504
+
505
+ export const options = {
506
+ stages: [
507
+ { duration: "2m", target: 50 }, // Ramp up to 50 VUs
508
+ { duration: "5m", target: 50 }, // Hold at 50 VUs
509
+ { duration: "2m", target: 200 }, // Spike to 200 VUs
510
+ { duration: "5m", target: 200 }, // Hold at 200 VUs
511
+ { duration: "2m", target: 0 }, // Ramp down
512
+ ],
513
+ thresholds: {
514
+ http_req_duration: [
515
+ "p(50)<100", // p50 < 100ms
516
+ "p(95)<300", // p95 < 300ms
517
+ "p(99)<500", // p99 < 500ms
518
+ ],
519
+ http_req_failed: ["rate<0.01"], // Error rate < 1%
520
+ http_reqs: ["rate>100"], // Throughput > 100 RPS
521
+ },
522
+ };
523
+
524
+ export default function () {
525
+ const BASE_URL = __ENV.BASE_URL || "http://localhost:3000";
526
+
527
+ // Simulate realistic user flow
528
+ const listRes = http.get(`${BASE_URL}/api/products?limit=20`);
529
+ check(listRes, {
530
+ "list status is 200": (r) => r.status === 200,
531
+ "list has products": (r) => JSON.parse(r.body).length > 0,
532
+ });
533
+
534
+ sleep(1); // Think time between requests
535
+
536
+ const detailRes = http.get(`${BASE_URL}/api/products/1`);
537
+ check(detailRes, {
538
+ "detail status is 200": (r) => r.status === 200,
539
+ });
540
+
541
+ sleep(0.5);
542
+ }
543
+ ```
544
+
545
+ ### Example 4: React Lazy Loading with Suspense
546
+
547
+ ```jsx
548
+ import { lazy, Suspense } from "react";
549
+ import { Routes, Route, Link } from "react-router-dom";
550
+
551
+ // Route-based code splitting -- each page loads only its own JS chunk
552
+ const Home = lazy(() => import("./pages/Home"));
553
+ const Products = lazy(() => import("./pages/Products"));
554
+ const Dashboard = lazy(() => import("./pages/Dashboard"));
555
+
556
+ function App() {
557
+ return (
558
+ <Suspense fallback={<div className="skeleton-loader" />}>
559
+ <Routes>
560
+ <Route path="/" element={<Home />} />
561
+ <Route path="/products" element={<Products />} />
562
+ <Route path="/dashboard" element={<Dashboard />} />
563
+ </Routes>
564
+ </Suspense>
565
+ );
566
+ }
567
+
568
+ // Preload on hover for perceived performance
569
+ const NavLink = ({ to, children }) => (
570
+ <Link to={to} onMouseEnter={() => { if (to === "/dashboard") import("./pages/Dashboard"); }}>
571
+ {children}
572
+ </Link>
573
+ );
574
+ ```
575
+
576
+ ### Example 5: OpenTelemetry Setup (Node.js)
577
+
578
+ ```javascript
579
+ // tracing.js -- import before all other modules
580
+ import { NodeSDK } from "@opentelemetry/sdk-node";
581
+ import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
582
+ import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
583
+ import { Resource } from "@opentelemetry/resources";
584
+ import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
585
+
586
+ const sdk = new NodeSDK({
587
+ resource: new Resource({ [ATTR_SERVICE_NAME]: "my-api-service" }),
588
+ traceExporter: new OTLPTraceExporter({
589
+ url: "http://otel-collector:4317", // Send to Collector, not directly to vendor
590
+ }),
591
+ instrumentations: [getNodeAutoInstrumentations()], // HTTP, Express, PG, Redis auto-traced
592
+ });
593
+
594
+ sdk.start();
595
+ process.on("SIGTERM", () => sdk.shutdown().then(() => process.exit(0)));
596
+ ```
597
+
598
+ ---
599
+
600
+ *Researched: 2026-03-07 | Sources: [web.dev Core Web Vitals](https://web.dev/articles/defining-core-web-vitals-thresholds), [Google SRE Workbook -- Implementing SLOs](https://sre.google/workbook/implementing-slos/), [Grafana k6 Documentation](https://grafana.com/docs/k6/latest/), [OpenTelemetry Docs](https://opentelemetry.io/docs/concepts/observability-primer/), [AWS Redis Caching Patterns](https://docs.aws.amazon.com/whitepapers/latest/database-caching-strategies-using-redis/caching-patterns.html), [Aerospike P99 Latency](https://aerospike.com/blog/what-is-p99-latency/), [GraphQL DataLoader](https://www.graphql-js.org/docs/n1-dataloader/), [Kubernetes HPA Docs](https://kubernetes.io/docs/concepts/workloads/autoscaling/horizontal-pod-autoscale/), [KEDA](https://keda.sh/), [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci), [Nobl9 SLO Best Practices](https://www.nobl9.com/service-level-objectives/slo-best-practices), [Spectro Cloud -- Kubernetes Autoscaling Patterns](https://www.spectrocloud.com/blog/kubernetes-autoscaling-patterns-hpa-vpa-and-keda)*