chore(skills): consolidate updates across k6 skill packs

Author: charlyautomatiza

skills/k6-config/SKILL.md

@@ -21,11 +21,27 @@ At the beginning of the workflow, detect and use interaction tools in this order
 4. Else emit the exact fallback and end the turn:
 
 ```md
-> [?] MISSING REQUIREMENT: [Missing required configuration detail]
+> [?] MISSING REQUIREMENT: Missing required configuration detail
+required: environment set, load profile inputs, and SLA target
+why: deterministic multi-environment config cannot be generated safely
+next_question: Which environments should be generated (dev/staging/prod) and what SLA should apply?
 ```
 
 Do not continue generation after fallback.
 
+## Interoperability Fallback Contract
+
+When fallback is required, always use this portable payload shape:
+
+```md
+> [?] MISSING REQUIREMENT: <short missing requirement summary>
+required: <comma-separated missing fields>
+why: <why generation cannot continue deterministically>
+next_question: <single question that unblocks next step>
+```
+
+Do not emit final configuration output after this fallback.
+
 ## Language Policy
 
 1. If user language is explicit, answer in that language.
@@ -42,6 +58,12 @@ Always enforce these validations before returning configuration output:
 2. **Load profile is required**
    - Every generated environment config must include explicit `vus` and `duration`.
    - If missing, derive defaults per environment and state derivation logic.
+3. **Parameter coherence is required**
+   - If arrival-rate style parameters are included, enforce `preAllocatedVUs <= maxVUs`.
+   - If `stages` are used, ensure stage durations are explicit and non-empty.
+4. **Secrets and runnable safety are required**
+   - Never hard-code credentials or tokens in runnable examples.
+   - Require environment-variable placeholders (`__ENV` or `.env.example`) for secrets.
 
 ## Configuration Patterns
 
@@ -73,6 +95,25 @@ Generate separate configs for dev/staging/prod with environment-specific:
 - `k6-config` applies environment-level policy (dev/staging/prod) and operational defaults.
 - If both are used, `k6-config` must preserve executor recommendation intent while enforcing environment safety defaults.
 
+Dashboard precedence order shared with `k6-executor`:
+
+1. CI/non-interactive contexts default to `K6_WEB_DASHBOARD=false` unless user explicitly opts in.
+2. Local interactive browser troubleshooting defaults to `K6_WEB_DASHBOARD=true`.
+3. Local non-browser runs default to `K6_WEB_DASHBOARD=false` unless user explicitly opts in.
+4. All other contexts default to `K6_WEB_DASHBOARD=false`.
+
+## Output Contract
+
+Every response must include these sections in order:
+
+1. Environment Matrix
+2. Configuration Snippets (by environment)
+3. Thresholds (provided or derived)
+4. Load Profile (explicit `vus`/`duration` or staged equivalent)
+5. Guardrail Validation
+6. Web Dashboard Policy
+7. Assumptions and Next Step
+
 ## Progressive Disclosure
 
 Keep this file focused on execution workflow. Place deep guidance in:
@@ -85,6 +126,7 @@ Keep this file focused on execution workflow. Place deep guidance in:
 2. Run Tool Discovery Protocol if critical input is missing.
 3. Validate or derive thresholds for each environment.
 4. Validate or derive `vus` and `duration` for each environment.
-5. Determine per-environment dashboard policy (`enable` only when explicitly requested for local analysis, or when the scenario requires browser UX troubleshooting differential analysis), aligned with `k6-executor` gate semantics.
+5. Determine per-environment dashboard policy using shared precedence with `k6-executor` (CI/headless first, local-browser second, default false otherwise).
 6. Generate deterministic config output and `.env.example` guidance, explicitly warning that real env files and generated reports must remain uncommitted.
-7. Include a short summary of derived assumptions.
+7. Validate guardrails and return output using the Output Contract section order.
+8. Include a short summary of derived assumptions.

skills/k6-config/references/sla-defaults.md

@@ -84,7 +84,9 @@ Output:
 }
 ```
 
-> **Note on p99 inference:** `p99 = p95 * 1.8` is an empirical heuristic, not an official k6 rule. Use measured p99 values from representative environments whenever possible.
+> **IMPORTANT: Note on p99 Inference:** The `p99 = p95 * 1.8` formula is an empirical heuristic based on common latency distributions. This is not an official k6 standard and must not be treated as universally valid.
+>
+> Use this approximation only as an initial baseline when real p99 measurements are unavailable. Replace it with measured p99 values from representative environments (staging or production-like) before final SLA sign-off.
 
 ## Protocol-Specific Metrics
 

skills/k6-executor/SKILL.md

@@ -21,11 +21,27 @@ At the beginning of the workflow, detect and use interaction tools in this order
 4. Else emit the exact fallback and end the turn:
 
 ```md
-> [?] MISSING REQUIREMENT: [Missing goal or execution constraints]
+> [?] MISSING REQUIREMENT: Missing goal or execution constraints
+required: goal, load-shape constraint, and execution context
+why: deterministic executor recommendation requires all three
+next_question: What is your primary goal and is it rate-controlled or VU-controlled?
 ```
 
 Do not continue recommendation after fallback.
 
+## Interoperability Fallback Contract
+
+When fallback is required, always use this portable payload shape:
+
+```md
+> [?] MISSING REQUIREMENT: <short missing requirement summary>
+required: <comma-separated missing fields>
+why: <why recommendation cannot continue deterministically>
+next_question: <single question that unblocks next step>
+```
+
+Do not emit final recommendation content after this fallback.
+
 ## Language Policy
 
 1. If user language is explicit, answer in that language.
@@ -47,12 +63,24 @@ Always enforce these validations before final recommendation:
 3. **Parameter coherence is required**
    - Arrival-rate executors must satisfy `preAllocatedVUs <= maxVUs`.
    - `duration` values must be explicit and valid for time-based executors.
+  - `constant-vus` must include explicit `vus` and `duration`.
+  - `ramping-vus` must include explicit `startVUs` and non-empty `stages`.
+  - `ramping-arrival-rate` must include `startRate`, `timeUnit`, non-empty `stages`, and valid capacity controls.
+  - `per-vu-iterations` and `shared-iterations` must include explicit `vus` and `iterations`.
    - `externally-controlled` recommendations must include execution-context assumptions.
+4. **Secrets and runnable safety are required**
+  - Never hard-code credentials or tokens in runnable snippets.
+  - Require environment variables (`__ENV`) when auth or secrets are needed.
 
 ## Decision Tree
 
 <decision-tree>
-Ask user three clarifying questions if `goal` parameter is incomplete:
+Round definition:
+
+- **Round 1 (baseline block)**: ask the three baseline questions as one consolidated block.
+- **Round 2 (tie-break only)**: ask at most one tie-break question if conflict remains.
+
+Ask user the baseline questions if `goal` parameter is incomplete:
 
 1. **Do you need to control VU count or request rate?**
    - VU count → constant-vus or ramping-vus
@@ -66,7 +94,7 @@ Ask user three clarifying questions if `goal` parameter is incomplete:
    - Time-based → use duration parameter
    - Iteration-based → per-vu-iterations or shared-iterations
 
-If user requirements conflict (for example strict RPS target and strict VU cap), ask one tie-break question:
+If user requirements conflict (for example strict RPS target and strict VU cap), ask one tie-break question in Round 2:
 
 - "Which is more critical for this run: exact request-rate target or strict virtual-user ceiling?"
 </decision-tree>
@@ -195,10 +223,11 @@ Do not silently replace explicit user SLAs with defaults.
 
 Apply this gate before final recommendation:
 
-1. If scenario involves browser UX troubleshooting or local interactive analysis, recommend `K6_WEB_DASHBOARD=true`.
-2. If scenario is CI/non-interactive, keep dashboard disabled by default and prefer exported summaries.
-3. For all other cases, default to disabled unless user explicitly asks for interactive local monitoring.
-4. State one deterministic dashboard recommendation: `K6_WEB_DASHBOARD=true` or `K6_WEB_DASHBOARD=false` with rationale.
+1. If scenario is CI/non-interactive, keep dashboard disabled by default (`K6_WEB_DASHBOARD=false`) and prefer exported summaries.
+2. If scenario involves local interactive browser troubleshooting, recommend `K6_WEB_DASHBOARD=true`.
+3. If scenario is local non-browser, default to disabled (`K6_WEB_DASHBOARD=false`) unless user explicitly asks for interactive monitoring.
+4. For all other cases, default to disabled unless user explicitly asks for interactive local monitoring.
+5. State one deterministic dashboard recommendation: `K6_WEB_DASHBOARD=true` or `K6_WEB_DASHBOARD=false` with rationale.
 
 Always emit a visible section in output:
 
@@ -220,7 +249,17 @@ Every recommendation response must include these sections in order:
 5. Web Dashboard Recommendation
 6. Next Step
 
-For arrival-rate executors, Guardrail Validation must include:
+Guardrail Validation must include executor-specific checks:
+
+- `constant-vus`: explicit `vus` and `duration`
+- `ramping-vus`: explicit `startVUs` and non-empty `stages`
+- `constant-arrival-rate`: explicit `rate`, `timeUnit`, `duration`, and `preAllocatedVUs <= maxVUs`
+- `ramping-arrival-rate`: explicit `startRate`, `timeUnit`, non-empty `stages`, and `preAllocatedVUs <= maxVUs`
+- `per-vu-iterations`: explicit `vus` and `iterations`
+- `shared-iterations`: explicit `vus` and `iterations`
+- `externally-controlled`: explicit `vus`, `maxVUs`, `duration`, execution-context assumption, and documented control workflow
+
+For arrival-rate executors, Guardrail Validation must also include:
 
 - `preAllocatedVUs <= maxVUs` check
 - explicit capacity assumption note
@@ -267,7 +306,7 @@ Keep this file focused on decision workflow. Place deep guidance in:
 2. Select response mode (brief or detailed).
 3. Run Tool Discovery Protocol if required inputs are missing.
 4. If explicit SLAs are present, apply SLA Reconfirmation Rule.
-5. If ambiguous or conflicting, ask decision-tree questions (max two rounds).
+5. If ambiguous or conflicting, run decision-tree rounds with the explicit contract (Round 1 baseline, Round 2 tie-break only).
 6. Map answers to the most appropriate executor.
 7. Validate thresholds, load-profile invariants, and parameter coherence.
 8. Apply Web Dashboard Recommendation Gate and emit it visibly.

skills/k6-plan/SKILL.md

@@ -21,11 +21,27 @@ At the beginning of the workflow, detect and use interaction tools in this order
 4. Else emit the exact fallback and end the turn:
 
 ```md
-> [?] MISSING REQUIREMENT: [Missing target, scenario, or SLA detail]
+> [?] MISSING REQUIREMENT: Missing target, scenario, or SLA detail
+required: target, scenario type, and SLA requirements
+why: deterministic planning cannot proceed without baseline planning inputs
+next_question: What target endpoint, scenario type, and SLA should this plan use?
 ```
 
 Do not continue plan generation after fallback.
 
+## Interoperability Fallback Contract
+
+When fallback is required, always use this portable payload shape:
+
+```md
+> [?] MISSING REQUIREMENT: <short missing requirement summary>
+required: <comma-separated missing fields>
+why: <why plan generation cannot continue deterministically>
+next_question: <single question that unblocks next step>
+```
+
+Do not emit final plan content after this fallback.
+
 ## Core Rules
 
 <rules>
@@ -59,6 +75,12 @@ Do not continue plan generation after fallback.
 5. **Determinism**: Same inputs produce identical outputs every time.
 </rules>
 
+## Terminology Contract
+
+- **Scenario type** means the test objective shape (`load`, `stress`, `spike`, `soak`, `smoke`).
+- **Profile** means default intensity presets (`minimal`, `standard`, `aggressive`) used when explicit `vus`/`duration` are missing.
+- Scenario type selects the executor strategy; profile sets default intensity values.
+
 ## Language Policy
 
 1. If user language is explicit, answer in that language.
@@ -96,6 +118,24 @@ Always enforce these validations before returning the plan:
    - Do not generate runnable scripts with fixed live target URLs.
    - Require `__ENV.BASE_URL` (or equivalent) for executable output.
    - If target is missing, ask for it instead of using a default live URL.
+4. **Parameter coherence is required**
+   - Derived or explicit profile values must map to explicit `vus` and `duration`, or explicit staged equivalents.
+   - If write methods are planned (`POST`/`PUT`/`PATCH`), payload assumptions and expected status must be explicit.
+5. **Secrets and runnable safety are required**
+   - Never hard-code credentials or tokens in runnable snippets.
+   - Require environment variables (`__ENV`) for auth inputs.
+
+## Output Contract
+
+Every response must include these sections in order:
+
+1. Planning Inputs Summary
+2. Executor Recommendation
+3. Load Profile (explicit or derived)
+4. Thresholds (SLA-derived or defaults)
+5. Protocol-Specific Notes
+6. Assumptions
+7. Next recommended step
 
 ## Scenario to Executor Mapping
 
@@ -183,6 +223,7 @@ When user invokes this skill:
 9. Parse SLA thresholds or apply deterministic defaults.
 10. Validate explicit or derived VUs and duration.
 11. Generate textual plan with recommendations.
-12. Add exactly one deterministic `Next recommended step` based on first unresolved dependency.
-13. If `output=script` or user explicitly requests code, generate complete k6 JavaScript.
-14. Return the plan and assumptions summary.
+12. Validate output structure using the Output Contract section order.
+13. Add exactly one deterministic `Next recommended step` based on first unresolved dependency.
+14. If `output=script` or user explicitly requests code, generate complete k6 JavaScript.
+15. Return the plan and assumptions summary.

skills/k6-plan/references/README.md

@@ -19,6 +19,13 @@ Complete reference materials for comprehensive k6 performance test planning.
 - HTTP method confirmation and auth discovery for executable plans
 - Deterministic next-step selection from unresolved dependencies
 
+## Terminology Contract
+
+- **Scenario type**: objective shape (`load`, `stress`, `spike`, `soak`, `smoke`) used to select executor strategy.
+- **Profile**: intensity preset (`minimal`, `standard`, `aggressive`) used to derive default `vus` and `duration` when missing.
+- **Round**: one consolidated question block in the same adaptive question system; baseline questions are Round 1 and optional tie-break is Round 2.
+- **Explicit** means user-provided; **derived** means deterministic defaults declared in assumptions.
+
 ## Implementation Rules
 
 1. **Plans must include explicit thresholds** — provided by user or derived from defaults

skills/k6-plan/references/protocol-guide.md

@@ -2,6 +2,13 @@
 
 ## HTTP
 
+### Timeout Coherence Rule
+
+1. Include explicit request timeout for executable HTTP examples (`timeout: '30s'` baseline).
+2. Use stricter values only when SLA requires them and document the rationale.
+3. Missing explicit timeout should be treated as a validation warning in `k6-validate`, not an automatic blocker.
+4. Plan and validation guidance must not contradict: if plan emits explicit timeout, validation should not warn on timeout absence.
+
 ### Method Confirmation Checklist
 
 Before generating executable HTTP scripts:

skills/k6-validate/SKILL.md

@@ -21,11 +21,27 @@ At the beginning of the workflow, detect and use interaction tools in this order
 4. Else emit the exact fallback and end the turn:
 
 ```md
-> [?] MISSING REQUIREMENT: [Missing script path or validation scope]
+> [?] MISSING REQUIREMENT: Missing script path or validation scope
+required: script path and validation scope (protocol or expected profile)
+why: deterministic validation report cannot run without target and scope
+next_question: Which script should be validated and what protocol/profile context applies?
 ```
 
 Do not continue validation after fallback.
 
+## Interoperability Fallback Contract
+
+When fallback is required, always use this portable payload shape:
+
+```md
+> [?] MISSING REQUIREMENT: <short missing requirement summary>
+required: <comma-separated missing fields>
+why: <why validation cannot continue deterministically>
+next_question: <single question that unblocks next step>
+```
+
+Do not emit final validation findings after this fallback.
+
 ## Language Policy
 
 1. If user language is explicit, answer in that language.
@@ -72,6 +88,23 @@ Always enforce these validations as mandatory checks:
 2. **Load profile is required**
    - Flag as error when no explicit load profile exists.
    - Require explicit `vus` and `duration` for time-based cases, or clear equivalent (`stages`, `iterations` + `vus`) for scenario-based definitions.
+3. **Parameter coherence is required**
+   - If arrival-rate parameters exist, validate `preAllocatedVUs <= maxVUs`.
+   - If staged scenarios exist, validate non-empty stages with explicit duration per stage.
+4. **Secrets and runnable safety are required**
+   - Flag hard-coded credentials/tokens as error.
+   - Flag insecure runnable defaults for secrets as error or warning based on impact.
+
+## Output Contract
+
+Every validation response must include these sections in order:
+
+1. Validation Summary (`pass`/`warn`/`fail`)
+2. Scope and Assumptions
+3. Mandatory Invariant Results
+4. Detailed Findings
+5. Suggested Fixes
+6. Next Step
 
 ## Progressive Disclosure
 
@@ -87,4 +120,4 @@ Keep this file focused on validation workflow. Place deep guidance in:
 4. Validate performance best practices and protocol-specific rules.
 5. Enforce required threshold and load-profile invariants.
 6. Run quality-hardening checks (silent catch, unsafe parse, static-analysis signals).
-7. Return deterministic report with pass/warn/fail, findings, and fixes.
+7. Return deterministic report using the Output Contract section order.

skills/k6-validate/references/load-profile-validation-rules.md

@@ -190,8 +190,9 @@ stages: [
 - **Behavior:** Iterations split across VUs
 
 ### externally-controlled
-- **Required:** None (controlled via k6 REST API)
-- **Typical:** REST calls to set VUs and runState
+- **Required:** Explicit `vus`, `maxVUs`, `duration`, and execution-context assumption (control workflow documented externally)
+- **Typical:** REST calls to set VUs and runState post-initialization
+- **Note:** Aligns with k6-executor guardrail requiring explicit baseline parameters and documented external control context
 
 ## Edge Cases
 

skills/k6-validate/references/severity-and-antipatterns.md

@@ -24,7 +24,7 @@
 | Scenario | Rule | Severity | Fix |
 |----------|------|----------|-----|
 | No thresholds defined | ERROR | MUST have at least one threshold | Add threshold (e.g., `p95<500`) |
-| Only success checks, no metrics | WARNING | Thresholds define success criteria (MOS - Measure of Success), not just checks | Add latency/availability thresholds |
+| Only checks pass-rate threshold, no latency/error metrics | WARNING | Checks alone are insufficient for SLA validation | Add latency and error-rate thresholds |
 | Inconsistent across environments | WARNING | Same test, different thresholds per env | Document environment-specific SLAs |
 | p95 > p99 | ERROR | Invalid percentile relationship (p95 must be ≤ p99) | Swap values or fix percentile order |
 | Error threshold > 5% | WARNING | Too lenient for most SLAs | Tighten error rate threshold |
@@ -49,6 +49,10 @@
 | Batch size > 10 | WARNING | Batch requests might mask individual failures | Reduce batch size or use separate calls |
 | No timeout defined | WARNING | No per-request timeout is defined; behavior falls back to k6 defaults that may not match SLA expectations | Set `timeout: '30s'` or similar |
 
+Timeout coherence note:
+
+- When a script follows approved plan/config guidance and already defines explicit timeouts, timeout warnings must not be emitted.
+
 #### gRPC
 | Scenario | Rule | Severity | Fix |
 |----------|------|----------|-----|