name: action-item-organizer
description: Systematic framework for extracting actionable items from documents and
  organizing them into prioritized, trackable checklists. Use when converting reports,
  meeting notes, audits, or any document with embedded action items into structured
  TODO lists.
author: Joseph OBrien
status: unpublished
updated: '2025-12-23'
version: 1.0.1
tag: skill
type: skill

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:

- [ ] **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

- [ ] Task description

Item with Metadata

- [ ] **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

- [ ] **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

## P0 - Blockers (Must Fix Before Merge)

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

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

Complete Output Template

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

Conflicting Priorities

• Defer to explicit priority markers in source
• Consider impact and urgency
• Document rationale for priority assignment

Existing TODO Files

• Confirm before overwriting
• Consider timestamped filenames
• Merge with existing if appropriate

Multiple Sources

• Process each independently
• Or consolidate into single list with source markers
• Deduplicate when appropriate

Anti-Patterns to Avoid

Losing Context

Bad: - [ ] Fix bug Good: - [ ] **Bug Fix: Handle null response in user fetch** (#789)

Flat Structure

Bad: Ten separate items for one complex task Good: One parent with nested sub-tasks

Missing Traceability

Bad: No file paths or line numbers Good: Always include location metadata

Vague Tasks

Bad: - [ ] Improve performance Good: - [ ] **Performance: Add caching to user query** - reduces DB calls from 100/req to 1/req

Priority Inflation

Bad: Everything is P0 Good: Reserve P0 for true blockers

Examples

Example 1: Code Review Report to TODO

Input: Code review report with security findings

Output:

# TODO List

> Generated from: CODE_REVIEW_REPORT.md
> Date: 2025-12-09 10:30:00
> Total Items: 8 | Total Estimated Hours: 23

## P0 - Blockers (Must Fix Before Merge)

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

- [ ] **Security: Add authentication to token endpoint** (#1)
  - [ ] Implement getServerSession check
  - [ ] Add authorization verification
  - [ ] Add rate limiting (10 req/min per IP)
  - **File**: `app/api/livekit/token/route.ts:15-30`
  - **Owner**: Backend Team
  - **Estimate**: 4 hours
  - **Context**: Public endpoint exposed without auth allows unauthorized access

- [ ] **Security: Remove hardcoded credentials** (#2)
  - [ ] Remove fallback values from environment reads
  - [ ] Add explicit validation for required credentials
  - [ ] Fail fast if credentials missing at startup
  - **File**: `experiments/livekit/src/index.ts:182-183`
  - **Owner**: Backend Team
  - **Estimate**: 1 hour
  - **Context**: Hardcoded fallbacks create security risk in production

Example 2: Meeting Notes to Action Items

Input: Team meeting notes with scattered action items

Output:

# Action Items - Q4 Planning Meeting

> Generated from: team-meeting-2025-12-09.md
> Date: 2025-12-09 14:00:00
> Total Items: 12 | Total Estimated Hours: 45

## P1 - High Priority

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

- [ ] **Architecture: Design new API gateway** (#45)
  - [ ] Research existing solutions (Kong, Tyk, AWS API Gateway)
  - [ ] Document requirements and constraints
  - [ ] Create comparison matrix
  - [ ] Present findings to team
  - **Owner**: Sarah
  - **Estimate**: 8 hours
  - **Context**: Current gateway hitting scale limits at 1000 req/s

- [ ] **Documentation: Update onboarding guide** (#46)
  - [ ] Add sections on local development setup
  - [ ] Document deployment process
  - [ ] Add troubleshooting guide
  - **Owner**: Mike
  - **Estimate**: 4 hours
  - **Context**: New engineers spending 2 days on setup

Reference Files

For detailed guidance on specific aspects of action item organization:

• references/priority-framework.md: Comprehensive priority classification criteria with domain-specific examples
• references/metadata-extraction-patterns.md: Detailed patterns for extracting different types of metadata from various document formats
• references/TODO_LIST.template.md: TODO list template with priority-based organization (P0-P3), blocked tasks, and completion tracking

Load these references when you need deeper guidance on priority decisions or metadata extraction strategies.

Related Workflows

• Code review processes
• Sprint planning
• Issue triage
• Project management
• Audit remediation
• Meeting facilitation
• Documentation review