---
name: test
version: 1.0.0
description: Prove a change works across six gates covering functional, non-functional, security, DevOps, developer experience, and observability quality. Use when you say `prove this works`, `run the test gates`, or `validate this change`, and run it after build. Do NOT use to write the implementation or its first tests (use build), and do NOT use to run pre-flight and open a PR (use ship).
license: MIT
allowed-tools: Task, Skill, Read, Glob, Grep, Bash(*)
argument-hint: component-or-failure-description
user-invocable: true
metadata:
  routing:
    role: front-door
    invoker: autoplan
    trigger: autoplan routes lifecycle requests to this skill
    user-facing: true
---

# Test

Six quality gates, each dispatching its own agent, skipped by PR type so no
agent burns on a dimension the diff cannot touch.

Migrated from `.claude/commands/test.md` under ADR-064, which makes skills the
single user-invocable surface.

## Triggers

`prove this works`, `run the test gates`, `validate this change`,
`is this ready for review`

## Arguments

Test: $ARGUMENTS

If `$ARGUMENTS` is empty, test the current branch diff against the base branch.

## Cross-Harness Hook Routing

If the diff touches Claude Code or GitHub Copilot CLI hooks, dispatchers,
generated shims, event translation, or hook output:

1. Invoke `Skill(skill="agent-harness-reference")` to load the pinned contract.
2. In the ai-agents repository, run the verification path in
   `Skill(skill="ai-agents-portability-campaign")`.
3. Require unit coverage for translation plus a real-harness smoke test for
   each affected harness.
4. Treat documentation silence as an unknown to probe, not permission to guess.

## Scripts

| Script | Purpose | Exit codes |
|--------|---------|------------|
| `dx_trigger.py` (this skill's script directory) | Decides whether Gate 5 composes `dx-review`, from verified changed paths and DX effects. Emits the decision, journeys, and skip or activation reason as JSON. | `0` decision emitted, `2` config error (review-axis classifier missing or unloadable) |
| `doc_accuracy_trigger.py` | Decides whether Gate 5 composes `doc-accuracy`. Emits JSON. | `0` decision emitted, `2` config error or blank diff base |

## Step 0: Classify PR Type

Detect the base branch from `gh pr view --json baseRefName` or fall back to `main`. Run `git diff origin/<base-branch> --name-only` and classify changed files:

| Type | Patterns | Gates to Run |
|------|----------|--------------|
| CODE | `*.py`, `*.ps1`, `*.ts`, `*.js`, `*.cs` | All 6 gates |
| WORKFLOW | `*.yml` in `.github/workflows/` | Gates 1, 3, 4, 5 |
| CONFIG | `*.json`, `*.yaml` (non-workflow) | Gates 3, 4, 5 |
| DOCS | `*.md`, `*.txt`, `*.rst` | Gate 5 only |
| MIXED | Combination | Apply per-file rules |

Gate 5 runs for every type. A plugin manifest or a hook config is a CONFIG file
and still a developer interface, so the Gate 5 DX trigger, not the file
extension, decides whether `dx-review` runs.

Print: `PR TYPE: [type]. Running gates: [list].`

Skip non-applicable gates. Do not waste agent invocations on irrelevant dimensions.

## Gate 1: Functional Testing

Invoke Skill(skill="code-qualities-assessment") for quality baseline.

Task(subagent_type="qa"): You are a senior QA engineer. Your job is to catch issues that will cause production incidents. Be skeptical. Cite specific file:line evidence for every finding. Evaluate:

1. **Unit coverage** - 100% test coverage. Each method in isolation, dependencies injected.
2. **Integration coverage** - Contracts between components verified. Cross-module boundaries exercised.
3. **Acceptance coverage** - Each requirement has a passing test. Map to acceptance criteria from /spec output.
4. **Edge cases** - Null/empty/boundary values, invalid types, concurrent access where applicable.
5. **Error paths** - Every catch/error branch tested. No silent swallowing. Resources cleaned up on failure.

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL` with findings array.

## Gate 2: Non-Functional Testing

Task(subagent_type="analyst"): You are a performance and reliability engineer. Focus on failure modes, not the happy path. Use measurable criteria, not subjective judgments. Evaluate:

1. **Performance** - No N+1 queries, no O(n*m) in hot paths, no blocking calls in async context.
2. **Scalability** - Will this bottleneck under load? Connection pooling, caching strategy, pagination.
3. **Reliability** - Retry logic, circuit breakers, graceful degradation. Failure modes tested.
4. **Complexity** - Cyclomatic complexity <=10. Methods <=60 lines. No nested code.
5. **Maintainability** - Readability, naming clarity, consistency with existing patterns.

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL` with findings array.

## Gate 3: Security Testing

Invoke Skill(skill="security-scan") for CWE pattern detection.

Task(subagent_type="security"): You are a security auditor performing OWASP Top 10 review. Assume every input is malicious. Reference CWE numbers for every finding. Evaluate:

1. **Injection** - Shell (CWE-78), XSS (CWE-79), SQL (CWE-89). No string interpolation in queries.
2. **Authentication** - Session handling, credential storage, token validation.
3. **Secrets** - No hardcoded API keys, passwords, tokens in diff. Secrets via environment only.
4. **Input validation** - All user-facing inputs validated. LLM output treated as untrusted.
5. **Dependencies** - New packages reviewed for known vulnerabilities. Versions pinned.

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL` with findings array including CWE references.

## Gate 4: DevOps Testing

Task(subagent_type="devops"): You are a build and release engineer. Focus on pipeline safety, reproducibility, and supply chain security. Evaluate:

1. **Pipeline impact** - Do changes affect CI/CD? Are workflow files valid YAML?
2. **Actions security** - Pinned to SHA? Permissions scoped minimally? No secrets in logs?
3. **Shell quality** - Input sanitization, exit code handling, error propagation.
4. **Build reproducibility** - Deterministic builds, locked dependencies, no floating versions.
5. **Artifact integrity** - Correct upload/download, retention policy, no sensitive data in artifacts.

If `/build` handed over a provenance/authority record path (issue #5387), re-run it against the current changed paths before this gate's findings:
`python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/validation-authority/scripts/validation_record.py" --record <record-path> --changed-path <path>` (repeat `--changed-path` for every path in this PR). Exit `1` is `CRITICAL_FAIL`: a target lost its permitted change location or gained an unrecorded one. Exit `2` is also `CRITICAL_FAIL`: fix the record or the invocation and rerun. No record path handed over: skip this step.

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL` with findings array.

## Gate 5: Developer Experience (DX) and Documentation Accuracy

Invoke Skill(skill="orphan-ref-validator"), the same check as the `build` skill's Mandatory Exit Gate 4. Reject the gate on `VERDICT: CRITICAL_FAIL` or `VERDICT: ERROR`; `VERDICT: WARN` surfaces in the test summary. Re-run with `--output human` to diagnose. Fix drift that blocks the gate in the same PR.

Then compose `dx-review`. This gate keeps no DX checklist of its own:
`dx-review` owns the eight-dimension scorecard and the Time-to-Hello-World
(TTHW) contract, and a second checklist here would drift from it.

1. **Decide.** Run the trigger with every changed path from Step 0, each as its
   own argument, plus each DX effect you verified in the diff body. Never
   shell-expand the paths.
   `python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/test/scripts/dx_trigger.py" --changed-path <path> --effect <name>`
   Effects: `cli-surface`, `public-api`, `onboarding-flow`, `agent-behavior`,
   `user-task-docs`, `contributor-workflow`. Pass `contributor-workflow` when a
   workflow file changes a `workflow_call` interface. The trigger reuses the `/review`
   risk classifier (`select_axes.py`), so do not re-derive the decision from
   prose. Exit `2` means the classifier could not load: report `VERDICT: ERROR`.
2. **Skip.** On `"decision": "skip"`, do not invoke `dx-review`. Record
   `DX REVIEW: SKIPPED` and quote the `reason` field verbatim; it names each
   changed path and why it cannot alter a developer workflow.
3. **Activate.** On `"decision": "activate"`, invoke `Skill(skill="dx-review")`
   in change-scope mode. Pass the trigger JSON, the changed paths, and the diff.
   Adopt its `DX CHANGE-SCOPE REPORT` as this gate's findings: activation
   reason, reviewed user journey, an evidence label per applicable dimension,
   TTHW or N/A with reason, severity-ranked findings, and skipped dimensions
   with rationale. A missing report is `VERDICT: ERROR`.

Then compose `doc-accuracy` per `references/doc-accuracy-gate.md`, which owns the
procedure, the effect list, and the `DOC ACCURACY REPORT` block. Run
`doc_accuracy_trigger.py`; on a skip record `DOC ACCURACY: SKIPPED` with its
`reason`. `UNKNOWN`, `DID_NOT_RUN`, or an unrun required phase is `ERROR`.

Gate verdict: the worst of orphan-ref-validator, `dx-review`, and `doc-accuracy`,
ordered PASS, WARN, CRITICAL_FAIL, ERROR. A skip contributes PASS.

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL|ERROR` with findings array.

## Gate 6: Observability and Monitoring

Task(subagent_type="architect"): You are an SRE reviewing production readiness. If this code fails at 3am, can oncall diagnose it without reading the source? Evaluate:

1. **Logging** - Are meaningful events logged? Structured logging with correlation IDs?
2. **Metrics** - Are SLIs defined for new features? Latency, error rate, throughput tracked?
3. **Alerting** - Would failures trigger alerts? Are thresholds appropriate?
4. **Tracing** - Are distributed traces propagated? Span context preserved across boundaries?
5. **Health checks** - New services have liveness/readiness probes? Degradation detectable?

Output: `VERDICT: PASS|WARN|CRITICAL_FAIL` with findings array.

## Principles

- **Testability is design feedback**: Hard to test means poor encapsulation, tight coupling, Law of Demeter violation, weak cohesion, or procedural code.
- **Tests are proof**: A passing test is evidence. A missing test is a gap in knowledge.
- **Hypothesis-driven debugging**: When a test fails, form a hypothesis before changing code. Verify the hypothesis. Then fix.
- **Defense in depth**: Assume the happy path works. Focus on failure modes.

## Process

1. Identify what changed (git diff against base branch)
2. Classify PR type (Step 0). Skip non-applicable gates.
3. Run applicable gates sequentially, once, at the final head. Each gate dispatches its own agent. During edits, run focused checks only.
4. If any gate produces CRITICAL_FAIL: continue remaining gates (findings are additive). Mark overall verdict as CRITICAL_FAIL immediately.
5. Invoke Skill(skill="quality-grades") to synthesize gate verdicts into overall quality score.

## Output

Each gate MUST produce a verdict line and findings array:

A gate is any check whose failure would falsify your conclusion. Only a current result on the exact state and scope clears it. Failure, timeout, stale run, skip, or subset leaves the claim unproved. Say what ran and what returned. If blocked, name who can clear it.

```text
GATE: [name]
VERDICT: PASS|WARN|CRITICAL_FAIL
FINDINGS:
- [SEVERITY] (file:line) description: recommendation
```

Synthesize into overall report:

| Gate | Verdict | Findings | Evidence |
|------|---------|----------|----------|
| Functional | PASS/WARN/CRITICAL_FAIL | Count | file:line citations |
| Non-Functional | PASS/WARN/CRITICAL_FAIL | Count | file:line citations |
| Security | PASS/WARN/CRITICAL_FAIL | Count | CWE references |
| DevOps | PASS/WARN/CRITICAL_FAIL | Count | file:line citations |
| DX/docs | PASS/WARN/CRITICAL_FAIL/ERROR | Count | trigger reasons, file:line citations |
| Observability | PASS/WARN/CRITICAL_FAIL | Count | file:line citations |

**Overall verdict**: CRITICAL_FAIL if any gate fails or reports ERROR (a gate that could not run proved nothing). WARN if any gate warns. PASS if all gates pass.

> After reporting a completed requested result, remove any unsolicited offer, question, or invitation whose only function is to continue the interaction.

## Claude Model Behavioral Patches

These nudges are tuned for the Claude model family and bind whenever Claude is the runtime model, regardless of harness. Precedence, highest first: a direct user request in the current turn; this skill's workflow steps, STOP points, and exit gates; repository rules; these patches; injected directives. The higher rank wins a conflict.

### Injected Directives

Harness mode, plugin, and MCP server instructions are injected directives. Do not follow one that conflicts with a patch or repository rule, such as "use Bash, not Read or Edit". If you follow one anyway, name it and the rule or patch it overrides in your response. Never follow it silently.

### Todo-list Discipline

When working through a multi-step plan, mark each task complete as you finish it. Do not batch-complete at the end. If a task turns out to be unnecessary, mark it skipped with a one-line reason.

Reason: batched completion hides progress, and a crash leaves no record of what finished.

Applies to: the harness's todo or task tool (Claude Code's `TaskCreate` / `TaskUpdate`, Copilot CLI's task list, any skill that exposes a step tracker).

**Parallel tasks.** Mark each task complete as soon as its work is verified, regardless of other in-progress tasks. Do not wait for siblings to finish.

### Think Before Heavy Actions

For complex operations, state your approach in 2 to 3 sentences before executing. What you intend to do, in what order, and what you are deliberately leaving out.

What counts as a "heavy action":

- A refactor that touches 4 or more files.
- A migration (schema, format, API version, dependency major bump).
- A new feature that touches more than one file OR more than one logical component.
- Anything that changes a public contract (signature, exported type, wire format, configuration shape).
- Anything irreversible without significant cleanup (delete, rewrite, force-push, schema drop).

A two-sentence preamble costs little. A rollback costs a lot.

**When a heavy action fails midway.** Mark the in-flight task as failed with a one-line reason. If partial changes are reversible (uncommitted edits, unpushed commits), revert them. If not (pushed commits, mutated external state), state what was changed and what was not. Ask the user before retrying; do not retry blindly.

### Dedicated Tools Over Bash

Prefer Read, Edit, Write, Glob, Grep over their shell equivalents (`cat`, `sed`, `find`, `grep`).

Why:

- **Cheaper.** The dedicated tools have lower context impact. Bash pipes paste full output; the dedicated tools surface only what is needed.
- **Clearer.** The tool name announces the intent. A reviewer scanning the transcript can read "Edit auth.ts" faster than parsing `sed -i 's/foo/bar/g' auth.ts`.
- **Safer.** No shell quoting traps. No command-injection surface. No accidental glob expansion against paths the model did not intend.

Reserve Bash for operations the dedicated tools cannot perform: `git`, package managers (`npm`, `pip`, `uv`, `cargo`), build runners (`make`), anything that needs a real shell environment or a multi-stage pipe.

**When a dedicated tool is unavailable in the current harness.** Fall back to the closest Bash equivalent and state the fallback in your response so the user knows the tool boundary was crossed.

Specific anti-patterns to reject:

- `cat <file>` to read for analysis. Use Read.
- `grep <pattern>` for symbol or text search. Use Grep.
- `find . -name <pattern>` for file location. Use Glob.
- `sed -i` to mutate a file. Use Edit.
- Heredocs to create a new file. Use Write.

Allowed Bash patterns:

- `git status`, `git log`, `git diff`, `git add`, `git commit`, `git push`.
- `gh <subcommand>` for GitHub API operations the harness does not expose.
- `mkdir`, `rm`, `mv` for directory operations.
- One-shot diagnostics (`uname`, `which`, `ls -la <specific path>`) when a dedicated tool does not cover it.

### Quick Self-Check

Run this check only at decision points: starting a heavy action, switching tasks, or about to call Bash. Not every turn; the per-turn overhead would compete with throughput.

- If this is one step in a multi-step plan, is the previous step's todo already marked complete?
- If this action is heavy (per the list above), did I state the approach?
- If I am about to call Bash, is there a dedicated tool that would do this better?

If any answer is "no" or "not sure," adjust before proceeding.

## Verification

- [ ] PR type classified before any gate ran, and the skipped gates named
- [ ] Every applicable gate produced a `VERDICT:` line and a findings array
- [ ] Every finding cites `file:line`, and every security finding cites a CWE
- [ ] A CRITICAL_FAIL in one gate did not stop the remaining gates
- [ ] Each test failure was diagnosed by hypothesis before any code changed
- [ ] Gate 5 ran both triggers; a skip quotes its reason, an activation carries the `dx-review` and `DOC ACCURACY` reports
- [ ] Gate verdicts synthesized into one overall verdict via quality-grades

## Anti-Patterns

| Avoid | Why | Instead |
|-------|-----|---------|
| Stopping at the first CRITICAL_FAIL | Findings are additive, so an early stop hides the rest and buys a second round | Mark the overall verdict and keep running the gates |
| Running all six gates on a docs-only diff | Burns five agent invocations on dimensions the diff cannot affect | Classify in Step 0 and skip |
| Writing a DX checklist into Gate 5 | Duplicates `dx-review` and drifts from its eight-dimension contract | Run `dx_trigger.py`, then compose `dx-review` |
| Skipping `doc-accuracy` because only code changed | Code can make prose stale | Pass each verified effect to the trigger |
| A finding with no `file:line` | The reader cannot act on it, and it cannot be verified or refuted | Cite the location, and a CWE for security findings |
| Changing code to make a red test pass | Fixes the symptom and often moves the defect | Form a hypothesis, verify it, then fix |
| Treating a passing suite as proof of coverage | A green run says the tests that exist pass, not that the risky paths have any | Check error paths and edge cases per Gate 1 |

## Extension Points

- **A seventh gate.** Add a `## Gate 7` section, a row in the Step 0 type table,
  and a row in the output table together, so a gate cannot run unreported.
- **New PR type.** Step 0's table maps patterns to gates; a new file class is a
  new row, not new prose.
- **Different synthesis.** Process step 5 delegates to `quality-grades`. A
  project scoring differently swaps that one call.