zhongwei/gh-levnikolaevich-claude-code-skills-full-development-workflow-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-levnikolaevich-claude-co…/skills/ln-113-tasks-docs-creator/references/questions.md
Zhongwei Li 37774aa937 Initial commit
2025-11-30 08:37:27 +08:00

9.0 KiB
Raw Permalink Blame History

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 3 None High L35
kanban_board.md 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

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 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 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 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

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

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 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 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

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

Version: 1.0 Last Updated: 2025-11-18

Reference in New Issue View Git Blame Copy Permalink