This skill creates and validates test documentation: testing-strategy.md (universal testing philosophy) + tests/README.md (test organization structure and Story-Level Test Task Pattern).

When to Use This Skill

This skill is a L2 WORKER invoked by ln-100-documents-pipeline orchestrator.

This skill should be used directly when:

Creating only test documentation (testing-strategy.md + tests/README.md)
Validating existing test documentation structure and content
Setting up test philosophy and structure documentation for existing project
NOT creating full documentation structure (use ln-100-documents-pipeline for complete setup)

How It Works

The skill follows a 3-phase workflow: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT. Each phase builds on the previous, ensuring complete structure and semantic validation.

Phase 1: Create Test Documentation

Objective: Establish test philosophy and documentation structure.

Process:

1.1 Check & create directories:

Check if docs/reference/guides/ exists → create if missing
Check if tests/ exists → create if missing
Check if tests/manual/ exists → create if missing
Check if tests/manual/results/ exists → create if missing
Add tests/manual/results/ to project .gitignore if not present
Log for each: "✓ Created [directory]/" or "✓ [directory]/ already exists"

1.2 Check & create documentation files:

Check if docs/reference/guides/testing-strategy.md exists
If exists:

Skip creation

Log: "✓ testing-strategy.md already exists, proceeding to validation"
If NOT exists:

Copy template: ln-114-test-docs-creator/references/testing_strategy_template.md → docs/reference/guides/testing-strategy.md

Replace placeholders:

[CURRENT_DATE] — current date (YYYY-MM-DD)

Log: "✓ Created testing-strategy.md from template"
Check if tests/README.md exists
If exists:

Skip creation

Log: "✓ tests/README.md already exists, proceeding to validation"
If NOT exists:

Copy template: ln-114-test-docs-creator/references/tests_readme_template.md → tests/README.md

Replace placeholders:

{{DATE}} — current date (YYYY-MM-DD)

Log: "✓ Created tests/README.md from template"

1.3 Output:

docs/reference/guides/
└── testing-strategy.md           # Created or existing

tests/
├── README.md                     # Created or existing
└── manual/
    └── results/                  # Created, added to .gitignore

Phase 2: Validate Structure

Objective: Ensure test documentation files comply with structural requirements and auto-fix violations.

Process:

2.1 Check SCOPE tags:

Read both files (testing-strategy.md, tests/README.md) - first 5 lines only
Check for  tag in each
Expected SCOPE tags:

testing-strategy.md: 

tests/README.md: 
If missing in either file:

Use Edit tool to add SCOPE tag at line 1 (before first heading)

Track violation: scope_tags_added += 1

2.2 Check required sections:

Load expected sections from references/questions.md
For testing-strategy.md, required sections:

"Testing Philosophy"

"Test Levels"
For tests/README.md, required sections:

"Test Organization"

"Running Tests"
For each file:

Read file content

Check if ## [Section Name] header exists
If missing:

Use Edit tool to add section with placeholder content from template

Track violation: missing_sections += 1

2.3 Check Maintenance section:

For each file (testing-strategy.md, tests/README.md):

Search for ## Maintenance header

If missing:

Use Edit tool to add at end of file:

## Maintenance

**Last Updated:** [current date]

**Update Triggers:**
- Test framework changes
- Test organization changes
- New test patterns introduced

**Verification:**
- [ ] All test examples follow current framework syntax
- [ ] Directory structure matches actual tests/
- [ ] Test runner commands are current

Track violation: maintenance_added += 1

2.4 Check POSIX file endings:

For each file:

Check if file ends with single blank line (LF)

If missing:

Use Edit tool to add final newline

Track fix: posix_fixed += 1

2.5 Report validation:

Log summary:

✅ Structure validation complete:
  - SCOPE tags: [added N / already present]
  - Missing sections: [added N sections]
  - Maintenance sections: [added N / already present]
  - POSIX endings: [fixed N / compliant]

If violations found: "⚠️ Auto-fixed [total] structural violations"

Phase 3: Validate Content

Objective: Ensure each section answers its questions with meaningful content and populate test-specific sections from auto-discovery.

Process:

3.1 Load validation spec:

Read references/questions.md
Parse questions and validation heuristics for 4 sections (2 per file)

3.2 Validate testing-strategy.md sections:

For this file, use standard template content (no auto-discovery needed):

Testing Philosophy section:

Read section content

Check validation heuristics from questions.md:

✅ Mentions "Risk-Based Testing"

✅ Has test pyramid description
✅ Mentions priority threshold (≥15)
✅ References Story-Level Test Task Pattern
✅ Length > 100 words
If ANY heuristic passes → content valid
If ALL fail → log warning: "⚠️ testing-strategy.md → Testing Philosophy section may need review"
Test Levels section:

Read section content

Check validation heuristics from questions.md:

✅ Lists 3 levels (E2E, Integration, Unit)

✅ Has numeric ranges (2-5, 3-8, 5-15)
✅ Explains rationale
✅ Length > 150 words
If ANY heuristic passes → content valid
If ALL fail → log warning: "⚠️ testing-strategy.md → Test Levels section may need review"

Note: testing-strategy.md is universal philosophy - no project-specific auto-discovery needed.

3.3 Validate tests/README.md sections with auto-discovery:

Section: Test Organization

Auto-discover test framework:

Check package.json → "devDependencies" and "dependencies":

Node.js frameworks: jest, vitest, mocha, ava, tap, jasmine

If found: Extract name and version
Check requirements.txt (if Python project):

Python frameworks: pytest, nose2, unittest2

If found: Extract name and version
Check go.mod (if Go project):

Go uses built-in testing package

If framework detected:

Log: "✓ Test framework detected: [framework]@[version]"

Track: framework_detected = "[framework]"
If NOT detected:

Log: "⚠️ No test framework detected. Will use generic test organization."

Track: framework_detected = None
Auto-discover test directory structure:

Use Glob tool to scan tests/ directory:

Pattern: "tests/e2e/**/*.{js,ts,py,go}"

Pattern: "tests/integration/**/*.{js,ts,py,go}"
Pattern: "tests/unit/**/*.{js,ts,py,go}"
Count files in each directory:

e2e_count = len(e2e_files)

integration_count = len(integration_files)
unit_count = len(unit_files)
If directories exist:

Log: "✓ Test structure: [e2e_count] E2E, [integration_count] Integration, [unit_count] Unit tests"

If directories DON'T exist:

Create placeholder structure:

tests/
  e2e/       (empty, ready for E2E tests)
  integration/  (empty, ready for Integration tests)
  unit/      (empty, ready for Unit tests)

Log: "✓ Created test directory structure (will be populated during Story test task execution)"
Auto-discover naming conventions:

For each test file found (from step 2):

Extract filename pattern:

*.test.js → "*.test.js" convention

*.spec.ts → "*.spec.ts" convention
test_*.py → "test_*.py" convention
*_test.go → "*_test.go" convention
Count occurrences of each pattern
Use most common pattern (majority rule)
If pattern detected:

Log: "✓ Naming convention: [pattern] (detected from [count] files)"

If NO files exist:

Use framework default:

Jest/Vitest → *.test.js

Mocha → *.spec.js
Pytest → test_*.py
Go → *_test.go
Log: "✓ Naming convention: [default_pattern] (framework default)"
Check Test Organization section content:

Read section from tests/README.md

Check validation heuristics:

✅ Describes directory structure (e2e/integration/unit)

✅ Mentions naming conventions
✅ References Story-Level Test Task Pattern
✅ Has framework mention
If ANY heuristic passes → content valid
If ALL fail → log warning: "⚠️ tests/README.md → Test Organization section needs update"

Section: Running Tests

Auto-discover test runner command:

Read package.json → "scripts" → "test"

If found:

Extract command value

Examples:

"jest" → Test runner: "npm test" (runs jest)

"vitest" → Test runner: "npm test" (runs vitest)
"mocha" → Test runner: "npm test" (runs mocha)
Custom script → Test runner: "npm test" (runs [custom])
Log: "✓ Test runner: npm test (runs [command])"
If NOT found (no package.json or no test script):

Use default based on detected framework (from step 3.3.1):

Jest → "npm test"

Vitest → "npm test"
Pytest → "pytest"
Go → "go test ./..."
Log: "⚠️ No test script found in package.json. Using default '[command]'."
Auto-discover coverage command (optional):

Check package.json → "scripts" for:

"test:coverage"

"coverage"
"test:cov"
If found:

Extract command

Log: "✓ Coverage command: npm run [script_name]"
If NOT found:

Use framework default:

Jest → "npm test -- --coverage"

Vitest → "npm test -- --coverage"
Pytest → "pytest --cov=src"
Go → "go test -cover ./..."
Log: "✓ Coverage command: [default] (framework default)"
Check Running Tests section content:

Read section from tests/README.md

Check validation heuristics:

✅ Has test runner command

✅ Mentions coverage
✅ Shows how to run specific tests
✅ Has command examples
If ANY heuristic passes → content valid
If ALL fail → log warning: "⚠️ tests/README.md → Running Tests section needs update"

3.4 Report content validation:

Log summary:

✅ Content validation complete:
  - testing-strategy.md: [2 sections checked]
  - tests/README.md: [2 sections checked]
  - Test framework: [detected framework or "Not detected"]
  - Test structure: [e2e/integration/unit counts or "Created placeholder"]
  - Naming convention: [pattern or "Framework default"]
  - Test runner: [command]
  - Coverage command: [command]

Complete Output Structure

docs/reference/guides/
└── testing-strategy.md           # Universal testing philosophy (465 lines)

tests/
└── README.md                     # Test organization + Story-Level Pattern (112 lines)

Note: Actual test directories (e2e/, integration/, unit/) created during Story test task execution or Phase 3 if missing.

Reference Files Used

Templates

Testing Strategy Template:

references/testing_strategy_template.md - Universal testing philosophy with:

SCOPE tags (testing philosophy, NOT framework-specific)

Core Philosophy ("Test YOUR code, not frameworks")
Risk-Based Testing Strategy (Priority Matrix, test caps)
Story-Level Testing Pattern
Test Organization (E2E/Integration/Unit definitions)
Isolation Patterns (Data Deletion/Transaction Rollback/DB Recreation)
What To Test vs NOT Test (universal examples)
Testing Patterns (Arrange-Act-Assert, Mock at the Seam, Test Data Builders)
Common Issues (Flaky Tests, Slow Tests, Test Coupling)
Coverage Guidelines
Verification Checklist

Tests README Template:

references/tests_readme_template.md - Test organization with:

SCOPE tags (test documentation ONLY)

Overview (E2E/Integration/Unit test organization)
Testing Philosophy (brief, link to testing-strategy.md)
Test Structure (directory tree)
Story-Level Test Task Pattern (tests in final Story task, NOT scattered)
Test Execution (project-specific commands)
Quick Navigation (links to testing-strategy.md, kanban_board, guidelines)
Maintenance section (Update Triggers, Verification, Last Updated)

Validation Specification:

references/questions.md (v1.0.0) - Question-driven validation:

Questions each section must answer (4 sections total)

Validation heuristics (ANY passes → valid)
Auto-discovery hints (test frameworks, directory structure, naming conventions)
MCP Ref hints (external research if needed)

Best Practices

No premature validation: Phase 1 creates structure, Phase 2 validates it (no duplicate checks)
Parametric validation: Phase 3 validates 4 sections across 2 files (no code duplication)
Auto-discovery first: Scan test frameworks and directory structure before using defaults
Idempotent: ✅ Can run multiple times safely (checks existence before creation, re-validates on each run)
Separation of concerns: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT
Story-Level Test Task Pattern: Tests consolidated in final Story task (ln-510-test-planner creates task, ln-420-test-executor implements)
Value-Based Testing: 2-5 E2E, 3-8 Integration, 5-15 Unit per Story (10-28 total max), Priority ≥15 MUST be tested
No test code: This skill creates DOCUMENTATION only, NOT actual tests

Documentation Standards

NO_CODE Rule: Test docs describe strategy, not test implementations
Stack Adaptation: Framework commands must match project stack
Format Priority: Tables (test levels, counts) > Lists > Text

Prerequisites

Invoked by: ln-110-documents-pipeline orchestrator

Requires:

docs/reference/guides/ directory (created by ln-112-reference-docs-creator or Phase 1 if missing)

Creates:

docs/reference/guides/testing-strategy.md (universal testing philosophy)
tests/README.md (test organization structure)
Validated structure and content (auto-discovery of test frameworks and directory structure)

Definition of Done

Before completing work, verify ALL checkpoints:

✅ Structure Created (Phase 1):

docs/reference/guides/ directory exists tests/ directory exists tests/manual/ directory exists tests/manual/results/ directory exists tests/manual/results/ added to .gitignore testing-strategy.md exists (created or existing) tests/README.md exists (created or existing)

✅ Structure Validated (Phase 2):

SCOPE tags present in both files (first 5 lines) testing-strategy.md has "Testing Philosophy" and "Test Levels" sections tests/README.md has "Test Organization" and "Running Tests" sections Maintenance sections present in both files at end POSIX file endings compliant (LF, single blank line at EOF)

✅ Content Validated (Phase 3):

testing-strategy.md → Testing Philosophy section checked (Risk-Based Testing mentioned) testing-strategy.md → Test Levels section checked (2-5 E2E, 3-8 Integration, 5-15 Unit) tests/README.md → Test Organization section checked or auto-discovered tests/README.md → Running Tests section checked or auto-discovered Test framework detected (if applicable) and logged Test directory structure scanned or created Naming conventions detected or defaults used Test runner command identified or defaults used

✅ Reporting:

Phase 1 logged: creation summary Phase 2 logged: structural fixes (if any) Phase 3 logged: content validation summary with auto-discovery results

Technical Details

Standards:

Story-Level Test Task Pattern
Value-Based Testing (2-5 E2E, 3-8 Integration, 5-15 Unit, 10-28 total max per Story)
Risk-Based Testing (Priority ≥15)

Language: English only

Auto-Discovery Support:

Node.js: jest, vitest, mocha, ava, tap, jasmine
Python: pytest, nose2, unittest2
Go: built-in testing package

Version: 7.2.0 (Added tests/manual/results/ structure creation and .gitignore entry) Last Updated: 2026-01-15

ln-140-test-docs-creator

安装

When to Use This Skill

How It Works

Phase 1: Create Test Documentation

Phase 2: Validate Structure

Phase 3: Validate Content

Complete Output Structure

Reference Files Used

Templates

Best Practices

Documentation Standards

Prerequisites

Definition of Done

Technical Details