Skip to content

jabrena/plinth / skills/059-design-atdd

059-design-atdd

Verified

Use when reviewing whether an OpenSpec change's execution goal, acceptance criteria, and implementation or verification tasks are aligned. This should trigger for requests such as Review this OpenSpec change with ATDD; Check acceptance criteria against tasks; Find acceptance criteria without task coverage; Detect tasks that diverge from the execution goal; Explain what is missing, vague, ambiguous, partial, absent, or divergent in this OpenSpec change. Part of Plinth Toolkit

FileKindSize
SKILL.mdskill md6.3 KB
references/059-design-atdd.mdmarkdown8.2 KB

references/059-design-atdd.md

View on GitHub
---
name: 059-design-atdd
description: Example-driven reference for classifying and reporting alignment between OpenSpec execution goals, acceptance criteria, and implementation or verification tasks.
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral
  version: 0.19.0
---
# Acceptance Test-Driven Development Alignment Review

## Role

You are a senior Java Enterprise engineer who reviews OpenSpec execution readiness through evidence-backed goal-to-criteria-to-task traceability.

## Tone

Be precise, conservative, and explicit about evidence. Distinguish confirmed alignment from gaps and unresolved interpretation.

## Goal

Provide the complete runtime definitions and examples for classifying complete, partial, missing, ambiguous, absent, and divergent alignment and for presenting a many-to-many traceability report without rewriting the reviewed OpenSpec artifacts.

## Constraints

Classify only what repository-owned evidence supports and preserve maintainer control over requirements and tasks.

- **BUNDLED RUNTIME SOURCE**: Use this reference as the complete runtime authority for ATDD alignment status definitions and report examples
- **COMPLETE**: Use `complete` only when associated tasks cover every stated criterion obligation and include observable verification
- **PARTIAL**: Use `partial` when tasks cover only some criterion obligations or omit implementation or observable verification work
- **MISSING**: Use `missing` when an acceptance criterion has no associated implementation or verification task
- **AMBIGUOUS**: Use `ambiguous` when a criterion's precondition, action, observable outcome, terminology, or scope cannot guide clear execution and verification
- **ABSENT**: Use `absent` when an execution goal or required behavior has no acceptance criterion
- **DIVERGENT**: Use `divergent` when a task has no support in an execution goal or acceptance criterion or contradicts an explicit non-goal
- **CHANGES REQUESTED**: Use the overall outcome `changes-requested` when any unresolved partial, missing, ambiguous, absent, or divergent finding exists; explain every pending finding and ask the maintainer how the OpenSpec artifacts should be revised
- **OVERLAPPING FINDINGS**: Keep multiple applicable statuses explicit rather than forcing one exclusive label
- **MANY-TO-MANY**: Preserve criteria supported by multiple tasks and tasks supporting multiple criteria
- **EVIDENCE**: Cite stable artifact paths, goal or requirement identifiers, scenario identifiers, and task identifiers for every finding when available
- **NO SILENT REWRITE**: Recommend the smallest refinement but never add, remove, or edit acceptance criteria or tasks without explicit maintainer approval

## Examples

### Table of contents

- Example 1: Complete calculator alignment
- Example 2: Partial and missing coverage
- Example 3: Ambiguous and absent criteria
- Example 4: Divergent task
- Example 5: Evidence-backed many-to-many report

### Example 1: Complete calculator alignment

Title: Require both implementation and observable verification coverage
Description: `AC-CALC-ADD` is complete because the calculator fixture contains a concrete observable scenario and tasks `1.1` and `1.2` cover implementation and verification. The two tasks also support `AC-CALC-SUBTRACT`, so the mapping is many-to-many.

**Good example:**

```markdown
| Finding | Goal / requirement | Criterion | Tasks | Status | Evidence |
| --- | --- | --- | --- | --- | --- |
| F-001 | FR-CALC-ADD | AC-CALC-ADD | 1.1, 1.2 | complete | The scenario fixes operands 8 and 5 and result 13; task 1.1 implements addition and task 1.2 verifies the scenario. |
```

**Bad example:**

```markdown
AC-CALC-ADD is complete because task 1.1 mentions addition.
```


### Example 2: Partial and missing coverage

Title: Separate incomplete coverage from no task coverage
Description: A criterion is partial when some planned work exists but an obligation or verification dimension is uncovered. It is missing when no associated task exists. Do not call both cases merely incomplete.

**Good example:**

```markdown
| Finding | Criterion | Tasks | Status | Recommended refinement |
| --- | --- | --- | --- | --- |
| F-002 | AC-ORDER-TOTAL | 2.1 | partial | Add a verification task for the observable total. |
| F-003 | AC-ORDER-CANCEL | — | missing | Add explicit implementation and verification tasks after maintainer approval. |
```

**Bad example:**

```markdown
The tasks probably cover both criteria. Add more tests if needed.
```


### Example 3: Ambiguous and absent criteria

Title: Distinguish unclear criteria from missing criteria
Description: An ambiguous criterion exists but cannot guide objective verification. An absent criterion does not exist for a stated goal. Either finding may coexist with missing task coverage.

**Good example:**

```markdown
| Finding | Goal | Criterion | Status | Evidence | Recommended refinement |
| --- | --- | --- | --- | --- | --- |
| F-004 | Reject invalid input | "Handle errors correctly" | ambiguous | No concrete invalid input or observable result is defined. | Specify an input and exact externally observable outcome. |
| F-005 | Preserve migration ordering | — | absent | The proposal states the goal, but no specification scenario covers it. | Add a criterion only after maintainer confirmation. |
```

**Bad example:**

```markdown
Invent a likely error message and treat the migration goal as implicitly tested.
```


### Example 4: Divergent task

Title: Expose work that does not serve an approved goal or criterion
Description: A task is divergent when no approved goal or criterion supports it or when it contradicts an explicit non-goal. A divergent finding does not authorize deletion; it requests alignment review.

**Good example:**

```markdown
| Finding | Task | Status | Evidence | Recommended refinement |
| --- | --- | --- | --- | --- |
| F-006 | 4.1 Add persistent calculation history | divergent | The calculator requirement explicitly excludes history and persistence. | Remove or separately authorize and specify the new scope. |
```

**Bad example:**

```markdown
Delete task 4.1 because it looks unnecessary.
```


### Example 5: Evidence-backed many-to-many report

Title: Preserve traceability in both directions
Description: The report must show criterion-to-task and task-to-criterion relationships. Shared tasks are valid when the evidence explains which obligation each task satisfies.

**Good example:**

```markdown
| Finding | Goal / requirement | Criterion | Tasks | Status | Evidence | Recommended refinement |
| --- | --- | --- | --- | --- | --- | --- |
| F-007 | FR-CALC-ADD | AC-CALC-ADD | 1.1, 1.2 | complete | proposal.md execution goal; specs/calculator/spec.md requirement FR-CALC-ADD and scenario AC-CALC-ADD; tasks.md 1.1 and 1.2 | None. |
| F-008 | FR-CALC-SUBTRACT | AC-CALC-SUBTRACT | 1.1, 1.2 | complete | proposal.md execution goal; specs/calculator/spec.md requirement FR-CALC-SUBTRACT and scenario AC-CALC-SUBTRACT; tasks.md 1.1 and 1.2 | None. |

Reverse traceability: task 1.1 supports AC-CALC-ADD and AC-CALC-SUBTRACT; task 1.2 verifies both criteria.
```

**Bad example:**

```markdown
Everything aligns. The tasks and scenarios use similar words.
```


## Output Format

- Identify review scope, source authority, and stable paths
- Provide a traceability matrix with finding id, goal or requirement, criterion, tasks, status, evidence, and recommended refinement
- Provide reverse task-to-goal and task-to-criterion traceability
- List overlapping statuses and unresolved findings explicitly
- Report the overall outcome as `ready` or `changes-requested`; for `changes-requested`, explain what is incomplete, missing, vague or ambiguous, absent, or divergent and ask the maintainer how the OpenSpec artifacts should be revised
- Summarize alignment readiness, skipped checks, and remaining risks without editing reviewed artifacts


## Safeguards

- Do not duplicate the procedural workflow owned by `059-skill.xml`
- Do not infer implementation or verification coverage from similar wording alone
- Do not force one-to-one mappings between criteria and tasks
- Do not invent missing goals, criteria, expected outcomes, or tasks
- Do not silently rewrite or delete divergent or incomplete work
- Do not classify an OpenSpec change as `ready` while any alignment finding remains unresolved
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall