README.md

k6-plan References

Complete reference materials for comprehensive k6 performance test planning.

Local Reference Files

• load-profiles.md — Standard VU and duration profiles (minimal, standard, aggressive)
• sla-defaults.md — Default SLA thresholds and parsing rules
• protocol-guide.md — HTTP, gRPC, and browser protocol patterns and examples
• data-integration.md — CSV/JSON/environment variable data source patterns
• certainty-and-compact-output.md — Verified-facts-only and compact response guidance
• exploratory-planning.md — Auto-detected exploratory mode, inferred flows, and provisional handoff rules

Core Topics

• SLA parsing, threshold derivation, and metric mapping
• Scenario-to-executor mapping heuristics (load, stress, spike, soak, smoke)
• Profile defaults, stage construction, and duration estimation
• Protocol-specific planning (HTTP, gRPC, browser VU requirements)
• Data source selection and integration strategies
• HTTP method confirmation and auth discovery for executable plans
• Exploratory planning from estimated load goals or application codebase context
• Deterministic next-step selection from unresolved dependencies
• Cloud runtime-family gating for v1.x/v2.x compatibility
• Cloud distribution validation (options.cloud.distribution percent sum must equal 100)
• strict certainty reporting and compact handoff outputs

Cloud Compatibility Vocabulary (Canonical)

Use this exact runtime family taxonomy across plan, builder, and validate:

• V0_53_TO_V1_5
• V1_6_PLUS_V1_X
• V2_0_PLUS

Verified cloud routing/auth env keys:

• K6_CLOUD_TOKEN
• K6_CLOUD_STACK_ID
• K6_CLOUD_PROJECT_ID

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.
• Exploratory mode: suggested plan generation from partial requirements or codebase evidence, with explicit pending clarifications.
• Explicit means user-provided; derived means deterministic defaults declared in assumptions.

Implementation Rules

1. Plans must include explicit thresholds — provided by user, derived from defaults, or emitted as suggested_sla candidates in exploratory mode
2. Plans must include explicit load profile — minimum: vus and duration, or staged equivalents
3. Missing critical parameters trigger the question protocol before plan generation
4. All assumptions must be listed in output when defaults are applied
5. Each plan includes executor recommendation with explicit rationale
6. Runnable URL hard-coding is forbidden in executable output; require __ENV.BASE_URL style variables
7. Auth discovery is mandatory before final handoff to k6-builder when auth requirements are uncertain
8. Exploratory plans must remain non-runnable until ready_for_builder blockers are cleared

Clarification Contract (Minimal)

When clarification is required (and provisional plan policy does not apply), return only:

missing: <comma-separated list of missing fields>
why: <one sentence explaining why these fields are required>
next_question: <single question that unblocks the next step>

Rules:

• Use exactly these three fields.
• Do not include partial plan fragments in clarification output.
• Ask only one next question, even if multiple fields are missing.

Provisional Plan Guardrail

• If core test shape is clear but target or sla is missing, generate a provisional plan with [assumption-based] labels.
• Always include pending_questions listing each assumption and why it is needed.
• If application-context exploration yields candidate routes or flows, include them under inferred_targets or inferred_flows and keep ready_for_builder: false.

HTTP Planning Requirements

Before finalizing an HTTP plan:

1. Confirm target endpoint and primary method (GET, POST, PUT, PATCH, DELETE).
2. If method is missing, ask for method before producing executable output.
3. Validate payload shape for write operations (POST/PUT/PATCH) and expected response status.
4. Add method-specific check guidance (status, latency, and optional response schema checks).

Auth Discovery Requirements

Before finalizing a plan and handoff recommendations:

1. Determine auth mode: none, bearer token, API key, basic auth, session cookie, or mTLS.
2. Declare required environment variables explicitly.
3. Never place credentials inline in examples.

Deterministic Next Step Rule

Every final plan must contain exactly one Next recommended step chosen by this order:

1. Missing target or method
2. Missing SLA
3. Missing auth details
4. Missing data source definition
5. Handoff to k6-builder for runnable artifact generation

Decision Criteria

When building a test plan, the skill gathers these decisions:

1. Target endpoint/URL — what are we testing?
2. Scenario type — load, stress, spike, soak, or smoke?
3. SLA requirements — latency (p95/p99), error rate, success rate?
4. Protocol context — HTTP, gRPC, browser, or mixed?
5. Load profile — explicit VUs/duration, or derive from scenario?
6. Exploratory evidence — is there enough app or request context to suggest targets, flows, and SLA candidates?

Example Workflow

User asks: "plan a k6 load test for my API"

1. Executor asks: What's the target URL?
2. Executor asks: What scenario type? (default: load)
3. Executor asks: What are your SLA requirements? (default: standard profile)
4. Executor derives: HTTP protocol, ramping-vus executor, standard load profile
5. Executor generates: Complete plan with thresholds, stages, and assumptions listed

Exploratory variant:

1. User asks: "Quiero validar si soportaré 2 mil usuarios concurrentes durante 1h para los flujos principales de mi backend"

2. Executor derives: scenario=load from the sustained validation goal and inspects the available app context if the workspace contains the backend

3. Executor suggests: candidate routes or business flows, one or more suggested_sla values from profile defaults, and explicit pending_clarifications

4. Executor marks: plan_mode: exploratory and ready_for_builder: false

5. Executor asks: What's the target URL?

6. Executor asks: What scenario type? (default: load)

7. Executor asks: What are your SLA requirements? (default: standard profile)

8. Executor derives: HTTP protocol, ramping-vus executor, standard load profile

9. Executor generates: Complete plan with thresholds, stages, and assumptions listed