help

What this skill does

# /help - Triqual Plugin Guide & Troubleshooting

Get guidance on using Triqual's test automation features, understand the workflow, and troubleshoot common issues.

## Quick Start

```bash
/help                    # Show overview and available commands
/help skills             # List all skills with descriptions
/help agents             # List all agents and when to use them
/help workflow           # Explain the recommended workflow
/help mcp                # MCP server setup and troubleshooting
/help troubleshooting    # Common issues and fixes
```

## Topics

### Overview (Default)

Display this comprehensive overview when no topic is specified:

```markdown
# Triqual - Unified Test Automation Plugin

Triqual helps you create, run, and maintain Playwright tests with integrated
pattern documentation (Quoth) and test analytics (Exolar).

## Available Skills

| Skill | Command | Description |
|-------|---------|-------------|
| Initialize | `/init` | Set up Triqual for your project |
| Test (default) | `/test login` | Full autonomous explore → plan → generate → heal |
| Test (explore) | `/test --explore login` | Interactive browser exploration only |
| Test (ticket) | `/test --ticket ENG-123` | Generate tests from Linear tickets |
| Test (describe) | `/test --describe "..."` | Generate from user description |
| Check | `/check` | Lint tests for best practices |
| Rules | `/rules` | View best practice documentation |
| Help | `/help` | This help guide |

## Available Agents

| Agent | Trigger | Description |
|-------|---------|-------------|
| test-planner | `/test` start, Linear ticket | Creates run log with ANALYZE/RESEARCH/PLAN stages |
| test-generator | After test-planner | Generates test code from plan |
| test-healer | Test failures | Auto-fix failing tests |
| failure-classifier | "Is this a flake?" | Classify failure type |
| pattern-learner | Recurring patterns | Propose documentation updates |

## MCP Servers

| Server | Purpose | Tool Examples |
|--------|---------|---------------|
| Quoth | Pattern documentation | `quoth_search_index`, `quoth_read_doc` |
| Exolar | Test analytics | `query_exolar_data`, `perform_exolar_action` |
| triqual-context | Context building | `triqual_load_context` |

## Key Tool: triqual_load_context

Builds comprehensive context files before test planning:
- `triqual_load_context({ feature: "login" })` — build context for a feature
- `triqual_load_context({ feature: "login", ticket: "ENG-123" })` — include ticket details
- `triqual_load_context({ feature: "login", force: true })` — regenerate existing context

Output: `.triqual/context/{feature}/` with patterns, anti-patterns, codebase analysis, failures, etc.

## Quick Commands

- Start fresh: `/init`
- Explore a feature: `/test --explore login`
- Full autonomous: `/test login`
- Generate from ticket: `/test --ticket ENG-123`
- Check code quality: `/check`
```

### Skills Topic

```markdown
## Triqual Skills Reference

### /init

**Purpose**: Initialize Triqual for a new project or after major changes.

**When to use**:
- First time using Triqual in a project
- After restructuring test directories
- After updating Triqual plugin

**What it does**:
1. Analyzes project structure
2. Detects existing tests and patterns
3. Generates `triqual.config.ts` with type-safe configuration
4. Creates context files for personalized behavior

---

### /test {feature} (Unified Test Skill)

The unified `/test` skill combines exploration, ticket-based, description-based, and autonomous test generation.

#### Default Mode: `/test login`

**Purpose**: Full autonomous test generation with pattern learning.

**What it does**:
1. **SETUP**: Auto-config, load patterns, discover credentials
2. **EXPLORE**: Uses Playwright MCP to explore the feature
3. **PLAN**: Creates test plan using Quoth patterns
4. **GENERATE**: Produces .spec.ts in draft folder
5. **HEAL LOOP**: Runs tests, fixes failures (max 5 iterations)
6. **PROMOTE**: Moves passing tests to production location
7. **LEARN**: Saves patterns and anti-patterns for future runs

---

#### Explore Mode: `/test --explore login`

**Purpose**: Interactive browser exploration only.

**When to use**:
- Testing if a page loads correctly
- Debugging a specific interaction
- Exploring UI before writing permanent tests
- Taking screenshots for documentation

**What it does**:
- Opens visible browser (headless: false)
- Uses Playwright MCP for real-time exploration
- Does NOT generate test files

---

#### Ticket Mode: `/test --ticket ENG-123`

**Purpose**: Generate tests from Linear ticket acceptance criteria.

**When to use**:
- Implementing tests for a new feature ticket
- Creating regression tests for a bug fix
- Following ticket-driven development

**What it does**:
1. Fetches ticket from Linear
2. Parses acceptance criteria
3. Creates test plan
4. Generates and heals tests
5. Provides PR instructions

---

#### Describe Mode: `/test --describe "user resets password"`

**Purpose**: Generate tests from a text description.

**When to use**:
- When you have clear test requirements
- No Linear ticket exists
- Quick test generation from description

**What it does**:
1. Uses the description as test requirements
2. Creates test plan
3. Generates and heals tests

---

### /check

**Purpose**: Lint test files for Playwright best practice violations.

**When to use**:
- Before committing new tests
- During code review
- When experiencing flaky tests
- As part of test maintenance

**What it does**:
1. Scans test files for violations
2. Reports issues by severity (ERROR/WARN/INFO)
3. Suggests fixes for each violation
4. Optionally applies auto-fixes

---

### /rules

**Purpose**: View comprehensive Playwright best practice documentation.

**When to use**:
- Learning Playwright patterns
- Understanding why a rule exists
- Finding the correct approach for a scenario

**What it provides**:
- 31 rules across 8 categories
- Examples of good and bad patterns
- Rationale for each rule
```

### Agents Topic

```markdown
## Triqual Agents Reference

### test-healer

**Purpose**: Automatically diagnose and fix failing Playwright tests.

**Triggered by**:
- User mentions "test failures", "failing tests", "flaky tests"
- User shares Playwright error output
- Post-test-run hook when failures detected

**What it does**:
1. Parses error message and stack trace
2. Identifies root cause from known patterns
3. Proposes specific fix
4. **Asks for approval before applying**
5. Verifies fix worked

**Common fixes**:
- Add `:visible` to ambiguous selectors
- Use `getTimeout()` for dynamic timeouts
- Add `.first()` for strict mode violations
- Clear stale auth state

---

### failure-classifier

**Purpose**: Classify test failures to guide appropriate action.

**Triggered by**:
- User asks "is this a flake or bug?"
- User wants to analyze failure patterns
- Post-test-run hook recommends it

**Classification types**:
- **FLAKE**: Intermittent, use test-healer
- **BUG**: Consistent failure, create ticket
- **ENV_ISSUE**: Infrastructure problem, check environment
- **TEST_ISSUE**: Test is incorrect, fix test

**What it does**:
1. Gathers failure data
2. Queries Exolar for history (if available)
3. Applies classification rules
4. Generates report with confidence level
5. Recommends next action

---

### pattern-learner

**Purpose**: Identify recurring patterns and propose Quoth documentation updates.

**Triggered by**:
- Same error appears across multiple tests
- A fix works successfully 3+ times
- User asks to "document this pattern"

**What it does**:
1. Identifies recurring failure/fix patterns
2. Validates pattern is generalizable
3. Checks if pattern already documented in Quoth
4. Proposes new pattern documentation
5. **Asks for approval before submitting**
```

### Workflow Topic

```markdown
## Recommended Triqual Workflow

### For New Projects

1. **Initialize**: `/init`
2. **Explore**: `/test --explore login` to understand the app
3. **Generate**: `/test login` or