SKILL.md

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Test Documentation Creator

Type: L2 Worker

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

Purpose

Creates and validates test documentation (testing-strategy.md + tests/README.md) establishing universal testing philosophy, Risk-Based Testing strategy, tests/automated/ as the default automated-test root, and the Story-Level Test Task Pattern for any project.

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)

Workflow

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

MANDATORY READ: Load references/docs_quality_contract.md, and references/markdown_read_protocol.md.

Optional rule catalog: load references/docs_quality_rules.json only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.

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-140-test-docs-creator/references/templates/testing_strategy_template.md → docs/reference/guides/testing-strategy.md

Replace placeholders:

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

Preserve shared metadata markers and standard top sections from the template

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-140-test-docs-creator/references/templates/tests_readme_template.md → tests/README.md

Replace placeholders:

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

Preserve shared metadata markers and standard top sections from the template

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) - opening block first

Check for  tag and metadata markers 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 the section with minimal concrete guidance from the template, not a raw placeholder

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/automated/e2e/**/*.{js,ts,py,go}"

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

Pattern: "tests/automated/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/

  automated/

    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 (tests/automated/e2e, tests/automated/integration, tests/automated/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: [automated/e2e, automated/integration, automated/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.

Critical Rules

Documentation only: This skill creates test DOCUMENTATION, NOT actual test code

3-phase pipeline: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT (no phase skipping)

Auto-discovery first: Scan test frameworks and directory structure before falling back to defaults

Idempotent execution: Checks existence before creation; re-validates on each run without duplication

Shared opening contract required: Both files must include SCOPE, metadata markers, Quick Navigation, Agent Entry, and Maintenance

Reference Files

Risk-based testing methodology: references/risk_based_testing_guide.md

Templates

Testing Strategy Template:

references/templates/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 (tests/automated/e2e, tests/automated/integration, tests/automated/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/templates/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 (test planner creates task, test executor implements)

Value-Based Testing: Priority ≥15 MUST be tested, each test justified by Usefulness Criteria

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

Shared docs-quality contract: SCOPE tags, Maintenance sections, placeholder policy, and stack-specific link validation come from the shared docs-quality contract/rules

Prerequisites

Invoked by: ln-100-documents-pipeline orchestrator

Requires:

docs/reference/guides/ directory (created by ln-120-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)

Return Contract

Return a normalized summary so ln-100 can run one centralized docs-quality gate:

{

  "created_files": [

    "docs/reference/guides/testing-strategy.md",

    "tests/README.md"

  ],

  "skipped_files": [],

  "quality_inputs": {

    "doc_paths": [

      "docs/reference/guides/testing-strategy.md",

      "tests/README.md"

    ],

    "owners": {

      "docs/reference/guides/testing-strategy.md": "ln-140-test-docs-creator",

      "tests/README.md": "ln-140-test-docs-creator"

    }

  },

  "validation_status": "passed|passed_with_fixes|skipped"

}

Runtime Summary Artifact

MANDATORY READ: Load references/docs_generation_summary_contract.md

Accept optional summaryArtifactPath.

Summary kind:

docs-generation

Required payload semantics:

worker = "ln-140"

status

created_files

skipped_files

quality_inputs

validation_status

warnings

Write the summary to the provided artifact path or return the same envelope in structured output.

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 Usefulness Criteria section checked

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

Return contract emitted with created_files, skipped_files, quality_inputs, and validation_status

Technical Details

Standards:

Story-Level Test Task Pattern

Risk-Based Testing (Priority ≥15, Usefulness Criteria)

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

Last Updated: 2026-01-15

ln-140-test-docs-creator

SKILL.md

Test Documentation Creator

Purpose

When to Use This Skill

Workflow

Phase 1: Create Test Documentation

Phase 2: Validate Structure

Phase 3: Validate Content

Complete Output Structure

Critical Rules

Reference Files

Templates

Best Practices

Documentation Standards

Prerequisites

Return Contract

Runtime Summary Artifact

Definition of Done

Technical Details

Let your agent run on any real-world website

Related skills

Stop writing automation&scrapers