@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
@@ -0,0 +1,24 @@
1
+ # Directory Purpose
2
+
3
+ The `foundations` performance directory establishes the theoretical and practical basics of writing efficient code and measuring system speed.
4
+
5
+ # Key Concepts
6
+
7
+ - Identifying computational complexity
8
+ - Implementing caching correctly
9
+ - Setting limits and tracking regressions
10
+
11
+ # File Map
12
+
13
+ - `algorithmic-complexity.md` — Big O notation and choosing the right data structures
14
+ - `caching-strategies.md` — read-through, write-behind, and cache invalidation
15
+ - `concurrency-and-parallelism.md` — threads, async, locks, and race conditions
16
+ - `measuring-and-profiling.md` — flame graphs, tracing, and identifying bottlenecks
17
+ - `memory-management.md` — garbage collection, memory leaks, and object pools
18
+ - `performance-budgets.md` — setting CI/CD limits on bundle sizes and latency
19
+
20
+ # Reading Guide
21
+
22
+ If code is generally inefficient → read `algorithmic-complexity.md`
23
+ If experiencing OOM errors → read `memory-management.md`
24
+ If unsure where the app is slow → read `measuring-and-profiling.md`
@@ -0,0 +1,440 @@
1
+ # Measuring & Profiling — Performance Expertise Module
2
+
3
+ > You cannot optimize what you cannot measure. Profiling is the foundation of all performance work — it separates data-driven optimization from superstition. Every performance improvement must start with measurement and end with verification.
4
+
5
+ > **Impact:** Critical
6
+ > **Applies to:** All (Web, Mobile, Backend, Infrastructure)
7
+ > **Key metrics:** Response Time (p50/p95/p99), Throughput (RPS), CPU/Memory utilization, Frame Rate
8
+
9
+ ---
10
+
11
+ ## Why This Matters
12
+
13
+ Performance work without measurement is guesswork. Teams routinely waste weeks optimizing the wrong bottleneck because they relied on intuition instead of profiling data.
14
+
15
+ **Knight Capital: $440M in 45 Minutes.** On August 1, 2012, Knight Capital deployed a routine update to the NYSE's Retail Liquidity Program. A dormant router function from 2005 was accidentally re-activated, sending over 4 million orders to fill just 212 customer orders. The $440 million loss was 3x the company's annual earnings; Knight's stock lost 75% of its value in two days. A proper load test simulating real market conditions would have exposed the runaway order generation immediately.
16
+
17
+ **Common measurement failures:**
18
+ 1. **Optimizing the wrong layer.** A team spends 3 weeks on database queries; the actual bottleneck is a synchronous HTTP call adding 800ms per request. Profiling would have found it in 15 minutes.
19
+ 2. **Averaging away the problem.** Average response time is 120ms, but p99 is 4,200ms — 1% of users (thousands per hour at scale) experience 35x worse performance.
20
+ 3. **Premature optimization.** Code that runs 0.001% of the time does not warrant optimization. Profile first — the actual bottleneck is elsewhere 70-90% of the time.
21
+
22
+ **Business case:** Google found 500ms of added load time reduced traffic by 20%. Amazon reported every 100ms of latency cost 1% in sales. At Meta-scale, regressions of 0.005-0.01% in CPU waste thousands of servers (FBDetect, SOSP 2024).
23
+
24
+ ---
25
+
26
+ ## Performance Budgets & Targets
27
+
28
+ ### Latency Percentiles
29
+
30
+ | Percentile | Meaning | Why It Matters |
31
+ |-----------|---------|----------------|
32
+ | p50 | 50% of requests faster | General baseline |
33
+ | p95 | 95% of requests faster | Standard SLO target |
34
+ | p99 | 99% of requests faster | Reveals tail latency; systemic bottlenecks surface here |
35
+ | p99.9 | 99.9% of requests faster | Critical for high-throughput services |
36
+
37
+ **Why p99 > average:** Mean latency can look stable while p99 spikes from GC pauses, cache evictions, or lock contention. At 10,000 RPM, a 4s p99 means 100 users/minute get unacceptable latency.
38
+
39
+ ### Apdex Scores
40
+
41
+ Formula: `Apdex = (Satisfied + Tolerating/2) / Total` where Satisfied <= T, Tolerating <= 4T. Scores: 0.94-1.00 excellent, 0.85-0.93 good, 0.70-0.84 fair, < 0.70 poor.
42
+
43
+ ### Platform-Specific Budgets
44
+
45
+ **Web (Core Web Vitals — INP replaced FID in March 2024):**
46
+
47
+ | Metric | Good | Needs Improvement | Poor |
48
+ |--------|------|--------------------|------|
49
+ | LCP | <= 2.5s | 2.5-4.0s | > 4.0s |
50
+ | INP | <= 200ms | 200-500ms | > 500ms |
51
+ | CLS | <= 0.1 | 0.1-0.25 | > 0.25 |
52
+
53
+ 2025 Web Almanac: only 48% of mobile pages pass all three CWVs. LCP is hardest (62% pass), then INP (77%), then CLS (81%).
54
+
55
+ **Backend API:** p50 < 50ms (good), p95 < 200ms, p99 < 500ms, error rate < 0.1%.
56
+ **Mobile:** Cold start < 1s, frame rate 60fps (16.7ms/frame), jank frames < 1%.
57
+ **Database:** Query p95 < 10ms, cache hit rate > 95%, connection pool utilization < 60%.
58
+
59
+ ---
60
+
61
+ ## Measurement & Profiling
62
+
63
+ ### Frontend Profiling
64
+
65
+ #### Chrome DevTools Performance Panel
66
+
67
+ 1. Open DevTools > **Performance** tab
68
+ 2. Enable **CPU throttling** (4x-6x) — mobile CPUs are far weaker than dev machines
69
+ 3. Record (Cmd+Shift+E for reload profile), interact, stop
70
+ 4. **Flame chart:** x-axis = time (wider = longer), y-axis = call stack. Yellow = JS, Purple = layout, Green = paint. Red triangles mark Long Tasks (> 50ms)
71
+ 5. **Call Tree tab:** top-down view of root activities. **Bottom-Up tab:** find where time is directly spent
72
+ 6. Chrome 124+: right-click functions to **Hide function/children** and focus on actionable entries
73
+
74
+ ```javascript
75
+ // Custom Performance API marks (appear in the Timings track)
76
+ performance.mark('render-start');
77
+ renderComponent();
78
+ performance.mark('render-end');
79
+ performance.measure('Component Render', 'render-start', 'render-end');
80
+
81
+ // Production measurement with PerformanceObserver
82
+ const observer = new PerformanceObserver((list) => {
83
+ for (const entry of list.getEntries()) {
84
+ navigator.sendBeacon('/analytics', JSON.stringify({
85
+ metric: entry.name, value: entry.duration, timestamp: Date.now()
86
+ }));
87
+ }
88
+ });
89
+ observer.observe({ entryTypes: ['measure', 'largest-contentful-paint', 'event'] });
90
+ ```
91
+
92
+ #### Lighthouse: Lab vs. Field Data
93
+
94
+ - **Lab** (Lighthouse): Fixed device/network, CPU throttled 4x, reproducible. Use in development and CI/CD.
95
+ - **Field** (CrUX): Real Chrome users, rolling 28-day window, reported at 75th percentile. Reflects actual conditions.
96
+ - **A perfect Lighthouse 100 does not guarantee passing CWVs.** CWVs are exclusively field data. Use Lighthouse for relative comparisons; CrUX/RUM for real impact.
97
+
98
+ #### Core Web Vitals in Production
99
+
100
+ ```javascript
101
+ import { onLCP, onINP, onCLS } from 'web-vitals';
102
+ function send(metric) {
103
+ navigator.sendBeacon('/api/vitals', JSON.stringify({
104
+ name: metric.name, value: metric.value, rating: metric.rating, id: metric.id
105
+ }));
106
+ }
107
+ onLCP(send); onINP(send); onCLS(send);
108
+ ```
109
+
110
+ ### Backend Profiling
111
+
112
+ #### Node.js
113
+
114
+ ```bash
115
+ # V8 built-in profiler
116
+ node --prof app.js && node --prof-process isolate-0x*.log > profile.txt
117
+
118
+ # clinic.js — production-grade suite
119
+ clinic doctor -- node app.js # Event loop delays, I/O issues, GC overhead
120
+ clinic flame -- node app.js # Interactive flame graph
121
+
122
+ # 0x — instant flame graphs
123
+ npx 0x app.js # Opens interactive flamegraph in browser
124
+ ```
125
+
126
+ #### Python
127
+
128
+ ```bash
129
+ # py-spy: zero code changes, <5% overhead, production-safe
130
+ py-spy top --pid 12345 # Live top-like view
131
+ py-spy record -o profile.svg --pid 12345 --duration 30 # Flame graph SVG
132
+
133
+ # Scalene: CPU + memory + GPU (separates Python vs C time, ~50% fewer false positives)
134
+ scalene your_script.py
135
+ ```
136
+
137
+ **cProfile** adds 30-50% overhead (deterministic tracing). Use only in development.
138
+
139
+ #### How to Read Flame Graphs
140
+
141
+ Invented by Brendan Gregg. **Width** = proportion of samples (not time order) — wider = more CPU. **Y-axis** = call stack depth — bottom is entry, top is leaf. **Look for plateaus** — wide flat bars at top are hotspots. Color is random (for contrast only). **Inverted flame graphs** (icicle charts) flip Y-axis to find which callers contribute to a hot leaf.
142
+
143
+ #### Distributed Tracing
144
+
145
+ For microservices, use OpenTelemetry (vendor-neutral) with Jaeger/Zipkin/Datadog as backends.
146
+
147
+ **Overhead:** Up to 15% on response times in Java; exporting is the main contributor. **Sampling is essential:**
148
+ - **Head sampling** (at agent): Decide at request start. 0.1-1% typical rate. Simple, low overhead.
149
+ - **Tail sampling** (at collector): Keep only errors/slow requests. Higher value but more overhead.
150
+ - CPU overhead drops from 17.8% to 3.6% as fewer traces are sampled. Tracing reduces MTTR by up to 70%.
151
+
152
+ ### Mobile Profiling
153
+
154
+ **Android:** Android Studio Profiler (CPU, Memory, Energy). Use "Sample Java/Kotlin Methods" (~5% overhead) not "Trace" (20-50%). Perfetto for system-level analysis.
155
+
156
+ **iOS:** Xcode Instruments — Time Profiler (CPU sampling, 1ms intervals), Allocations (memory leaks), Core Animation (GPU frame rate). Use "Invert Call Tree" + "Hide System Libraries" to find hotspots.
157
+
158
+ **Flutter:** `showPerformanceOverlay: true` in MaterialApp. Both UI and GPU thread bars must stay below 16ms (60fps).
159
+
160
+ ```kotlin
161
+ // Android custom trace sections
162
+ android.os.Trace.beginSection("processData")
163
+ try { /* work */ } finally { android.os.Trace.endSection() }
164
+ ```
165
+
166
+ ```swift
167
+ // iOS signposts for Instruments
168
+ let log = OSLog(subsystem: "com.app", category: "Perf")
169
+ os_signpost(.begin, log: log, name: "LoadDashboard")
170
+ // ... work ...
171
+ os_signpost(.end, log: log, name: "LoadDashboard")
172
+ ```
173
+
174
+ ### Database Profiling
175
+
176
+ ```sql
177
+ -- EXPLAIN ANALYZE (wrap in transaction for UPDATE/DELETE)
178
+ BEGIN;
179
+ EXPLAIN (ANALYZE, BUFFERS) SELECT o.id, c.name FROM orders o
180
+ JOIN customers c ON c.id = o.customer_id
181
+ WHERE o.created_at > NOW() - INTERVAL '7 days';
182
+ ROLLBACK;
183
+ -- Look for: Seq Scan on large tables, actual vs planned row mismatch (>10x = stale stats),
184
+ -- shared_blks_read (cache misses = disk I/O), Nested Loop with high rows (N+1)
185
+
186
+ -- pg_stat_statements: top queries by total impact
187
+ SELECT calls, round(total_exec_time::numeric, 2) AS total_ms,
188
+ round(mean_exec_time::numeric, 2) AS avg_ms, query
189
+ FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;
190
+ -- Sort by total_exec_time, not mean. 5ms * 100K calls/hr > 2s * 10 calls/hr.
191
+ ```
192
+
193
+ ### RUM vs. Synthetic Monitoring
194
+
195
+ | Dimension | Synthetic | RUM |
196
+ |-----------|----------|-----|
197
+ | Data source | Scripted agents, emulated devices | Actual user sessions |
198
+ | When it works | 24/7, even with zero users | Only when users are active |
199
+ | Best for | Regression detection, SLA, CI/CD gates | Real impact, business correlation |
200
+
201
+ **Best practice:** Synthetics to block regressions before release; RUM to validate real-world impact after deployment.
202
+
203
+ ---
204
+
205
+ ## Common Bottlenecks
206
+
207
+ 10 measurement mistakes that lead to wrong conclusions:
208
+
209
+ 1. **Averages instead of percentiles** — p99 of 4.2s hides behind a 120ms average
210
+ 2. **Measuring in dev, not prod** — dev has 10-100x more CPU, 1ms network latency, warm caches
211
+ 3. **Observer effect** — deterministic profilers add 30-50% overhead; use sampling profilers (<5%) in production
212
+ 4. **Battery vs. plugged in** — laptops throttle CPU 20-60% on battery
213
+ 5. **Browser extensions active** — ad blockers and DevTools inject JS that distorts results
214
+ 6. **Ignoring GC pauses** — Java 10-200ms, Node.js 5-50ms, Go <1ms; invisible in averages
215
+ 7. **Cold cache only** — real users have mixed cache states; test both First View and Repeat View
216
+ 8. **Single-run benchmarks** — run 10+ times, report median with confidence intervals
217
+ 9. **Ignoring JIT warm-up** — first 100-1000 invocations are 2-10x slower; discard warm-up iterations
218
+ 10. **Wall-clock time only** — 500ms wall / 50ms CPU = I/O-bound, not CPU-bound
219
+
220
+ ---
221
+
222
+ ## Anti-Patterns
223
+
224
+ 1. **`console.log` timestamps** — variable overhead (0.1-5ms/call). Use `performance.now()` (microsecond precision).
225
+ 2. **Gut-feeling optimization** — the actual bottleneck is elsewhere 70-90% of the time. Profile first.
226
+ 3. **Micro-benchmarking without context** — `Map` 15% faster than `Object` is meaningless if lookups are 0.01% of request time.
227
+ 4. **Benchmarking in a debugger** — disables JIT, adds breakpoint overhead; 50ms in debugger may be 2ms in production.
228
+ 5. **Cross-machine benchmark comparison** — benchmark on target deployment hardware or identical instance types.
229
+ 6. **`Date.now()` for sub-ms timing** — millisecond resolution, affected by clock adjustments. Use `performance.now()` or `process.hrtime.bigint()`.
230
+ 7. **Flame graphs without source maps** — minified names (`a`, `t`, `n`) are unreadable. Enable source maps.
231
+ 8. **Lighthouse score as absolute truth** — simulated device; use for relative comparisons only.
232
+ 9. **Over-instrumenting production** — 91% of orgs actively reduce observability spend. Instrument critical paths; sample the rest.
233
+ 10. **Not resetting state between runs** — caches, JIT state, connection pools from prior runs contaminate results.
234
+
235
+ ---
236
+
237
+ ## Architecture-Level Decisions
238
+
239
+ ### Observability Architecture
240
+
241
+ | Layer | What to measure | Overhead budget |
242
+ |-------|----------------|-----------------|
243
+ | Edge/CDN | Cache hit rate, TTFB | Near zero (built-in) |
244
+ | Application | Latency percentiles, error rate | 1-5% CPU |
245
+ | Database | Query time, cache hit rate | < 1% CPU |
246
+ | Infrastructure | CPU, memory, disk I/O | < 0.5% CPU |
247
+
248
+ **Sampling strategies:**
249
+
250
+ | Strategy | Rate | Overhead | Use Case |
251
+ |----------|------|----------|----------|
252
+ | No sampling | 100% | 15-20% CPU | Low-traffic (< 100 RPS) |
253
+ | Fixed head sampling | 1-10% | 3-5% CPU | Medium traffic |
254
+ | Probabilistic head | 0.1-1% | 1-2% CPU | High traffic (> 10K RPS) |
255
+ | Tail sampling | Varies | 5-10% at collector | Error/latency investigation |
256
+
257
+ **Cost rule of thumb:** Keep total observability overhead below 5% of application CPU and 3% of infrastructure cost. Grafana 2024 Survey: 91% of organizations actively reduce observability spend.
258
+
259
+ ---
260
+
261
+ ## Testing & Regression Prevention
262
+
263
+ ### Statistical Regression Detection
264
+
265
+ - Use **Wilcoxon rank-sum test** (non-parametric) at 5% significance level
266
+ - Supplement with **Cliff's Delta** effect size: small (< 0.33), medium (0.33-0.47), large (> 0.47)
267
+ - Run benchmarks **10+ times** (30+ preferred) for reliable distributions
268
+ - A regression requires BOTH statistical significance (p < 0.05) AND meaningful effect size (Cliff's Delta > 0.33)
269
+
270
+ Application benchmarks reliably detect meaningful regressions; microbenchmarks tend toward false positives.
271
+
272
+ ```yaml
273
+ # Lighthouse CI performance gate (.lighthouserc.json)
274
+ { "ci": { "collect": { "numberOfRuns": 5, "url": ["http://localhost:3000/"] },
275
+ "assert": { "assertions": {
276
+ "categories:performance": ["error", { "minScore": 0.85 }],
277
+ "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
278
+ "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }]
279
+ }}}}
280
+ ```
281
+
282
+ ### Reducing Benchmark Noise
283
+
284
+ 1. **Dedicated runners** — shared CI has unpredictable CPU contention
285
+ 2. **CPU pinning** — `taskset -c 0-3 node benchmark.js`
286
+ 3. **Disable frequency scaling** — `cpupower frequency-set --governor performance`
287
+ 4. **Relative comparisons** — % change is more stable than absolute values across hardware
288
+ 5. **Discard outliers** — remove top/bottom 5% before comparing
289
+
290
+ ---
291
+
292
+ ## Decision Trees
293
+
294
+ ### "My App is Slow" Diagnostic
295
+
296
+ ```
297
+ Is it slow for ALL users or SOME?
298
+ SOME → Check RUM: specific region (CDN), device, or browser?
299
+ ALL → Continue
300
+
301
+ Slow on FIRST load or SUBSEQUENT?
302
+ FIRST → Caching, code splitting, asset optimization
303
+ SUBSEQUENT → Memory leak, state accumulation, connection pool exhaustion
304
+
305
+ Where is time spent? (waterfall / flame graph)
306
+ NETWORK (TTFB > 600ms)?
307
+ → DNS (prefetch) / TLS (session resumption) / Server (see Backend) / Download (CDN, compression)
308
+ BACKEND (> 200ms)?
309
+ CPU-bound (CPU > 80%)? → Flame graph → optimize hot functions
310
+ I/O-bound (CPU < 30%)? → DB queries (EXPLAIN) / External APIs (cache, circuit breaker)
311
+ Memory-bound? → Heap profiling → reduce allocation rate
312
+ FRONTEND (rendering > 100ms)?
313
+ JS Long Tasks (> 50ms)? → Code splitting, Web Workers
314
+ Layout/Reflow (purple)? → Batch DOM reads/writes
315
+ Paint (green)? → contain, will-change, composite layers
316
+ ```
317
+
318
+ ### Which Profiling Tool?
319
+
320
+ | Platform | Quick Check | Deep Analysis | Production-Safe | CI/CD |
321
+ |----------|-------------|---------------|-----------------|-------|
322
+ | Web | Lighthouse | DevTools Perf | RUM (Datadog, Sentry) | Lighthouse CI |
323
+ | Node.js | `npx 0x` | clinic.js | `node --prof` | autocannon |
324
+ | Python | cProfile | Scalene | py-spy | pytest-benchmark |
325
+ | Android | Studio Profiler | Perfetto | Firebase Perf | Macrobenchmark |
326
+ | iOS | Time Profiler | Instruments | MetricKit | XCTest Perf |
327
+ | PostgreSQL | EXPLAIN ANALYZE | pg_stat_statements | auto_explain | pgbench |
328
+
329
+ ---
330
+
331
+ ## Code Examples
332
+
333
+ ### N+1 Query Fix (Before/After with Measurements)
334
+
335
+ ```python
336
+ # BEFORE: 502 queries, mean response 1,847ms
337
+ def get_orders_slow(user_id):
338
+ orders = db.execute("SELECT * FROM orders WHERE user_id = %s", (user_id,))
339
+ for order in orders:
340
+ order['items'] = db.execute(
341
+ "SELECT * FROM order_items WHERE order_id = %s", (order['id'],))
342
+ return orders # 1 + N queries
343
+
344
+ # AFTER: 1 query, mean response 23ms (80x faster)
345
+ def get_orders_fast(user_id):
346
+ rows = db.execute("""
347
+ SELECT o.*, oi.product_id, oi.quantity, oi.price
348
+ FROM orders o LEFT JOIN order_items oi ON oi.order_id = o.id
349
+ WHERE o.user_id = %s ORDER BY o.id""", (user_id,))
350
+ orders = {}
351
+ for row in rows:
352
+ orders.setdefault(row['id'], {**row, 'items': []})['items'].append(
353
+ {k: row[k] for k in ('product_id', 'quantity', 'price')})
354
+ return list(orders.values()) # 1 query total
355
+ ```
356
+
357
+ ### Load Test with SLO Thresholds (k6)
358
+
359
+ ```javascript
360
+ import http from 'k6/http';
361
+ import { check } from 'k6';
362
+ export const options = {
363
+ stages: [
364
+ { duration: '2m', target: 50 }, { duration: '5m', target: 200 },
365
+ { duration: '3m', target: 200 }, { duration: '2m', target: 0 },
366
+ ],
367
+ thresholds: {
368
+ http_req_duration: ['p(50)<200', 'p(95)<500', 'p(99)<1000'],
369
+ http_req_failed: ['rate<0.01'],
370
+ },
371
+ };
372
+ export default function () {
373
+ check(http.get('https://app.example.com/api/products'),
374
+ { 'status 200': (r) => r.status === 200 });
375
+ }
376
+ ```
377
+
378
+ ### React Render Profiling
379
+
380
+ ```jsx
381
+ import { Profiler, memo, useMemo } from 'react';
382
+
383
+ // Before: 45ms/render. After (memoized): 3ms/render
384
+ const ProductList = memo(({ products, filters }) => {
385
+ const filtered = useMemo(
386
+ () => products.filter(p => matchesFilters(p, filters)), [products, filters]);
387
+ return filtered.map(p => <MemoizedCard key={p.id} product={p} />);
388
+ });
389
+
390
+ function onRender(id, phase, actualDuration) {
391
+ if (actualDuration > 16) // Exceeds 60fps budget
392
+ sendMetric('slow_render', { component: id, duration: actualDuration });
393
+ }
394
+ <Profiler id="ProductList" onRender={onRender}><ProductList {...props} /></Profiler>
395
+ ```
396
+
397
+ ### Proper Benchmarking with JIT Warm-up
398
+
399
+ ```javascript
400
+ function benchmark(fn, iterations = 10000) {
401
+ for (let i = 0; i < 1000; i++) fn(); // Warm-up: let JIT compile
402
+ const start = performance.now(); // NOT Date.now()
403
+ for (let i = 0; i < iterations; i++) fn();
404
+ return (performance.now() - start) / iterations; // ms per iteration
405
+ }
406
+ ```
407
+
408
+ ---
409
+
410
+ ## Quick Reference
411
+
412
+ | Metric | Good | Acceptable | Needs Work |
413
+ |--------|------|------------|------------|
414
+ | LCP | < 2.5s | 2.5-4.0s | > 4.0s |
415
+ | INP | < 200ms | 200-500ms | > 500ms |
416
+ | CLS | < 0.1 | 0.1-0.25 | > 0.25 |
417
+ | TTFB | < 200ms | 200-600ms | > 600ms |
418
+ | API p50 | < 50ms | 50-200ms | > 200ms |
419
+ | API p95 | < 200ms | 200-500ms | > 500ms |
420
+ | API p99 | < 500ms | 500ms-1s | > 1s |
421
+ | Error rate | < 0.1% | 0.1-1% | > 1% |
422
+ | Mobile FPS | 60 fps | 45-59 fps | < 45 fps |
423
+ | Cold start | < 1s | 1-2s | > 2s |
424
+ | DB query p95 | < 10ms | 10-100ms | > 100ms |
425
+ | Cache hit rate | > 95% | 85-95% | < 85% |
426
+ | Apdex | > 0.94 | 0.85-0.93 | < 0.85 |
427
+
428
+ ### Overhead Budget
429
+
430
+ | Instrumentation | Typical | Max Acceptable |
431
+ |----------------|---------|----------------|
432
+ | Metrics (counters) | < 0.1% CPU | 0.5% |
433
+ | Structured logging | 0.1-1% | 2% |
434
+ | Distributed tracing (sampled) | 1-5% | 5% |
435
+ | Continuous profiling | 2-5% | 5% |
436
+ | Full tracing (100%) | 10-20% | Low traffic only |
437
+
438
+ ---
439
+
440
+ *Researched: 2026-03-08 | Sources: [Chrome DevTools Performance](https://developer.chrome.com/docs/devtools/performance), [Chrome Flame Graphs Guide](https://medium.com/slalom-blog/flame-graphs-in-chrome-devtools-a-guide-for-front-end-developers-b9503ff4a4d), [MDN RUM vs Synthetic](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Rum-vs-Synthetic), [DebugBear Synthetic vs RUM](https://www.debugbear.com/blog/synthetic-vs-rum), [Brendan Gregg Flame Graphs](https://www.brendangregg.com/flamegraphs.html), [Profiling in Production](https://www.caduh.com/blog/profiling-in-production), [Clinic.js](https://medium.com/@connect.hashblock/profiling-node-js-in-production-with-flamegraphs-clinic-js-9125e236d770), [Python Profiling](https://roman.pt/posts/python-performance-profiling/), [Scalene & py-spy 2025](https://johal.in/profiling-scalene-py-spy-memory-cpu-flamegraphs-2025/), [Core Web Vitals 2026](https://www.corewebvitals.io/core-web-vitals), [CWV Thresholds](https://web.dev/articles/defining-core-web-vitals-thresholds), [Knight Capital](https://www.henricodolfing.com/2019/06/project-failure-case-study-knight-capital.html), [P99 Latency](https://www.baeldung.com/cs/whats-the-p99-latency), [Apdex Score](https://coralogix.com/docs/user-guides/apm/features/apdex-score/), [pg_stat_statements](https://www.tigerdata.com/blog/using-pg-stat-statements-to-optimize-queries), [EXPLAIN ANALYZE](https://www.enterprisedb.com/blog/postgresql-query-optimization-performance-tuning-with-explain-analyze), [Lab vs Field Data](https://web.dev/articles/lab-and-field-data-differences), [FBDetect SOSP 2024](https://tangchq74.github.io/FBDetect-SOSP24.pdf), [Grafana Observability Survey 2024](https://grafana.com/observability-survey/2024/), [Tracing Overhead](https://atlarge-research.com/pdfs/2024-msc-anders_tracing_overhead.pdf), [Perfetto](https://perfetto.dev/), [BrowserStack iOS Tools](https://www.browserstack.com/guide/ios-app-performance-testing-tools), [Sentry Profiling](https://sentry.io/product/profiling/), [Performance Regression CI/CD](https://www.in-com.com/blog/performance-regression-testing-in-ci-cd-pipelines-a-strategic-framework/)*