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
- Read
references/questions.md - Parse document sections and questions
- Extract validation heuristics for each section
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
- 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
Step 3.2.3: Placeholder Detection:
Check for placeholders:
```
Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
If ANY placeholder present β Interactive Setup Mode
If NO placeholders present β Validation Mode
```
Interactive Setup Mode (if placeholders detected):
- Prompt user for Team Name:
- Question: "What is your Linear Team Name?"
- Validation: Non-empty string
- Example: "My Project Team"
- Prompt user for Team UUID:
- Question: "What is your Linear Team UUID?"
- Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- Validation Regex: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
- If invalid:
- Show error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)"
- Re-prompt user
- Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
- Prompt user for Team Key:
- Question: "What is your Linear Team Key (2-4 uppercase letters)?"
- Format: 2-4 uppercase letters
- Validation Regex: /^[A-Z]{2,4}$/
- If invalid:
- Show error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)"
- Re-prompt user
- Example: "PROJ"
- Replace placeholders:
- Use Edit tool to replace in kanban_board.md:
- [TEAM_NAME] β {user_team_name}
- [TEAM_UUID] β {user_team_uuid}
- [TEAM_KEY] β {user_team_key}
- [WORKSPACE_URL] β https://linear.app/{workspace_slug} (if placeholder exists)
- Set initial counters (if table exists):
- Set "Next Epic Number" β 1
- Set "Next Story Number" β 1
- Update Last Updated date:
- Replace [YYYY-MM-DD] β {current_date} in Maintenance section
- Save updated kanban_board.md
- Log success:
```
β Linear configuration updated:
- Team Name: {user_team_name}
- Team UUID: {user_team_uuid}
- Team Key: {user_team_key}
- Next Epic Number: 1
- Next Story Number: 1
```
Validation Mode (if real values present, no placeholders):
- Extract existing values:
- Extract Team UUID from line matching: Team UUID: {value} or in table
- Extract Team Key from line matching: Team Key: {value} or in table
- Validate formats:
- UUID: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
- Team Key: /^[A-Z]{2,4}$/
- If validation fails:
```
β Invalid format detected in Linear Configuration:
- Team UUID: {uuid} (expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
- Team Key: {key} (expected: 2-4 uppercase letters)
Fix manually or re-run skill to replace with correct values.
```
- Mark as invalid but continue (don't block)
- If validation passes:
```
β Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
```
3.3 Validate tasks/README.md sections
Parametric loop for 3 questions (from questions.md):
For each question in:
- "How is Linear integrated into the task management system?"
- "What are the task state transitions and review criteria?"
- "What task templates are available and how to use them?"
Validation process:
- Extract validation heuristics from questions.md
- Read corresponding section content from tasks/README.md
- Check if ANY heuristic passes:
- Contains keyword X β pass
- Has pattern Y β pass
- Length > N words β pass
- If ANY passes β Section valid
- If NONE passes β Log warning:
β Section may be incomplete: {section_name}
Example validation (Question 1: Linear Integration):
```
Heuristics:
- Contains "Linear" or "MCP" β pass
- Mentions team ID or UUID β pass
- Has workflow states (Backlog, Todo, In Progress) β pass
- Length > 100 words β pass
Check content:
- β Contains "Linear" β PASS
β Section valid
```
No auto-discovery needed (workflow is standardized in template)
3.4 Validate kanban_board.md β Epic Tracking
Question: "Are Epics being tracked in the board?"
If kanban_board.md exists:
Validation heuristics:
```
- Has "Epic" or "Epics Overview" section header β pass
- Has table with columns: Epic, Name, Status, Progress β pass
- OR has placeholder: "No active epics" β pass
- Length > 20 words β pass
```
Action:
- Read Epic Tracking or Epics Overview section
- Check if ANY heuristic passes
- If passes β valid
- If none pass β log warning:
β Epic Tracking section may be incomplete
If kanban_board.md does NOT exist:
- Skip validation
- Log:
βΉ Epic Tracking validation skipped (kanban_board.md not found)
3.5 Report content validation summary
Log summary:
```
β Content validation completed:
tasks/README.md:
- β Linear Integration: valid (contains "Linear", "MCP", workflow states)
- β Task Workflow: valid (contains state transitions)
- β Task Templates: valid (contains template references)
kanban_board.md:
- β Linear Configuration: {status} (Team: {name}, UUID: {uuid}, Key: {key})
- β Epic Tracking: valid (table present or placeholder)
```
Output: Validated and potentially updated task management documentation with Linear configuration
---
|