michsindlinger/specwright/templates/skills/atomicity-validator

Atomicity Validator Skill

Project: Specwright (Framework) Generated: 2026-05-20 Purpose: Validate story/task atomicity per Six-Sigma Agent §4.2 (Patel et al. 2026)

Source of truth: specwright/templates/skills/atomicity-validator/SKILL.md. Do NOT edit .claude/skills/atomicity-validator/SKILL.md directly — that copy is regenerated by setup-claude-code.sh.

When to Use

• /create-spec Step 3.5.1 (V1 Classic only) — primary use
• Optional in /add-story, /add-bug, /change-spec when new stories are introduced
• V2 Lean mode uses an inline simplified subset directly in Step 2.6-lean — not this skill

This skill is advisory. It surfaces atomicity flags; the user decides whether to refine or accept.

The Three Atomicity Criteria

Source: Six-Sigma Agent paper §4.2, Definition 2. An atomic action must satisfy:

1. Minimality — cannot be meaningfully decomposed into sub-tasks without loss of semantic coherence
2. Verifiability — given input and candidate output, correctness is objectively determinable
3. Functional Determinism — given perfect reasoning, the correct output is uniquely determined by input

In Specwright terms: each story/task must be small enough, must name a concrete test oracle, and must avoid subjective vocabulary that admits multiple "correct" answers.

Heuristic Algorithms

checkPlanSectionFormat(task) — Format Validation (v3.16+)

Applies only to V2 Lean tasks (tasks with planSection field). Checks that the planSection reference is well-formed and resolvable. The check uses the plan's anchor set if available (built by Step 2.6-lean pre-scan).

Given task.planSection and planAnchors (Set<string>):

1. IF planSection matches /^System: / → PASS (system task; routes to hardcoded handler)
2. IF planSection contains '\n' → FAIL ("planSection must be a single string — never concatenate headings")
3. IF planSection matches /^[a-z0-9][a-z0-9-]{0,79}$/ (anchor-ID format):
   - IF planSection IN planAnchors → PASS (valid anchor reference)
   - ELSE → FAIL ("anchor ID '<id>' not present in implementation-plan.md; typo or stale reference")
4. IF planSection starts with '## ' or '### ' (heading-string format):
   - WARN deprecated ("plan should provide <!-- section:id --> anchors; falling back to heading-match (v3.15 compat mode)")
   - Treat as PASS for the purpose of atomicity, but emit warning so user can upgrade plan
5. ELSE → FAIL ("planSection format unknown — use anchor-ID slug or single heading string")

This catches the \n-mid-planSection class of bugs (real example from MWDS-2026-05-20) and prevents Strategy-0 silent-fallback (which would hide typos in anchor-IDs).

checkDecomposability(story) — Minimality

Inspect the story's WO: section (file paths) and WAS: field (work description).

Return FAIL if any of:

• file_count > 5 in WO section
• WAS contains AND (English) or sowie (German) connecting 3 or more distinct verbs. Example: "rename X AND add Y AND migrate Z" → 3 concerns → FAIL.
• WAS description spans ≥3 different architectural layers (frontend / backend / db / test / infra). Single-layer or two-layer = PASS.

Return PASS otherwise.

Note: file_count > 5 may also be flagged by Step 3.5 (Size). That double-coverage is intentional — different criteria, same finding.

hasConcreteOracle(story) — Verifiability

1. Locate the ## Technische Verifikation heading in the story file (case-sensitive).

   If the section is missing: return FAIL with reason "legacy story format — add Technische Verifikation section".

2. Scan lines within the section for at least one match of this regex:

   ^(FILE_EXISTS|CONTAINS|LINT_PASS|TEST_PASS|MCP_PLAYWRIGHT)\s*:\s*(.*)$
   

   Validate the argument per oracle type:

   | Oracle | Required argument | |--------|-------------------| | FILE_EXISTS: | non-empty file path | | CONTAINS: | non-empty path + search text | | LINT_PASS: | none — line just LINT_PASS: is valid | | TEST_PASS: | non-empty test path or scenario name | | MCP_PLAYWRIGHT: | non-empty scenario name |

   Arguments equal to TBD, tbd, <TODO>, ?, or empty (where required) are NOT concrete oracles → FAIL.

3. If at least one valid oracle line is found: return PASS.

containsSubjectiveVocab(story) — Functional Determinism

1. Combine text: story title + WAS: field + Akzeptanzkriterien text.
2. Lowercase, case-insensitive WORD-BOUNDARY (\b) match against the banned list.

Banned list (English): improve, polish, clean up, refactor for clarity, make better, nicer, smoother, optimize ux, optimize performance, beautify, streamline

Banned list (German): verbessern, aufräumen, optimieren, schöner, sauberer, klarer, robuster, einfacher, eleganter, übersichtlicher, polishen, vereinfachen, hübscher

3. Allowed context: any banned word followed by a measurable target counts as PASS:

   • "optimize X to <100ms" → PASS (numeric target)
   • "verbessern auf 200 req/sec" → PASS (numeric target)
   • "clean up — see TEST_PASS in section" → PASS (oracle reference)

4. If any banned word appears WITHOUT numeric metric or oracle reference: return FAIL.

5. Override: if the story's YAML frontmatter contains atomicity_override: <reason> (any non-empty reason string), skip this check entirely → PASS.

Validation Report Format

After running all three checks per story, print this Markdown table:

| Story | Minimal | Verifiable | Deterministic | Status |
|-------|---------|------------|---------------|--------|
| story-001-auth-form | ✅ | ❌ no oracle | ✅ | FLAG-VERIFY |
| story-002-rename | ❌ AND-concern | ✅ | ✅ | FLAG-MINIMAL |
| story-003-ux-polish | ✅ | ✅ | ❌ "verbessern" w/o metric | FLAG-DETERMIN |
| story-004-migration | ✅ | ✅ | ✅ | PASS |

Status legend:

• PASS — all three checks pass
• FLAG-VERIFY — Verifiability FAIL (user must add oracle or accept warning)
• FLAG-MINIMAL — Minimality FAIL (suggest re-decompose)
• FLAG-DETERMIN — Functional Determinism FAIL (suggest measurable acceptance criterion)
• Multiple flags compose: FLAG-VERIFY+MINIMAL

Advisory Decision Tree

FOR each story with Verifiability-FAIL:
  PROMPT user via AskUserQuestion:
    "Story [ID]: '[title]' has no concrete Test-Oracle.
     Acceptable oracles:
       LINT_PASS:
       TEST_PASS: <path>
       MCP_PLAYWRIGHT: <scenario>
       FILE_EXISTS: <path>
       CONTAINS: <path> <text>
     Choose:
     1. Add oracle now (enter type + argument)
     2. Skip — accept warning"

  IF "Add oracle now":
    Ask for type + argument
    Edit story file: append to "## Technische Verifikation" section
    (Create section if missing)
  IF "Skip":
    Edit YAML frontmatter to add/update:
      atomicity_status: warn-no-oracle
      atomicity_accepted_on: YYYY-MM-DD

AFTER Verifiability loop:
  IF any Minimality-FAIL or Determinism-FAIL remains:
    DISPLAY advisory per finding from "Common Pitfalls" below.
    PROMPT user:
      "1. Continue (accept flags, write audit-log)
       2. Re-decompose stories (jump back to Step 2.6)"

    IF "Re-decompose":
      INCREMENT [spec-folder]/.atomicity-retry-count
      IF retry_count >= 3: forced PROCEED with audit-log
      ELSE: JUMP TO Step 2.6 with hint listing FAIL stories

    IF "Continue":
      APPEND audit-log to spec.md tail:
        "## Atomicity Audit
         Validated on YYYY-MM-DD. Accepted flags: [list].
         Retry count: N."

Common Pitfalls (Static Advisory Text)

Use these verbatim as suggestions — no dynamic LLM generation (keep advice deterministic across runs).

Refactor for clarity / Aufräumen ohne Ziel

• Bad: WAS: Refactor module X for clarity
• Better: WAS: Extract config-loading into ConfigLoader class. Verify via TEST_PASS: tests/config/test_loader.py

Improve UX / Verbessere UX

• Bad: WAS: Improve checkout UX
• Better: WAS: Reduce checkout from 4 steps to 2 steps. Verify via MCP_PLAYWRIGHT: checkout-2step-flow

Clean up code / Vereinfachen

• Bad: WAS: Clean up logging across app
• Better: Three atomic stories: (1) Replace console.log with logger.info in auth module. (2) Same in payment. (3) Same in admin.

Multi-concern AND

• Bad: WAS: Rename UserSvc to MemberSvc AND add MFA AND migrate DB schema
• Better: Three stories with dependencies. Story 1: rename. Story 2: schema migration. Story 3: MFA feature.

Missing oracle

• Bad: Story has no ## Technische Verifikation section.
• Better: Add at least one of LINT_PASS:, TEST_PASS: <path>, MCP_PLAYWRIGHT: <scenario>, FILE_EXISTS: <path>, CONTAINS: <path> <text>.

Subjective without metric

• Bad: WAS: Optimize query performance
• Better: WAS: Optimize getUserDashboard query to <50ms p95. Verify via TEST_PASS: tests/perf/dashboard.py

Examples (Atomic vs Non-Atomic)

ATOMIC ✅

# story-014-add-mfa-totp

## Feature
Als User möchte ich MFA via TOTP aktivieren, damit mein Login sicherer ist.

## WAS:
TOTP-Endpoint /auth/mfa/totp/setup hinzufügen + UI-Component MfaSetupForm.

## WO:
- src/server/routes/auth.py (POST endpoint)
- frontend/src/components/MfaSetupForm.tsx (new)
- tests/auth/test_totp.py (new)

## Technische Verifikation
TEST_PASS: tests/auth/test_totp.py
MCP_PLAYWRIGHT: mfa-setup-flow
LINT_PASS:

All three: PASS.

NON-ATOMIC ❌

# story-007-improve-auth

## Feature
Als User möchte ich besseren Auth-Flow.

## WAS:
Improve auth UX overall. Refactor session handling AND clean up password validation AND make login smoother.

## WO:
- src/auth/session.py
- src/auth/password.py
- src/auth/login.py
- src/middleware/auth.py
- frontend/src/Login.tsx
- frontend/src/Session.tsx
- frontend/src/MFA.tsx
- tests/auth/

## Technische Verifikation
TBD

Issues:

• 7 file paths > 5 → Minimality FAIL
• "Improve" + "clean up" + "smoother" without metrics → Determinism FAIL
• "AND" connecting 3 concerns → Minimality FAIL
• TBD argument → Verifiability FAIL

Result: FLAG-VERIFY+MINIMAL+DETERMIN. Suggest split into 3 atomic stories with concrete oracles.