ln-140-test-docs-creator

What this skill does

> **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 `<!-- SCOPE: ... -->` tag and metadata markers in each
- Expected SCOPE tags:
  - testing-strategy.md: `<!-- SCOPE: Universal testing philosophy (Risk-Based Testing, test pyramid, isolation patterns) -->`
  - tests/README.md: `<!-- SCOPE: Test organization structure (directory layout, Story-Level Test Task Pattern) -->`
- 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:
      ```markdown
      ## 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):

1. **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"

2. **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**

1. **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 detec