perfpilot-hub / rules

---
description: Pre-flight validation for all workflows — artifact structure, MCP server availability, config file reference
alwaysApply: true
---

# Prerequisites & Pre-Flight Checks

## API Keys & Credentials — Graceful Failure

MCP tools handle missing or invalid credentials gracefully. If an API key or credential
is not configured, the MCP tool will return an error at call time. **Do not** attempt to
read or validate `.env` files before starting a workflow.

- `.env` files are **gitignored** and not available in the repository. Only `.env.example`
  files are committed as reference templates.
- Cursor may not be able to read `.env` files. This is expected — assume credentials are
  configured by the Performance Test Engineer. If they are not, MCP tools will fail with
  a clear error message.
- Do not block a workflow due to inability to verify credentials. Proceed and let the
  MCP tool report any authentication failures.

**Credential reference** (for documentation purposes only — do not validate these):

| MCP Server | Required Credentials | Config Location |
|------------|---------------------|----------------|
| BlazeMeter | `BLAZEMETER_API_KEY`, `BLAZEMETER_API_SECRET` | `.env` or environment variables |
| Datadog | `DD_API_KEY`, `DD_APP_KEY` | `.env` or environment variables |
| Confluence | `CONFLUENCE_TOKEN`, `CONFLUENCE_USER` (cloud) or `CONFLUENCE_PAT` (onprem) | `.env` or environment variables |

**Azure DevOps (optional):** ADO integration is only relevant for users who use Azure
DevOps. It is not a universal requirement. Users who use JIRA or other systems will not
have ADO configured. If ADO access is needed for a specific workflow (e.g., ADO test case
conversion), the skill will state this as a prerequisite.

## Artifact Structure

- `test_run_id` is always required for any workflow
- If the user does not provide one, ask. As a fallback, generate as `YYYY-MM-DD-HH-MM-SS`
- Artifacts directory: `artifacts/{test_run_id}/`
- Canonical subfolder structure:

```
artifacts/{test_run_id}/
├── blazemeter/       # BlazeMeter CSV, logs, session data
├── datadog/          # Host/k8s metrics, logs, APM traces
├── analysis/         # PerfAnalysis JSON outputs
├── reports/          # Generated reports, revisions, metadata
├── charts/           # Generated PNG chart images
└── jmeter/           # JMX scripts, network captures, correlation files
```

- Test comparison artifacts use: `artifacts/comparisons/{comparison_id}/`
- File existence checks are mandatory gates between workflows

## Environment Configuration

- Environment names are defined in each MCP server's configuration files (see table below)
- If an environment name is invalid, the MCP tool will return an error at call time
- Do not attempt to read or validate environment config files upfront

## MCP Server Availability

- If an MCP server is not available, inform the user which MCP server is unavailable and ask for next steps (e.g. skip the unavailable MCP workflow? Stop and wait for the MCP to become available?)
- Do not fail silently

## Configuration Files Reference

| MCP Server   | Config File                                               | Purpose                                        |
|--------------|-----------------------------------------------------------|------------------------------------------------|
| JMeter       | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | JMeter paths, browser settings, think time     |
| JMeter       | `jmeter_config.yaml`                                      | JMX generation settings, verbose logging       |
| JMeter       | `correlation_config.yaml`                                 | Custom naming mappings for correlations        |
| BlazeMeter   | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | BlazeMeter API settings, max artifact download retries, shared folder allowed extensions |
| Datadog      | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | Datadog API pagination limits                  |
| Datadog      | `environments.json`                                       | Host/k8s/services definitions per environment  |
| Datadog      | `custom_queries.json`                                     | Custom log, APM, and timeseries metric queries |
| PerfAnalysis | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | Analysis settings, resouce thresholds, bottleneck analysis settings |
| PerfAnalysis | `slas.yaml`                                               | SLA configurations for response times and error rate thresholds     |
| PerfReport   | `report_config.yaml`                                      | Report sections, revisable sections, unit display                   |
| PerfReport   | `chart_schema.yaml`                                       | Chart definitions, unit configuration                               |
| PerfReport   | `chart_colors.yaml`                                       | Color palettes for charts                                           |
| Confluence   | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | Pagination limits                              |
| Streamlit    | `config.yaml` / `config.mac.yaml` / `config.windows.yaml` | Port settings, page title                      |