# Describe Structure

> Required whenever adding, editing, or restructuring tests or specifications, including *.test.* and *.spec.* files. Use for unit-test coverage, regression tests, TDD, mutation testing, bug fixes, and refactoring—even when the user does not name test structure. Invoke before writing test code. In suites that already use describe, structure every new or changed test as component → when [action] → given [condition] → outcome-focused it; preserve flat suites without describe.

- Skill: `jonfazzaro/describe-structure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jonfazzaro/describe-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jonfazzaro/describe-structure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jonfazzaro (https://skillmd.com/u/jonfazzaro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jonfazzaro/describe-structure

---


## Context marker

🔺

When the skill activates, begin the first commentary update with `🔺` and a concise `Using describe-structure ...` announcement. Do not repeat the marker on later updates unless another skill activates.

# Describe Structure

**REQUIRED:** Use this skill whenever coding with test-driven development or Continuous Specification.

When a test file already has a root `describe`, organize the new or changed specifications so the affected tree reads as complete behavior sentences. Preserve a flat test file with no `describe` structure.

```text
Component
  when the playback probe starts
    given a rejected play request
      reports unsupported playback
```

## Build the hierarchy

- Extract the action or triggering event from each existing `it` caption into a `describe` caption beginning with `when`.
- Extract each state, input, or precondition into a nested `describe` caption beginning with `given`.
- Write every `describe` and `it` caption for people, in plain-English domain language; try not to use a code function, method, or API name as the caption.
- Keep the observable outcome in the `it` caption.
- Put shared actions above their distinct givens. A `when` block should contain every applicable `given` branch.
- Read every root-to-leaf path aloud. Each must be grammatical without relying on test setup code.

Use `given` for a condition: `given a nullable probe with a configured result`.

Use `when` for an event: `when disposing the session`.

Write `when` captions in active voice. Avoid passive voice (`when the session is disposed`). When the action's subject is unknown, use a gerund phrase: `when saving changes`, not `when changes are saved`.

Name similar lifecycle events precisely. For example, distinguish `when the playback probe starts` from `when video playback begins`; the first initiates the probe, while the second confirms the player has started playing.

## Preserve the specification

- Limit restructuring to the new or changed tests unless the request explicitly includes broader test cleanup.
- Rearrange only the `describe` and `it` naming structure unless the requested work includes behavioral changes.
- Preserve assertions, test data, setup, and execution paths.
- Wrap tests without moving setup across hook boundaries; preserve each test's effective setup and execution scope.
- Run the focused specification after the restructuring and inspect its reported full test names.