test-spec

What this skill does

> **Version:** 1.0.0 | **Framework:** Jerry Framework | **Constitutional compliance:** P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception)
> **Status:** PROPOSED | **Author:** eng-backend | **Date:** 2026-03-09

---

## Document Sections

| Section | Purpose |
|---------|---------|
| [Document Audience](#document-audience) | Who reads which sections |
| [Purpose](#purpose) | What this skill does and key capabilities |
| [When to Use](#when-to-use) | Activation conditions and anti-patterns |
| [Available Agents](#available-agents) | Agent routing table with decision signals |
| [P-003 Agent Topology](#p-003-agent-topology) | ASCII hierarchy diagram (multi-agent required) |
| [Invoking an Agent](#invoking-an-agent) | Three invocation modes |
| [Clark Transformation Reference](#clark-transformation-reference) | Domain methodology summary |
| [Input Requirements](#input-requirements) | Use case artifact prerequisites |
| [Output Artifacts](#output-artifacts) | Feature file and coverage report formats |
| [Integration Points](#integration-points) | Cross-skill connections |
| [Routing Entry (Priority 14)](#routing-entry-priority-14) | Trigger map entry for mandatory-skill-usage.md |
| [Constitutional Compliance](#constitutional-compliance) | Principle-to-agent mapping |
| [Quick Reference](#quick-reference) | Common workflows and agent selection |
| [References](#references) | File paths and external citations |

---

## Document Audience

| Level | Audience | Sections |
|-------|----------|---------|
| L0 | Stakeholders, project managers | [Purpose](#purpose), [When to Use](#when-to-use), [Quick Reference](#quick-reference) |
| L1 | Developers, QA engineers using the skill | [Available Agents](#available-agents), [Invoking an Agent](#invoking-an-agent), [Clark Transformation Reference](#clark-transformation-reference), [Input Requirements](#input-requirements), [Output Artifacts](#output-artifacts) |
| L2 | Framework maintainers, reviewers | [P-003 Agent Topology](#p-003-agent-topology), [Integration Points](#integration-points), [Constitutional Compliance](#constitutional-compliance), [References](#references) |

---

## Purpose

The `/test-spec` skill transforms structured use case artifacts produced by `/use-case` into BDD Gherkin test specifications using Clark's (2018) UC2.0-to-Gherkin deterministic mapping algorithm. It closes the gap between use case specifications and testable acceptance criteria.

**Key Capabilities:**

- Deterministic Clark transformation: every use case flow element maps to exactly one Gherkin scenario type (no invented scenarios)
- Happy path generation: basic flow -> 1 happy path Scenario with Given/When/Then clauses derived from preconditions, steps, and postconditions
- Error scenario generation: each extension -> 1 error/negative/rejoin Scenario determined by outcome type (failure, success, rejoin:{N})
- Alternative flow coverage: each alternative_flow -> 1 additional Scenario
- Full traceability: every Scenario carries a Source annotation and the Feature file includes a Traceability Matrix
- Coverage analysis: quantitative C1 Coverage metrics (mapped / total_mappable flows) with 7 Cs quality framework assessment and prioritized gap remediation
- Slice-scoped generation: when slices are defined via uc-slicer, generate Feature files scoped to specific implementation increments

---

## When to Use

**Activate this skill when:**

- Generating BDD Gherkin scenarios from a use case artifact
- Transforming use case flows (basic, alternative, extensions) into test specifications
- Creating a test plan document from use case structure for project planning
- Analyzing test coverage completeness against use case flow steps
- Verifying that all use case extensions have corresponding error scenarios
- Mapping use case preconditions/postconditions to Given/Then clauses

**NEVER invoke this skill when:**

- Task is writing or editing use case artifacts -- Consequence: `/test-spec` agents do not implement Cockburn's writing methodology; they consume use case output, not produce it; use `/use-case` instead.
- Task is generating API contracts from use case artifacts -- Consequence: `/test-spec` produces Gherkin BDD scenarios, not OpenAPI specifications; use `/contract-design` instead.
- Task is writing unit tests or pytest code -- Consequence: `/test-spec` produces human-readable BDD specifications, not executable test code; write tests directly or use `/eng-team` for test implementation guidance.
- Task is adversarial quality review of deliverables -- Consequence: use `/adversary` for quality scoring and adversarial critique.
- Use case artifact is at detail_level < ESSENTIAL_OUTLINE -- Consequence: Clark transformation requires typed flow steps and extensions; artifacts below ESSENTIAL_OUTLINE lack these; use `/use-case` to elaborate first.

---

## Available Agents

| Agent | Role | Model | Cognitive Mode | Tool Tier | Output Location | Decision Signal |
|-------|------|-------|----------------|-----------|-----------------|-----------------|
| `tspec-generator` | Transforms use case flows into Gherkin BDD scenarios using Clark algorithm | sonnet | systematic | T2 | `projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}.feature.md` | "generate", "transform", "create feature file", "map to Gherkin", "BDD from use case", "Clark" |
| `tspec-analyst` | Analyzes test coverage completeness against use case flows using 7 Cs framework | sonnet | convergent | T2 | `projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}-coverage.md` | "coverage", "analyze coverage", "coverage gap", "missing scenarios", "completeness check", "7 Cs" |

**Default routing:** When intent is ambiguous between generation and analysis, route to `tspec-generator` first. Generation must precede coverage analysis. When the user says "generate and check coverage," invoke `tspec-generator` first, then `tspec-analyst` on the output.

---

## P-003 Agent Topology

Both `tspec-generator` and `tspec-analyst` are T2 worker agents. They are invoked independently from MAIN CONTEXT. They do NOT invoke each other. The output of tspec-generator (Feature file on disk) is consumed by tspec-analyst via the filesystem -- not via direct agent-to-agent communication.

```
MAIN CONTEXT (orchestrator)
    |
    +-- tspec-generator (T2 worker) -- via Task tool
    |   Reads: UC artifact (.md with YAML frontmatter)
    |         docs/schemas/use-case-realization-v1.schema.json
    |         skills/test-spec/rules/clark-transformation-rules.md
    |   Writes: Feature file (.feature.md)
    |           Optional: test plan (-test-plan.md)
    |
    +-- tspec-analyst (T2 worker) -- via Task tool
        Reads: Feature file (.feature.md) -- produced by tspec-generator
               UC artifact (.md) -- same source artifact
        Writes: Coverage report (-coverage.md)

Workers do NOT invoke each other.
tspec-generator output (Feature file) is consumed by tspec-analyst via filesystem.
Cross-agent data flow is mediated by shared artifact files on disk (P-003 compliant).
```

---

## Invoking an Agent

### Natural Language Invocation

```
Generate BDD scenarios from use case UC-AUTH-001.
```

```
Analyze test coverage for the Feature file at
projects/PROJ-021/test-specs/UC-AUTH-001-validate-credentials.feature.md
against the source use case.
```

### Explicit Agent Invocation

```
Use tspec-generator to transform UC-AUTH-001 from
projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
into a Gherkin Feature file.
```

```
Use tspec-analyst to produce a coverage report for
UC-AUTH-001-validate-credentials.feature.md.
```

### Task Tool Invocation (composition file)

```yaml
# Invoke tspec-generator via Task tool
task:
  agent: skills/test-spec/composition/tspec-generator.agent.yaml
  prompt: |
    Transform use case at projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
    into a Gherkin Feature file. Output path:
    projects/PROJ-021/t