aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/po-pull-story-from-clickup.md

@@ -1,540 +1,540 @@
----
-tools:
-  - clickup  # Required for ClickUp integration
-checklists:
-  - po-master-checklist.md
----
-
-# pull-story-from-clickup
-
-**Purpose:** Pull complete story updates from ClickUp to local file, including task completions, description changes, and status updates. This is the **reverse direction** of sync-story-to-clickup.
-
-**When to Use:**
-- After making changes directly in ClickUp UI (marking checkboxes, updating description)
-- When you need to pull latest state from ClickUp to continue work locally
-- After collaborators update the ClickUp task
-- To resolve sync conflicts (ClickUp is the source of truth)
-
-**Important:** This overwrites local changes with ClickUp data. Use carefully if you have uncommitted local edits.
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: poPullStoryFromClickup()
-responsável: Pax (Balancer)
-responsavel_type: Agente
-atomic_layer: Organism
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-15 min (estimated)
-cost_estimated: $0.003-0.010
-token_usage: ~3,000-10,000 tokens
-```
-
-**Optimization Notes:**
-- Break into smaller workflows; implement checkpointing; use async processing where possible
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - product-management
-  - planning
-updated_at: 2025-11-17
-```
-
----
-
-
-## Task Inputs
-
-```yaml
-required:
-  - story_id: '{epic}.{story}' # e.g., "99.2" or "5.2.2"
-
-optional:
-  - force: false # If true, pull even if last_sync indicates local is newer
-```
-
-## Prerequisites
-
-- Story file must exist in `docs/stories/`
-- Story must have ClickUp metadata in frontmatter (clickup.task_id)
-- ClickUp MCP tool must be available and authenticated
-
-## Task Execution Steps
-
-### Step 1: Locate Story File
-
-- Find story file in `docs/stories/` matching story_id pattern
-- Expected format: `{epic}.{story}.*.md`
-- If multiple files found, show list and ask user to clarify
-- If no file found, ERROR and exit
-
-### Step 2: Get ClickUp Task Data
-
-```javascript
-const clickupTool = await getClickUpTool();
-
-// Get complete task data including description
-const task = await clickupTool.getTask({
-  taskId: storyData.frontmatter.clickup.task_id
-});
-```
-
-**What to extract from ClickUp task:**
-- Task description (contains full story markdown)
-- Story-status custom field
-- Task native status
-- Tags
-- Custom fields (epic_number, story_number, story_file_path)
-
-### Step 3: Parse ClickUp Description
-
-The ClickUp task description contains the **complete story markdown**. We need to:
-
-1. Extract the markdown from `task.description`
-2. Parse sections:
-   - Story Statement
-   - Context
-   - Acceptance Criteria (with checkboxes)
-   - Tasks/Subtasks (with checkboxes)
-   - Dev Notes
-   - Testing
-   - File List
-   - QA Results
-   - Notes
-   - Change Log
-
-3. **Critical:** Preserve checkbox states from ClickUp
-   - `- [x] Task` = completed
-   - `- [ ] Task` = pending
-
-### Step 4: Merge with Local Frontmatter
-
-**DO NOT overwrite entire file** - preserve frontmatter structure:
-
-```javascript
-const localFrontmatter = storyData.frontmatter;
-const clickupFrontmatter = {
-  version: localFrontmatter.version,
-  story_id: localFrontmatter.story_id,
-  epic_id: localFrontmatter.epic_id,
-  title: task.name,
-  status: mapStatusFromClickUp(task.custom_fields.find(f => f.name === 'story-status').value),
-  created: localFrontmatter.created,
-  updated: new Date().toISOString().split('T')[0], // Today's date
-  clickup: {
-    task_id: task.id,
-    epic_task_id: task.parent,
-    list: task.list.name,
-    list_id: task.list.id,
-    url: task.url,
-    last_sync: new Date().toISOString(),
-    custom_fields: {
-      epic_number: task.custom_fields.find(f => f.name === 'epic-number')?.value || localFrontmatter.clickup.custom_fields.epic_number,
-      story_number: task.custom_fields.find(f => f.name === 'story-number')?.value || localFrontmatter.clickup.custom_fields.story_number,
-      story_file_path: task.custom_fields.find(f => f.name === 'story-file-path')?.value || localFrontmatter.clickup.custom_fields.story_file_path,
-      'story-status': task.custom_fields.find(f => f.name === 'story-status')?.value
-    }
-  },
-  tags: task.tags.map(t => t.name)
-};
-```
-
-### Step 5: Reconstruct Story File
-
-Build complete story markdown:
-
-```markdown
-# Story {story_id}: {title}
-
-```yaml
-{frontmatter}
-```
-
-{story body from ClickUp description}
-```
-
-**Important:** Use the ClickUp description as the **source of truth** for the story body.
-
-### Step 6: Write Updated Story File
-
-```javascript
-const { saveStoryFile } = require('../../common/scripts/story-manager');
-
-// Save with skipSync=true to avoid circular sync
-await saveStoryFile(storyFilePath, newContent, true);
-```
-
-**Why skipSync=true?**
-- We just pulled from ClickUp, so we don't want to immediately push back
-- Prevents infinite sync loops
-
-### Step 7: Display Sync Summary
-
-```markdown
-✅ Story {story_id} pulled from ClickUp
-
-**Task ID:** {task_id}
-**Task URL:** {url}
-**Last Sync:** {timestamp}
-
-**Changes Pulled:**
-- Status: {old_status} → {new_status} (if changed)
-- Tasks completed: {count of checkboxes changed from [ ] to [x]}
-- Tasks reopened: {count of checkboxes changed from [x] to [ ]}
-- Description updated: {yes/no}
-- Tags updated: {changes}
-
-**Local File Updated:**
-- Frontmatter: ✓
-- Story Body: ✓
-- Checkbox States: ✓
-- Last Sync Timestamp: ✓
-```
-
-## Error Handling
-
-**Error: Story file not found**
-```
-❌ Story file not found for ID: {story_id}
-
-Please check:
-- Story ID format correct? (e.g., "99.2" not "Story 99.2")
-- Story file exists in docs/stories/?
-- File naming follows pattern: {epic}.{story}.*.md
-```
-
-**Error: No ClickUp metadata**
-```
-❌ Story has no ClickUp integration
-
-This story was not created via ClickUp workflow and has no task_id.
-Cannot pull from ClickUp without task_id in frontmatter.
-```
-
-**Error: ClickUp task not found**
-```
-❌ ClickUp task not found: {task_id}
-
-Possible reasons:
-- Task was deleted from ClickUp
-- Task ID is incorrect in frontmatter
-- You don't have access to this task
-- ClickUp API authentication failed
-
-Verify task exists: {task_url}
-```
-
-**Error: Description empty or malformed**
-```
-❌ ClickUp task description is empty or malformed
-
-The task description should contain the full story markdown.
-This may indicate:
-- Task was created manually in ClickUp (not via story-manager)
-- Description was accidentally cleared
-- Task needs to be synced from local first
-
-Recommendation:
-1. Run: *sync-story {story_id}
-2. Then try pulling again
-```
-
-## Usage Examples
-
-### Basic Pull
-```
-*pull-story 99.2
-```
-
-### Force Pull (even if local is newer)
-```
-*pull-story 5.2.2 --force
-```
-
-### After ClickUp Updates
-```
-# Scenario: You marked checkboxes in ClickUp UI
-1. Run: *pull-story {story_id}
-2. Review changes shown in summary
-3. Local file now matches ClickUp
-4. Continue working locally
-```
-
-## Integration Notes
-
-**For PO Agent:**
-- Add to po.md commands: `pull-story {story}`: Pull story updates from ClickUp
-- Use after collaborators update ClickUp tasks
-- Use before starting validation if task was modified in ClickUp
-
-**For Dev Agent:**
-- Add to dev.md commands: `pull-story {story}`: Pull story updates from ClickUp
-- Use at start of work session to get latest state
-- Use after QA or PO updates task in ClickUp
-
-**For QA Agent:**
-- Add to qa.md commands: `pull-story {story}`: Pull story updates from ClickUp
-- Use before starting review to get latest state
-- Use after Dev marks tasks complete in ClickUp
-
-**Best Practice:**
-- Pull at the **start** of work sessions
-- Push (*sync-story) at the **end** of work sessions
-- ClickUp is the source of truth for collaborative updates
-- Local file is the source of truth for agent work
-
-## Workflow Examples
-
-### Collaborative Workflow
-```
-1. PO updates story in ClickUp UI (adds acceptance criteria)
-2. Dev pulls story: *pull-story 5.2.2
-3. Dev implements locally, marks tasks done
-4. Dev pushes to ClickUp: *sync-story 5.2.2
-5. QA pulls latest: *pull-story 5.2.2
-6. QA reviews and updates locally
-7. QA pushes results: *sync-story 5.2.2
-```
-
-### Conflict Resolution
-```
-# If local and ClickUp diverged:
-
-Option 1: ClickUp wins (recommended for collaborative work)
-*pull-story 5.2.2 --force
-
-Option 2: Local wins (when you have important uncommitted work)
-*sync-story 5.2.2 --force
-
-Option 3: Manual merge (complex changes)
-1. Backup local file
-2. Pull from ClickUp
-3. Compare with backup
-4. Manually merge important changes
-5. Push back to ClickUp
-```
-
-## Technical Implementation
-
-**Dependencies:**
-- `common/scripts/story-manager.js` - saveStoryFile, parseStoryFile
-- `common/scripts/status-mapper.js` - mapStatusFromClickUp
-- ClickUp MCP tool (via global.mcp__clickup__* or tool-resolver)
-
-**Process Flow:**
-```
-Task invoked
-    ↓
-Read local story file
-    ↓
-Extract task_id from frontmatter
-    ↓
-Fetch complete task from ClickUp (via MCP tool)
-    ↓
-Parse ClickUp description (story markdown)
-    ↓
-Merge frontmatter (preserve local structure, update from ClickUp)
-    ↓
-Reconstruct complete story file
-    ↓
-    ├─ Frontmatter (merged)
-    ├─ Story body (from ClickUp description)
-    └─ Checkbox states (from ClickUp description)
-    ↓
-Write to local file (skipSync=true)
-    ↓
-Display sync summary
-```
-
-## Testing This Task
-
-**Manual Test:**
-1. Mark checkboxes in ClickUp UI for Story 99.2
-2. Run: `*pull-story 99.2`
-3. Verify:
-   - Checkboxes updated in local file
-   - last_sync timestamp updated
-   - Status changes reflected
-   - Summary shows correct change count
-
-**Automated Test:** `tests/tasks/pull-story-from-clickup.test.js`
-
----
-
-*Task created to provide reverse synchronization from ClickUp to local story files*
+---
+tools:
+  - clickup  # Required for ClickUp integration
+checklists:
+  - po-master-checklist.md
+---
+
+# pull-story-from-clickup
+
+**Purpose:** Pull complete story updates from ClickUp to local file, including task completions, description changes, and status updates. This is the **reverse direction** of sync-story-to-clickup.
+
+**When to Use:**
+- After making changes directly in ClickUp UI (marking checkboxes, updating description)
+- When you need to pull latest state from ClickUp to continue work locally
+- After collaborators update the ClickUp task
+- To resolve sync conflicts (ClickUp is the source of truth)
+
+**Important:** This overwrites local changes with ClickUp data. Use carefully if you have uncommitted local edits.
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: poPullStoryFromClickup()
+responsável: Pax (Balancer)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - product-management
+  - planning
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Task Inputs
+
+```yaml
+required:
+  - story_id: '{epic}.{story}' # e.g., "99.2" or "5.2.2"
+
+optional:
+  - force: false # If true, pull even if last_sync indicates local is newer
+```
+
+## Prerequisites
+
+- Story file must exist in `docs/stories/`
+- Story must have ClickUp metadata in frontmatter (clickup.task_id)
+- ClickUp MCP tool must be available and authenticated
+
+## Task Execution Steps
+
+### Step 1: Locate Story File
+
+- Find story file in `docs/stories/` matching story_id pattern
+- Expected format: `{epic}.{story}.*.md`
+- If multiple files found, show list and ask user to clarify
+- If no file found, ERROR and exit
+
+### Step 2: Get ClickUp Task Data
+
+```javascript
+const clickupTool = await getClickUpTool();
+
+// Get complete task data including description
+const task = await clickupTool.getTask({
+  taskId: storyData.frontmatter.clickup.task_id
+});
+```
+
+**What to extract from ClickUp task:**
+- Task description (contains full story markdown)
+- Story-status custom field
+- Task native status
+- Tags
+- Custom fields (epic_number, story_number, story_file_path)
+
+### Step 3: Parse ClickUp Description
+
+The ClickUp task description contains the **complete story markdown**. We need to:
+
+1. Extract the markdown from `task.description`
+2. Parse sections:
+   - Story Statement
+   - Context
+   - Acceptance Criteria (with checkboxes)
+   - Tasks/Subtasks (with checkboxes)
+   - Dev Notes
+   - Testing
+   - File List
+   - QA Results
+   - Notes
+   - Change Log
+
+3. **Critical:** Preserve checkbox states from ClickUp
+   - `- [x] Task` = completed
+   - `- [ ] Task` = pending
+
+### Step 4: Merge with Local Frontmatter
+
+**DO NOT overwrite entire file** - preserve frontmatter structure:
+
+```javascript
+const localFrontmatter = storyData.frontmatter;
+const clickupFrontmatter = {
+  version: localFrontmatter.version,
+  story_id: localFrontmatter.story_id,
+  epic_id: localFrontmatter.epic_id,
+  title: task.name,
+  status: mapStatusFromClickUp(task.custom_fields.find(f => f.name === 'story-status').value),
+  created: localFrontmatter.created,
+  updated: new Date().toISOString().split('T')[0], // Today's date
+  clickup: {
+    task_id: task.id,
+    epic_task_id: task.parent,
+    list: task.list.name,
+    list_id: task.list.id,
+    url: task.url,
+    last_sync: new Date().toISOString(),
+    custom_fields: {
+      epic_number: task.custom_fields.find(f => f.name === 'epic-number')?.value || localFrontmatter.clickup.custom_fields.epic_number,
+      story_number: task.custom_fields.find(f => f.name === 'story-number')?.value || localFrontmatter.clickup.custom_fields.story_number,
+      story_file_path: task.custom_fields.find(f => f.name === 'story-file-path')?.value || localFrontmatter.clickup.custom_fields.story_file_path,
+      'story-status': task.custom_fields.find(f => f.name === 'story-status')?.value
+    }
+  },
+  tags: task.tags.map(t => t.name)
+};
+```
+
+### Step 5: Reconstruct Story File
+
+Build complete story markdown:
+
+```markdown
+# Story {story_id}: {title}
+
+```yaml
+{frontmatter}
+```
+
+{story body from ClickUp description}
+```
+
+**Important:** Use the ClickUp description as the **source of truth** for the story body.
+
+### Step 6: Write Updated Story File
+
+```javascript
+const { saveStoryFile } = require('../../common/scripts/story-manager');
+
+// Save with skipSync=true to avoid circular sync
+await saveStoryFile(storyFilePath, newContent, true);
+```
+
+**Why skipSync=true?**
+- We just pulled from ClickUp, so we don't want to immediately push back
+- Prevents infinite sync loops
+
+### Step 7: Display Sync Summary
+
+```markdown
+✅ Story {story_id} pulled from ClickUp
+
+**Task ID:** {task_id}
+**Task URL:** {url}
+**Last Sync:** {timestamp}
+
+**Changes Pulled:**
+- Status: {old_status} → {new_status} (if changed)
+- Tasks completed: {count of checkboxes changed from [ ] to [x]}
+- Tasks reopened: {count of checkboxes changed from [x] to [ ]}
+- Description updated: {yes/no}
+- Tags updated: {changes}
+
+**Local File Updated:**
+- Frontmatter: ✓
+- Story Body: ✓
+- Checkbox States: ✓
+- Last Sync Timestamp: ✓
+```
+
+## Error Handling
+
+**Error: Story file not found**
+```
+❌ Story file not found for ID: {story_id}
+
+Please check:
+- Story ID format correct? (e.g., "99.2" not "Story 99.2")
+- Story file exists in docs/stories/?
+- File naming follows pattern: {epic}.{story}.*.md
+```
+
+**Error: No ClickUp metadata**
+```
+❌ Story has no ClickUp integration
+
+This story was not created via ClickUp workflow and has no task_id.
+Cannot pull from ClickUp without task_id in frontmatter.
+```
+
+**Error: ClickUp task not found**
+```
+❌ ClickUp task not found: {task_id}
+
+Possible reasons:
+- Task was deleted from ClickUp
+- Task ID is incorrect in frontmatter
+- You don't have access to this task
+- ClickUp API authentication failed
+
+Verify task exists: {task_url}
+```
+
+**Error: Description empty or malformed**
+```
+❌ ClickUp task description is empty or malformed
+
+The task description should contain the full story markdown.
+This may indicate:
+- Task was created manually in ClickUp (not via story-manager)
+- Description was accidentally cleared
+- Task needs to be synced from local first
+
+Recommendation:
+1. Run: *sync-story {story_id}
+2. Then try pulling again
+```
+
+## Usage Examples
+
+### Basic Pull
+```
+*pull-story 99.2
+```
+
+### Force Pull (even if local is newer)
+```
+*pull-story 5.2.2 --force
+```
+
+### After ClickUp Updates
+```
+# Scenario: You marked checkboxes in ClickUp UI
+1. Run: *pull-story {story_id}
+2. Review changes shown in summary
+3. Local file now matches ClickUp
+4. Continue working locally
+```
+
+## Integration Notes
+
+**For PO Agent:**
+- Add to po.md commands: `pull-story {story}`: Pull story updates from ClickUp
+- Use after collaborators update ClickUp tasks
+- Use before starting validation if task was modified in ClickUp
+
+**For Dev Agent:**
+- Add to dev.md commands: `pull-story {story}`: Pull story updates from ClickUp
+- Use at start of work session to get latest state
+- Use after QA or PO updates task in ClickUp
+
+**For QA Agent:**
+- Add to qa.md commands: `pull-story {story}`: Pull story updates from ClickUp
+- Use before starting review to get latest state
+- Use after Dev marks tasks complete in ClickUp
+
+**Best Practice:**
+- Pull at the **start** of work sessions
+- Push (*sync-story) at the **end** of work sessions
+- ClickUp is the source of truth for collaborative updates
+- Local file is the source of truth for agent work
+
+## Workflow Examples
+
+### Collaborative Workflow
+```
+1. PO updates story in ClickUp UI (adds acceptance criteria)
+2. Dev pulls story: *pull-story 5.2.2
+3. Dev implements locally, marks tasks done
+4. Dev pushes to ClickUp: *sync-story 5.2.2
+5. QA pulls latest: *pull-story 5.2.2
+6. QA reviews and updates locally
+7. QA pushes results: *sync-story 5.2.2
+```
+
+### Conflict Resolution
+```
+# If local and ClickUp diverged:
+
+Option 1: ClickUp wins (recommended for collaborative work)
+*pull-story 5.2.2 --force
+
+Option 2: Local wins (when you have important uncommitted work)
+*sync-story 5.2.2 --force
+
+Option 3: Manual merge (complex changes)
+1. Backup local file
+2. Pull from ClickUp
+3. Compare with backup
+4. Manually merge important changes
+5. Push back to ClickUp
+```
+
+## Technical Implementation
+
+**Dependencies:**
+- `common/scripts/story-manager.js` - saveStoryFile, parseStoryFile
+- `common/scripts/status-mapper.js` - mapStatusFromClickUp
+- ClickUp MCP tool (via global.mcp__clickup__* or tool-resolver)
+
+**Process Flow:**
+```
+Task invoked
+    ↓
+Read local story file
+    ↓
+Extract task_id from frontmatter
+    ↓
+Fetch complete task from ClickUp (via MCP tool)
+    ↓
+Parse ClickUp description (story markdown)
+    ↓
+Merge frontmatter (preserve local structure, update from ClickUp)
+    ↓
+Reconstruct complete story file
+    ↓
+    ├─ Frontmatter (merged)
+    ├─ Story body (from ClickUp description)
+    └─ Checkbox states (from ClickUp description)
+    ↓
+Write to local file (skipSync=true)
+    ↓
+Display sync summary
+```
+
+## Testing This Task
+
+**Manual Test:**
+1. Mark checkboxes in ClickUp UI for Story 99.2
+2. Run: `*pull-story 99.2`
+3. Verify:
+   - Checkboxes updated in local file
+   - last_sync timestamp updated
+   - Status changes reflected
+   - Summary shows correct change count
+
+**Automated Test:** `tests/tasks/pull-story-from-clickup.test.js`
+
+---
+
+*Task created to provide reverse synchronization from ClickUp to local story files*