275 lines
9.0 KiB
Markdown
275 lines
9.0 KiB
Markdown
# Task Management Documentation Questions
|
|
|
|
**Purpose:** Define validation questions for task management system (tasks/README.md, kanban_board.md). Used in CREATE mode (user answers questions) and VALIDATE mode (check document compliance).
|
|
|
|
**Format:** Document → Questions (with target sections) → Validation Heuristics → Auto-Discovery → Special Handling
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
| Document | Questions | Auto-Discovery | Priority | Line |
|
|
|----------|-----------|----------------|----------|------|
|
|
| [tasks/README.md](#tasksreadmemd) | 3 | None | High | L35 |
|
|
| [kanban_board.md](#kanban_boardmd) | 2 | Placeholder Detection | Critical | L110 |
|
|
|
|
**Priority Legend:**
|
|
- **Critical:** Must answer all questions (Linear Configuration required for workflow)
|
|
- **High:** Strongly recommended (standard workflow content)
|
|
|
|
**Auto-Discovery Legend:**
|
|
- **None:** No auto-discovery needed (workflow is standardized)
|
|
- **Placeholder Detection:** Detect and replace placeholders with user input
|
|
|
|
---
|
|
|
|
<!-- DOCUMENT_START: tasks/README.md -->
|
|
## tasks/README.md
|
|
|
|
**File:** docs/tasks/README.md
|
|
**Target Sections:** Linear Integration, Task Workflow, Task Templates
|
|
|
|
**Rules for this document:**
|
|
- Must have SCOPE tag in first 10 lines
|
|
- Must explain Linear MCP integration
|
|
- Must document state transitions and review criteria
|
|
- Must list available task templates
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 1 -->
|
|
### Question 1: How is Linear integrated into the task management system?
|
|
|
|
**Expected Answer:** Team ID location, issue statuses (Backlog, Todo, In Progress, To Review, Done), label conventions, Linear MCP methods reference, workflow configuration
|
|
|
|
**Target Section:** ## Core Concepts, ## Critical Rules, ## Linear MCP Methods Reference
|
|
|
|
**Validation Heuristics:**
|
|
- ✅ Contains "Linear" or "MCP" → pass
|
|
- ✅ Mentions team ID or team UUID → pass
|
|
- ✅ Has workflow states: Backlog, Todo, In Progress, To Review, Done → pass
|
|
- ✅ Has "Linear MCP Methods" section with examples → pass
|
|
- ✅ Length > 100 words → pass
|
|
|
|
**Auto-Discovery:**
|
|
- None needed (standardized workflow provided by template)
|
|
|
|
**MCP Ref Hints:**
|
|
- Research "Linear API MCP integration"
|
|
- Search "Linear issue workflow states"
|
|
<!-- QUESTION_END: 1 -->
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 2 -->
|
|
### Question 2: What are the task state transitions and review criteria?
|
|
|
|
**Expected Answer:** State transition rules (Backlog → Todo → In Progress → To Review → Done), review criteria, rework process, Epic Grouping Pattern
|
|
|
|
**Target Section:** ## Task Workflow, ## Core Concepts
|
|
|
|
**Validation Heuristics:**
|
|
- ✅ Contains "Backlog" or "Todo" or "In Progress" → pass
|
|
- ✅ Mentions "Review" or "To Review" → pass
|
|
- ✅ Mentions "Done" or "Completed" → pass
|
|
- ✅ Has workflow states diagram or table → pass
|
|
- ✅ Mentions "Epic Grouping" → pass
|
|
- ✅ Length > 60 words → pass
|
|
|
|
**Auto-Discovery:**
|
|
- None needed (standard workflow states)
|
|
|
|
**MCP Ref Hints:**
|
|
- None needed
|
|
<!-- QUESTION_END: 2 -->
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 3 -->
|
|
### Question 3: What task templates are available and how to use them?
|
|
|
|
**Expected Answer:** List of templates (Epic, Story, Task, Test Task), usage guidelines, required sections, links to template files
|
|
|
|
**Target Section:** ## Task Workflow, ## Critical Rules
|
|
|
|
**Validation Heuristics:**
|
|
- ✅ Contains "template" (case insensitive) → pass
|
|
- ✅ Mentions "Epic" or "Story" or "Task" → pass
|
|
- ✅ Has links to template files or references → pass
|
|
- ✅ Mentions "Story-Level Test Strategy" or testing → pass
|
|
- ✅ Length > 40 words → pass
|
|
|
|
**Auto-Discovery:**
|
|
- None needed (templates provided by other skills)
|
|
|
|
**MCP Ref Hints:**
|
|
- None needed
|
|
<!-- QUESTION_END: 3 -->
|
|
|
|
---
|
|
|
|
**Overall File Validation:**
|
|
- ✅ Has SCOPE tag in first 10 lines: `<!-- SCOPE: Task tracking system workflow and rules ONLY -->`
|
|
- ✅ Total length > 200 words (meaningful content)
|
|
- ✅ Has Maintenance section at end
|
|
|
|
<!-- DOCUMENT_END: tasks/README.md -->
|
|
|
|
---
|
|
|
|
<!-- DOCUMENT_START: kanban_board.md -->
|
|
## kanban_board.md
|
|
|
|
**File:** docs/tasks/kanban_board.md
|
|
**Target Sections:** Linear Configuration, Work in Progress (Epic Tracking)
|
|
|
|
**Rules for this document:**
|
|
- Must have SCOPE tag in first 10 lines
|
|
- Must have Linear Configuration section with Team Name, Team UUID, Team Key
|
|
- Must have Epic tracking table or placeholder
|
|
- Single Source of Truth for Next Epic/Story Numbers
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 1 -->
|
|
### Question 1: What is the Linear team configuration?
|
|
|
|
**Expected Answer:** Team Name, Team UUID (valid format), Team Key (2-4 uppercase letters), Workspace URL, Next Epic Number (≥1), Next Story Number (≥1)
|
|
|
|
**Target Section:** ## Linear Configuration, ## Epic Story Counters
|
|
|
|
**Validation Heuristics:**
|
|
- ✅ Has Team Name (not placeholder `[TEAM_NAME]`) → pass
|
|
- ✅ Has valid UUID format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) → pass
|
|
- ✅ Has Team Key (2-4 uppercase letters, e.g., PROJ, WEB, API) → pass
|
|
- ✅ Has Next Epic Number (integer ≥ 1) → pass
|
|
- ✅ Has Next Story Number (integer ≥ 1) → pass
|
|
- ✅ Has Workspace URL or Team ID → pass
|
|
|
|
**Auto-Discovery:**
|
|
- **Placeholder Detection Pattern:**
|
|
- Check for: `[TEAM_NAME]`, `[TEAM_UUID]`, `[TEAM_KEY]`
|
|
- If placeholders found → Trigger interactive user prompt (see Special Handling)
|
|
- If real values present → Validate format only
|
|
|
|
**Special Handling (Phase 3 VALIDATE CONTENT):**
|
|
|
|
**Placeholder Detection:**
|
|
```
|
|
Pattern: [TEAM_NAME], [TEAM_UUID], [TEAM_KEY]
|
|
If ANY placeholder present → Interactive Setup Mode
|
|
If NO placeholders → Validation Mode
|
|
```
|
|
|
|
**Interactive Setup Mode (if placeholders detected):**
|
|
|
|
1. **Prompt user for Team Name:**
|
|
- Question: "What is your Linear Team Name?"
|
|
- Validation: Non-empty string
|
|
- Example: "My Project Team"
|
|
|
|
2. **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 → Re-prompt with error: "Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hex)"
|
|
- Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
|
|
3. **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 → Re-prompt with error: "Invalid Team Key format. Expected: 2-4 uppercase letters (e.g., PROJ, WEB, API)"
|
|
- Example: "PROJ"
|
|
|
|
4. **Replace placeholders:**
|
|
- Replace `[TEAM_NAME]` → `{user_team_name}`
|
|
- Replace `[TEAM_UUID]` → `{user_team_uuid}`
|
|
- Replace `[TEAM_KEY]` → `{user_team_key}`
|
|
- Replace `[WORKSPACE_URL]` → `https://linear.app/{workspace_slug}` (if placeholder exists)
|
|
|
|
5. **Set initial counters:**
|
|
- Set "Next Epic Number" → 1
|
|
- Set "Next Story Number" → 1
|
|
|
|
6. **Update Last Updated date:**
|
|
- Replace `[YYYY-MM-DD]` → `{current_date}`
|
|
|
|
7. **Save updated kanban_board.md**
|
|
|
|
8. **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):**
|
|
|
|
1. **Extract existing values:**
|
|
- Extract Team UUID from line matching: `Team UUID: {value}`
|
|
- Extract Team Key from line matching: `Team Key: {value}`
|
|
|
|
2. **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}$/`
|
|
|
|
3. **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.
|
|
```
|
|
|
|
4. **If validation passes:**
|
|
```
|
|
✓ Linear Configuration valid (Team: {name}, UUID: {uuid}, Key: {key})
|
|
```
|
|
|
|
**MCP Ref Hints:**
|
|
- Research "Linear team UUID format"
|
|
- Search "Linear workspace configuration"
|
|
<!-- QUESTION_END: 1 -->
|
|
|
|
---
|
|
|
|
<!-- QUESTION_START: 2 -->
|
|
### Question 2: Are Epics being tracked in the board?
|
|
|
|
**Expected Answer:** Table with Epic data (Epic ID, Name, Status, Progress) or placeholder ("No active epics")
|
|
|
|
**Target Section:** ## Work in Progress (Epics Overview subsection)
|
|
|
|
**Validation Heuristics:**
|
|
- ✅ Has "Epic" or "Epics Overview" section header → pass
|
|
- ✅ Has table with columns: Epic, Name, Status, Progress (or similar) → pass
|
|
- ✅ OR has placeholder: "No active epics" or "No epics yet" → pass
|
|
- ✅ Length > 20 words → pass
|
|
|
|
**Auto-Discovery:**
|
|
- None needed (Epics are populated by workflow skills: ln-210, ln-220, ln-300)
|
|
|
|
**MCP Ref Hints:**
|
|
- None needed
|
|
<!-- QUESTION_END: 2 -->
|
|
|
|
---
|
|
|
|
**Overall File Validation:**
|
|
- ✅ Has SCOPE tag in first 10 lines: `<!-- SCOPE: Quick navigation to active tasks in Linear -->`
|
|
- ✅ Has Linear Configuration section with valid Team Name, UUID, Key
|
|
- ✅ Has Epic Story Counters table
|
|
- ✅ Has Maintenance section at end
|
|
|
|
<!-- DOCUMENT_END: kanban_board.md -->
|
|
|
|
---
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** 2025-11-18
|