Acceptance Pipeline Feature Design

Acceptance Pipeline Feature Design

Guides agents through designing new features that extend Uncle Bob's Acceptance Pipeline Specification. Produces spec-quality output — language-neutral, implementation-agnostic, with precise behavioral requirements — that matches the style and rigor of the original spec.

This is a composition skill. It does not catalog what exists (that is acceptance-pipeline-catalog's job). Instead, it provides a structured workflow for designing what comes next.

When to Apply

• Designing a new mutation strategy, value type, or filter mechanism for the mutator
• Adding new Gherkin syntax support (data tables, tags, Rules keyword) to the parser
• Extending the JSON IR with new fields or objects
• Creating new report formats (HTML, JUnit XML) or output channels
• Adding new pipeline stages or operating modes (parallel runs, coverage filtering)
• Any spec-level change that affects multiple pipeline components (cross-cutting)

Prerequisite

Before using this skill, ensure acceptance-pipeline-catalog is available. That skill provides the baseline reference for the 9 required components, JSON IR schema, conformance checklist (21 items), and agent setup checklist (15 steps). This skill builds on top of that foundation.

Workflow Overview

The workflow has five phases, executed in order. Each phase builds on the output of the previous one — skipping phases produces incomplete or inconsistent designs.

Phase 1: Survey Existing Spec     → Know what exists before proposing changes
Phase 2: Identify Extension Point → Classify where the feature attaches
Phase 3: Draft Feature Spec       → Write the spec section in Uncle Bob's style
Phase 4: Conformance Design       → Add testable conformance items
Phase 5: Impact Analysis          → Assess backward compatibility and migration

Why this order matters:

• Phase 1 prevents reinventing existing capabilities and ensures the design uses established patterns.
• Phase 2 forces classification before writing — a parser extension has different constraints than a reporter extension.
• Phase 3 produces the actual spec text, informed by the classification from Phase 2.
• Phase 4 ensures the feature is testable from outside the implementation — if you cannot write conformance items, the spec is too vague.
• Phase 5 comes last because you need the complete spec and conformance items to assess impact accurately.

How to Use

1. Start by reading the acceptance-pipeline-catalog skill to understand the current spec 2. Read the phase reference that matches your current workflow step:

3. Consult supporting references as needed:

Extension Point Quick Reference

Features attach to one or more of these 9 components. The JSON IR is the highest-impact extension point because all components consume it.

Output

The workflow produces these artifacts:

1. Feature spec section — Ready to insert into the Acceptance Pipeline Specification. Written in Uncle Bob's style with purpose paragraph, behavioral requirements, data formats, and examples. 2. Conformance items — Numbered, testable items extending the existing 21-item checklist. 3. Impact analysis table — Component-by-component assessment of change type, IR effects, breaking changes, and new conformance items.

Related Skills

• acceptance-pipeline-catalog — Baseline reference for the complete spec (prerequisite)
• clean-code — Uncle Bob's coding principles (useful context for style alignment)

Gotchas

See gotchas.md for failure points discovered during use.

Gotchas

No gotchas recorded yet.

Extension Catalog

Ideas for future extensions to the Acceptance Pipeline Specification, with notes on complexity, affected components, and design considerations. Use this during Phase 2 to see if your feature matches a known pattern, and to understand the ripple effects before committing to a design.

This is not a roadmap — it is a reference for feature designers.

Parser + IR Extensions

Data Tables Attached to Steps

Complexity: Medium (3 components) Affected: Parser, IR, Runtime IR impact: New optional dataTable field on step objects

Gherkin data tables let you attach tabular data directly to a step, separate from Examples tables. The parser would need to recognize pipe-delimited rows after a step line and produce a structured table object in the IR. The runtime would need to pass table data to step handlers.

Key design question: How do data table values interact with mutation? If the mutator mutates them, it significantly increases the mutation space. If it ignores them, they become an untested blind spot.

Tag-Based Filtering

Complexity: High (4 components) Affected: Parser, IR, Runtime, Mutator IR impact: New optional tags array on feature and scenario objects

Tags (@smoke, @slow, @wip) enable selective execution and mutation scoping. The parser must accept @tag lines before Feature and Scenario keywords. The IR stores tags as string arrays. The runtime filters scenarios by tag expression. The mutator can scope mutations to tagged scenarios only.

Key design question: Tag expressions (AND, OR, NOT logic) add significant complexity. Consider starting with simple tag presence matching before adding expression support.

Rule Keyword Grouping

Complexity: Low-Medium (2 components) Affected: Parser, IR IR impact: New optional rules array wrapping scenario groups

The Rule keyword groups related scenarios under a business rule. This is purely organizational — it does not change execution behavior. The parser would need to recognize Rule blocks and the IR would nest scenarios under rule objects.

Key design question: Does grouping affect mutation? If mutations are scoped per-rule, this becomes a 3-component change (adding Mutator).

Localized Keywords

Complexity: Low (1 component) Affected: Parser only IR impact: None (parser normalizes to English keywords in the IR)

Gherkin supports keywords in many languages (e.g., French: Fonctionnalite, Scenario, Soit, Quand, Alors). The parser would accept localized keywords and normalize them to English in the IR. No downstream components are affected.

Key design question: Keyword mapping table — static or configurable? Static is simpler and covers Cucumber's standard set. Configurable allows custom keywords but adds complexity.

Runtime + Handler Extensions

Step Expression Matching

Complexity: Medium (2 components) Affected: Runtime, Handlers IR impact: None

Step expressions use {type} placeholders instead of regex: "a user named {string} aged {int}". This is more readable than regex and provides type hints. The runtime would need a new matching engine and handlers would receive typed parameters.

Key design question: Typed parameters conflict with the spec's "all values are strings" principle. The runtime would need to convert strings to types before passing to handlers, which is a significant contract change.

Before/After Hooks

Complexity: Medium (1 component) Affected: Runtime IR impact: None

Hooks run before/after each scenario, feature, or the entire suite. They handle setup and teardown (database seeding, browser launch, cleanup). The runtime would need hook registration and execution ordering.

Key design question: Hook failures — should a before-hook failure skip the scenario (mark as errored) or fail it? This affects mutation classification.

Parallel Acceptance Runs

Complexity: High (2 components) Affected: Runtime, Runner Adapter IR impact: None

Running scenarios in parallel reduces wall-clock time for large suites. The runtime would need to partition scenarios and the runner adapter would need to manage concurrent processes.

Key design question: Parallelism breaks step handler state isolation. If handlers share mutable state (database, files), parallel runs produce flaky results. The spec would need to define isolation requirements.

Mutator Extensions

Custom Mutation Strategies

Complexity: Low-Medium (1 component) Affected: Mutator IR impact: None

Allow users to define project-specific mutation rules beyond the 8 built-in value mutations. For example, a project might want to mutate email addresses, URLs, or domain-specific codes.

Key design question: How are custom strategies registered? A script-based approach (external command that transforms a value) is the most portable but slowest. A configuration-based approach (pattern + replacement in JSON) is faster but less flexible.

Coverage-Based Mutation Filtering

Complexity: High (2 components) Affected: Mutator, Reporter IR impact: None

Use code coverage data from a normal acceptance run to skip mutations that cannot possibly be detected (because no test exercises the code path). This reduces the mutation space dramatically but requires coverage tooling integration.

Key design question: Coverage data is language-specific. The spec would need to define a portable coverage format or accept that this feature is language-specific (which contradicts the spec's language-neutrality).

Reporter Extensions

HTML Report Format

Complexity: Low (1 component) Affected: Reporter only IR impact: None

Produce an HTML report with color-coded mutation results, sortable tables, and scenario-level drill-down. This is purely additive — a new output format alongside the existing text format.

Key design question: How is the output format selected? A command-line flag (--format html) is simplest. A configuration file adds flexibility but complexity.

JUnit XML Report Format

Complexity: Low (1 component) Affected: Reporter only IR impact: None

Produce JUnit-compatible XML for CI integration (Jenkins, GitHub Actions, GitLab). Most CI systems parse JUnit XML natively for test result display.

Key design question: How do mutation results map to JUnit concepts? Each mutant could be a test case, with killed = passed, survived = failed, errored = errored. But this inverts the usual pass/fail semantics (we want mutations to be killed, not survive).

Pipeline Extensions

Multi-Feature Support

Complexity: Medium-High (4 components) Affected: Parser, IR, Generator, Scripts IR impact: Top-level structure changes (array of features vs single feature)

Process multiple .feature files in a single pipeline run. The IR would need to support multiple features, the generator would need to produce tests for all features, and scripts would need to accept directories or globs.

Key design question: Does the mutator run across all features or per-feature? Cross-feature mutation is more thorough but slower and harder to attribute results.

Dry-Run Mode

Complexity: Low (1 component) Affected: Scripts (new convenience script) IR impact: None

Validate the pipeline without executing tests. Parse feature files, generate test code, but skip the runner. Useful for CI validation that the spec is well-formed before running the full suite.

Key design question: How deep does dry-run go? Parse-only is simplest. Parse + generate catches generation bugs. Parse + generate + compile (where applicable) catches the most issues but is language-specific.

Complexity Summary

Recommended starting points (low complexity, high value): 1. HTML/JUnit reports — single component, additive, high CI value 2. Localized keywords — single component, no IR change 3. Data tables — well-understood Gherkin feature, moderate complexity

Phase 1: Survey Existing Spec

Goal: Build a mental model of the complete Acceptance Pipeline Specification before proposing any changes.

Why first: Designing a feature without understanding the existing spec leads to proposals that duplicate existing capabilities, contradict established patterns, or break implicit contracts between components. The spec is tightly integrated — the JSON IR connects everything — so changes in one component ripple through others.

Steps

1.1 Load the Baseline

Read the acceptance-pipeline-catalog skill. Focus on understanding, not memorizing. You need to internalize the architecture, not recite it.

1.2 Map the 9 Required Components

Confirm you can describe what each component does and what it consumes/produces:

1.3 Understand the Two Operating Modes

Normal acceptance run:

feature file → parser → JSON IR → generator → test files → runner → pass/fail

Mutation run:

JSON IR → mutator (mutate values) → generator → test files → runner → classify each mutant

The mutation mode reuses the normal pipeline but inserts the mutator before generation. Any feature you design must work in both modes unless it explicitly only applies to one.

1.4 Understand the JSON IR

The JSON IR is the hub of the pipeline. Every component either produces it, consumes it, or both. Key properties:

• Structure: Feature → Scenarios → Steps + Examples
• All example values are strings — the mutator operates on string representations
• The IR is the canonical interchange format — changing it affects every component downstream
• IR changes are the highest-impact changes in the spec

1.5 Review the Conformance Checklist

The spec defines 21 testable conformance items. Each is:

• Observable from outside the implementation
• Binary (pass/fail)
• Grouped by component

Any new feature must add conformance items to remain testable. Review the existing items to understand the pattern and numbering.

1.6 Review the Agent Setup Checklist

The spec defines 15 steps for installing the pipeline in a new project. If your feature adds setup requirements, they must be added to this checklist.

Checklist Before Proceeding

Before moving to Phase 2, confirm:

• [ ] You can name all 9 components and their roles
• [ ] You understand both operating modes (normal + mutation)
• [ ] You know the JSON IR structure and that all values are strings
• [ ] You have reviewed the conformance checklist numbering (currently ends at 21)
• [ ] You know which Gherkin features are intentionally unsupported (and why)
• [ ] You understand the 8 value mutation rules and their priority order

If any of these are unclear, re-read the relevant section of acceptance-pipeline-catalog before proceeding.

Phase 2: Identify Extension Point

Goal: Classify exactly where the new feature attaches to the pipeline and determine its blast radius.

Why second: Classification before writing prevents scope creep. A feature that starts as "add data tables to Gherkin" might seem like a parser-only change, but actually requires IR extensions, generator changes, and runtime modifications. Classifying up front forces you to acknowledge the full scope before committing to a spec draft.

Steps

2.1 Name the Extension Category

Every feature falls into one of these categories. Pick the primary one:

If the feature is cross-cutting, list all affected components. Cross-cutting features are the most complex to design because they require coordinated changes across component boundaries.

2.2 Map Affected Spec Sections

For each affected component, identify:

1. Which spec sections describe this component? Reference by name from the catalog. 2. What existing behaviors are relevant? List the current capabilities the feature interacts with. 3. Are there implicit contracts? For example, the generator assumes every scenario has at least one example row. Does your feature change that assumption?

2.3 Classify the Change Type

For each affected component, classify the change:

Rule of thumb: If an existing, conformant implementation would break or produce different output after your change, it is modifying or breaking — not additive.

2.4 Assess IR Impact

The JSON IR question is critical enough to get its own step:

• Does this feature add new fields to the IR? If yes, are they optional or required?
• Does this feature change existing IR fields? If yes, this is almost certainly a breaking change.
• Does this feature add new top-level objects? If yes, this needs careful versioning consideration.
• Can this feature work without any IR changes? Sometimes a feature can be implemented entirely within one component (e.g., a new reporter that reads the existing IR differently).

Prefer additive IR changes (new optional fields) over modifying changes (changing existing fields). Optional fields let old implementations ignore what they do not understand.

2.5 Document the Classification

Record your classification in this format before proceeding to Phase 3:

## Feature: [Name]

**Primary category:** [Parser/IR/Generator/Runtime/Handler/Mutator/Reporter/Pipeline/Cross-cutting]
**Affected components:** [List]
**Change type per component:**
- Parser: [Additive/Modifying/Breaking/None]
- IR: [Additive/Modifying/Breaking/None]
- Generator: [Additive/Modifying/Breaking/None]
- Runtime: [Additive/Modifying/Breaking/None]
- Handlers: [Additive/Modifying/Breaking/None]
- Mutator: [Additive/Modifying/Breaking/None]
- Reporter: [Additive/Modifying/Breaking/None]
- Scripts: [Additive/Modifying/Breaking/None]

**IR impact:** [None / New optional fields / New required fields / Changed existing fields]
**Backward compatible:** [Yes/No]

Checklist Before Proceeding

• [ ] Primary extension category identified
• [ ] All affected components listed (not just the obvious one)
• [ ] Change type classified per component
• [ ] IR impact assessed explicitly
• [ ] Classification documented in the format above

Phase 3: Draft Feature Spec

Goal: Write the feature specification section in Uncle Bob's style, ready to insert into the Acceptance Pipeline Specification.

Why third: Writing the spec after classification ensures you know the scope and constraints. Writing before classification leads to specs that discover new requirements mid-draft, producing inconsistent or incomplete sections.

Spec Section Structure

Every feature spec section follows this structure. Not all subsections apply to every feature — omit those that do not apply, but follow this order for those that do.

1. Purpose Paragraph

One paragraph explaining what problem this feature solves and why it matters. Written in present tense.

Pattern:

[Component] [verb: accepts/produces/supports] [what]. This [enables/prevents/simplifies]
[user benefit]. Without this, [what problem exists].

Good example:

The parser accepts data tables attached to steps using pipe-delimited rows. This enables parameterized step definitions that operate on structured data without encoding everything as example values. Without data tables, complex test data must be hardcoded in step handlers or split across multiple steps.

Bad example:

This feature will add data table support to the parser. Data tables are useful for testing.

The purpose paragraph is the most important sentence in the section. A reader should understand the value proposition without reading further.

2. Command Interface (if applicable)

For features that add or modify CLI commands:

USAGE
    command [options] <required-arg> [optional-arg]

OPTIONS
    --flag    Description (default: value)

EXIT CODES
    0    Success description
    1    Failure description
    2    Specific failure description

Use POSIX shell conventions. Document every exit code — these are part of the contract.

3. Behavioral Requirements

Numbered list using RFC 2119 keywords (must, should, may):

1. The parser must accept pipe-delimited data tables immediately following a step line.
2. Each data table row must contain the same number of cells as the header row.
3. The parser must strip leading and trailing whitespace from cell values.
4. An empty data table (header only, no data rows) must be accepted without error.
5. The parser should reject data tables with inconsistent column counts with a diagnostic message.

Writing rules for requirements:

• Use present tense ("The parser accepts..." not "The parser will accept...")
• Use "must" for requirements, "should" for recommendations, "may" for options
• One requirement per numbered item — do not combine requirements
• Each requirement must be independently testable
• Include edge cases explicitly (empty inputs, boundary values, error conditions)
• Reference existing spec terminology consistently (use "JSON IR" not "intermediate representation")

4. Data Format (if applicable)

For features that add or change data structures:

1. Show the JSON schema with types 2. Provide a concrete example with realistic values 3. Document every field — type, whether required or optional, default value if optional 4. Show how the new structure nests within the existing IR

Pattern:

{
  "steps": [
    {
      "keyword": "Given",
      "text": "the following users exist",
      "dataTable": {
        "headers": ["name", "email", "role"],
        "rows": [
          ["Alice", "alice@example.com", "admin"],
          ["Bob", "bob@example.com", "member"]
        ]
      }
    }
  ]
}

Then document:

dataTable (object, optional): Attached data table for this step.
  headers (array of string, required): Column names from the first pipe-delimited row.
  rows (array of array of string, required): Data rows. Each inner array has the same
    length as headers. May be empty (header-only table).

Critical: All values in the IR are strings. Even if a value looks like a number, it is stored and transmitted as a string. The mutator depends on this — it applies string-based mutation rules.

5. Error Handling

For each failure mode:

• What triggers it (input condition)
• What the component produces (error message, exit code)
• Whether processing continues or halts

Pattern:

**Inconsistent column count:** If a data row contains fewer or more cells than the header
row, the parser must emit a diagnostic referencing the line number and expected column
count, then skip the malformed row. Parsing continues — this is a warning, not a fatal error.

Do not silently swallow errors. Every error condition must produce observable output.

6. Interaction with Existing Components

Describe how this feature changes the pipeline flow. For each affected component, state:

• What new input it receives (if any)
• What new output it produces (if any)
• What existing behavior changes (if any)
• What remains unchanged (explicitly)

This section prevents hidden coupling. If you cannot describe the interaction, the feature is under-specified.

Style Checklist

Before finalizing the spec draft, verify it follows the style guide (see style-guide.md):

• [ ] Language-neutral — no language-specific syntax or idioms
• [ ] Implementation-agnostic — describes what, not how
• [ ] POSIX shell for all script examples
• [ ] JSON for all data format examples
• [ ] Gherkin for all feature file examples
• [ ] Present tense throughout
• [ ] Must/should/may used consistently per RFC 2119
• [ ] Concrete examples for every data format
• [ ] Each section is self-contained (readable without the rest of the spec)
• [ ] Edge cases addressed explicitly, not left to "implementation discretion"
• [ ] Exit codes documented for any CLI-facing behavior
• [ ] No vague phrases ("appropriate error", "relevant information", "as needed")

Common Mistakes

Specifying implementation details: The spec says WHAT, not HOW. "The parser must produce a dataTable object" is correct. "The parser must use a recursive descent approach to parse data tables" is implementation detail.

Forgetting mutation mode: Every IR change must be evaluated for mutation impact. If you add a dataTable field, does the mutator mutate table cell values? If yes, specify the mutation rules. If no, specify that the mutator ignores it.

Assuming optional means ignorable: Optional IR fields still need behavior specified for when they are absent vs present. "If dataTable is absent, the step has no attached data. If present, the runtime must pass table data to the step handler."

Under-specifying string encoding: All IR values are strings. If your feature introduces values that look like numbers or booleans, specify that they are stored as strings and any type interpretation happens at the consumer, not in the IR.

Phase 4: Conformance Design

Goal: Define testable conformance items for every new capability introduced by the feature.

Why fourth: Conformance items are the spec's enforcement mechanism. A feature without conformance items is a suggestion, not a requirement. Writing them after the spec draft ensures they test what was actually specified, not what you intended to specify. If you cannot write a conformance item for a requirement, the requirement is too vague — go back to Phase 3 and tighten it.

What Makes a Good Conformance Item

Each conformance item must be:

Writing Pattern

Conformance items follow this grammar:

[Component] [verb] [what] [condition/constraint].

Good examples:

22. Parser accepts pipe-delimited data tables immediately following a step line.
23. Parser rejects data tables with inconsistent column counts and emits a diagnostic.
24. IR writer includes dataTable object in step output when a data table is present.
25. IR writer omits dataTable field when no data table is attached to a step.
26. Runtime passes data table contents to step handler as a structured argument.

Bad examples:

22. Data tables work correctly.                    — Not specific, not binary
23. The parser should handle data tables well.     — Subjective, uses "should"
24. Implementation supports data table parsing.    — "Implementation" is vague

Process

4.1 Extract Testable Requirements

Go through each behavioral requirement from Phase 3 and ask: "How would an external tester verify this?" If the answer involves inspecting internal state, the requirement needs to be rephrased as an observable behavior.

4.2 Add Negative Cases

For every positive conformance item, consider the negative:

• What input should be rejected? (Parser rejects X)
• What output should be absent? (IR omits X when Y)
• What behavior should not change? (Mutator ignores dataTable field)

Negative cases catch regressions. If you only test that data tables work when present, you miss bugs where data tables appear when they should not.

4.3 Consider Mutation Mode

If the feature affects mutation mode:

• Does the mutator interact with new IR fields? Add conformance items for mutation behavior.
• Does the feature change how mutants are classified? Add items for classification accuracy.
• Does the feature affect mutation determinism? Add items verifying deterministic output with the same seed.

4.4 Number and Group

• Number sequentially from 22 (the next available after the existing 21)
• Group by component for readability
• Keep the numbering continuous — do not leave gaps

Output format:

## New Conformance Items

### Parser
22. Parser accepts pipe-delimited data tables immediately following a step line.
23. Parser rejects data tables with inconsistent column counts and emits a line-number diagnostic.
24. Parser strips leading and trailing whitespace from data table cell values.

### IR
25. IR writer includes dataTable object with headers and rows arrays when data table is present.
26. IR writer omits dataTable field entirely when no data table is attached to a step.

### Runtime
27. Runtime passes data table contents to step handler as a structured argument.
28. Runtime raises an error if a step handler expects a data table but none is attached.

### Mutator
29. Mutator applies value mutation rules to data table cell values.
30. Mutator preserves data table structure (headers unchanged, row count unchanged).

Estimating Count

A well-specified feature typically produces 2-5 conformance items per affected component. If you have fewer than 2 per component, you may be under-specifying. If you have more than 5 per component, you may be over-specifying — consider whether some items are testing the same capability from different angles.

Checklist Before Proceeding

• [ ] Every behavioral requirement from Phase 3 has at least one conformance item
• [ ] Negative cases included (rejection, absence, no-change)
• [ ] Mutation mode impact covered (or explicitly noted as not affected)
• [ ] Items are numbered sequentially from 22
• [ ] Items are grouped by component
• [ ] Each item is observable, binary, and specific

Phase 5: Impact Analysis

Goal: Assess backward compatibility, migration requirements, and the full blast radius of the proposed feature.

Why last: Impact analysis requires the complete spec draft (Phase 3) and conformance items (Phase 4) to be accurate. Analyzing impact on an incomplete design produces false confidence — you think the change is safe, but you missed a component interaction that only becomes visible when writing conformance items.

Steps

5.1 Component-by-Component Assessment

For each of the 9 components, answer these questions:

5.2 Classify Overall Change

Based on the per-component assessment, classify the overall feature:

Additive — New capability, no existing behavior changes. An existing conformant implementation continues to pass all 21 existing conformance items without modification.

Indicators:

• New optional IR fields only
• New commands alongside existing ones
• New exit codes that were previously undefined
• New conformance items that only apply to implementations claiming the new feature

Modifying — Existing behavior changes. An existing conformant implementation may need updates to pass existing conformance items, or existing conformance items are reworded.

Indicators:

• Required IR fields change meaning
• Existing commands gain new required arguments
• Exit code meanings change
• Existing conformance items are modified

Breaking — Existing interfaces change in incompatible ways. An existing conformant implementation will fail existing conformance items.

Indicators:

• IR fields removed or renamed
• Commands removed or renamed
• Exit codes reassigned
• Conformance items removed or fundamentally changed

5.3 For Breaking Changes: Mitigation

If any component has a breaking change, explore these mitigation strategies in order of preference:

1. Make it additive with an opt-in flag. Can the new behavior be activated by a flag while preserving the old default? This is the strongest mitigation because existing users are unaffected.

2. Add a deprecation period. Can the old behavior be preserved alongside the new behavior for one version, with a deprecation warning?

3. Provide a migration script. Can a script convert existing IR files, configuration, or step handlers to the new format?

4. Document the minimum viable change. What is the smallest change that still solves the problem? Sometimes breaking changes are proposed because the first design was ambitious, but a smaller additive change is possible.

If none of these work, the breaking change may be justified — but document why each mitigation strategy was rejected.

5.4 Produce the Impact Summary Table

This table is the primary output of Phase 5. It gives a complete picture at a glance.

| Component | Change Type | IR Affected | Breaking | Conformance Items | Notes |
|-----------|------------|-------------|----------|-------------------|-------|
| Parser    | Additive   | Yes         | No       | 22, 23, 24        | New syntax only |
| IR        | Additive   | Yes         | No       | 25, 26            | New optional field |
| Generator | Modifying  | N/A         | No       | —                 | Must handle new field |
| Runtime   | Additive   | N/A         | No       | 27, 28            | New handler argument |
| Handlers  | None       | N/A         | No       | —                 | User-authored, no spec change |
| Mutator   | Additive   | No          | No       | 29, 30            | Mutates table values |
| Reporter  | None       | N/A         | No       | —                 | No change |
| Runner    | None       | N/A         | No       | —                 | No change |
| Scripts   | Additive   | N/A         | No       | —                 | No new scripts needed |

Column definitions:

• Change Type: Additive, Modifying, Breaking, or None
• IR Affected: Does this component's change involve IR schema changes?
• Breaking: Would this break an existing conformant implementation of this component?
• Conformance Items: Which new items (from Phase 4) apply to this component?
• Notes: Brief justification or clarification

5.5 Agent Setup Checklist Impact

If the feature requires new setup steps:

• Where in the 15-step checklist do they go?
• Are they required for all users or only those using the new feature?
• Do they add new dependencies?

If no setup changes are needed, state explicitly: "No changes to agent setup checklist."

5.6 Write the Impact Summary

Combine everything into a concise summary:

## Impact Summary: [Feature Name]

**Overall classification:** [Additive/Modifying/Breaking]
**IR changes:** [None / New optional fields / New required fields / Changed existing fields]
**Backward compatible:** [Yes/No]
**Migration required:** [None / Script provided / Manual steps documented]
**Setup checklist changes:** [None / New steps added]
**Conformance items added:** [Count] (items [range])

[Impact summary table from 5.4]

### Risk Assessment
[1-3 sentences on the highest-risk aspects of this change]

### Recommendation
[1-2 sentences: proceed as designed / simplify to reduce blast radius / prototype first]

Checklist: Feature Design Complete

After Phase 5, the complete feature design package includes:

• [ ] Phase 1 output: Confirmed understanding of existing spec
• [ ] Phase 2 output: Extension point classification with change types per component
• [ ] Phase 3 output: Feature spec section (purpose, requirements, data formats, interactions)
• [ ] Phase 4 output: Numbered conformance items grouped by component
• [ ] Phase 5 output: Impact summary table with classification, migration notes, and recommendation

Uncle Bob's Spec Writing Style Guide

This guide extracts the writing patterns used in the Acceptance Pipeline Specification. Use it during Phase 3 to ensure your feature spec reads as a natural extension of the original.

Document Structure Patterns

Section Organization

The spec organizes each component with this consistent structure:

1. Component name as heading — e.g., "Gherkin Parser", "Mutation Engine" 2. Purpose paragraph — What the component does and why it exists 3. Interface — Commands, arguments, exit codes (where applicable) 4. Behavioral requirements — Numbered must/should/may statements 5. Data formats — JSON schemas and concrete examples 6. Edge cases and errors — Explicit handling for boundary conditions

Every section is self-contained. A reader should understand the section without having read the rest of the spec. Cross-references are used sparingly and only to connect related concepts, not to avoid repetition.

Heading Hierarchy

# Spec Title
## Component Name
### Subsection (e.g., "Command Interface", "Data Format")
#### Sub-subsection (rare, only for complex data structures)

Do not go deeper than ####. If you need more depth, the section is too complex — split it.

Terminology Conventions

RFC 2119 Keywords

Use lowercase throughout. The spec does not use ALL CAPS RFC 2119 keywords.

Pipeline Terminology

Use these terms consistently — they are established in the spec:

Portable vs Project-Specific

The spec distinguishes between:

• Portable commands — Work anywhere (POSIX shell, standard tools)
• Project-specific commands — Depend on the project's test runner, language, or framework

Spec examples always use portable commands. Project-specific behavior is described abstractly: "The runner adapter invokes the project's test runner" — not "The runner adapter runs pytest."

Code Block Conventions

POSIX Shell for Scripts

All script examples use POSIX shell (sh), not Bash. This means:

• No [[ ]] — use [ ]
• No arrays — use positional parameters
• No local keyword in functions (not POSIX) — use subshells for scope
• No source — use .
• Always include set -e at the top

#!/bin/sh
set -e

feature_file="$1"
output_dir="$2"

if [ -z "$feature_file" ]; then
  echo "Usage: acceptance-run <feature-file> [output-dir]" >&2
  exit 1
fi

JSON for Data Formats

All data format examples use JSON with realistic values — not placeholders:

Good:

{
  "feature": "User Login",
  "scenarios": [
    {
      "name": "valid credentials",
      "steps": [
        {"keyword": "Given", "text": "a user with email <email>"}
      ],
      "examples": {
        "headers": ["email", "password"],
        "rows": [
          ["alice@example.com", "correct-password"],
          ["bob@example.com", "also-correct"]
        ]
      }
    }
  ]
}

Bad:

{
  "feature": "...",
  "scenarios": [{"...": "..."}]
}

Gherkin for Feature Files

Feature file examples use the supported Gherkin subset only:

Feature: User Login

  Scenario Outline: valid credentials
    Given a user with email <email>
    When the user logs in with password <password>
    Then the response status is <status>

    Examples:
      | email             | password         | status |
      | alice@example.com | correct-password | 200    |
      | bob@example.com   | wrong-password   | 401    |

Writing Good vs Bad Spec Prose

Present Tense

Good: "The parser accepts pipe-delimited data tables." Bad: "The parser will accept pipe-delimited data tables." Bad: "The parser should be able to accept pipe-delimited data tables."

Specific Over Vague

Good: "The mutator replaces the string true with false and vice versa." Bad: "The mutator handles boolean values appropriately."

Good: "Exit code 0 indicates all scenarios passed. Exit code 1 indicates one or more scenarios failed. Exit code 2 indicates a parser error." Bad: "The script returns an appropriate exit code."

Behavioral Over Structural

Good: "The parser emits a diagnostic on stderr when encountering an unsupported keyword, including the line number and the keyword found." Bad: "The parser has error handling for unsupported keywords."

Self-Contained Sections

Each section should be understandable without reading the full spec. This means:

• Define terms on first use within a section (or reference the terminology section)
• Do not rely on "as described above" — name the specific section
• Include a concrete example even if a similar one appears elsewhere

Requirements as Observable Behaviors

Good: "When the feature file contains a Background section, the parser includes background steps in every scenario's step list in the JSON IR." Bad: "The parser handles Background sections correctly."

The first version tells you exactly what to test. The second requires you to already know what "correctly" means.

Exit Code Conventions

The spec uses a consistent exit code scheme:

New features should reuse these codes where they apply and allocate new codes only for genuinely new failure modes. Document new exit codes in the command interface section.

Field Requirement Documentation

When documenting JSON fields, use this format:

fieldName (type, required|optional [, default: value]): Description.
  Constraints or notes on a new indented line.

Example:

dataTable (object, optional): Attached data table for this step.
  headers (array of string, required): Column names from the header row.
    Must contain at least one element.
  rows (array of array of string, required): Data rows, each with length equal to headers.
    May be empty (header-only table is valid).

This format is scannable, consistent, and makes it easy to verify that every field is documented with type, optionality, and constraints.

Scripts

No automation scripts yet. Add scripts here for deterministic tasks like:

• Spec section template generation
• Conformance item numbering validation
• Impact analysis table generation