Document Orchestrator

Document Orchestrator

This skill handles creation of all structured documentation for workflow, bugfix, and plan commands.

When to Use

Use this skill when:

• After selecting a Linear task with linear-task-selector
• Need to generate PRD, tasks, investigation plans, or decomposition docs
• Creating directory structure for feature/bug/plan workflows

Instructions

Step 1: Load Task Context

Read the selected task from the appropriate directory (created by linear-task-selector):

• For features: features/<feature-name>/selected-task.json
• For bugs: bugs/<bug-name>/selected-task.json
• For epics: epics/<epic-name>/selected-task.json

The featureName field in the JSON tells you which directory to use.

Extract:

• workflowType: "feature", "bugfix", or "plan"
• featureName: Directory name for locating/storing files
• title: Task title
• description: Full task description
• taskId: Linear issue ID

Step 2: Verify Directory Structure

The directory should already exist (created by linear-task-selector).

For feature workflows: Use existing features/<feature-name>/ directory

For bugfix workflows: Use existing bugs/<bug-name>/ directory

For plan workflows: Use existing epics/<epic-name>/ directory

If directory doesn't exist, create it using the featureName from selected-task.json.

Step 3: Generate Documents

For Feature Workflow

3a. Generate PRD Use the PRD template from ~/.claude/tools/prompts/prd-prompt-template.md:

Role: Senior product manager for Hokusai Task: Generate PRD that a junior team member can follow Input: Replace {{PROJECT_SUMMARY}} with task title + description Output: features/<feature-name>/prd.md

Required sections:

• Objectives
• Personas (if applicable)
• Success criteria
• Clearly delineated tasks
• Straightforward language
• No dates, versions, icons, or emojis

Reference: Review project README.md and https://docs.hokus.ai/

3b. Generate Tasks Use the tasks template from ~/.claude/tools/prompts/tasks-prompt-template.md:

Role: Product manager working with junior developer Task: Create detailed, prioritized task list from PRD Input: Read features/<feature-name>/prd.md Output: features/<feature-name>/tasks.md

Required format:

## Section Name
1. [ ] Task description
   a. [ ] Subtask description
   b. [ ] Subtask description

## Testing
7. [ ] Write and implement tests
   a. [ ] Database schema tests
   b. [ ] API endpoint tests
   c. [ ] Integration tests

Required components:

1. Automated testing (consistent with existing test suite)
2. Documentation (technical changes in README.md)
3. Dependencies (noted in section headers)

For Bugfix Workflow

3a. Generate Investigation Plan Use template from ~/.claude/tools/prompts/bug-investigation-template.md:

Role: Senior software engineer and debugging specialist Task: Create comprehensive investigation plan Input: Replace {{BUG_SUMMARY}} with task title + description Output: bugs/<bug-name>/investigation.md

Required sections:

1. Bug Summary (description, when/who affected, impact, severity)
2. Reproduction Steps (verified steps, environment, success rate)
3. Affected Components (services, tables, endpoints, dependencies)
4. Initial Observations (errors, logs, metrics, recent changes)
5. Data Analysis Required (logs, queries, metrics, reports)
6. Investigation Strategy (priority, tools, questions, success criteria)
7. Risk Assessment (impact, escalation, security, data integrity)
8. Timeline (first appeared, deployments, frequency, patterns)

3b. Generate Hypotheses Document Use template from ~/.claude/tools/prompts/bug-hypothesis-template.md:

Output: bugs/<bug-name>/hypotheses.md

Format for each hypothesis:

## Hypothesis N: [Brief description]

**Proposed Root Cause:**
[What you think is causing the bug]

**Why This Could Cause Observed Behavior:**
[Technical explanation]

**How to Test:**
[Specific steps to validate/invalidate]

**Expected Outcome if Correct:**
[What you'll observe if this is the root cause]

**Priority:** [High/Medium/Low]
**Likelihood:** [High/Medium/Low]
**Status:** [Untested/Testing/Confirmed/Rejected]

3c. Generate Fix Tasks Document Use template from ~/.claude/tools/prompts/bug-tasks-template.md:

Output: bugs/<bug-name>/fix-tasks.md

Required sections:

1. Root cause fix implementation
2. Tests to prevent regression
3. Documentation updates
4. Monitoring/alerting improvements

For Plan Workflow

3a. Generate Decomposition Request Output: epics/<epic-name>/decomposition-request.json

{
  "issueNumber": 10,
  "title": "Epic Title",
  "projectName": "Project Name",
  "description": "Epic description summary"
}

3b. Research Existing Implementation Use Read, Grep, Glob tools to:

• Understand what already exists
• Identify what's missing
• Find relevant files and patterns

Output: epics/<epic-name>/research.md

3c. Generate Decomposition Plan Output: epics/<epic-name>/decomposition-plan.json

{
  "masterDocumentPath": "path/to/main/doc.md",
  "relevantFiles": ["file1.ts", "file2.tsx"],
  "subIssues": [
    {
      "title": "Task title (action verb + specific noun)",
      "description": "Detailed description with context, requirements, acceptance criteria, references, edge cases",
      "dependencies": [0, 1],
      "estimate": 5,
      "priority": 1
    }
  ]
}

Guidelines:

• 3-10 sub-issues per epic
• Each completable in single PR
• Include tests and docs in each task
• Clear dependencies using array indices
• Estimates: 1-2 simple, 3-5 moderate, 5-8 complex
• Priority: 1 urgent, 2 high, 3 normal, 4 low

Step 4: Validate Documents

Check that:

• All required sections are present
• Content is specific and actionable
• No placeholder text remains (e.g., {{PROJECT_SUMMARY}})
• File paths are correct
• Markdown formatting is valid

Step 5: Return Summary

Provide user with:

✓ Documents generated:
  - features/add-user-auth/prd.md
  - features/add-user-auth/tasks.md

Next step: Review PRD and tasks, then begin implementation

Examples

Example 1: Feature Documentation

Input: features/add-user-auth/selected-task.json with workflowType: "feature"
Process:
1. Use existing features/add-user-auth/
2. Generate prd.md from template + task description
3. Generate tasks.md from PRD
4. Return: "✓ PRD and tasks created"

Example 2: Bug Documentation

Input: bugs/contact-discovery-timeout/selected-task.json with workflowType: "bugfix"
Process:
1. Use existing bugs/contact-discovery-timeout/
2. Generate investigation.md from template + bug description
3. Generate hypotheses.md with 3-5 initial hypotheses
4. Generate fix-tasks.md template
5. Return: "✓ Investigation plan created"

Example 3: Plan Documentation

Input: epics/user-management-system/selected-task.json with workflowType: "plan"
Process:
1. Use existing epics/user-management-system/
2. Generate decomposition-request.json
3. Research existing codebase → research.md
4. Generate decomposition-plan.json with 5 sub-issues
5. Return: "✓ Decomposition plan created"

Error Handling

Missing Task Context

If no selected-task.json exists in the expected directory:

1. Error: "No task selected. Run linear-task-selector first."
2. Exit gracefully

Directory Already Exists

If feature/bug directory exists:

1. Warn user: "Directory already exists: features/X"
2. Ask: "Overwrite? (y/n)"
3. If no, suggest alternative name

Template Errors

If template generation fails:

1. Show specific error (missing info, API failure, etc.)
2. Ask user for missing information
3. Retry generation

Output

This skill outputs:

• Feature workflow: features/<name>/prd.md, features/<name>/tasks.md
• Bugfix workflow: bugs/<name>/investigation.md, bugs/<name>/hypotheses.md, bugs/<name>/fix-tasks.md
• Plan workflow: epics/<name>/decomposition-request.json, epics/<name>/decomposition-plan.json, epics/<name>/research.md
• Console: Summary of created documents

Note: All files are stored in workflow-specific directories to prevent conflicts when multiple Claude sessions run concurrently.

Integration

This skill integrates with:

• Input from: linear-task-selector (task context)
• Output to: git-workflow-manager (branch creation, commits)
• Used by: workflow, bugfix, plan commands