ronce-racine 0.5.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 +90 -0
- package/LICENSE +21 -0
- package/README.md +281 -0
- package/agents/code-reviewer.md +33 -0
- package/agents/qa-tester.md +28 -0
- package/dist/hooks/README.md +182 -0
- package/dist/hooks/bash-npm-silent.mjs +81 -0
- package/dist/hooks/session-inject.mjs +53 -0
- package/dist/hooks/session-precompact.mjs +36 -0
- package/dist/hooks/session-writer.mjs +142 -0
- package/dist/hooks/skill-reminder.mjs +89 -0
- package/dist/hooks/truncate-bash-output.mjs +46 -0
- package/dist/hooks/truncate-output.mjs +88 -0
- package/dist/hooks/worktree-env-setup.mjs +123 -0
- package/dist/install.js +962 -0
- package/docs/adopting-a-repo.md +80 -0
- package/docs/architecture.md +76 -0
- package/docs/decisions.md +72 -0
- package/docs/developing.md +143 -0
- package/docs/evaluating-skills.md +41 -0
- package/docs/git-worktrees.md +62 -0
- package/docs/rules/clean-architecture-deps.md +66 -0
- package/docs/rules/commits.md +59 -0
- package/docs/rules/detection-gap-protocol.md +55 -0
- package/docs/rules/error-handling-discipline.md +62 -0
- package/docs/rules/minimal-code.md +58 -0
- package/docs/rules/no-raw-sql-interpolation.md +57 -0
- package/docs/rules/pre-commit-secret-detection.md +54 -0
- package/docs/rules/secure-logging.md +53 -0
- package/docs/rules/sql-migrations-discipline.md +58 -0
- package/docs/rules/subscription-cleanup.md +63 -0
- package/docs/rules/test-discipline.md +66 -0
- package/docs/rules/ui-states-complete.md +52 -0
- package/docs/templates/SKILL.template.md +66 -0
- package/docs/templates/rule.template.md +16 -0
- package/docs/writing-a-rule.md +43 -0
- package/docs/writing-a-skill.md +118 -0
- package/package.json +45 -0
- package/rules/clean-architecture-deps.md +20 -0
- package/rules/commits.md +16 -0
- package/rules/detection-gap-protocol.md +35 -0
- package/rules/error-handling-discipline.md +23 -0
- package/rules/minimal-code.md +32 -0
- package/rules/no-raw-sql-interpolation.md +20 -0
- package/rules/pre-commit-secret-detection.md +14 -0
- package/rules/secure-logging.md +16 -0
- package/rules/sql-migrations-discipline.md +18 -0
- package/rules/subscription-cleanup.md +22 -0
- package/rules/test-discipline.md +20 -0
- package/rules/ui-states-complete.md +23 -0
- package/scripts/subscription-leak-scan.ts +53 -0
- package/skills/adversarial-feature-challenge/README.md +65 -0
- package/skills/adversarial-feature-challenge/SKILL.md +96 -0
- package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
- package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
- package/skills/api-contract-versioning/README.md +62 -0
- package/skills/api-contract-versioning/SKILL.md +76 -0
- package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
- package/skills/audit-architecture/README.md +56 -0
- package/skills/audit-architecture/SKILL.md +97 -0
- package/skills/audit-architecture/reference/ar-architecture.md +275 -0
- package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
- package/skills/audit-architecture/reference/im-incidents.md +217 -0
- package/skills/audit-architecture/reference/pa-pannes.md +362 -0
- package/skills/audit-architecture/reference/re-recuperation.md +300 -0
- package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
- package/skills/audit-architecture/reference/su-support.md +180 -0
- package/skills/audit-ci-cd/README.md +54 -0
- package/skills/audit-ci-cd/SKILL.md +124 -0
- package/skills/audit-ci-cd/reference/artefacts.md +39 -0
- package/skills/audit-ci-cd/reference/deploiement.md +100 -0
- package/skills/audit-ci-cd/reference/dora.md +94 -0
- package/skills/audit-ci-cd/reference/iac.md +40 -0
- package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
- package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
- package/skills/audit-compliance/README.md +69 -0
- package/skills/audit-compliance/SKILL.md +176 -0
- package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
- package/skills/audit-compliance/reference/finops.md +318 -0
- package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
- package/skills/audit-industrialisation/README.md +53 -0
- package/skills/audit-industrialisation/SKILL.md +251 -0
- package/skills/audit-observability/README.md +64 -0
- package/skills/audit-observability/SKILL.md +134 -0
- package/skills/audit-observability/reference/alerting.md +214 -0
- package/skills/audit-observability/reference/logging.md +114 -0
- package/skills/audit-observability/reference/metriques.md +166 -0
- package/skills/audit-observability/reference/traces-dashboards.md +90 -0
- package/skills/audit-performance-frontend/README.md +91 -0
- package/skills/audit-performance-frontend/SKILL.md +194 -0
- package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
- package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
- package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
- package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
- package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
- package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
- package/skills/audit-quality/README.md +85 -0
- package/skills/audit-quality/SKILL.md +126 -0
- package/skills/audit-quality/reference/qa-devops.md +539 -0
- package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
- package/skills/audit-report/README.md +72 -0
- package/skills/audit-report/SKILL.md +241 -0
- package/skills/audit-report/reference/scoring-model.md +45 -0
- package/skills/audit-security/README.md +72 -0
- package/skills/audit-security/SKILL.md +140 -0
- package/skills/audit-security/reference/auth-identite.md +98 -0
- package/skills/audit-security/reference/autorisation.md +66 -0
- package/skills/audit-security/reference/chiffrement-tls.md +97 -0
- package/skills/audit-security/reference/detection-patching.md +67 -0
- package/skills/audit-security/reference/incident-response.md +98 -0
- package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
- package/skills/audit-security/reference/secrets.md +36 -0
- package/skills/audit-testing/README.md +82 -0
- package/skills/audit-testing/SKILL.md +131 -0
- package/skills/audit-testing/reference/golden-dataset.md +65 -0
- package/skills/audit-testing/reference/resilience-chaos.md +93 -0
- package/skills/audit-testing/reference/tests-contractuels.md +65 -0
- package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
- package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
- package/skills/bug-ticket-root-cause/README.md +67 -0
- package/skills/bug-ticket-root-cause/SKILL.md +86 -0
- package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
- package/skills/bug-triage-structured/README.md +63 -0
- package/skills/bug-triage-structured/SKILL.md +104 -0
- package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
- package/skills/ci-pipeline-orchestration/README.md +55 -0
- package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
- package/skills/commit-readiness-review/README.md +66 -0
- package/skills/commit-readiness-review/SKILL.md +82 -0
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
- package/skills/comprehensive-test-strategy/README.md +64 -0
- package/skills/comprehensive-test-strategy/SKILL.md +108 -0
- package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
- package/skills/daily-workflow-optimization/README.md +56 -0
- package/skills/daily-workflow-optimization/SKILL.md +80 -0
- package/skills/database-schema-evolution/README.md +54 -0
- package/skills/database-schema-evolution/SKILL.md +107 -0
- package/skills/ddd-backend-implementation/README.md +63 -0
- package/skills/ddd-backend-implementation/SKILL.md +95 -0
- package/skills/design-system-component-lifecycle/README.md +56 -0
- package/skills/design-system-component-lifecycle/SKILL.md +97 -0
- package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
- package/skills/detection-sweep/README.md +58 -0
- package/skills/detection-sweep/SKILL.md +93 -0
- package/skills/detection-sweep/scripts/sweep.ts +80 -0
- package/skills/domain-modeling-design/README.md +57 -0
- package/skills/domain-modeling-design/SKILL.md +83 -0
- package/skills/frontend-fullstack-implementation/README.md +60 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
- package/skills/frontend-spec-call-site-audit/README.md +66 -0
- package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
- package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
- package/skills/merge-request-review/README.md +60 -0
- package/skills/merge-request-review/SKILL.md +77 -0
- package/skills/merge-request-review/templates/mr-review-report.md +29 -0
- package/skills/production-incident-diagnostic/README.md +63 -0
- package/skills/production-incident-diagnostic/SKILL.md +103 -0
- package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
- package/skills/qa-session-intake/README.md +56 -0
- package/skills/qa-session-intake/SKILL.md +78 -0
- package/skills/recording-decisions/README.md +91 -0
- package/skills/recording-decisions/SKILL.md +84 -0
- package/skills/recurring-bug-root-cause/README.md +64 -0
- package/skills/recurring-bug-root-cause/SKILL.md +93 -0
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
- package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
- package/skills/refactoring-shared-component-api/README.md +50 -0
- package/skills/refactoring-shared-component-api/SKILL.md +84 -0
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
- package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
- package/skills/validating-features-end-to-end/README.md +50 -0
- package/skills/validating-features-end-to-end/SKILL.md +90 -0
- package/skills/visual-regression-check/README.md +51 -0
- package/skills/visual-regression-check/SKILL.md +89 -0
- package/skills/writing-robust-tests/README.md +53 -0
- package/skills/writing-robust-tests/SKILL.md +88 -0
- package/templates/.adopted.example +8 -0
- package/templates/anti-drift.gitlab-ci.yml +23 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Logging section - Logs, guidelines, baggage
|
|
2
|
+
|
|
3
|
+
3 questions. Correlated structured logs, logging guideline, contextual baggage.
|
|
4
|
+
|
|
5
|
+
## Table of contents
|
|
6
|
+
|
|
7
|
+
- [ob-01 - Correlated structured logs](#ob-01--correlated-structured-logs--criticality-must)
|
|
8
|
+
- [ob-02 - Logging guideline and message structure](#ob-02--logging-guideline-and-message-structure--criticality-should)
|
|
9
|
+
- [ob-03 - Analysis and implementation of useful baggage](#ob-03--analysis-and-implementation-of-useful-baggage--criticality-should)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
### ob-01 - Correlated structured logs · Criticality: **MUST**
|
|
14
|
+
|
|
15
|
+
**Analyze:** Logging config (Winston, Pino, Bunyan, structlog, slog), log format, traceId/spanId correlation, centralized aggregator
|
|
16
|
+
|
|
17
|
+
**Verification commands:**
|
|
18
|
+
```bash
|
|
19
|
+
# Count console.log/error/warn in the code
|
|
20
|
+
grep -r "console.log\|console.error\|console.warn" --include="*.ts" --include="*.vue" | grep -v node_modules | wc -l
|
|
21
|
+
# Check for the presence of logging frameworks
|
|
22
|
+
grep -ri "winston\|pino\|loglevel\|sentry\|structlog\|slog\|bunyan" package.json composer.json requirements.txt go.mod 2>/dev/null
|
|
23
|
+
# Look for traceId propagation
|
|
24
|
+
grep -ri "traceId\|trace_id\|traceparent\|correlationId\|x-request-id" --include="*.ts" --include="*.py" --include="*.go" --include="*.java" --include="*.php" 2>/dev/null | head -10
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**Check:**
|
|
28
|
+
- Structured logs (JSON, no `console.log` in prod)
|
|
29
|
+
- Standard fields: timestamp, level, service, traceId, spanId, message
|
|
30
|
+
- Correlation via traceId/correlationId across services
|
|
31
|
+
- Indexing in a centralized aggregator (ELK, Loki, Datadog)
|
|
32
|
+
- Automatic PII masking, documented retention policy
|
|
33
|
+
|
|
34
|
+
**Levels:**
|
|
35
|
+
| Level | Criteria |
|
|
36
|
+
|--------|----------|
|
|
37
|
+
| 0 | No logs or unstructured logs (free text). Impossible to parse or search automatically. |
|
|
38
|
+
| 1 | Partially structured logs. Format varies per service. No common standard and no traceId. |
|
|
39
|
+
| 2 | JSON logs with basic fields (timestamp, level, message). Missing traceId/spanId for cross-service correlation. |
|
|
40
|
+
| 3 | Structured logs with traceId/spanId (OpenTelemetry). Correlation possible across services. Indexing in an aggregator (ELK, Loki). |
|
|
41
|
+
| 4 | Logs enriched with business context, automatic alerting on error patterns, documented retention policy, automatic PII masking. |
|
|
42
|
+
|
|
43
|
+
**Client-side variant (SPA/PWA):**
|
|
44
|
+
| Level | Criteria |
|
|
45
|
+
|--------|----------|
|
|
46
|
+
| 0 | Raw `console.log` in production. No control. |
|
|
47
|
+
| 1 | Conditional logger (loglevel, disabled in prod). |
|
|
48
|
+
| 2 | Integrated error tracking (Sentry, Bugsnag). Automatic error capture. |
|
|
49
|
+
| 3 | Structured client logs. User/session context attached to errors. |
|
|
50
|
+
| 4 | Session replay (LogRocket, Sentry Replay). Correlation of errors/user actions. |
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
### ob-02 - Logging guideline and message structure · Criticality: **SHOULD**
|
|
55
|
+
|
|
56
|
+
**Analyze:** Documentation of logging conventions, message templates, automatic validation, severity levels
|
|
57
|
+
|
|
58
|
+
**Verification commands:**
|
|
59
|
+
```bash
|
|
60
|
+
# Look for a documented logging guideline
|
|
61
|
+
find . -name "*.md" -o -name "*.adoc" | xargs grep -li "log\|logging\|guideline" 2>/dev/null | head -5
|
|
62
|
+
# Check consistent use of log levels
|
|
63
|
+
grep -rn "\.error\|\.warn\|\.info\|\.debug\|Log::error\|Log::warning\|Log::info\|Log::debug" --include="*.ts" --include="*.php" --include="*.py" 2>/dev/null | head -10
|
|
64
|
+
# Look for ESLint/linter rules for logs
|
|
65
|
+
grep -ri "no-console\|log\|logging" .eslintrc* eslint.config* 2>/dev/null
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Check:**
|
|
69
|
+
- Documented guideline: when to log, at which level, which fields to include
|
|
70
|
+
- Standardized levels: ERROR (action required), WARN (attention), INFO (business events), DEBUG (development)
|
|
71
|
+
- Mandatory fields defined (ISO8601 timestamp, severity, service, action, traceId)
|
|
72
|
+
- Automatic validation in CI (log linting)
|
|
73
|
+
- Templates per use case (audit trail, technical debug, business events)
|
|
74
|
+
- Documented anti-patterns (no PII, no secrets, no logs inside loops)
|
|
75
|
+
|
|
76
|
+
**Levels:**
|
|
77
|
+
| Level | Criteria |
|
|
78
|
+
|--------|----------|
|
|
79
|
+
| 0 | No guideline. Each developer logs however they want. Inconsistent messages like "error occurred". |
|
|
80
|
+
| 1 | A few undocumented verbal conventions. Variable adoption across teams. |
|
|
81
|
+
| 2 | Guideline document exists but not always followed. No automatic validation. |
|
|
82
|
+
| 3 | Guidelines documented and reviewed in code review. Mandatory fields defined (severity, service, action). |
|
|
83
|
+
| 4 | Automatic log linting in CI. Standardized message templates. Examples per use case (audit, debug, business). |
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
### ob-03 - Analysis and implementation of useful baggage · Criticality: **SHOULD**
|
|
88
|
+
|
|
89
|
+
**Analyze:** Context propagation (MDC, AsyncLocalStorage, context.Context), OpenTelemetry baggage, automatic log/trace enrichment
|
|
90
|
+
|
|
91
|
+
**Verification commands:**
|
|
92
|
+
```bash
|
|
93
|
+
# Look for context propagation (MDC, AsyncLocalStorage, OTel Baggage)
|
|
94
|
+
grep -ri "AsyncLocalStorage\|MDC\|context\.Context\|opentelemetry.*baggage\|W3C.*Baggage\|traceparent" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
95
|
+
# Look for propagated business baggage
|
|
96
|
+
grep -ri "tenantId\|userId\|orderId\|batchId\|requestId" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**Check:**
|
|
100
|
+
- Essential baggage propagated: tenantId, userId, requestId, environment
|
|
101
|
+
- Business baggage defined per domain (orderId, batchId, connectorName, etc.)
|
|
102
|
+
- Automatic propagation via MDC/AsyncLocalStorage/context.Context
|
|
103
|
+
- W3C Baggage / OpenTelemetry Baggage standard used
|
|
104
|
+
- Dashboards segmented by baggage (per tenant, per connector)
|
|
105
|
+
- No sensitive data in the baggage (transmitted in clear text in headers)
|
|
106
|
+
|
|
107
|
+
**Levels:**
|
|
108
|
+
| Level | Criteria |
|
|
109
|
+
|--------|----------|
|
|
110
|
+
| 0 | No contextual baggage. Impossible to know which customer/connector is impacted without manual analysis. |
|
|
111
|
+
| 1 | Some business information logged manually, not systematic. Context lost between calls. |
|
|
112
|
+
| 2 | Basic baggage (userId, tenantId) propagated. No advanced business context (orderId, batchId). |
|
|
113
|
+
| 3 | Business baggage defined per domain and propagated automatically via context/MDC. Documentation of critical baggage. |
|
|
114
|
+
| 4 | Baggage enriched dynamically (feature flags, A/B test groups). Dashboards per baggage. Alerts segmented per customer. |
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Metrics section - RED/USE, latency, saturation, transient errors
|
|
2
|
+
|
|
3
|
+
4 questions. RED/USE metrics, latency drift tracking, pool saturation, abnormal transient-error detection.
|
|
4
|
+
|
|
5
|
+
## Table of contents
|
|
6
|
+
|
|
7
|
+
- [ob-04 - RED/USE metrics](#ob-04--reduse-metrics--criticality-should)
|
|
8
|
+
- [ob-07 - Latency drift tracking](#ob-07--latency-drift-tracking--criticality-should)
|
|
9
|
+
- [ob-08 - Pool saturation (thread, DB, API)](#ob-08--pool-saturation-thread-db-api--criticality-could)
|
|
10
|
+
- [ob-09 - Abnormal transient-error detection](#ob-09--abnormal-transient-error-detection--criticality-should)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
### ob-04 - RED/USE metrics · Criticality: **SHOULD**
|
|
15
|
+
|
|
16
|
+
**Analyze:** Prometheus instrumentation, OpenTelemetry metrics, StatsD, custom metrics, SLIs/SLOs
|
|
17
|
+
|
|
18
|
+
**Verification commands:**
|
|
19
|
+
```bash
|
|
20
|
+
# Check for the presence of metrics libraries
|
|
21
|
+
grep -ri "prometheus\|micrometer\|opentelemetry.*metrics\|statsd\|web-vitals\|@sentry/tracing" package.json composer.json requirements.txt go.mod 2>/dev/null
|
|
22
|
+
# Look for a /metrics endpoint
|
|
23
|
+
grep -ri "/metrics\|metrics_path\|PrometheusController" --include="*.ts" --include="*.yaml" --include="*.yml" --include="*.php" --include="*.go" 2>/dev/null | head -5
|
|
24
|
+
# Look for custom histograms or counters
|
|
25
|
+
grep -ri "histogram\|counter\|gauge\|summary\|observe\|increment" --include="*.ts" --include="*.go" --include="*.java" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Check:**
|
|
29
|
+
- RED metrics (Rate, Errors, Duration) for services
|
|
30
|
+
- USE metrics (Utilization, Saturation, Errors) for resources
|
|
31
|
+
- Percentiles measured (p50, p95, p99), not just the average
|
|
32
|
+
- Custom business metrics
|
|
33
|
+
- Metrics exposure (/metrics endpoint, OTLP)
|
|
34
|
+
- SLIs derived from RED/USE metrics
|
|
35
|
+
|
|
36
|
+
**Levels:**
|
|
37
|
+
| Level | Criteria |
|
|
38
|
+
|--------|----------|
|
|
39
|
+
| 0 | No application metrics. Only basic infra metrics (CPU, RAM) if available. |
|
|
40
|
+
| 1 | A few ad-hoc metrics (homemade counters). No RED/USE standard. Manual collection. |
|
|
41
|
+
| 2 | RED metrics (Rate, Errors, Duration) on main endpoints. No USE metrics on resources. |
|
|
42
|
+
| 3 | Complete RED metrics + USE on critical resources (DB pools, queues). Standard dashboards. Percentiles (p50, p95, p99). |
|
|
43
|
+
| 4 | SLIs derived from RED/USE metrics. Error budgets computed automatically. Business metrics (conversion, business throughput). |
|
|
44
|
+
|
|
45
|
+
**Client-side variant (SPA/PWA):**
|
|
46
|
+
| Level | Criteria |
|
|
47
|
+
|--------|----------|
|
|
48
|
+
| 0 | No performance metrics collected. |
|
|
49
|
+
| 1 | Basic Web Vitals (LCP, FID, CLS) measured manually. |
|
|
50
|
+
| 2 | Web Vitals + custom metrics collected (e.g. `web-vitals` lib). |
|
|
51
|
+
| 3 | Real User Monitoring (RUM) integrated. Metrics per page/component. |
|
|
52
|
+
| 4 | Performance budgets enforced in CI. Blocking regression if budget exceeded. |
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
### ob-07 - Latency drift tracking · Criticality: **SHOULD**
|
|
57
|
+
|
|
58
|
+
**Analyze:** Latency alerts, latency SLO, dynamic baseline, anomaly detection, deployment correlation
|
|
59
|
+
|
|
60
|
+
**Verification commands:**
|
|
61
|
+
```bash
|
|
62
|
+
# Look for references to performance and latency metrics
|
|
63
|
+
grep -ri "web-vitals\|lcp\|fid\|inp\|cls\|lighthouse\|latency\|p95\|p99\|percentile\|apdex" . --include="*.ts" --include="*.json" --include="*.yaml" --include="*.yml" 2>/dev/null | head -10
|
|
64
|
+
# Look for latency alerts
|
|
65
|
+
grep -ri "predict_linear\|latency.*alert\|duration.*threshold\|slo.*latency" --include="*.yaml" --include="*.yml" --include="*.rules" 2>/dev/null | head -5
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Check:**
|
|
69
|
+
- Latency measured in percentiles (p50, p95, p99)
|
|
70
|
+
- Dynamic baseline per endpoint
|
|
71
|
+
- Drift detection (baseline vs current, ±2 sigma)
|
|
72
|
+
- Predictive alerts (trend, not just threshold)
|
|
73
|
+
- Correlation latency ↔ deployments ↔ load
|
|
74
|
+
- Latency budget per feature/SLO
|
|
75
|
+
|
|
76
|
+
**Levels:**
|
|
77
|
+
| Level | Criteria |
|
|
78
|
+
|--------|----------|
|
|
79
|
+
| 0 | No latency tracking. Degradation detected only on user complaint. |
|
|
80
|
+
| 1 | Average latency monitored. No history or comparison. Poorly calibrated fixed thresholds. |
|
|
81
|
+
| 2 | Percentiles tracked (p95, p99). Alerts on fixed-threshold breach. No trend analysis. |
|
|
82
|
+
| 3 | Latency baseline per endpoint. Anomaly detection against history (±2 sigma). Predictive alerts. |
|
|
83
|
+
| 4 | ML for subtle drift detection. Automatic correlation latency↔deployments. Latency budget per feature. |
|
|
84
|
+
|
|
85
|
+
**Client-side variant (SPA/PWA):**
|
|
86
|
+
| Level | Criteria |
|
|
87
|
+
|--------|----------|
|
|
88
|
+
| 0 | No frontend performance measurement. |
|
|
89
|
+
| 1 | LCP/FID measured basically (in dev only). |
|
|
90
|
+
| 2 | LCP/INP/CLS measured in production via `web-vitals` or Sentry. |
|
|
91
|
+
| 3 | Performance budgets defined per page/route. CI checks the budgets. |
|
|
92
|
+
| 4 | Alerts on performance regression. Correlation with deployments. |
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
### ob-08 - Pool saturation (thread, DB, API) · Criticality: **COULD**
|
|
97
|
+
|
|
98
|
+
**Analyze:** Connection pool config (DB, Redis, HTTP), pool monitoring, thread pools, circuit breakers, PgBouncer
|
|
99
|
+
|
|
100
|
+
**Verification commands:**
|
|
101
|
+
```bash
|
|
102
|
+
# Look for pool configurations
|
|
103
|
+
grep -ri "pool_size\|max_connections\|maxPoolSize\|connectionLimit\|hikari\|pgbouncer\|connection.*pool" --include="*.ts" --include="*.yaml" --include="*.yml" --include="*.env*" --include="*.php" --include="*.java" --include="*.go" 2>/dev/null | head -10
|
|
104
|
+
# Look for exposed pool metrics
|
|
105
|
+
grep -ri "pool.*active\|pool.*idle\|pool.*wait\|pool.*size\|pool.*metric" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" 2>/dev/null | head -5
|
|
106
|
+
# Look for circuit breakers
|
|
107
|
+
grep -ri "circuit.*breaker\|resilience4j\|bulkhead\|rate.*limit" --include="*.ts" --include="*.java" --include="*.go" --include="*.yaml" 2>/dev/null | head -5
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**Check:**
|
|
111
|
+
- Pool saturation metrics exposed (active, idle, max, queue depth, wait time)
|
|
112
|
+
- Graduated alerts before saturation (warning 70%, critical 90%)
|
|
113
|
+
- Sizing documented and justified
|
|
114
|
+
- Circuit breakers tied to saturation (fail fast vs timeout)
|
|
115
|
+
- Auto-scaling if applicable (PgBouncer, ThreadPoolExecutor)
|
|
116
|
+
|
|
117
|
+
**Levels:**
|
|
118
|
+
| Level | Criteria |
|
|
119
|
+
|--------|----------|
|
|
120
|
+
| 0 | No visibility into pools. Saturation discovered only at crash time (connection refused). |
|
|
121
|
+
| 1 | Pool metrics exposed but not monitored. No saturation alert. |
|
|
122
|
+
| 2 | Alerts on >80% saturation of critical pools (DB connections, thread pools). No prediction. |
|
|
123
|
+
| 3 | Dedicated pool dashboards with history. Graduated alerts (warning 70%, critical 90%). Capacity planning. |
|
|
124
|
+
| 4 | Auto-scaling of pools based on prediction. Alerts before saturation (trend). Circuit breakers tied to saturation. |
|
|
125
|
+
|
|
126
|
+
**Client-side variant (SPA/PWA):**
|
|
127
|
+
| Level | Criteria |
|
|
128
|
+
|--------|----------|
|
|
129
|
+
| 0 | No client resource monitoring. |
|
|
130
|
+
| 1 | IndexedDB/localStorage quota monitoring (alert when space is low). |
|
|
131
|
+
| 2 | Bundle size tracking (bundle size tracked in CI). |
|
|
132
|
+
| 3 | Memory leak detection (heap monitoring in dev/staging). |
|
|
133
|
+
| 4 | Automated Lighthouse CI. Performance budgets on bundle/memory/assets. |
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
### ob-09 - Abnormal transient-error detection · Criticality: **SHOULD**
|
|
138
|
+
|
|
139
|
+
**Analyze:** Error classification (transient vs permanent), error-rate baseline, anomaly detection, retry policies
|
|
140
|
+
|
|
141
|
+
**Verification commands:**
|
|
142
|
+
```bash
|
|
143
|
+
# Look for transient-error handling and retries
|
|
144
|
+
grep -ri "retry\|transient\|circuit.*breaker\|backoff\|exponential" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
145
|
+
# Look for error categorization
|
|
146
|
+
grep -ri "isRetryable\|isTransient\|error.*class\|error.*type\|HttpStatus\.\(5\|SERVICE_UNAVAILABLE\|GATEWAY_TIMEOUT\)" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
147
|
+
# Look for error-rate alerts
|
|
148
|
+
grep -ri "error_rate\|error.*ratio\|5xx.*rate\|error.*budget" --include="*.yaml" --include="*.yml" --include="*.rules" 2>/dev/null | head -5
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**Check:**
|
|
152
|
+
- Error classification: transient (retry OK) vs permanent (action required)
|
|
153
|
+
- Error-rate baseline per endpoint
|
|
154
|
+
- Statistical analysis (z-score, standard deviation) vs static thresholds
|
|
155
|
+
- Correlation with deployments and infra changes
|
|
156
|
+
- ML anomaly detection (Isolation Forest, Prophet) if applicable
|
|
157
|
+
- Signal vs noise distinction to avoid alert fatigue
|
|
158
|
+
|
|
159
|
+
**Levels:**
|
|
160
|
+
| Level | Criteria |
|
|
161
|
+
|--------|----------|
|
|
162
|
+
| 0 | Transient errors ignored or drowned in the noise. No permanent/transient distinction. |
|
|
163
|
+
| 1 | Basic error counting. Fixed thresholds triggering too many false positives or missing real issues. |
|
|
164
|
+
| 2 | Error categorization (transient, permanent). Distinct alerts but manual thresholds. |
|
|
165
|
+
| 3 | Statistical analysis of error rates (standard deviation). Baseline per endpoint. Correlation with deployments. |
|
|
166
|
+
| 4 | ML anomaly detection on error patterns. Automatic root-cause classification. Auto-attached runbooks. |
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Traces & Dashboards section - Visualization and distributed tracing
|
|
2
|
+
|
|
3
|
+
2 questions. Real-time dashboards, distributed traces.
|
|
4
|
+
|
|
5
|
+
## Table of contents
|
|
6
|
+
|
|
7
|
+
- [ob-05 - Real-time dashboards](#ob-05--real-time-dashboards--criticality-should)
|
|
8
|
+
- [ob-06 - Distributed traces (OTel, Elastic APM)](#ob-06--distributed-traces-otel-elastic-apm--criticality-could)
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
### ob-05 - Real-time dashboards · Criticality: **SHOULD**
|
|
13
|
+
|
|
14
|
+
**Analyze:** Grafana files (JSON), dashboard configs, links to dashboards in the docs, hierarchical structure
|
|
15
|
+
|
|
16
|
+
**Verification commands:**
|
|
17
|
+
```bash
|
|
18
|
+
# Look for dashboard configuration files
|
|
19
|
+
find . -name "*.grafana.*" -o -name "*dashboard*" -o -name "*.json" -path "*/grafana/*" 2>/dev/null | head -5
|
|
20
|
+
# Look for references to dashboards in the documentation
|
|
21
|
+
grep -ri "grafana\|dashboard\|datadog\|kibana" --include="*.md" --include="*.yaml" --include="*.yml" 2>/dev/null | head -5
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
**Check:**
|
|
25
|
+
- Existing dashboards accessible to the team
|
|
26
|
+
- Hierarchical structure: overview → service → endpoint → instance
|
|
27
|
+
- Deployment and incident annotations
|
|
28
|
+
- Time comparisons (week-over-week)
|
|
29
|
+
- Real-time refresh (auto-refresh < 1min)
|
|
30
|
+
- Dashboards as code (versioned JSON/Terraform)
|
|
31
|
+
|
|
32
|
+
**Levels:**
|
|
33
|
+
| Level | Criteria |
|
|
34
|
+
|--------|----------|
|
|
35
|
+
| 0 | No dashboard or obsolete/unmaintained dashboard. Visibility only via manual logs. |
|
|
36
|
+
| 1 | Basic infra dashboard (default Grafana/CloudWatch). No application view. |
|
|
37
|
+
| 2 | Per-service dashboards with main metrics. No cross-cutting view or drill-down. |
|
|
38
|
+
| 3 | Hierarchical dashboards (overview → service → endpoint). Filters per environment/tenant. Incident annotations. |
|
|
39
|
+
| 4 | Real-time dashboards with auto-refresh <1min. Period comparison (week-over-week). Business dashboards integrated. TV screens. |
|
|
40
|
+
|
|
41
|
+
**Client-side variant (SPA/PWA):**
|
|
42
|
+
| Level | Criteria |
|
|
43
|
+
|--------|----------|
|
|
44
|
+
| 0 | No dashboard. |
|
|
45
|
+
| 1 | Sentry/error dashboard (error rate, most frequent errors). |
|
|
46
|
+
| 2 | Web Vitals dashboard (LCP, FID/INP, CLS per page). |
|
|
47
|
+
| 3 | Complete UX dashboard (errors + performance + usage per feature). |
|
|
48
|
+
| 4 | Correlation of errors/performance/deployments. Comparative before/after-release dashboards. |
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
### ob-06 - Distributed traces (OTel, Elastic APM) · Criticality: **COULD**
|
|
53
|
+
|
|
54
|
+
**Analyze:** OpenTelemetry config, Jaeger, Zipkin, Elastic APM, in-code instrumentation, sampling strategy
|
|
55
|
+
|
|
56
|
+
**Verification commands:**
|
|
57
|
+
```bash
|
|
58
|
+
# Check for the presence of tracing
|
|
59
|
+
grep -ri "opentelemetry\|@sentry/tracing\|elastic-apm\|jaeger\|zipkin\|@opentelemetry" package.json composer.json requirements.txt go.mod 2>/dev/null
|
|
60
|
+
# Look for tracing configuration
|
|
61
|
+
grep -ri "TracerProvider\|tracer\|OTEL_\|otel.*exporter\|apm.*agent" --include="*.ts" --include="*.yaml" --include="*.yml" --include="*.env*" --include="*.php" 2>/dev/null | head -10
|
|
62
|
+
# Look for custom spans
|
|
63
|
+
grep -ri "startSpan\|withSpan\|createSpan\|@Traced\|tracer\.start" --include="*.ts" --include="*.java" --include="*.go" --include="*.py" --include="*.php" 2>/dev/null | head -10
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**Check:**
|
|
67
|
+
- Tracing instrumentation (OpenTelemetry, Elastic APM)
|
|
68
|
+
- Context propagation across services (W3C Trace Context)
|
|
69
|
+
- Spans on critical operations (DB, HTTP, queues)
|
|
70
|
+
- Smart sampling (head-based, tail-based, adaptive)
|
|
71
|
+
- Trace visualization (Jaeger, Grafana Tempo)
|
|
72
|
+
- Correlation of traces/logs/metrics (exemplars)
|
|
73
|
+
|
|
74
|
+
**Levels:**
|
|
75
|
+
| Level | Criteria |
|
|
76
|
+
|--------|----------|
|
|
77
|
+
| 0 | No tracing. Debugging in production = manual log analysis service by service. |
|
|
78
|
+
| 1 | Partial tracing (1-2 services). Manual correlation via timestamps. Gaps in traces. |
|
|
79
|
+
| 2 | Tracing on main services with Jaeger/Zipkin. Context propagated but not always exploited. |
|
|
80
|
+
| 3 | OpenTelemetry deployed across all services. Complete traces with business spans. Smart sampling. |
|
|
81
|
+
| 4 | Traces correlated with logs and metrics (exemplars). Automatic analysis of slow traces. Topology maps generated. |
|
|
82
|
+
|
|
83
|
+
**Client-side variant (SPA/PWA):**
|
|
84
|
+
| Level | Criteria |
|
|
85
|
+
|--------|----------|
|
|
86
|
+
| 0 | No session or user-journey tracking. |
|
|
87
|
+
| 1 | Session ID tracking (session identifier propagated to the backend). |
|
|
88
|
+
| 2 | User journey tracking (navigation, clicks, errors correlated per session). |
|
|
89
|
+
| 3 | OpenTelemetry browser SDK. Frontend-to-backend traces correlated. |
|
|
90
|
+
| 4 | Full session replay with correlation of traces/errors/performance. |
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# `audit-performance-frontend`
|
|
2
|
+
|
|
3
|
+
> Score a project's low-level frontend performance maturity - DOM, CSS pipeline, JSC engine, memory/GC, network/cache, profiling - on a 0-4 scale, targeting sub-100ms rendering, with prioritized, evidence-backed recommendations.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand audit) |
|
|
8
|
+
| **Category** | `audit` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | Bash (grep, find, ls) - read-only static inspection; progressive-disclosure grids in [`reference/`](reference/) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`audit-performance-frontend` is one domain audit in a family of maturity audits. It takes a repository and produces a structured assessment of how well the frontend is built for speed at the level the browser actually cares about: DOM shape, the CSS rendering pipeline, JavaScriptCore (JSC/WebKit) engine behavior, memory and garbage collection, the network critical path, and profiling discipline.
|
|
15
|
+
|
|
16
|
+
The domain is broken into **29 questions** (`PF-01` … `PF-29`) across 6 categories. Each question carries a criticality (`MUST` / `SHOULD` / `COULD`), a set of bash commands that gather objective evidence, an explicit checklist, and a 0-4 level rubric. The skill runs the commands, reads the relevant source, scores each question with a confidence level, and emits a report with an overall (optionally weighted) score.
|
|
17
|
+
|
|
18
|
+
It is deliberately micro-optimization oriented - aimed at embedded or real-time WebKit contexts (WKWebView, Electron) and any project chasing a sub-100ms render - rather than at generic Lighthouse-score advice.
|
|
19
|
+
|
|
20
|
+
## Why it exists
|
|
21
|
+
|
|
22
|
+
Frontend performance is usually audited from the outside (a Lighthouse number) and rarely from the inside (why the number is what it is). This skill inspects the mechanisms that produce the number:
|
|
23
|
+
|
|
24
|
+
- **Objective first** - every question starts from commands (`grep` for `document.write`, layout-thrashing reads, `delete` on hot paths, `will-change` in static CSS, missing `defer`/`async`, uncleaned listeners), so a score is anchored to what is actually in the repo.
|
|
25
|
+
- **Engine-aware** - the JSC category (`PF-10` … `PF-18`) scores the things that make or break the JIT: monomorphic shapes, NaN-boxing, compilation tiers, deopt/bailouts, closure allocation, array indexing types, the event loop. These rarely show up in a black-box audit.
|
|
26
|
+
- **Honest about confidence** - much of real performance (JIT profiling, actual GC pauses, real-world VRAM, runtime metrics) cannot be settled by static analysis. The skill marks those `low` confidence and lists them as non-auditable rather than inventing a number.
|
|
27
|
+
- **Prioritized** - criticality weighting means a render-blocking critical path (`MUST`) outranks unscoped custom properties (`COULD`) in the recommendations.
|
|
28
|
+
|
|
29
|
+
## When it triggers
|
|
30
|
+
|
|
31
|
+
Invoke it for a **domain-scoped** frontend performance audit. Trigger phrases: "audit performance", "audit frontend", "audit perf", "audit rendering", "audit webkit", "audit jsc".
|
|
32
|
+
|
|
33
|
+
For a **full multi-domain** project audit, use [`audit-industrialisation`](../audit-industrialisation/) instead - it orchestrates every domain audit (this one included) and consolidates the results. Do not invoke each domain skill by hand for a global audit.
|
|
34
|
+
|
|
35
|
+
## How it works
|
|
36
|
+
|
|
37
|
+
The approach, at a glance - the supplementary tables below (grids per category, confidence tags) are the parts worth keeping close; the full step-by-step protocol lives in [`SKILL.md`](SKILL.md).
|
|
38
|
+
|
|
39
|
+
### 1. Detect the project type
|
|
40
|
+
|
|
41
|
+
Identify whether the project is a SPA, SSR app, PWA, embedded WebKit app, or component library. The type selects a variant that marks whole categories N/A - e.g. a static site with no custom JS makes `PF-10` … `PF-18` N/A; a component library makes the network category `PF-23` … `PF-26` N/A.
|
|
42
|
+
|
|
43
|
+
### 2. Gather evidence per question
|
|
44
|
+
|
|
45
|
+
For each of `PF-01` … `PF-29`, run the verification commands from the matching reference grid and read the relevant CSS/JS/HTML and build config.
|
|
46
|
+
|
|
47
|
+
| Category | Reference | Questions |
|
|
48
|
+
|----------|-----------|-----------|
|
|
49
|
+
| HTML & Critical Path | [`reference/html-critical-path.md`](reference/html-critical-path.md) | PF-01 … PF-04 |
|
|
50
|
+
| CSS & Rendering Pipeline | [`reference/css-rendering-pipeline.md`](reference/css-rendering-pipeline.md) | PF-05 … PF-09 |
|
|
51
|
+
| JavaScript Engine & Runtime JSC | [`reference/js-engine-runtime.md`](reference/js-engine-runtime.md) | PF-10 … PF-18 |
|
|
52
|
+
| Memory & Garbage Collection | [`reference/memory-gc.md`](reference/memory-gc.md) | PF-19 … PF-22 |
|
|
53
|
+
| Assets, Cache & Network | [`reference/assets-cache-network.md`](reference/assets-cache-network.md) | PF-23 … PF-26 |
|
|
54
|
+
| Profiling & Tooling | [`reference/profiling-tooling.md`](reference/profiling-tooling.md) | PF-27 … PF-29 |
|
|
55
|
+
|
|
56
|
+
### 3. Score each question
|
|
57
|
+
|
|
58
|
+
Assign a level 0-4 from the rubric, with a confidence tag:
|
|
59
|
+
|
|
60
|
+
- **high** - verified by a command or direct file reading
|
|
61
|
+
- **medium** - inferred from structure/config, not deeply verified
|
|
62
|
+
- **low** - needs runtime measurement or profiling (JIT tiers, GC pauses, VRAM, Core Web Vitals under load)
|
|
63
|
+
|
|
64
|
+
Mark a question **N/A** when the project profile makes it irrelevant (see the variant in step 1).
|
|
65
|
+
|
|
66
|
+
### 4. Compute the domain score
|
|
67
|
+
|
|
68
|
+
- Simple domain score = average of scored questions (N/A excluded), reported as "X scored out of 29".
|
|
69
|
+
- Weighted score = `sum(level × weight) / sum(weight)` where `MUST`=3, `SHOULD`=2, `COULD`=1 (the per-question weight assignments are in [`SKILL.md`](SKILL.md)).
|
|
70
|
+
|
|
71
|
+
### 5. Emit the report
|
|
72
|
+
|
|
73
|
+
The standard output (see [`SKILL.md`](SKILL.md)) includes a summary with the detected project type, a per-question table (code / question / criticality / level / confidence / justification), strengths, weaknesses, recommendations tagged `[MUST]`/`[SHOULD]`/`[COULD]`, and an explicit list of non-auditable items.
|
|
74
|
+
|
|
75
|
+
## Worked example
|
|
76
|
+
|
|
77
|
+
> Auditing `acme-app`, a Vue SPA rendered inside a WKWebView, chasing a sub-100ms first paint.
|
|
78
|
+
|
|
79
|
+
1. **Detect** - embedded WebKit application → every category applies, with extra focus on the JSC and memory categories (`PF-10` … `PF-22`).
|
|
80
|
+
2. **PF-02** - `grep` finds three `<script>` tags in `index.html` without `defer`/`async`. Render-blocking, no critical-CSS inlining. Level **0**, confidence **high**. Because `PF-02` is a `MUST`, this drives a top recommendation.
|
|
81
|
+
3. **PF-10** - hot-path objects are built with `Object.assign` and a couple of `delete` calls, breaking JSC Structure stability. Level **1**, confidence **medium** (shape stability inferred statically, not JIT-profiled).
|
|
82
|
+
4. **PF-21** - several `addEventListener` on `window` with no matching `removeEventListener` in the component teardown → likely detached-DOM leaks. Level **1**, confidence **medium**.
|
|
83
|
+
5. **PF-19/PF-27/PF-28** - real GC pauses and Core Web Vitals under load can't be derived from the repo. Levels tentative, confidence **low**, listed under non-auditable items ("requires runtime profiling and RUM").
|
|
84
|
+
6. **Report** - weighted overall score, with `[MUST] Add defer/async and inline critical CSS to unblock acme-app's first paint` first in the recommendations.
|
|
85
|
+
|
|
86
|
+
## Related artifacts
|
|
87
|
+
|
|
88
|
+
- [`audit-industrialisation`](../audit-industrialisation/) - orchestrator that runs all domain audits and consolidates them; use it for a full audit.
|
|
89
|
+
- [`audit-report`](../audit-report/) - template and scoring rules for the consolidated report.
|
|
90
|
+
- [`audit-observability`](../audit-observability/) - logging, metrics, tracing, and alerting; complements the runtime performance metrics this skill can only measure statically.
|
|
91
|
+
- [`audit-quality`](../audit-quality/) - QA/DevOps and code quality; overlaps on performance CI and regression gating (`PF-29`).
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: audit-performance-frontend
|
|
3
|
+
description: Low-level frontend performance audit, specialized for WebKit/JSC and embedded or real-time contexts - on a mainstream stack (React/Chrome SPA) many questions are N/A and the grid adapts. Use when auditing frontend rendering performance, WebKit internals, JSC optimization, DOM structure, CSS rendering pipeline, memory/GC, cache strategy, or profiling methodology. Triggers on "audit performance", "audit frontend", "audit perf", "audit rendering", "audit webkit", "audit jsc".
|
|
4
|
+
version: 1.0.2
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-07-20
|
|
7
|
+
category: audit
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## When ME and not audit-industrialisation
|
|
11
|
+
|
|
12
|
+
- **ME** when: an audit scoped to this domain only
|
|
13
|
+
- **audit-industrialisation** instead if: a cross-domain global audit - it orchestrates every audit (including ME) and produces a consolidated report
|
|
14
|
+
|
|
15
|
+
> For a full project audit, use `audit-industrialisation` rather than invoking each skill separately.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# Low-Level Frontend Performance Audit
|
|
20
|
+
|
|
21
|
+
> **Scope check before starting**: this grid targets WebKit/JSC internals and
|
|
22
|
+
> embedded/real-time constraints. On a mainstream stack (e.g. a React SPA on
|
|
23
|
+
> evergreen browsers), mark the engine-specific questions N/A per the Variants
|
|
24
|
+
> section instead of forcing answers - a mostly-N/A domain is a valid outcome.
|
|
25
|
+
|
|
26
|
+
## Overview
|
|
27
|
+
|
|
28
|
+
Audit a project's frontend performance maturity, targeting sub-100ms rendering. Covers the integrity of the rendering pipeline: DOM structure, CSS rendering, JS engine internals (JSC), memory and GC management, network/cache strategy, and profiling tooling. Micro-optimization oriented, for embedded or real-time contexts running on WebKit.
|
|
29
|
+
|
|
30
|
+
**29 questions** split across **6 categories**:
|
|
31
|
+
|
|
32
|
+
| Category | Questions | Grid |
|
|
33
|
+
|-------|-----------|--------|
|
|
34
|
+
| 1 - HTML & Critical Path | 4 (PF-01 to PF-04) | [reference/html-critical-path.md](reference/html-critical-path.md) |
|
|
35
|
+
| 2 - CSS & Rendering Pipeline | 5 (PF-05 to PF-09) | [reference/css-rendering-pipeline.md](reference/css-rendering-pipeline.md) |
|
|
36
|
+
| 3 - JavaScript Engine & Runtime JSC | 9 (PF-10 to PF-18) | [reference/js-engine-runtime.md](reference/js-engine-runtime.md) |
|
|
37
|
+
| 4 - Memory & Garbage Collection | 4 (PF-19 to PF-22) | [reference/memory-gc.md](reference/memory-gc.md) |
|
|
38
|
+
| 5 - Assets, Cache & Network | 4 (PF-23 to PF-26) | [reference/assets-cache-network.md](reference/assets-cache-network.md) |
|
|
39
|
+
| 6 - Profiling & Tooling | 3 (PF-27 to PF-29) | [reference/profiling-tooling.md](reference/profiling-tooling.md) |
|
|
40
|
+
|
|
41
|
+
## Scoring
|
|
42
|
+
|
|
43
|
+
- Each scored question gets a level from 0 to 4.
|
|
44
|
+
- Questions marked **N/A** are excluded from the calculation.
|
|
45
|
+
- **Domain score** = sum of levels / number of scored questions (excluding N/A).
|
|
46
|
+
- Criticality (used to prioritize remediation, NOT in the score - see `audit-report/reference/scoring-model.md`):
|
|
47
|
+
- **MUST**: PF-01, PF-02, PF-03, PF-06, PF-10, PF-13, PF-17, PF-23, PF-27, PF-28, PF-29
|
|
48
|
+
- **SHOULD**: PF-04, PF-05, PF-07, PF-09, PF-11, PF-12, PF-14, PF-15, PF-19, PF-20, PF-21, PF-22, PF-24, PF-25, PF-26
|
|
49
|
+
- **COULD**: PF-08, PF-16, PF-18
|
|
50
|
+
|
|
51
|
+
## Audit protocol
|
|
52
|
+
|
|
53
|
+
1. **Detect the project type**: SPA, SSR, PWA, embedded WebKit, component library.
|
|
54
|
+
2. **Category 1 - HTML**: scan for `document.write`, measure DOM depth, check blocking scripts and priority attributes.
|
|
55
|
+
3. **Category 2 - CSS**: audit selectors, animations, compositing, custom properties, fonts.
|
|
56
|
+
4. **Category 3 - JS Engine**: look for polymorphism patterns, `delete`, arrow functions in loops, `eval`, sparse arrays.
|
|
57
|
+
5. **Category 4 - Memory**: check allocations in loops, event listeners without cleanup, caches without eviction.
|
|
58
|
+
6. **Category 5 - Assets**: measure critical-path size, check compression, cache headers, font loading.
|
|
59
|
+
7. **Category 6 - Profiling**: check instrumentation, metrics, performance CI.
|
|
60
|
+
8. **Run the verification commands** for each question (see grids).
|
|
61
|
+
9. **Assign a level** (0-4) per question with justification and confidence level.
|
|
62
|
+
10. **Mark N/A** the non-applicable questions (e.g. PF-10 to PF-18 if there is no custom JS, just a framework).
|
|
63
|
+
11. **Produce the report** (output format below).
|
|
64
|
+
|
|
65
|
+
### Variants by project type
|
|
66
|
+
|
|
67
|
+
**SSR application (Nuxt, Next.js)**
|
|
68
|
+
- **PF-01 to PF-04**: Fully applicable, the server generates the initial HTML
|
|
69
|
+
- **PF-23**: Adapted - TTFB includes server render time
|
|
70
|
+
|
|
71
|
+
**UI component library**
|
|
72
|
+
- **PF-23 to PF-26**: N/A (no control over deployment)
|
|
73
|
+
- **PF-27 to PF-29**: Adapted - component performance benchmarks
|
|
74
|
+
|
|
75
|
+
**Static site (11ty, Hugo, Astro)**
|
|
76
|
+
- **PF-10 to PF-18**: Often N/A (little custom JS)
|
|
77
|
+
- **PF-01 to PF-09, PF-23 to PF-29**: Fully applicable
|
|
78
|
+
|
|
79
|
+
**Embedded WebKit application (WKWebView, Electron)**
|
|
80
|
+
- Every question applies with the standard grid
|
|
81
|
+
- Particular focus on PF-10 to PF-22 (memory/CPU constraints)
|
|
82
|
+
|
|
83
|
+
## Grids by category
|
|
84
|
+
|
|
85
|
+
Each grid contains, per question: statement, criticality, elements to analyze, bash verification commands, points to check, and a 0-4 level table.
|
|
86
|
+
|
|
87
|
+
- [reference/html-critical-path.md](reference/html-critical-path.md) - **Category 1, HTML & Critical Path**, 4 questions (PF-01 to PF-04)
|
|
88
|
+
- [reference/css-rendering-pipeline.md](reference/css-rendering-pipeline.md) - **Category 2, CSS & Rendering Pipeline**, 5 questions (PF-05 to PF-09)
|
|
89
|
+
- [reference/js-engine-runtime.md](reference/js-engine-runtime.md) - **Category 3, JavaScript Engine & Runtime JSC**, 9 questions (PF-10 to PF-18)
|
|
90
|
+
- [reference/memory-gc.md](reference/memory-gc.md) - **Category 4, Memory & Garbage Collection**, 4 questions (PF-19 to PF-22)
|
|
91
|
+
- [reference/assets-cache-network.md](reference/assets-cache-network.md) - **Category 5, Assets, Cache & Network**, 4 questions (PF-23 to PF-26)
|
|
92
|
+
- [reference/profiling-tooling.md](reference/profiling-tooling.md) - **Category 6, Profiling & Tooling**, 3 questions (PF-27 to PF-29)
|
|
93
|
+
|
|
94
|
+
## Output format
|
|
95
|
+
|
|
96
|
+
```markdown
|
|
97
|
+
## Frontend Performance - Global score: X.X/4 (Y questions scored out of 29)
|
|
98
|
+
|
|
99
|
+
### Summary
|
|
100
|
+
[2-3 sentences summarizing frontend performance maturity]
|
|
101
|
+
[Detected project type: SPA / SSR / PWA / embedded / static]
|
|
102
|
+
|
|
103
|
+
### Detail by question
|
|
104
|
+
|
|
105
|
+
#### Category 1 - HTML & Critical Path
|
|
106
|
+
|
|
107
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
108
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
109
|
+
| PF-01 | DOM structure and parsing | MUST | X | high/medium/low | ... |
|
|
110
|
+
| PF-02 | Render-blocking | MUST | X | high/medium/low | ... |
|
|
111
|
+
| PF-03 | Layout thrashing | MUST | X | high/medium/low | ... |
|
|
112
|
+
| PF-04 | Loading & priority | SHOULD | X | high/medium/low | ... |
|
|
113
|
+
|
|
114
|
+
#### Category 2 - CSS & Rendering Pipeline
|
|
115
|
+
|
|
116
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
117
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
118
|
+
| PF-05 | CSS selectors | SHOULD | X | high/medium/low | ... |
|
|
119
|
+
| PF-06 | Layout triggers | MUST | X | high/medium/low | ... |
|
|
120
|
+
| PF-07 | Paint & GPU | SHOULD | X | high/medium/low | ... |
|
|
121
|
+
| PF-08 | Custom properties | COULD | X | high/medium/low | ... |
|
|
122
|
+
| PF-09 | Font rendering | SHOULD | X | high/medium/low | ... |
|
|
123
|
+
|
|
124
|
+
#### Category 3 - JavaScript Engine & Runtime
|
|
125
|
+
|
|
126
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
127
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
128
|
+
| PF-10 | JSC monomorphism | MUST | X | high/medium/low | ... |
|
|
129
|
+
| PF-11 | NaN-boxing | SHOULD | X | high/medium/low | ... |
|
|
130
|
+
| PF-12 | JSC compilation tiers | SHOULD | X | high/medium/low | ... |
|
|
131
|
+
| PF-13 | Deoptimization | MUST | X | high/medium/low | ... |
|
|
132
|
+
| PF-14 | Functions & closures | SHOULD | X | high/medium/low | ... |
|
|
133
|
+
| PF-15 | JSC arrays | SHOULD | X | high/medium/low | ... |
|
|
134
|
+
| PF-16 | Strings & RegExp | COULD | X | high/medium/low | ... |
|
|
135
|
+
| PF-17 | Event loop | MUST | X | high/medium/low | ... |
|
|
136
|
+
| PF-18 | Weak references | COULD | X | high/medium/low | ... |
|
|
137
|
+
|
|
138
|
+
#### Category 4 - Memory & GC
|
|
139
|
+
|
|
140
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
141
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
142
|
+
| PF-19 | GC Riptide | SHOULD | X | high/medium/low | ... |
|
|
143
|
+
| PF-20 | Allocation pressure | SHOULD | X | high/medium/low | ... |
|
|
144
|
+
| PF-21 | Memory leaks | SHOULD | X | high/medium/low | ... |
|
|
145
|
+
| PF-22 | GPU memory | SHOULD | X | high/medium/low | ... |
|
|
146
|
+
|
|
147
|
+
#### Category 5 - Assets, Cache & Network
|
|
148
|
+
|
|
149
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
150
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
151
|
+
| PF-23 | Network critical path | MUST | X | high/medium/low | ... |
|
|
152
|
+
| PF-24 | Compression & encoding | SHOULD | X | high/medium/low | ... |
|
|
153
|
+
| PF-25 | Multi-layer cache | SHOULD | X | high/medium/low | ... |
|
|
154
|
+
| PF-26 | Font loading | SHOULD | X | high/medium/low | ... |
|
|
155
|
+
|
|
156
|
+
#### Category 6 - Profiling & Tooling
|
|
157
|
+
|
|
158
|
+
| Code | Question | Criticality | Level | Confidence | Justification |
|
|
159
|
+
|------|----------|-----------|--------|-----------|---------------|
|
|
160
|
+
| PF-27 | Methodical profiling | MUST | X | high/medium/low | ... |
|
|
161
|
+
| PF-28 | Sub-100ms metrics | MUST | X | high/medium/low | ... |
|
|
162
|
+
| PF-29 | Performance regression CI | MUST | X | high/medium/low | ... |
|
|
163
|
+
|
|
164
|
+
### Strengths
|
|
165
|
+
- ...
|
|
166
|
+
|
|
167
|
+
### Weaknesses
|
|
168
|
+
- ...
|
|
169
|
+
|
|
170
|
+
### Recommendations
|
|
171
|
+
1. [MUST] ...
|
|
172
|
+
2. [SHOULD] ...
|
|
173
|
+
3. [COULD] ...
|
|
174
|
+
|
|
175
|
+
### Non-auditable items
|
|
176
|
+
- [List the items impossible to verify by static analysis: runtime metrics, JIT profiling, real GC pauses, real-world VRAM, etc.]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Exit condition
|
|
180
|
+
|
|
181
|
+
- [ ] Project type detected and matching variant applied
|
|
182
|
+
- [ ] All 29 questions reviewed (scored 0-4 or marked N/A with justification)
|
|
183
|
+
- [ ] Verification commands run for each scored question
|
|
184
|
+
- [ ] Confidence level assigned per question
|
|
185
|
+
- [ ] Global score computed (excluding N/A)
|
|
186
|
+
- [ ] Report produced in the output format, with strengths/weaknesses, prioritized recommendations, and non-auditable items
|
|
187
|
+
|
|
188
|
+
## Changelog
|
|
189
|
+
|
|
190
|
+
- 1.0.2 (2026-07-20) - scope made explicit (WebKit/JSC specialization; mainstream stacks expect many N/A)
|
|
191
|
+
|
|
192
|
+
- 1.0.1 (2026-07-20) - scoring aligned with scoring-model.md: flat mean only; criticality kept for remediation priority, weights removed from the score
|
|
193
|
+
|
|
194
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition); audit grids in reference/ (progressive disclosure)
|