@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.
- package/AGENTS.md +111 -0
- package/CHANGELOG.md +14 -0
- package/CONTRIBUTING.md +101 -0
- package/LICENSE +21 -0
- package/README.md +314 -0
- package/assets/composition-engine.mmd +34 -0
- package/assets/demo-script.sh +17 -0
- package/assets/logo-dark.svg +14 -0
- package/assets/logo.svg +14 -0
- package/assets/pipeline.mmd +39 -0
- package/assets/record-demo.sh +51 -0
- package/docs/README.md +51 -0
- package/docs/adapters/context-mode.md +60 -0
- package/docs/concepts/architecture.md +87 -0
- package/docs/concepts/artifact-model.md +60 -0
- package/docs/concepts/composition-engine.md +36 -0
- package/docs/concepts/indexing-and-recall.md +160 -0
- package/docs/concepts/observability.md +41 -0
- package/docs/concepts/roles-and-workflows.md +59 -0
- package/docs/concepts/terminology-policy.md +27 -0
- package/docs/getting-started/01-installation.md +78 -0
- package/docs/getting-started/02-first-run.md +102 -0
- package/docs/getting-started/03-adding-to-project.md +15 -0
- package/docs/getting-started/04-host-setup.md +15 -0
- package/docs/guides/ci-integration.md +15 -0
- package/docs/guides/creating-skills.md +15 -0
- package/docs/guides/expertise-module-authoring.md +15 -0
- package/docs/guides/hook-development.md +15 -0
- package/docs/guides/memory-and-learnings.md +34 -0
- package/docs/guides/multi-host-export.md +15 -0
- package/docs/guides/troubleshooting.md +101 -0
- package/docs/guides/writing-custom-roles.md +15 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
- package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
- package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
- package/docs/readmes/INDEX.md +99 -0
- package/docs/readmes/features/expertise/README.md +171 -0
- package/docs/readmes/features/exports/README.md +222 -0
- package/docs/readmes/features/hooks/README.md +103 -0
- package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
- package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
- package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
- package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
- package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
- package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
- package/docs/readmes/features/hooks/session-start.md +119 -0
- package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
- package/docs/readmes/features/roles/README.md +157 -0
- package/docs/readmes/features/roles/clarifier.md +152 -0
- package/docs/readmes/features/roles/content-author.md +190 -0
- package/docs/readmes/features/roles/designer.md +193 -0
- package/docs/readmes/features/roles/executor.md +184 -0
- package/docs/readmes/features/roles/learner.md +210 -0
- package/docs/readmes/features/roles/planner.md +182 -0
- package/docs/readmes/features/roles/researcher.md +164 -0
- package/docs/readmes/features/roles/reviewer.md +184 -0
- package/docs/readmes/features/roles/specifier.md +162 -0
- package/docs/readmes/features/roles/verifier.md +215 -0
- package/docs/readmes/features/schemas/README.md +178 -0
- package/docs/readmes/features/skills/README.md +63 -0
- package/docs/readmes/features/skills/brainstorming.md +96 -0
- package/docs/readmes/features/skills/debugging.md +148 -0
- package/docs/readmes/features/skills/design.md +120 -0
- package/docs/readmes/features/skills/prepare-next.md +109 -0
- package/docs/readmes/features/skills/run-audit.md +159 -0
- package/docs/readmes/features/skills/scan-project.md +109 -0
- package/docs/readmes/features/skills/self-audit.md +176 -0
- package/docs/readmes/features/skills/tdd.md +137 -0
- package/docs/readmes/features/skills/using-skills.md +92 -0
- package/docs/readmes/features/skills/verification.md +120 -0
- package/docs/readmes/features/skills/writing-plans.md +104 -0
- package/docs/readmes/features/tooling/README.md +320 -0
- package/docs/readmes/features/workflows/README.md +186 -0
- package/docs/readmes/features/workflows/author.md +181 -0
- package/docs/readmes/features/workflows/clarify.md +154 -0
- package/docs/readmes/features/workflows/design-review.md +171 -0
- package/docs/readmes/features/workflows/design.md +169 -0
- package/docs/readmes/features/workflows/discover.md +162 -0
- package/docs/readmes/features/workflows/execute.md +173 -0
- package/docs/readmes/features/workflows/learn.md +167 -0
- package/docs/readmes/features/workflows/plan-review.md +165 -0
- package/docs/readmes/features/workflows/plan.md +170 -0
- package/docs/readmes/features/workflows/prepare-next.md +167 -0
- package/docs/readmes/features/workflows/review.md +169 -0
- package/docs/readmes/features/workflows/run-audit.md +191 -0
- package/docs/readmes/features/workflows/spec-challenge.md +159 -0
- package/docs/readmes/features/workflows/specify.md +160 -0
- package/docs/readmes/features/workflows/verify.md +177 -0
- package/docs/readmes/packages/README.md +50 -0
- package/docs/readmes/packages/ajv.md +117 -0
- package/docs/readmes/packages/context-mode.md +118 -0
- package/docs/readmes/packages/gray-matter.md +116 -0
- package/docs/readmes/packages/node-test.md +137 -0
- package/docs/readmes/packages/yaml.md +112 -0
- package/docs/reference/configuration-reference.md +159 -0
- package/docs/reference/expertise-index.md +52 -0
- package/docs/reference/git-flow.md +43 -0
- package/docs/reference/hooks.md +87 -0
- package/docs/reference/host-exports.md +50 -0
- package/docs/reference/launch-checklist.md +172 -0
- package/docs/reference/marketplace-listings.md +76 -0
- package/docs/reference/release-process.md +34 -0
- package/docs/reference/roles-reference.md +77 -0
- package/docs/reference/skills.md +33 -0
- package/docs/reference/templates.md +29 -0
- package/docs/reference/tooling-cli.md +94 -0
- package/docs/truth-claims.yaml +222 -0
- package/expertise/PROGRESS.md +63 -0
- package/expertise/README.md +18 -0
- package/expertise/antipatterns/PROGRESS.md +56 -0
- package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
- package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
- package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
- package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
- package/expertise/antipatterns/backend/index.md +24 -0
- package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
- package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
- package/expertise/antipatterns/code/async-antipatterns.md +622 -0
- package/expertise/antipatterns/code/code-smells.md +1186 -0
- package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
- package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
- package/expertise/antipatterns/code/index.md +27 -0
- package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
- package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
- package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
- package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
- package/expertise/antipatterns/design/dark-patterns.md +1121 -0
- package/expertise/antipatterns/design/index.md +22 -0
- package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
- package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
- package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
- package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
- package/expertise/antipatterns/frontend/index.md +23 -0
- package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
- package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
- package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
- package/expertise/antipatterns/index.md +31 -0
- package/expertise/antipatterns/performance/index.md +20 -0
- package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
- package/expertise/antipatterns/performance/premature-optimization.md +623 -0
- package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
- package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
- package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
- package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
- package/expertise/antipatterns/process/index.md +23 -0
- package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
- package/expertise/antipatterns/security/index.md +20 -0
- package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
- package/expertise/antipatterns/security/security-theater.md +843 -0
- package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
- package/expertise/architecture/PROGRESS.md +70 -0
- package/expertise/architecture/data/caching-architecture.md +671 -0
- package/expertise/architecture/data/data-consistency.md +574 -0
- package/expertise/architecture/data/data-modeling.md +536 -0
- package/expertise/architecture/data/event-streams-and-queues.md +634 -0
- package/expertise/architecture/data/index.md +25 -0
- package/expertise/architecture/data/search-architecture.md +663 -0
- package/expertise/architecture/data/sql-vs-nosql.md +708 -0
- package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
- package/expertise/architecture/decisions/build-vs-buy.md +616 -0
- package/expertise/architecture/decisions/index.md +23 -0
- package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
- package/expertise/architecture/decisions/technology-selection.md +616 -0
- package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
- package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
- package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
- package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
- package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
- package/expertise/architecture/distributed/index.md +25 -0
- package/expertise/architecture/distributed/saga-pattern.md +797 -0
- package/expertise/architecture/foundations/architectural-thinking.md +460 -0
- package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
- package/expertise/architecture/foundations/design-principles-solid.md +649 -0
- package/expertise/architecture/foundations/domain-driven-design.md +719 -0
- package/expertise/architecture/foundations/index.md +25 -0
- package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
- package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
- package/expertise/architecture/index.md +34 -0
- package/expertise/architecture/integration/api-design-graphql.md +638 -0
- package/expertise/architecture/integration/api-design-grpc.md +804 -0
- package/expertise/architecture/integration/api-design-rest.md +892 -0
- package/expertise/architecture/integration/index.md +25 -0
- package/expertise/architecture/integration/third-party-integration.md +795 -0
- package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
- package/expertise/architecture/integration/websockets-realtime.md +791 -0
- package/expertise/architecture/mobile-architecture/index.md +22 -0
- package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
- package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
- package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
- package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
- package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
- package/expertise/architecture/patterns/event-driven.md +797 -0
- package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
- package/expertise/architecture/patterns/index.md +27 -0
- package/expertise/architecture/patterns/layered-architecture.md +736 -0
- package/expertise/architecture/patterns/microservices.md +753 -0
- package/expertise/architecture/patterns/modular-monolith.md +692 -0
- package/expertise/architecture/patterns/monolith.md +626 -0
- package/expertise/architecture/patterns/plugin-architecture.md +735 -0
- package/expertise/architecture/patterns/serverless.md +780 -0
- package/expertise/architecture/scaling/database-scaling.md +615 -0
- package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
- package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
- package/expertise/architecture/scaling/index.md +24 -0
- package/expertise/architecture/scaling/multi-tenancy.md +800 -0
- package/expertise/architecture/scaling/stateless-design.md +787 -0
- package/expertise/backend/embedded-firmware.md +625 -0
- package/expertise/backend/go.md +853 -0
- package/expertise/backend/index.md +24 -0
- package/expertise/backend/java-spring.md +448 -0
- package/expertise/backend/node-typescript.md +625 -0
- package/expertise/backend/python-fastapi.md +724 -0
- package/expertise/backend/rust.md +458 -0
- package/expertise/backend/solidity.md +711 -0
- package/expertise/composition-map.yaml +443 -0
- package/expertise/content/foundations/content-modeling.md +395 -0
- package/expertise/content/foundations/editorial-standards.md +449 -0
- package/expertise/content/foundations/index.md +24 -0
- package/expertise/content/foundations/microcopy.md +455 -0
- package/expertise/content/foundations/terminology-governance.md +509 -0
- package/expertise/content/index.md +34 -0
- package/expertise/content/patterns/accessibility-copy.md +518 -0
- package/expertise/content/patterns/index.md +24 -0
- package/expertise/content/patterns/notification-content.md +433 -0
- package/expertise/content/patterns/sample-content.md +486 -0
- package/expertise/content/patterns/state-copy.md +439 -0
- package/expertise/design/PROGRESS.md +58 -0
- package/expertise/design/disciplines/dark-mode-theming.md +577 -0
- package/expertise/design/disciplines/design-systems.md +595 -0
- package/expertise/design/disciplines/index.md +25 -0
- package/expertise/design/disciplines/information-architecture.md +800 -0
- package/expertise/design/disciplines/interaction-design.md +788 -0
- package/expertise/design/disciplines/responsive-design.md +552 -0
- package/expertise/design/disciplines/usability-testing.md +516 -0
- package/expertise/design/disciplines/user-research.md +792 -0
- package/expertise/design/foundations/accessibility-design.md +796 -0
- package/expertise/design/foundations/color-theory.md +797 -0
- package/expertise/design/foundations/iconography.md +795 -0
- package/expertise/design/foundations/index.md +26 -0
- package/expertise/design/foundations/motion-and-animation.md +653 -0
- package/expertise/design/foundations/rtl-design.md +585 -0
- package/expertise/design/foundations/spacing-and-layout.md +607 -0
- package/expertise/design/foundations/typography.md +800 -0
- package/expertise/design/foundations/visual-hierarchy.md +761 -0
- package/expertise/design/index.md +32 -0
- package/expertise/design/patterns/authentication-flows.md +474 -0
- package/expertise/design/patterns/content-consumption.md +789 -0
- package/expertise/design/patterns/data-display.md +618 -0
- package/expertise/design/patterns/e-commerce.md +1494 -0
- package/expertise/design/patterns/feedback-and-states.md +642 -0
- package/expertise/design/patterns/forms-and-input.md +819 -0
- package/expertise/design/patterns/gamification.md +801 -0
- package/expertise/design/patterns/index.md +31 -0
- package/expertise/design/patterns/microinteractions.md +449 -0
- package/expertise/design/patterns/navigation.md +800 -0
- package/expertise/design/patterns/notifications.md +705 -0
- package/expertise/design/patterns/onboarding.md +700 -0
- package/expertise/design/patterns/search-and-filter.md +601 -0
- package/expertise/design/patterns/settings-and-preferences.md +768 -0
- package/expertise/design/patterns/social-and-community.md +748 -0
- package/expertise/design/platforms/desktop-native.md +612 -0
- package/expertise/design/platforms/index.md +25 -0
- package/expertise/design/platforms/mobile-android.md +825 -0
- package/expertise/design/platforms/mobile-cross-platform.md +983 -0
- package/expertise/design/platforms/mobile-ios.md +699 -0
- package/expertise/design/platforms/tablet.md +794 -0
- package/expertise/design/platforms/web-dashboard.md +790 -0
- package/expertise/design/platforms/web-responsive.md +550 -0
- package/expertise/design/psychology/behavioral-nudges.md +449 -0
- package/expertise/design/psychology/cognitive-load.md +1191 -0
- package/expertise/design/psychology/error-psychology.md +778 -0
- package/expertise/design/psychology/index.md +22 -0
- package/expertise/design/psychology/persuasive-design.md +736 -0
- package/expertise/design/psychology/user-mental-models.md +623 -0
- package/expertise/design/tooling/open-pencil.md +266 -0
- package/expertise/frontend/angular.md +1073 -0
- package/expertise/frontend/desktop-electron.md +546 -0
- package/expertise/frontend/flutter.md +782 -0
- package/expertise/frontend/index.md +27 -0
- package/expertise/frontend/native-android.md +409 -0
- package/expertise/frontend/native-ios.md +490 -0
- package/expertise/frontend/react-native.md +1160 -0
- package/expertise/frontend/react.md +808 -0
- package/expertise/frontend/vue.md +1089 -0
- package/expertise/humanize/domain-rules-code.md +79 -0
- package/expertise/humanize/domain-rules-content.md +67 -0
- package/expertise/humanize/domain-rules-technical-docs.md +56 -0
- package/expertise/humanize/index.md +35 -0
- package/expertise/humanize/self-audit-checklist.md +87 -0
- package/expertise/humanize/sentence-patterns.md +218 -0
- package/expertise/humanize/vocabulary-blacklist.md +105 -0
- package/expertise/i18n/PROGRESS.md +65 -0
- package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
- package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
- package/expertise/i18n/advanced/complex-scripts.md +30 -0
- package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
- package/expertise/i18n/advanced/testing-i18n.md +28 -0
- package/expertise/i18n/content/content-adaptation.md +23 -0
- package/expertise/i18n/content/locale-specific-formatting.md +23 -0
- package/expertise/i18n/content/machine-translation-integration.md +28 -0
- package/expertise/i18n/content/translation-management.md +29 -0
- package/expertise/i18n/foundations/date-time-calendars.md +67 -0
- package/expertise/i18n/foundations/i18n-architecture.md +272 -0
- package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
- package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
- package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
- package/expertise/i18n/foundations/string-externalization.md +236 -0
- package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
- package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
- package/expertise/i18n/index.md +38 -0
- package/expertise/i18n/platform/backend-i18n.md +31 -0
- package/expertise/i18n/platform/flutter-i18n.md +148 -0
- package/expertise/i18n/platform/native-android-i18n.md +36 -0
- package/expertise/i18n/platform/native-ios-i18n.md +36 -0
- package/expertise/i18n/platform/react-i18n.md +103 -0
- package/expertise/i18n/platform/web-css-i18n.md +81 -0
- package/expertise/i18n/rtl/arabic-specific.md +175 -0
- package/expertise/i18n/rtl/hebrew-specific.md +149 -0
- package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
- package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
- package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
- package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
- package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
- package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
- package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
- package/expertise/i18n/rtl/rtl-typography.md +160 -0
- package/expertise/index.md +113 -0
- package/expertise/index.yaml +216 -0
- package/expertise/infrastructure/cloud-aws.md +597 -0
- package/expertise/infrastructure/cloud-gcp.md +599 -0
- package/expertise/infrastructure/cybersecurity.md +816 -0
- package/expertise/infrastructure/database-mongodb.md +447 -0
- package/expertise/infrastructure/database-postgres.md +400 -0
- package/expertise/infrastructure/devops-cicd.md +787 -0
- package/expertise/infrastructure/index.md +27 -0
- package/expertise/performance/PROGRESS.md +50 -0
- package/expertise/performance/backend/api-latency.md +1204 -0
- package/expertise/performance/backend/background-jobs.md +506 -0
- package/expertise/performance/backend/connection-pooling.md +1209 -0
- package/expertise/performance/backend/database-query-optimization.md +515 -0
- package/expertise/performance/backend/index.md +23 -0
- package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
- package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
- package/expertise/performance/foundations/caching-strategies.md +489 -0
- package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
- package/expertise/performance/foundations/index.md +24 -0
- package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
- package/expertise/performance/foundations/memory-management.md +964 -0
- package/expertise/performance/foundations/performance-budgets.md +1314 -0
- package/expertise/performance/index.md +31 -0
- package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
- package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
- package/expertise/performance/infrastructure/index.md +22 -0
- package/expertise/performance/infrastructure/load-balancing.md +1081 -0
- package/expertise/performance/infrastructure/observability.md +1079 -0
- package/expertise/performance/mobile/index.md +23 -0
- package/expertise/performance/mobile/mobile-animations.md +544 -0
- package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
- package/expertise/performance/mobile/mobile-network.md +452 -0
- package/expertise/performance/mobile/mobile-rendering.md +599 -0
- package/expertise/performance/mobile/mobile-startup-time.md +505 -0
- package/expertise/performance/platform-specific/flutter-performance.md +647 -0
- package/expertise/performance/platform-specific/index.md +22 -0
- package/expertise/performance/platform-specific/node-performance.md +1307 -0
- package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
- package/expertise/performance/platform-specific/react-performance.md +1403 -0
- package/expertise/performance/web/bundle-optimization.md +1239 -0
- package/expertise/performance/web/image-and-media.md +636 -0
- package/expertise/performance/web/index.md +24 -0
- package/expertise/performance/web/network-optimization.md +1133 -0
- package/expertise/performance/web/rendering-performance.md +1098 -0
- package/expertise/performance/web/ssr-and-hydration.md +918 -0
- package/expertise/performance/web/web-vitals.md +1374 -0
- package/expertise/quality/accessibility.md +985 -0
- package/expertise/quality/evidence-based-verification.md +499 -0
- package/expertise/quality/index.md +24 -0
- package/expertise/quality/ml-model-audit.md +614 -0
- package/expertise/quality/performance.md +600 -0
- package/expertise/quality/testing-api.md +891 -0
- package/expertise/quality/testing-mobile.md +496 -0
- package/expertise/quality/testing-web.md +849 -0
- package/expertise/security/PROGRESS.md +54 -0
- package/expertise/security/agentic-identity.md +540 -0
- package/expertise/security/compliance-frameworks.md +601 -0
- package/expertise/security/data/data-encryption.md +364 -0
- package/expertise/security/data/data-privacy-gdpr.md +692 -0
- package/expertise/security/data/database-security.md +1171 -0
- package/expertise/security/data/index.md +22 -0
- package/expertise/security/data/pii-handling.md +531 -0
- package/expertise/security/foundations/authentication.md +1041 -0
- package/expertise/security/foundations/authorization.md +603 -0
- package/expertise/security/foundations/cryptography.md +1001 -0
- package/expertise/security/foundations/index.md +25 -0
- package/expertise/security/foundations/owasp-top-10.md +1354 -0
- package/expertise/security/foundations/secrets-management.md +1217 -0
- package/expertise/security/foundations/secure-sdlc.md +700 -0
- package/expertise/security/foundations/supply-chain-security.md +698 -0
- package/expertise/security/index.md +31 -0
- package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
- package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
- package/expertise/security/infrastructure/container-security.md +721 -0
- package/expertise/security/infrastructure/incident-response.md +1295 -0
- package/expertise/security/infrastructure/index.md +24 -0
- package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
- package/expertise/security/infrastructure/network-security.md +1337 -0
- package/expertise/security/mobile/index.md +23 -0
- package/expertise/security/mobile/mobile-android-security.md +1218 -0
- package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
- package/expertise/security/mobile/mobile-data-storage.md +1265 -0
- package/expertise/security/mobile/mobile-ios-security.md +1401 -0
- package/expertise/security/mobile/mobile-network-security.md +1520 -0
- package/expertise/security/smart-contract-security.md +594 -0
- package/expertise/security/testing/index.md +22 -0
- package/expertise/security/testing/penetration-testing.md +1258 -0
- package/expertise/security/testing/security-code-review.md +1765 -0
- package/expertise/security/testing/threat-modeling.md +1074 -0
- package/expertise/security/testing/vulnerability-scanning.md +1062 -0
- package/expertise/security/web/api-security.md +586 -0
- package/expertise/security/web/cors-and-headers.md +433 -0
- package/expertise/security/web/csrf.md +562 -0
- package/expertise/security/web/file-upload.md +1477 -0
- package/expertise/security/web/index.md +25 -0
- package/expertise/security/web/injection.md +1375 -0
- package/expertise/security/web/session-management.md +1101 -0
- package/expertise/security/web/xss.md +1158 -0
- package/exports/README.md +17 -0
- package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
- package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
- package/exports/hosts/claude/.claude/agents/designer.md +55 -0
- package/exports/hosts/claude/.claude/agents/executor.md +55 -0
- package/exports/hosts/claude/.claude/agents/learner.md +51 -0
- package/exports/hosts/claude/.claude/agents/planner.md +53 -0
- package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
- package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
- package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
- package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
- package/exports/hosts/claude/.claude/commands/author.md +42 -0
- package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
- package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
- package/exports/hosts/claude/.claude/commands/design.md +44 -0
- package/exports/hosts/claude/.claude/commands/discover.md +37 -0
- package/exports/hosts/claude/.claude/commands/execute.md +48 -0
- package/exports/hosts/claude/.claude/commands/learn.md +38 -0
- package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
- package/exports/hosts/claude/.claude/commands/plan.md +39 -0
- package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
- package/exports/hosts/claude/.claude/commands/review.md +40 -0
- package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
- package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
- package/exports/hosts/claude/.claude/commands/specify.md +38 -0
- package/exports/hosts/claude/.claude/commands/verify.md +37 -0
- package/exports/hosts/claude/.claude/settings.json +34 -0
- package/exports/hosts/claude/CLAUDE.md +19 -0
- package/exports/hosts/claude/export.manifest.json +38 -0
- package/exports/hosts/claude/host-package.json +67 -0
- package/exports/hosts/codex/AGENTS.md +19 -0
- package/exports/hosts/codex/export.manifest.json +38 -0
- package/exports/hosts/codex/host-package.json +41 -0
- package/exports/hosts/cursor/.cursor/hooks.json +16 -0
- package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
- package/exports/hosts/cursor/export.manifest.json +38 -0
- package/exports/hosts/cursor/host-package.json +42 -0
- package/exports/hosts/gemini/GEMINI.md +19 -0
- package/exports/hosts/gemini/export.manifest.json +38 -0
- package/exports/hosts/gemini/host-package.json +41 -0
- package/hooks/README.md +18 -0
- package/hooks/definitions/loop_cap_guard.yaml +21 -0
- package/hooks/definitions/post_tool_capture.yaml +24 -0
- package/hooks/definitions/pre_compact_summary.yaml +19 -0
- package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
- package/hooks/definitions/protected_path_write_guard.yaml +19 -0
- package/hooks/definitions/session_start.yaml +19 -0
- package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
- package/hooks/loop-cap-guard +17 -0
- package/hooks/post-tool-lint +36 -0
- package/hooks/protected-path-write-guard +17 -0
- package/hooks/session-start +41 -0
- package/llms-full.txt +2355 -0
- package/llms.txt +43 -0
- package/package.json +79 -0
- package/roles/README.md +20 -0
- package/roles/clarifier.md +42 -0
- package/roles/content-author.md +63 -0
- package/roles/designer.md +55 -0
- package/roles/executor.md +55 -0
- package/roles/learner.md +51 -0
- package/roles/planner.md +53 -0
- package/roles/researcher.md +43 -0
- package/roles/reviewer.md +54 -0
- package/roles/specifier.md +47 -0
- package/roles/verifier.md +71 -0
- package/schemas/README.md +24 -0
- package/schemas/accepted-learning.schema.json +20 -0
- package/schemas/author-artifact.schema.json +156 -0
- package/schemas/clarification.schema.json +19 -0
- package/schemas/design-artifact.schema.json +80 -0
- package/schemas/docs-claim.schema.json +18 -0
- package/schemas/export-manifest.schema.json +20 -0
- package/schemas/hook.schema.json +67 -0
- package/schemas/host-export-package.schema.json +18 -0
- package/schemas/implementation-plan.schema.json +19 -0
- package/schemas/proposed-learning.schema.json +19 -0
- package/schemas/research.schema.json +18 -0
- package/schemas/review.schema.json +29 -0
- package/schemas/run-manifest.schema.json +18 -0
- package/schemas/spec-challenge.schema.json +18 -0
- package/schemas/spec.schema.json +20 -0
- package/schemas/usage.schema.json +102 -0
- package/schemas/verification-proof.schema.json +29 -0
- package/schemas/wazir-manifest.schema.json +173 -0
- package/skills/README.md +40 -0
- package/skills/brainstorming/SKILL.md +77 -0
- package/skills/debugging/SKILL.md +50 -0
- package/skills/design/SKILL.md +61 -0
- package/skills/dispatching-parallel-agents/SKILL.md +128 -0
- package/skills/executing-plans/SKILL.md +70 -0
- package/skills/finishing-a-development-branch/SKILL.md +169 -0
- package/skills/humanize/SKILL.md +123 -0
- package/skills/init-pipeline/SKILL.md +124 -0
- package/skills/prepare-next/SKILL.md +20 -0
- package/skills/receiving-code-review/SKILL.md +123 -0
- package/skills/requesting-code-review/SKILL.md +105 -0
- package/skills/requesting-code-review/code-reviewer.md +108 -0
- package/skills/run-audit/SKILL.md +197 -0
- package/skills/scan-project/SKILL.md +41 -0
- package/skills/self-audit/SKILL.md +153 -0
- package/skills/subagent-driven-development/SKILL.md +154 -0
- package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
- package/skills/subagent-driven-development/implementer-prompt.md +102 -0
- package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
- package/skills/tdd/SKILL.md +23 -0
- package/skills/using-git-worktrees/SKILL.md +163 -0
- package/skills/using-skills/SKILL.md +95 -0
- package/skills/verification/SKILL.md +22 -0
- package/skills/wazir/SKILL.md +463 -0
- package/skills/writing-plans/SKILL.md +30 -0
- package/skills/writing-skills/SKILL.md +157 -0
- package/skills/writing-skills/anthropic-best-practices.md +122 -0
- package/skills/writing-skills/persuasion-principles.md +50 -0
- package/templates/README.md +20 -0
- package/templates/artifacts/README.md +10 -0
- package/templates/artifacts/accepted-learning.md +19 -0
- package/templates/artifacts/accepted-learning.template.json +12 -0
- package/templates/artifacts/author.md +74 -0
- package/templates/artifacts/author.template.json +19 -0
- package/templates/artifacts/clarification.md +21 -0
- package/templates/artifacts/clarification.template.json +12 -0
- package/templates/artifacts/execute-notes.md +19 -0
- package/templates/artifacts/implementation-plan.md +21 -0
- package/templates/artifacts/implementation-plan.template.json +11 -0
- package/templates/artifacts/learning-proposal.md +19 -0
- package/templates/artifacts/next-run-handoff.md +21 -0
- package/templates/artifacts/plan-review.md +19 -0
- package/templates/artifacts/proposed-learning.template.json +12 -0
- package/templates/artifacts/research.md +21 -0
- package/templates/artifacts/research.template.json +12 -0
- package/templates/artifacts/review-findings.md +19 -0
- package/templates/artifacts/review.template.json +11 -0
- package/templates/artifacts/run-manifest.template.json +8 -0
- package/templates/artifacts/spec-challenge.md +19 -0
- package/templates/artifacts/spec-challenge.template.json +11 -0
- package/templates/artifacts/spec.md +21 -0
- package/templates/artifacts/spec.template.json +12 -0
- package/templates/artifacts/verification-proof.md +19 -0
- package/templates/artifacts/verification-proof.template.json +11 -0
- package/templates/examples/accepted-learning.example.json +14 -0
- package/templates/examples/author.example.json +152 -0
- package/templates/examples/clarification.example.json +15 -0
- package/templates/examples/docs-claim.example.json +8 -0
- package/templates/examples/export-manifest.example.json +7 -0
- package/templates/examples/host-export-package.example.json +11 -0
- package/templates/examples/implementation-plan.example.json +17 -0
- package/templates/examples/proposed-learning.example.json +13 -0
- package/templates/examples/research.example.json +15 -0
- package/templates/examples/research.example.md +6 -0
- package/templates/examples/review.example.json +17 -0
- package/templates/examples/run-manifest.example.json +9 -0
- package/templates/examples/spec-challenge.example.json +14 -0
- package/templates/examples/spec.example.json +21 -0
- package/templates/examples/verification-proof.example.json +21 -0
- package/templates/examples/wazir-manifest.example.yaml +65 -0
- package/templates/task-definition-schema.md +99 -0
- package/tooling/README.md +20 -0
- package/tooling/src/adapters/context-mode.js +50 -0
- package/tooling/src/capture/command.js +376 -0
- package/tooling/src/capture/store.js +99 -0
- package/tooling/src/capture/usage.js +270 -0
- package/tooling/src/checks/branches.js +50 -0
- package/tooling/src/checks/brand-truth.js +110 -0
- package/tooling/src/checks/changelog.js +231 -0
- package/tooling/src/checks/command-registry.js +36 -0
- package/tooling/src/checks/commits.js +102 -0
- package/tooling/src/checks/docs-drift.js +103 -0
- package/tooling/src/checks/docs-truth.js +201 -0
- package/tooling/src/checks/runtime-surface.js +156 -0
- package/tooling/src/cli.js +116 -0
- package/tooling/src/command-options.js +56 -0
- package/tooling/src/commands/validate.js +320 -0
- package/tooling/src/doctor/command.js +91 -0
- package/tooling/src/export/command.js +77 -0
- package/tooling/src/export/compiler.js +498 -0
- package/tooling/src/guards/loop-cap-guard.js +52 -0
- package/tooling/src/guards/protected-path-write-guard.js +67 -0
- package/tooling/src/index/command.js +152 -0
- package/tooling/src/index/storage.js +1061 -0
- package/tooling/src/index/summarizers.js +261 -0
- package/tooling/src/loaders.js +18 -0
- package/tooling/src/project-root.js +22 -0
- package/tooling/src/recall/command.js +225 -0
- package/tooling/src/schema-validator.js +30 -0
- package/tooling/src/state-root.js +40 -0
- package/tooling/src/status/command.js +71 -0
- package/wazir.manifest.yaml +135 -0
- package/workflows/README.md +19 -0
- package/workflows/author.md +42 -0
- package/workflows/clarify.md +38 -0
- package/workflows/design-review.md +46 -0
- package/workflows/design.md +44 -0
- package/workflows/discover.md +37 -0
- package/workflows/execute.md +48 -0
- package/workflows/learn.md +38 -0
- package/workflows/plan-review.md +42 -0
- package/workflows/plan.md +39 -0
- package/workflows/prepare-next.md +37 -0
- package/workflows/review.md +40 -0
- package/workflows/run-audit.md +41 -0
- package/workflows/spec-challenge.md +41 -0
- package/workflows/specify.md +38 -0
- 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/)*
|