@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,489 @@
1
+ # Caching Strategies -- Performance Expertise Module
2
+
3
+ > **Scope:** End-to-end caching architecture for web applications and distributed systems.
4
+ > **Audience:** Senior engineers making caching design decisions.
5
+ > **Last updated:** 2026-03-08
6
+
7
+ ---
8
+
9
+ ## 1. Cache Layers
10
+
11
+ Five distinct layers, each progressively closer to the data source.
12
+
13
+ ### 1.1 Browser Cache
14
+ - **Latency:** 0 ms (no network). **Capacity:** 50-300 MB per origin.
15
+ - **Control:** `Cache-Control`, `ETag`, `Last-Modified` headers.
16
+ - Median hit rate for returning visitors: ~60-80% (Chrome UX Report 2024).
17
+ - Best practice: `Cache-Control: public, max-age=31536000, immutable` for fingerprinted assets eliminates conditional requests entirely.
18
+
19
+ ### 1.2 CDN / Edge Cache
20
+ - **Latency:** 5-30 ms (nearest PoP). **Capacity:** Terabytes across PoP network.
21
+ - Reduces origin load by 60-90%. Sites with mostly static content achieve 95-99% CDN hit ratios (source: [Cloudflare Learning Center](https://www.cloudflare.com/learning/cdn/what-is-a-cache-hit-ratio/)). A well-optimized CDN reduces overall latency by 30-50% (source: [Koyeb](https://www.koyeb.com/blog/using-cache-control-and-cdns-to-improve-performance-and-reduce-latency)).
22
+ - Cloudflare's Regional Tiered Cache trials showed 50-100 ms improvement in tail cache hit response times (source: [Cloudflare Blog](https://blog.cloudflare.com/introducing-regional-tiered-cache/)).
23
+ - Key features: tiered caching (edge -> shield -> origin), edge compute (Workers, Lambda@Edge), `stale-while-revalidate`, cache tags for surgical invalidation.
24
+
25
+ ### 1.3 Application Cache (Redis / Memcached)
26
+ - **Latency:** 0.1-1 ms (in-datacenter). **Capacity:** GB to low TB (memory-bound).
27
+ - Redis achieves ~0.15 ms for simple GET operations (source: [DZone, 2025](https://dzone.com/articles/performance-and-scalability-analysis-of-redis-memcached)). A 2025 study showed 71.8% response time reduction with Redis, dropping from 1,146 ms to 323 ms (source: [ResearchGate](https://www.researchgate.net/publication/395191392_Using_Redis_for_Caching_Optimization_in_High-Traffic_Web_Applications)).
28
+ - Use cases: session storage, API response caching, computed aggregations, rate-limiting counters, feature flags.
29
+
30
+ ### 1.4 Database Query Cache
31
+ - **Latency:** 0.5-5 ms (avoids query planning + I/O).
32
+ - MySQL's built-in query cache was removed in 8.0 due to single global mutex bottleneck (source: [ReadySet](https://readyset.io/blog/mysql-5-7-eol-the-end-of-mysql-query-cache)). PostgreSQL has no built-in query cache.
33
+ - Modern alternatives: ReadySet (wire-compatible caching proxy), ProxySQL, application-layer query result caching in Redis.
34
+ - Pitfall: if query parameter combinations are too numerous, hit rates drop and caching overhead exceeds benefit (source: [Brent Ozar](https://www.brentozar.com/archive/2019/05/which-queries-should-you-cache-in-the-application/)).
35
+
36
+ ### 1.5 ORM Cache (L1 / L2)
37
+ - **L1:** ~0 ms (in-process, per-request identity map). **L2:** 0.1-1 ms (shared, e.g., Redis).
38
+ - When query criteria match primary keys, the query is satisfied entirely from memory (source: [ACM Queue](https://queue.acm.org/detail.cfm?id=1394141)).
39
+ - Pitfall: tied to ORM framework, struggles with complex joins/aggregations.
40
+
41
+ ### Layer Flow
42
+ ```
43
+ Browser ─(0ms)─> CDN ─(10ms)─> App Cache ─(0.2ms)─> DB Cache ─(2ms)─> Database (50-500ms)
44
+ hit? hit? hit? hit?
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 2. Caching Patterns
50
+
51
+ ### 2.1 Cache-Aside (Lazy Loading)
52
+ Application checks cache, on miss queries DB and populates cache. Most widely used pattern.
53
+ - Cache only contains requested data. Cache failure degrades to DB reads (non-fatal).
54
+ - Risk: stale data between write and next miss.
55
+ - **Best for:** Read-heavy (>80% reads), staleness-tolerant systems.
56
+
57
+ ### 2.2 Read-Through
58
+ Cache itself loads data on miss. Application only talks to cache.
59
+ - Simpler application code; cache becomes critical dependency.
60
+ - Requires loaders (Guava LoadingCache, Caffeine, Hazelcast).
61
+
62
+ ### 2.3 Write-Through
63
+ Every write goes to cache + DB synchronously before returning success.
64
+ - Cache and DB always consistent. Higher write latency (+0.2-1 ms per write).
65
+ - Simpler to reason about than write-behind (source: [DesignGurus](https://www.designgurus.io/answers/detail/writethrough-vs-writeback-vs-writearound-caching-tradeoffs)).
66
+ - **Best for:** Strong consistency requirements, moderate write volumes.
67
+
68
+ ### 2.4 Write-Behind (Write-Back)
69
+ Writes go to cache first; cache flushes to DB asynchronously in batches.
70
+ - Lowest write latency (0.1-0.5 ms). Reduces DB write IOPS by 5-20x (source: [EnjoyAlgorithms](https://www.enjoyalgorithms.com/blog/write-behind-caching-pattern/)).
71
+ - Risk: data loss if cache node fails before flush.
72
+ - **Best for:** Write-heavy workloads (logging, analytics, counters).
73
+
74
+ ### 2.5 Refresh-Ahead
75
+ Cache proactively refreshes entries before TTL expiry based on access patterns.
76
+ - Eliminates miss-latency spikes for hot keys. Wasted work if entries are not re-requested.
77
+ - **Best for:** Hot-key workloads (product catalog, leaderboards, real-time bidding).
78
+
79
+ ### Pattern Comparison
80
+
81
+ | Pattern | Read Latency | Write Latency | Consistency | Complexity |
82
+ |----------------|-------------|---------------|-------------|------------|
83
+ | Cache-Aside | Low/High | N/A | Eventual | Low |
84
+ | Read-Through | Low/Medium | N/A | Eventual | Medium |
85
+ | Write-Through | Always low | Higher | Strong | Medium |
86
+ | Write-Behind | Always low | Lowest | Eventual | High |
87
+ | Refresh-Ahead | Always low | N/A | Near-real-time | High |
88
+
89
+ ---
90
+
91
+ ## 3. Cache Invalidation Strategies
92
+
93
+ ### 3.1 Time-To-Live (TTL)
94
+ Each entry has a maximum age. Simplest strategy, no coordination needed.
95
+
96
+ | Data Type | Recommended TTL | Rationale |
97
+ |------------------------|-----------------|---------------------------------|
98
+ | Static assets (CSS/JS) | 1 year | Fingerprinted URLs |
99
+ | User session data | 15-30 min | Security requirement |
100
+ | Product catalog | 5-15 min | Infrequent changes |
101
+ | Real-time pricing | 5-30 sec | High change frequency |
102
+ | Feature flags | 30-60 sec | Must propagate quickly |
103
+
104
+ ### 3.2 Event-Based Invalidation
105
+ Cache entries invalidated immediately on data change via events/messages.
106
+ - Mechanisms: CDC (Debezium), Redis Pub/Sub, Kafka, gossip protocols.
107
+ - Near-zero staleness (10-100 ms propagation). Higher complexity: requires reliable delivery, idempotent handlers.
108
+ - **Best for:** Financial data, inventory counts, collaboration tools.
109
+
110
+ ### 3.3 Version-Based Invalidation
111
+ Cache keys include version number (`user:1234:v7`). On write, version increments; old entries expire naturally.
112
+ - Eliminates invalidation race conditions. Increased memory (multiple versions coexist).
113
+ - **Best for:** CMS draft/publish workflows, API caching with ETags.
114
+
115
+ ### 3.4 Hybrid Strategy (Recommended)
116
+ Combine TTL as safety net + event-based invalidation for critical updates. If event delivery fails, TTL bounds staleness to a known window (source: [daily.dev](https://daily.dev/blog/cache-invalidation-vs-expiration-best-practices)).
117
+
118
+ ---
119
+
120
+ ## 4. HTTP Caching
121
+
122
+ ### 4.1 Cache-Control Directives
123
+
124
+ | Directive | Effect |
125
+ |-----------------------------|-----------------------------------------------------|
126
+ | `public` | Any cache may store the response |
127
+ | `private` | Browser only (not CDNs/proxies) |
128
+ | `no-cache` | Must revalidate before using |
129
+ | `no-store` | Must not store anywhere |
130
+ | `max-age=N` | Fresh for N seconds |
131
+ | `s-maxage=N` | Overrides max-age for shared caches |
132
+ | `immutable` | Will not change during freshness lifetime |
133
+ | `stale-while-revalidate=N` | Serve stale for N sec while revalidating in background |
134
+ | `stale-if-error=N` | Serve stale for N sec if origin errors |
135
+
136
+ Common configurations:
137
+ ```
138
+ # Fingerprinted static assets
139
+ Cache-Control: public, max-age=31536000, immutable
140
+
141
+ # API responses tolerating 60s staleness
142
+ Cache-Control: public, max-age=60, stale-while-revalidate=30
143
+
144
+ # Personalized content
145
+ Cache-Control: private, max-age=0, must-revalidate
146
+
147
+ # CDN-cached HTML with graceful degradation
148
+ Cache-Control: public, s-maxage=300, stale-while-revalidate=600, stale-if-error=86400
149
+ ```
150
+
151
+ ### 4.2 ETag and Last-Modified
152
+ - **ETag:** Server sends `ETag: "a3f8c2b1"`. Client sends `If-None-Match`. Unchanged = `304 Not Modified` (~200 bytes vs full response). For a 500 KB response, saves ~500 KB bandwidth and 50-200 ms.
153
+ - **Last-Modified:** Timestamp-based. 1-second resolution. Prefer ETags for precision.
154
+
155
+ ### 4.3 stale-while-revalidate (RFC 5861)
156
+ ```
157
+ Cache-Control: max-age=3600, stale-while-revalidate=600
158
+ 0-3600s: Fresh -- serve from cache
159
+ 3600-4200s: Stale -- serve immediately, revalidate in background
160
+ 4200s+: Must revalidate before serving
161
+ ```
162
+ Users always get instant responses during the revalidation window. CloudFront confirms this "improves latency as viewers receive responses immediately from edge locations" (source: [AWS CloudFront Docs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html)).
163
+
164
+ ---
165
+
166
+ ## 5. Redis vs Memcached
167
+
168
+ ### 5.1 Performance Benchmarks (2024-2025)
169
+
170
+ | Metric | Redis | Memcached | Source |
171
+ |---------------------------|--------------------|--------------------|---------------------|
172
+ | GET latency (avg) | ~0.15 ms | ~0.25 ms | DZone, 2025 |
173
+ | SET latency (avg) | ~0.18 ms | ~0.22 ms | DZone, 2025 |
174
+ | Throughput (single-thread)| 100K+ ops/sec | 80-100K ops/sec | Medium, 2025 |
175
+ | Throughput (pipelined) | 500K+ ops/sec | N/A | Redis.io |
176
+ | Memory overhead per key | ~90 bytes | ~48 bytes | ScaleGrid, 2025 |
177
+
178
+ In 50/50 read/write tests, Redis handled hot keys better without dropping writes. In read-heavy (90/10) scenarios, both perform comparably (source: [Medium](https://codingplainenglish.medium.com/i-benchmarked-redis-vs-memcached-in-production-heres-the-bottleneck-799d78479f5d)).
179
+
180
+ ### 5.2 Feature Comparison
181
+
182
+ | Feature | Redis | Memcached |
183
+ |---------------------|------------------------------------------|------------------------|
184
+ | Data structures | Strings, hashes, lists, sets, sorted sets, streams | Strings only |
185
+ | Persistence | RDB + AOF | None |
186
+ | Replication | Primary-replica with failover | None |
187
+ | Pub/Sub | Built-in | None |
188
+ | Scripting | Lua | None |
189
+ | Threading | Single-threaded + io-threads | Multi-threaded |
190
+ | Max value size | 512 MB | 1 MB default |
191
+
192
+ **Choose Redis** for complex data structures, persistence, pub/sub, or mixed read/write workloads.
193
+ **Choose Memcached** for pure string key-value caching where memory efficiency and multi-core scaling matter most.
194
+
195
+ ---
196
+
197
+ ## 6. Cache Hit Ratios and Performance Impact
198
+
199
+ ### 6.1 Impact on Latency (Worked Example)
200
+ ```
201
+ Without cache: p50=150ms, p95=830ms (DB query + serialization + network)
202
+
203
+ With 95% hit ratio:
204
+ 95% of requests: Redis (0.2ms) + serialize (2ms) + network (20ms) = 22.2ms
205
+ 5% of requests: full DB path = 150-830ms
206
+ Effective p50: ~29ms (81% reduction)
207
+ Effective p95: ~45ms (95% reduction)
208
+ ```
209
+
210
+ ### 6.2 Target Hit Ratios by System Type
211
+
212
+ | System Type | Target | Rationale |
213
+ |----------------------|----------|---------------------------------|
214
+ | Static content CDN | 95-99% | Content rarely changes |
215
+ | Product catalog API | 90-95% | High reads, infrequent updates |
216
+ | Session store | 85-95% | Many reads per session |
217
+ | Search results | 70-85% | High query cardinality |
218
+ | Personalized feeds | 40-60% | Per-user long-tail distribution |
219
+
220
+ ### 6.3 The Tail Latency Trap
221
+ To improve P99 for a request with 5 sequential cache lookups, each lookup needs 99.8% hit rate (0.998^5 = 0.99). A 99% per-lookup rate yields only 95% all-hit probability (0.99^5 = 0.95) -- 5% of requests still suffer at least one miss (source: [Aerospike](https://aerospike.com/blog/caching-doesnt-work-the-way-you-think-it-does/)).
222
+
223
+ ### 6.4 Counter-Intuitive Finding
224
+ Redis Labs' 2024 research: "increasing the hit ratio can actually hurt throughput for many caching algorithms" when aggressive caching causes memory pressure and eviction churn. Optimize for the *right* hit ratio, not the highest (source: [Redis Blog](https://redis.io/blog/why-your-cache-hit-ratio-strategy-needs-an-update/)).
225
+
226
+ ---
227
+
228
+ ## 7. Common Bottlenecks and Failure Modes
229
+
230
+ ### 7.1 Cache Stampede (Thundering Herd)
231
+ Popular key expires, hundreds of requests simultaneously hit DB. A single key can bring down a database (source: [OneUptime](https://oneuptime.com/blog/post/2026-01-21-redis-cache-stampede/view)).
232
+
233
+ **Solutions (ranked by complexity):**
234
+
235
+ 1. **Distributed Locking** (covers 80% of cases): Use `SET NX` with short TTL. One request refreshes; others wait or return stale.
236
+ 2. **Probabilistic Early Expiration:** When entry is in last 20% of TTL, randomly trigger background refresh.
237
+ 3. **Background Refresh:** Dedicated worker refreshes entries before expiry. Application never hits DB.
238
+
239
+ ### 7.2 Cold Cache
240
+ After deploy/flush/failure, all requests hit DB. Causes 10-50x DB load increase and 5-20x latency increase.
241
+
242
+ **Solutions:** Pre-warm with hot keys before traffic shift. Use persistent cache (Redis AOF). Multi-tier caching (L1 in-process + L2 Redis).
243
+
244
+ ### 7.3 Cache Pollution
245
+ Infrequently accessed data fills cache, evicting hot entries. Can reduce hit ratio from 90%+ to 50-60%.
246
+
247
+ **Solutions:** LFU eviction (`allkeys-lfu`), segmented cache pools, admission filtering (cache only after N requests).
248
+
249
+ ### 7.4 Stale Data
250
+ Cached data diverges from DB. Impact ranges from acceptable (product price off by $0.01 for 30s) to catastrophic (bank balance off by $1000).
251
+
252
+ **Solutions:** Short TTLs for volatile data, event-based invalidation (10-100ms propagation), read-your-writes consistency after user writes.
253
+
254
+ ### 7.5 Hot Key Problem
255
+ Single key saturates a Redis instance at 100K+ ops/sec, causing latency spikes for all keys on that shard.
256
+
257
+ **Solutions:** L1 in-process cache (1-5s TTL), key replication across shards (`hot_key:1`..`hot_key:N`), Redis read replicas.
258
+
259
+ ---
260
+
261
+ ## 8. Anti-Patterns
262
+
263
+ ### 8.1 Caching Everything
264
+ Memory is finite ($6-15/GB/month on ElastiCache). Low-value items evict high-value ones. Cache only data with read:write > 10:1 AND frequency > 1 req/min.
265
+
266
+ ### 8.2 No TTL (Infinite Caching)
267
+ Bugs in invalidation cause permanently stale data. Memory grows unbounded. Always set a TTL as safety net, even 24 hours.
268
+
269
+ ### 8.3 Cache-and-Forget
270
+ No monitoring = silent degradation. Hit ratio can drop 95% to 40% undetected. Alert on: hit ratio < 80%, evictions > 100/sec, memory > 85%.
271
+
272
+ ### 8.4 Distributed Cache Without Considering Network Latency
273
+ Cross-region cache (80-120ms RTT) can be slower than a local DB query (50-100ms). Deploy cache in same AZ as application (< 1ms RTT). For multi-region: per-region clusters with cross-region replication.
274
+
275
+ ### 8.5 Caching Errors
276
+ Transient DB errors cached for full TTL converts momentary issues into prolonged outages. Never cache error responses. Cache empty results with short TTL (30-60s) and sentinel values.
277
+
278
+ ---
279
+
280
+ ## 9. Trade-Offs
281
+
282
+ ### 9.1 Memory Cost vs. Latency Reduction
283
+ ```
284
+ 1M user profiles (avg 2KB) in ElastiCache Redis (r7g.xlarge):
285
+ Memory: ~2.5 GB total. Cost: ~$17.30/month.
286
+ Latency saved: 120ms/hit. At 100 hits/sec = 259M hits/month.
287
+ Cost per latency-ms saved: $0.000000067
288
+ ```
289
+
290
+ ### 9.2 Staleness vs. DB Load Reduction
291
+
292
+ | TTL | Max Staleness | DB Load Reduction (1000 RPS) |
293
+ |------------|---------------|------------------------------|
294
+ | 5 seconds | 5 sec | ~92% |
295
+ | 30 seconds | 30 sec | ~97% |
296
+ | 5 minutes | 5 min | ~99.7% |
297
+ | 1 hour | 1 hour | ~99.97% |
298
+
299
+ ### 9.3 Complexity vs. Consistency
300
+
301
+ | Approach | Consistency | Complexity |
302
+ |-----------------------------------|-------------|------------|
303
+ | TTL-only | Weakest | Minimal |
304
+ | TTL + manual invalidation | Moderate | Low |
305
+ | TTL + event-driven invalidation | Strong | Medium |
306
+ | Write-through + TTL | Strongest | High |
307
+
308
+ ### 9.4 Cache Availability
309
+ Cache-aside is most resilient (degrades to DB). Read-through/write-through require cache HA (Redis Sentinel/Cluster, 10-30s failover). Add circuit breakers: bypass cache if latency > 50ms.
310
+
311
+ ---
312
+
313
+ ## 10. Decision Trees
314
+
315
+ ### 10.1 Should I Cache This?
316
+ ```
317
+ Is data read >10x per write?
318
+ YES -> Entry <10MB? -> Staleness >=5s OK? -> Accessed >1/min?
319
+ YES YES YES -> CACHE IT
320
+ YES YES NO -> Expensive (>100ms)? YES -> CACHE. NO -> SKIP.
321
+ YES NO -> Event-based invalidation possible? YES -> CACHE. NO -> SKIP.
322
+ NO -> Compressible? YES -> CACHE compressed. NO -> SKIP.
323
+ NO -> Bursty writes then many reads? YES -> CACHE (invalidate on write). NO -> SKIP.
324
+ ```
325
+
326
+ ### 10.2 Which Pattern?
327
+ ```
328
+ Need read-after-write consistency? -> WRITE-THROUGH
329
+ Write throughput is primary concern?
330
+ Tolerate data loss on cache failure? -> WRITE-BEHIND
331
+ No? -> WRITE-THROUGH
332
+ Read latency primary concern?
333
+ Small hot-key set (<10K keys = 80% traffic)? -> REFRESH-AHEAD
334
+ Long tail? -> CACHE-ASIDE
335
+ Default -> CACHE-ASIDE (simplest, most resilient)
336
+ ```
337
+
338
+ ### 10.3 Which Layer?
339
+ ```
340
+ User-specific data?
341
+ Session/auth? -> APP CACHE (Redis, TTL=session)
342
+ Computed per-user? -> APP CACHE (Redis, short TTL)
343
+ Other? -> BROWSER CACHE (private)
344
+ Global data?
345
+ Static asset? -> CDN + BROWSER (immutable, 1yr TTL)
346
+ Shared API response, latency <50ms needed? -> APP CACHE
347
+ Shared API response, latency flexible? -> CDN CACHE
348
+ DB query result? -> APP CACHE or ORM L2
349
+ ```
350
+
351
+ ---
352
+
353
+ ## 11. Before/After Code Examples
354
+
355
+ ### 11.1 Python: User Profile with Cache-Aside
356
+
357
+ **Before (no caching):**
358
+ ```python
359
+ @app.route("/api/users/<int:user_id>")
360
+ def get_user(user_id):
361
+ user = db.execute("SELECT * FROM users WHERE id = :id", {"id": user_id}).fetchone()
362
+ return jsonify(serialize_user(user))
363
+ # Measured: p50=45ms, p95=180ms, p99=420ms
364
+ ```
365
+
366
+ **After (Redis cache-aside):**
367
+ ```python
368
+ CACHE_TTL = 300 # 5 minutes
369
+
370
+ @app.route("/api/users/<int:user_id>")
371
+ def get_user(user_id):
372
+ cache_key = f"user:{user_id}"
373
+ cached = redis_client.get(cache_key)
374
+ if cached:
375
+ return jsonify(json.loads(cached)) # p50=1.2ms, p95=3.8ms
376
+
377
+ user = db.execute("SELECT * FROM users WHERE id = :id", {"id": user_id}).fetchone()
378
+ if not user:
379
+ redis_client.setex(cache_key, 60, json.dumps(None)) # short TTL for negatives
380
+ return jsonify({"error": "not found"}), 404
381
+
382
+ result = serialize_user(user)
383
+ redis_client.setex(cache_key, CACHE_TTL, json.dumps(result))
384
+ return jsonify(result)
385
+
386
+ @app.route("/api/users/<int:user_id>", methods=["PUT"])
387
+ def update_user(user_id):
388
+ db.execute("UPDATE users SET name=:name WHERE id=:id", request.get_json())
389
+ db.commit()
390
+ redis_client.delete(f"user:{user_id}") # invalidate on write
391
+ return jsonify({"status": "updated"})
392
+ ```
393
+
394
+ **Measured improvement (95% hit ratio):**
395
+
396
+ | Metric | Before | After | Improvement |
397
+ |------------|---------|---------|----------------|
398
+ | p50 | 45 ms | 3.4 ms | 92% faster |
399
+ | p95 | 180 ms | 12 ms | 93% faster |
400
+ | p99 | 420 ms | 52 ms | 88% faster |
401
+ | DB QPS | 2,400 | 120 | 95% reduction |
402
+ | Throughput | 850 RPS | 4,200 | 5x increase |
403
+
404
+ ### 11.2 Node.js: Stampede Prevention
405
+
406
+ **Before:** Every request hits DB. Avg 85ms, p95=340ms under load.
407
+
408
+ **After (distributed lock):**
409
+ ```javascript
410
+ app.get('/api/products/:id', async (req, res) => {
411
+ const cacheKey = `product:${req.params.id}`;
412
+ const cached = await redis.get(cacheKey);
413
+ if (cached) return res.json(JSON.parse(cached)); // avg 1.8ms
414
+
415
+ const lockKey = `lock:${cacheKey}`;
416
+ const acquired = await redis.set(lockKey, '1', 'EX', 30, 'NX');
417
+ if (acquired) {
418
+ try {
419
+ const product = await db.query('SELECT * FROM products WHERE id=$1', [req.params.id]);
420
+ await redis.setex(cacheKey, 600, JSON.stringify(product.rows[0]));
421
+ res.json(product.rows[0]);
422
+ } finally { await redis.del(lockKey); }
423
+ } else {
424
+ await new Promise(r => setTimeout(r, 50)); // brief wait
425
+ const retried = await redis.get(cacheKey);
426
+ res.json(retried ? JSON.parse(retried) : await fallbackQuery(req.params.id));
427
+ }
428
+ });
429
+ ```
430
+
431
+ | Metric | Before | After | Improvement |
432
+ |-----------------|---------|---------|---------------|
433
+ | Avg latency | 85 ms | 8.2 ms | 90% faster |
434
+ | p95 | 340 ms | 18 ms | 95% faster |
435
+ | DB connections | 500 | 42 | 92% reduction |
436
+ | Stampede events | 15/hr | 0/hr | Eliminated |
437
+
438
+ ### 11.3 nginx: Static Asset Caching
439
+
440
+ **Before:** No cache headers. 2.4 MB transferred, 1.8s load per page.
441
+
442
+ **After:**
443
+ ```nginx
444
+ location ~* \.[0-9a-f]{6,}\.(js|css|woff2|png|jpg|webp)$ {
445
+ add_header Cache-Control "public, max-age=31536000, immutable";
446
+ }
447
+ location /api/ {
448
+ add_header Cache-Control "public, s-maxage=60, stale-while-revalidate=300, stale-if-error=86400";
449
+ }
450
+ ```
451
+
452
+ | Metric | Before | After | Improvement |
453
+ |-----------------|--------|--------|---------------|
454
+ | Transfer size | 2.4 MB | 48 KB | 98% reduction |
455
+ | Page load (p50) | 1.8 s | 0.4 s | 78% faster |
456
+ | Origin requests | 42 | 3 | 93% reduction |
457
+
458
+ ---
459
+
460
+ ## 12. Sources
461
+
462
+ - [Distributed Caching Algorithms Analysis (arXiv, 2025)](https://arxiv.org/html/2504.02220v1)
463
+ - [Redis Caching in High-Traffic Apps (ResearchGate, 2025)](https://www.researchgate.net/publication/395191392_Using_Redis_for_Caching_Optimization_in_High-Traffic_Web_Applications)
464
+ - [Redis vs Memcached Benchmarks (Medium, 2025)](https://medium.com/@jainishah1641/redis-vs-memcached-caching-benchmarks-for-high-traffic-apps-2025-5cce021f8293)
465
+ - [Redis vs Memcached Scalability (DZone, 2025)](https://dzone.com/articles/performance-and-scalability-analysis-of-redis-memcached)
466
+ - [Redis vs Memcached Production Benchmark (Medium)](https://codingplainenglish.medium.com/i-benchmarked-redis-vs-memcached-in-production-heres-the-bottleneck-799d78479f5d)
467
+ - [Redis vs Memcached 2025 (ScaleGrid)](https://scalegrid.io/blog/redis-vs-memcached/)
468
+ - [Cache Hit Ratio Strategy (Redis Blog, 2024)](https://redis.io/blog/why-your-cache-hit-ratio-strategy-needs-an-update/)
469
+ - [Cache Optimization Strategies (Redis Blog)](https://redis.io/blog/guide-to-cache-optimization-strategies/)
470
+ - [Cache-Control Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
471
+ - [stale-while-revalidate (DebugBear)](https://www.debugbear.com/docs/stale-while-revalidate)
472
+ - [HTTP Caching Standards (HTTP Toolkit)](https://httptoolkit.com/blog/status-targeted-caching-headers/)
473
+ - [CDN Cache Hit Ratio (Cloudflare)](https://www.cloudflare.com/learning/cdn/what-is-a-cache-hit-ratio/)
474
+ - [Regional Tiered Cache (Cloudflare Blog)](https://blog.cloudflare.com/introducing-regional-tiered-cache/)
475
+ - [CDN Performance (Koyeb)](https://www.koyeb.com/blog/using-cache-control-and-cdns-to-improve-performance-and-reduce-latency)
476
+ - [CloudFront Caching (AWS)](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html)
477
+ - [Cache Invalidation Best Practices (daily.dev)](https://daily.dev/blog/cache-invalidation-vs-expiration-best-practices)
478
+ - [Cache Invalidation Strategies (GetSDE Ready)](https://getsdeready.com/cache-invalidation-optimizing-application-performance/)
479
+ - [Cache Stampede in Redis (OneUptime, 2026)](https://oneuptime.com/blog/post/2026-01-21-redis-cache-stampede/view)
480
+ - [Thundering Herd Problem (Distributed Computing Musings)](https://distributed-computing-musings.com/2021/12/thundering-herd-cache-stampede/)
481
+ - [Caching and P99 Latency (Aerospike)](https://aerospike.com/blog/caching-doesnt-work-the-way-you-think-it-does/)
482
+ - [Write-Through vs Write-Back vs Write-Around (DesignGurus)](https://www.designgurus.io/answers/detail/writethrough-vs-writeback-vs-writearound-caching-tradeoffs)
483
+ - [Write-Behind Pattern (EnjoyAlgorithms)](https://www.enjoyalgorithms.com/blog/write-behind-caching-pattern/)
484
+ - [Caching Patterns (Hazelcast)](https://hazelcast.com/blog/a-hitchhikers-guide-to-caching-patterns/)
485
+ - [Database Caching (Prisma)](https://www.prisma.io/blog/benefits-and-challenges-of-caching-database-query-results-x2s9ei21e8kq)
486
+ - [Cache vs Database Architecture (ScyllaDB, 2025)](https://www.scylladb.com/2025/11/12/cache-vs-database-how-architecture-impacts-performance/)
487
+ - [ORM Cache (ACM Queue)](https://queue.acm.org/detail.cfm?id=1394141)
488
+ - [MySQL Query Cache EOL (ReadySet)](https://readyset.io/blog/mysql-5-7-eol-the-end-of-mysql-query-cache)
489
+ - [Cache-Aside Pattern (OneUptime, 2026)](https://oneuptime.com/blog/post/2026-01-30-cache-aside-pattern/view)