action-item-organizer

What this skill does

# Action Item Organizer

This skill provides a systematic framework for extracting actionable items from unstructured documents and transforming them into well-organized, prioritized, trackable checklists in markdown format.

## When to Use This Skill

- Converting code review reports into TODO lists
- Extracting action items from meeting notes
- Organizing audit findings into remediation checklists
- Breaking down project planning documents into task lists
- Structuring issue reports into actionable work items
- Creating trackable checklists from any document containing embedded action items
- Organizing team backlogs by priority
- Creating sprint planning checklists

## Core Principles

### 1. Extraction with Context Preservation

Action items must be extracted with sufficient context so that anyone reading the checklist understands:

- **What** needs to be done
- **Why** it matters
- **Where** it applies (files, systems, components)
- **Who** is responsible
- **When** it should be completed (priority and estimates)

### 2. Priority-Based Organization

Use a clear priority framework to organize items by urgency and impact:

- **P0 / Blockers**: Critical issues that prevent progress, deployment, or merge
- **P1 / High Priority**: Significant quality, security, or correctness concerns requiring prompt attention
- **P2 / Medium Priority**: Important improvements and refactorings that enhance the system
- **P3 / Low Priority**: Future optimizations, minor suggestions, and nice-to-have enhancements

Within each priority level, group related items logically (e.g., security items together, performance items together).

### 3. Nested Structure for Complex Tasks

Break down complex action items into hierarchical checklists:

- Parent items represent the main task or goal
- Child items represent specific steps or sub-tasks
- Grandchild items represent detailed implementation steps

This creates a clear execution path and allows for granular progress tracking.

### 4. Traceability and Metadata

Maintain links between action items and their sources:

- File paths and line numbers
- Issue or tracking IDs
- Owner or responsible team
- Time estimates
- Original context from source document

This enables bidirectional traceability and informed prioritization.

## Extraction Workflow

### Step 1: Document Analysis

1. Read the complete source document
2. Identify sections containing actionable content:
   - "Action Items", "Todo List", "Recommendations"
   - "Issues", "Findings", "Follow-ups"
   - "Next Steps", "Tasks", "Requirements"
3. Understand the document structure and conventions

### Step 2: Action Item Identification

Extract items that are:

- **Actionable**: Specific tasks that can be completed
- **Testable**: Clear completion criteria
- **Assigned or assignable**: Can be owned by a person or team
- **Contextual**: Include enough detail to understand the task

Skip items that are:

- Purely informational (unless they imply action)
- Already completed
- Vague or unclear without additional context

### Step 3: Metadata Extraction

For each action item, extract:

**Required Metadata:**

- Task description
- Priority level

**Optional Metadata (extract if available):**

- File paths and line numbers
- Owner/responsible party
- Time estimate
- Issue/tracking numbers
- Category or domain (security, performance, etc.)
- Implementation steps or sub-tasks

### Step 4: Priority Classification

Assign each item to a priority level based on:

**P0 Criteria:**

- Blocks deployment or merge
- Critical security vulnerability
- Data loss or corruption risk
- System availability impact
- Compliance violation

**P1 Criteria:**

- Significant security concern
- Major performance impact
- Correctness issues affecting functionality
- Important architectural problems
- High technical debt

**P2 Criteria:**

- Code quality improvements
- Moderate refactoring needs
- Test coverage gaps
- Documentation needs
- Minor performance optimizations

**P3 Criteria:**

- Code style and consistency
- Future enhancements
- Nice-to-have features
- Minor optimizations
- Exploratory tasks

### Step 5: Hierarchical Organization

Structure items using nested checklists:

```markdown
- [ ] **Category: Main task description** (#tracking-id)
  - [ ] Sub-task 1
  - [ ] Sub-task 2
    - [ ] Detailed implementation step
  - **File**: `path/to/file.ext:lines`
  - **Owner**: Team/Person
  - **Estimate**: Time estimate
  - **Context**: Why this matters and what it achieves
```

### Step 6: Summary Generation

For each priority section, calculate:

- Total number of items
- Total estimated hours (if available)
- Completion percentage (if tracking existing checklist)

### Step 7: Output Formatting

Create a structured markdown document with:

1. **Header**: Title, generation metadata, source reference
2. **Overview**: Total items and time across all priorities
3. **Priority Sections**: P0, P1, P2, P3 with summaries
4. **Completion Tracking**: Progress metrics at the bottom

## Checklist Format Standards

### Basic Checkbox Item

```markdown
- [ ] Task description
```

### Item with Metadata

```markdown
- [ ] **Category: Task description** (#123)
  - **File**: `src/file.js:45-67`
  - **Owner**: Backend Team
  - **Estimate**: 3 hours
  - **Context**: Explanation of why this matters
```

### Nested Sub-tasks

```markdown
- [ ] **Security: Implement authentication** (#456)
  - [ ] Add session validation
  - [ ] Implement rate limiting
  - [ ] Add authorization checks
  - **File**: `api/auth.ts`
  - **Owner**: Security Team
  - **Estimate**: 8 hours
```

### Section Summary

```markdown
## P0 - Blockers (Must Fix Before Merge)

**Summary**: 5 items | 12 hours estimated

- [ ] Item 1...
- [ ] Item 2...
```

## Complete Output Template

```markdown
# TODO List

> Generated from: [source-document.md]
> Date: YYYY-MM-DD HH:MM:SS
> Total Items: X | Total Estimated Hours: Y

## P0 - Blockers (Must Fix Before Merge)

**Summary**: N items | M hours estimated

- [ ] **Category: Task description** (#id)
  - [ ] Sub-task
  - **File**: `path/file.ext:lines`
  - **Owner**: Team
  - **Estimate**: X hours
  - **Context**: Why this matters

## P1 - High Priority

**Summary**: N items | M hours estimated

[items...]

## P2 - Medium Priority

**Summary**: N items | M hours estimated

[items...]

## P3 - Low Priority / Future

**Summary**: N items | M hours estimated

[items...]

---

## Completion Tracking

- P0 Blockers: 0/N completed (0%)
- P1 High Priority: 0/M completed (0%)
- P2 Medium Priority: 0/K completed (0%)
- P3 Low Priority: 0/J completed (0%)

**Overall Progress**: 0/X tasks completed (0%)
```

## Best Practices

### Context Preservation

- Include enough detail that readers understand WHY each task matters
- Preserve the original rationale and justification
- Link to related issues or documentation
- Capture the impact of not completing the task

### Logical Grouping

- Group related items within priority levels
- Use category prefixes (Security, Performance, Testing, etc.)
- Keep dependent tasks near each other
- Consider execution order in grouping

### Actionability

- Each checkbox should be a clear, completable action
- Avoid vague tasks like "improve performance"
- Use specific verbs: implement, add, remove, refactor, fix
- Include success criteria when helpful

### Traceability

- Always link back to source files and line numbers
- Include issue or tracking IDs
- Reference original documentation
- Enable bidirectional navigation

### Completeness

- Verify all action items from source are included
- Preserve nested relationships
- Don't lose metadata in extraction
- Handle edge cases explicitly

## Handling Edge Cases

### Missing Priority

- Place in "Uncategorized" section at bottom
- Flag for review and prioritization
- Use context clues to infer if possible

### Missing Metadata

- Use "TBD" markers for missing estimates
- Note "File: TBD" to prompt investigation
- Flag items with insufficient cont