TDD Spec — Test-Driven Specification Writer

[MANDATORY] You MUST use TaskCreate to break ALL work into small tasks BEFORE starting. NEVER skip task creation.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Process Discipline: MUST READ .claude/skills/shared/rationalization-prevention-protocol.md — prevents "tests aren't relevant" and "I'll test after" evasions.

Quick Summary

Goal: Generate or update test specifications in feature docs Section 17 (canonical TC registry) using the unified TC-{FEATURE}-{NNN} format. Supports 5 modes: TDD-first, implement-first, update (post-change/PR), sync, and from-integration-tests.

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

MANDATORY IMPORTANT MUST Plan ToDo Task to READ the following project-specific reference doc:

.claude/skills/shared/references/module-codes.md — TC ID format and feature codes

.claude/skills/shared/evidence-based-reasoning-protocol.md — Evidence requirements

.claude/skills/shared/cross-cutting-quality-concerns-protocol.md — Authorization, Seed Data, Performance Data, Data Migration TC requirements

.claude/skills/tdd-spec/references/tdd-spec-template.md — TC template format

docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

docs/test-specs/ — Test specifications by module (read existing TCs before generating new to avoid duplicates and maintain TC ID continuity)

Workflow:

Mode Detection — Determine mode: TDD-first, implement-first, update, sync, or from-integration-tests
Investigation — Analyze PBI/codebase/existing TCs/git changes based on mode
TC Generation — Generate TC outlines, review interactively with user
Write to Feature Doc — Upsert TCs into target feature doc Section 17
Dashboard Sync — Optionally update docs/test-specs/ cross-module dashboard
Next Steps — Suggest follow-on actions based on mode

Key Rules:

Unified format: TC-{FEATURE}-{NNN} — see module-codes.md for feature codes
Source of truth: Feature docs Section 17 is the canonical TC registry
Evidence required: Every TC MUST have Evidence: {FilePath}:{LineRange} or TBD (pre-implementation) for TDD-first mode
Minimum 4 categories: Positive (happy path), negative (error handling), authorization (role-based access), edge cases
Cross-cutting TC categories (ref: .claude/skills/shared/cross-cutting-quality-concerns-protocol.md):
- Authorization TCs (mandatory): Authorized access succeeds, unauthorized access rejected, role-based visibility verified
- Seed Data TCs (if applicable): Reference data exists, seeder runs correctly
- Performance TCs (if applicable): Feature performs within SLA under production-like data volume
- Data Migration TCs (if applicable): Data transforms correctly, rollback works, no data loss
Interactive review: ALWAYS use AskUserQuestion to review TC list with user before writing

Quick Reference

Related Skills

Skill	Relationship
`test-spec`	Heavyweight planning/investigation → feeds into this skill
`test-specs-docs`	Dashboard writer → syncs FROM feature docs Section 17
`integration-test`	Code generator → generates integration tests FROM TCs written by this skill
`feature-docs`	Feature doc creator → creates the Section 17 that this skill populates

Output Locations

Artifact	Path
TCs (canonical)	`docs/business-features/{App}/detailed-features/{feature}.md` Section 17
Dashboard (optional)	`docs/test-specs/{Module}/README.md` Implementation Index
Priority index (optional)	`docs/test-specs/PRIORITY-INDEX.md`

Phase-Mapped Coverage: When a plan exists with multiple phases, generate test cases PER PHASE — not just per feature. Each phase's success criteria MUST have ≥1 test case. See .claude/skills/shared/iterative-phase-quality-protocol.md.

Detailed Workflow

Phase 1: Mode Detection & Context

Detect mode from user prompt and context:

Mode	Signal	Action
TDD-first	PBI/story exists, code not yet written	Generate specs from requirements
Implement-first	Code already exists, no/incomplete TCs	Generate specs from codebase analysis
Update	Existing TCs + code changes / bugfix / PR	Diff existing TCs against current code/PR, find gaps, update both
Sync	User says "sync test specs" or bidirectional need	Reconcile feature docs ↔ docs/test-specs/ (either direction)
From-integration-tests	Tests exist with test spec annotations, no docs	Extract TC metadata from test code → write to feature docs

Must read FIRST:

module-codes.md — identify the correct {FEATURE} code for TC IDs
Target feature doc — check if Section 17 exists, read existing TCs to avoid ID collisions

If target feature doc doesn't exist:

Suggest running /feature-docs first, OR
Create a minimal Section 17 stub in the appropriate feature doc

Phase 2: Investigation

TDD-first mode:

Read the PBI/story document (from team-artifacts/pbis/ or user-provided)
Extract acceptance criteria
Identify test categories: CRUD operations, validation rules, authorization (mandatory), workflows, edge cases, seed data, performance data, data migration
Cross-reference with existing feature doc requirements (Sections 1-16)
Cross-reference PBI Authorization section → generate authorization TCs (unauthorized access rejection per role)
Cross-reference PBI Seed Data section → generate seed data TCs if reference/config data needed
Cross-reference PBI Data Migration section → generate migration TCs if schema changes exist

Implement-first mode:

Grep for commands/queries in the target service: grep -r "class.*Command.*:" src/Services/{service}/
Grep for entities and domain events
Trace code paths: Controller → Command → Handler → Entity → Event Handler
Identify testable behaviors from actual implementation

Update mode (post-change / post-bugfix / post-PR):

Read existing Section 17 TCs
git diff or git diff main...HEAD (for PRs) to find code changes since TCs were last updated
Identify: new commands/queries not covered, changed behaviors, removed features
For bugfixes: add a regression TC for the bug that was fixed (e.g., TC-GM-040: Regression — goal title validation bypass)
Generate gap analysis
Update both feature docs Section 17 AND docs/test-specs/ dashboard

Sync mode (bidirectional reconciliation):

Read feature docs Section 17 TCs for target module
Read docs/test-specs/{Module}/README.md TCs
Read test files: grep for test spec annotations in src/Services/{service}*.IntegrationTests/
Build 3-way comparison table:

| TC ID | In Feature Doc? | In test-specs/? | In Test Code? | Action Needed |
|-------|----------------|-----------------|---------------|---------------|
| TC-OM-001 | ✅ | ✅ | ✅ | None |
| TC-OM-025 | ✅ | ❌ | ✅ | Add to test-specs/ |
| TC-OM-030 | ❌ | ✅ | ❌ | Add to feature doc |

Reconcile: write missing TCs to whichever system lacks them
Feature docs remain source of truth — any conflict uses feature doc version

From-integration-tests mode (reverse-engineer specs from existing tests):

Grep for [Trait("TestSpec", "TC-...")] in target test project
For each test method: extract TC ID, method name, test description from comments
Read the test method body to generate GWT steps and evidence
Write extracted TCs to feature doc Section 17 (if not already there)
Useful when: tests were written before the spec system existed, or imported from another project

Phase 3: TC Generation with Interactive Review

Generate TC outlines as a summary table:

| TC ID | Name | Priority | Category | Status |
|-------|------|----------|----------|--------|
| TC-GM-037 | Create goal with cascading key results | P0 | CRUD | New |
| TC-GM-038 | Reject goal without required title | P1 | Validation | New |
| TC-GM-039 | External user cannot access goals | P0 | Permission | New |

Use AskUserQuestion to review with user:

Question: "These {N} test cases cover {feature}. Review the list:"
Options:
- "Approve as-is (Recommended)" — Proceed to writing
- "Add missing scenario" — Describe what's missing
- "Adjust priorities" — Change P0/P1/P2 assignments
- "Regenerate" — Re-analyze and try again

Iterate until user approves.

Phase 4: Write to Feature Doc Section 17

This is the canonical write — feature docs own the TCs.

Locate Section 17 in target feature doc
If Section 17 exists: append new TCs after existing ones, preserving existing TC IDs
If Section 17 doesn't exist: create it from template
Use Edit tool to upsert — never overwrite existing TCs

TC format (from tdd-spec-template.md):

#### TC-{FEATURE}-{NNN}: {Descriptive Test Name} [{Priority}]

**Objective:** {What this test verifies}

**Preconditions:**

- {Setup requirement}

**Test Steps:**
\`\`\`gherkin
Given {initial state}
And {additional context}
When {action}
Then {expected outcome}
And {additional verification}
\`\`\`

**Acceptance Criteria:**

- ✅ {Success behavior}
- ❌ {Failure behavior}

**Test Data:**
\`\`\`json
{ "field": "value" }
\`\`\`

**Edge Cases:**

- {Boundary condition}

**Evidence:** `{FilePath}:{LineRange}` or `TBD (pre-implementation)`

Evidence rules by mode:

TDD-first: Evidence: TBD (pre-implementation) — will be updated after implementation
Implement-first: Evidence: {actual file}:{actual lines} — trace to real code
Update: Update existing evidence references if code moved

Phase 5: Update docs/test-specs/ Dashboard (Optional)

If docs/test-specs/{Module}/README.md exists:

Update the Implementation Index section with new TC→test method mappings
For TDD-first: map to expected test method names (will be created by /integration-test)
Update PRIORITY-INDEX.md with new TC entries in correct priority tier

Skip this phase if user says "skip dashboard" or if no docs/test-specs/ file exists for the module.

Phase 6: Next Step Suggestion

Based on mode, suggest via AskUserQuestion:

TDD-first:

1. "/integration-test — Generate test stubs from these TCs (Recommended)"
2. "/plan — Plan the feature implementation"
3. "Done for now — I'll implement later"

Implement-first:

1. "/integration-test — Generate integration tests (Recommended)"
2. "/review-changes — Review all changes"
3. "Done for now"

Update (post-change/PR):

1. "/integration-test — Generate/update tests for changed TCs (Recommended)"
2. "/test — Run existing tests to verify coverage"
3. "/test-specs-docs — Sync dashboard with updated TCs"
4. "Done for now"

Sync:

1. "/test-specs-docs — Sync dashboard after reconciliation (Recommended)"
2. "/integration-test — Generate tests for any TCs missing test coverage"
3. "Done for now"

From-integration-tests:

1. "/test-specs-docs — Sync dashboard with newly documented TCs (Recommended)"
2. "/test — Run tests to verify all documented TCs pass"
3. "Done for now"

Anti-Patterns

❌ Writing TCs to docs/test-specs/ as the primary destination (use feature docs Section 17)
❌ Using TC-{SVC}-{NNN} or TC-{SVC}-{FEATURE}-{NNN} format (use unified TC-{FEATURE}-{NNN})
❌ Generating TCs without reading existing Section 17 (causes ID collisions)
❌ Skipping the interactive review step (user must approve TC list)
❌ Writing TCs without Evidence field (every TC needs it, even if TBD)

Workflow Recommendation

IMPORTANT MUST: If you are NOT already in a workflow, use AskUserQuestion to ask the user:

Activate pbi-to-tests workflow (Recommended) — tdd-spec → tdd-spec-review → quality-gate

Execute /tdd-spec directly — run this skill standalone

Next Steps

MANDATORY IMPORTANT MUST after completing this skill, use AskUserQuestion to recommend:

"/integration-test (Recommended)" — Generate integration test code from specs
"/test" — Run tests to verify implementation
"Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST add a final review todo task to verify work quality.

tdd-spec