ln-130-tasks-docs-creator

What this skill does

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

**Type:** L2 Worker
**Category:** 1XX Documentation Pipeline

# Tasks Documentation Creator

This skill creates task management documentation: docs/tasks/README.md (task management system rules) and docs/tasks/kanban_board.md (configured tracker integration with Epic Story Counters).

## Purpose

Create and validate task management documentation (docs/tasks/). Generates README.md with workflow rules and kanban_board.md with tracker integration that adapts to the configured provider (linear/github/file), including interactive setup for provider-specific configuration.

## When to Use This Skill

**This skill is a L2 WORKER** invoked by **ln-100-documents-pipeline** orchestrator OR used standalone.

Use this skill when:
- Creating task management documentation (docs/tasks/)
- Setting up tracker integration and kanban board
- Validating existing task documentation structure and content
- Configuring provider-specific tracker settings (linear: Team Name/UUID/Key; github: repository/project_number; file: nothing)

**Part of workflow**: ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → **ln-130-tasks-docs-creator** → ln-140-test-docs-creator (optional)

## Workflow

The skill follows a **3-phase workflow**: CREATE → VALIDATE STRUCTURE → VALIDATE CONTENT.

**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** - Create tasks/README.md from template with SCOPE tags, workflow rules, configured tracker integration
**Phase 2: VALIDATE STRUCTURE** - Auto-fix structural violations (SCOPE tags, sections, Maintenance, POSIX)
**Phase 3: VALIDATE CONTENT** - Validate semantic content + provider-conditional Tracker Configuration handling (placeholder detection, provider-specific field validation, interactive user prompts). Raw placeholders are allowed only during setup for `docs/tasks/README.md` and `docs/tasks/kanban_board.md`; published output must not leak unresolved markers into any other document.

---

## Phase 1: Create tasks/README.md

**Objective**: Create task management system documentation from template.

**When to execute**: Always (first phase)

**Process**:

1. **Check if tasks/README.md exists**:
   - Use Glob tool: `pattern: "docs/tasks/README.md"`
   - If file exists:
     - Skip creation
     - Log: `✓ docs/tasks/README.md already exists (preserved)`
     - Proceed to Phase 2
   - If NOT exists:
     - Continue to step 2

2. **Create tasks directory**:
   - Create the `docs/tasks/` directory if it doesn't exist

3. **Create tasks/README.md from template**:
   - **MANDATORY READ:** Load `references/templates/tasks_readme_template.md`
   - Copy template → `docs/tasks/README.md`
   - Replace placeholders:
     - `{{DATE}}` → current date (YYYY-MM-DD)
   - Template contains:
     - Full shared header contract (`SCOPE`, `DOC_KIND`, `DOC_ROLE`, `READ_WHEN`, `SKIP_WHEN`, `PRIMARY_SOURCES`)
     - Story-Level Test Task Pattern
     - Kanban Board Structure (Epic Grouping Pattern)
     - Linear Integration (MCP methods)
     - Quick Navigation, Agent Entry, and Maintenance sections

4. **Notify user**:
   - If created: `✓ Created docs/tasks/README.md with task management rules`
   - If skipped: `✓ docs/tasks/README.md already exists (preserved)`

**Output**: docs/tasks/README.md (created or existing)

---

## Phase 2: Validate Structure

**Objective**: Ensure tasks/README.md and kanban_board.md comply with structural requirements. Auto-fix violations.

**When to execute**: After Phase 1 completes (files exist or created)

**Process**:

### 2.1 Validate SCOPE tags

**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:
1. Read the opening block
2. Check for `<!-- SCOPE: ... -->` tag and metadata markers
3. Expected values:
   - tasks/README.md: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
   - kanban_board.md: `<!-- SCOPE: Quick navigation to active tasks in Linear -->`
4. **If missing:**
   - Use Edit tool to add SCOPE tag after first heading
   - Log: `⚠ Auto-fixed: Added missing SCOPE tag to {filename}`

### 2.2 Validate required sections

**MANDATORY READ:** Load `references/questions.md` for validation specs (section names, heuristics, special handling rules).

**For tasks/README.md**:
- Required sections (from questions.md):
  - "Linear Integration" OR "Core Concepts" (Linear MCP methods)
  - "Task Workflow" OR "Critical Rules" (state transitions)
  - "Task Templates" (template references)
- For each section:
  - Check if section header exists (case-insensitive)
  - **If missing:**
    - Use Edit tool to add the section with minimal concrete guidance or an explicit empty-state note
    - Log: `⚠ Auto-fixed: Added missing section '{section}' to tasks/README.md`

**For kanban_board.md** (if exists):
- Required sections:
  - "Linear Configuration" (Team Name, UUID, Key)
  - "Work in Progress" OR "Epic Tracking" (Kanban sections)
- For each section:
  - Check if section header exists
  - **If missing:**
    - Use Edit tool to add section with placeholder
    - Log: `⚠ Auto-fixed: Added missing section '{section}' to kanban_board.md`

### 2.3 Validate Maintenance section

**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:
1. Search for `## Maintenance` header in last 20 lines
2. **If missing:**
   - Use Edit tool to add at end of file:
     ```markdown
     ## Maintenance

     **Update Triggers:**
     - When Linear workflow changes
     - When task templates are added/modified
     - When label taxonomy changes

     **Last Updated:** {current_date}
     ```
   - Log: `⚠ Auto-fixed: Added Maintenance section to {filename}`

### 2.4 Validate POSIX line endings

**Files to check**: docs/tasks/README.md, docs/tasks/kanban_board.md (if exists)

For each file:
1. Check if file ends with single newline character
2. **If missing:**
   - Use Edit tool to add final newline
   - Log: `⚠ Auto-fixed: Added POSIX newline to {filename}`

### 2.5 Report validation summary

Log summary:
```
✓ Structure validation completed:
  tasks/README.md:
    - SCOPE tag: [added/present]
    - Required sections: [count] sections [added/present]
    - Maintenance section: [added/present]
    - POSIX endings: [fixed/compliant]
  kanban_board.md:
    - SCOPE tag: [added/present/skipped - file not exists]
    - Required sections: [count] sections [added/present/skipped]
    - Maintenance section: [added/present/skipped]
    - POSIX endings: [fixed/compliant/skipped]
```

If violations found: `⚠ Auto-fixed {total} structural violations`

**Output**: Structurally valid task management documentation

---

## Phase 3: Validate Content

**Objective**: Ensure each section answers its validation questions with meaningful content. Special handling for Linear Configuration (placeholder detection, user prompts, UUID/Team Key validation).

**When to execute**: After Phase 2 completes (structure valid, auto-fixes applied)

**Process**:

### 3.1 Load validation spec

**MANDATORY READ:** Load `references/questions.md` — parse sections and extract validation heuristics.

### 3.2 Validate kanban_board.md → Linear Configuration (Special Handling)

**Question**: "What is the Linear team configuration?"

**Step 3.2.1: Check if kanban_board.md exists**:
- Use Glob tool: `pattern: "docs/tasks/kanban_board.md"`
- If NOT exists:
  - Log: `ℹ kanban_board.md not found - skipping Linear Configuration validation`
  - Skip to Step 3.3
- If exists:
  - Continue to Step 3.2.2

**Step 3.2.2: Read Linear Configuration section**:
- Read `docs/tasks/kanban_board.md`
- Locate `## Linear Configuration` section
- Extract Team Name, Team UUID, Team Key values

*