Action Item Organizer

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

Metadata Extraction Patterns

This document provides detailed patterns and strategies for extracting metadata from various document formats when converting them into actionable TODO lists.

Core Metadata Types

1. Task Description

The primary action to be completed.

Extraction Strategies:

From Prose:

• Look for imperative verbs: "Add", "Remove", "Fix", "Implement", "Refactor"
• Extract sentences starting with "Should", "Must", "Need to"
• Convert recommendations into action statements

Examples:

Source: "The authentication system should be updated to use OAuth2."
Extracted: "Update authentication system to use OAuth2"

Source: "Consider refactoring the user service for better maintainability."
Extracted: "Refactor user service for better maintainability"

Source: "It would be good to add caching here."
Extracted: "Add caching to improve performance"

From Lists:

• Already in action format, extract directly
• Add context if the list item is terse

Examples:

Source: "- Add tests"
Extracted: "Add unit tests for user service"

Source: "- Fix bug"
Extracted: "Fix null pointer exception in data processing"

2. Priority Level

The urgency and importance of the task.

Extraction Strategies:

Explicit Markers:

• "P0", "P1", "P2", "P3"
• "Critical", "High", "Medium", "Low"
• "Blocker", "Major", "Minor", "Trivial"
• "Must", "Should", "Could", "Won't" (MoSCoW)

Implicit Signals:

• Section headings: "Critical Issues", "Immediate Actions"
• Language intensity: "MUST fix", "Should consider"
• Context clues: "blocking deployment", "nice to have"

Examples:

Source: "CRITICAL: Fix authentication bypass"
Extracted Priority: P0

Source: "Consider adding pagination for better UX"
Extracted Priority: P3

Source: "Security Issue: SQL injection in user query"
Extracted Priority: P0 or P1 (based on exposure)

Source: "Code smell: Large function could be split"
Extracted Priority: P2

Priority Inference Table:

3. File Paths and Line Numbers

Location in the codebase where action is needed.

Extraction Patterns:

Standard Formats:

path/to/file.ext:line
path/to/file.ext:startLine-endLine
path/to/file.ext:line:column
/absolute/path/to/file.ext:line

Common Variations:

"in file.ext at line 123"
"file.ext (line 123)"
"See path/to/file.ext"
"path/to/file.ext, lines 10-20"

Regex Patterns:

# Standard colon format
[\w/.-]+\.(js|ts|py|java|go|rb|php|cs|cpp|h):\d+(-\d+)?

# Prose format
(?:in|at|see)\s+[\w/.-]+\.(ext)(?:\s+at\s+)?(?:line|lines)?\s*\d+

# Parenthetical format
[\w/.-]+\.(ext)\s*\(line\s*\d+\)

Examples:

Source: "Add validation in app/api/user/route.ts:45"
Extracted: app/api/user/route.ts:45

Source: "The calculateTotal function (utils/math.js, line 89) needs error handling"
Extracted: utils/math.js:89

Source: "See authentication middleware for details"
Extracted: (Note: File path not specified, mark as TBD)

Handling Missing Paths:

When file paths are not specified:

• Mark as "File: TBD" in output
• Add note to investigate and add path
• Try to infer from context or section headings

4. Owner/Responsible Party

Who should complete the task.

Extraction Patterns:

Direct Assignment:

"@username"
"Assigned to: Team Name"
"Owner: Sarah"
"Responsibility: Backend team"

Implicit Assignment:

• Section headings: "Backend Tasks", "Frontend Items"
• Context clues: "security team should review"
• Component ownership: "API gateway team"

Examples:

Source: "@sarah: Update user model schema"
Extracted Owner: Sarah

Source: "Frontend team needs to add loading states"
Extracted Owner: Frontend Team

Source: "Security audit required"
Extracted Owner: Security Team (or TBD if unclear)

Owner Normalization:

• Convert handles to names if known
• Use consistent team names
• Default to "TBD" if unspecified

5. Time Estimates

Expected effort to complete the task.

Extraction Patterns:

Standard Formats:

"2 hours"
"4h"
"1 day"
"3-5 hours"
"2-4d"
"30 minutes"

Conversion Rules:

• Standardize to hours when possible
• "days" → multiply by 8 (1 day = 8 hours)
• "minutes" → keep as-is or convert to decimal hours
• Ranges → keep as range or use upper bound

Examples:

Source: "Should take about 2 hours"
Extracted: 2 hours

Source: "Est: 1-2 days"
Extracted: 8-16 hours (or "1-2 days")

Source: "Quick fix, 30 min"
Extracted: 0.5 hours (or "30 minutes")

Source: "Complex refactor, at least a week"
Extracted: 40+ hours (or "1+ weeks")

Inference When Missing:

• Mark as "Estimate: TBD"
• Consider task complexity for rough estimate
• Don't guess without reasonable basis

Estimate Complexity Factors:

Simple (1-2 hours):
- Small bug fixes
- Minor text changes
- Simple configuration updates

Medium (4-8 hours):
- New small features
- Moderate refactoring
- Integration of existing components

Complex (16+ hours):
- New major features
- Architectural changes
- Complex security implementations

6. Tracking IDs

Issue, ticket, or tracking numbers.

Extraction Patterns:

Common Formats:

"#123"
"JIRA-456"
"GH-789"
"Issue #123"
"Ticket: 456"

Regex Patterns:

# Hash format
#\d+

# Prefix format
[A-Z]+-\d+

# Full text format
(?:Issue|Ticket|Bug|Task)\s*[:#]?\s*\d+

Examples:

Source: "Fix caching issue #234"
Extracted ID: #234

Source: "JIRA-1234: Implement user roles"
Extracted ID: JIRA-1234

Source: "Related to GitHub issue 567"
Extracted ID: GH-567 (or #567)

Multiple IDs:

Source: "Fixes #123, relates to #456"
Extracted: (#123, #456)

Source: "Implements JIRA-789 and JIRA-790"
Extracted: (JIRA-789, JIRA-790)

7. Categories/Tags

Domain or type classification.

Common Categories:

• Security
• Performance
• Bug Fix
• Feature
• Refactoring
• Testing
• Documentation
• DevOps
• UI/UX
• Database
• API
• Accessibility

Extraction Strategies:

From Section Headers:

Source: Under "Security Issues" heading
Extracted Category: Security

Source: Under "Performance Optimizations"
Extracted Category: Performance

From Keywords:

Source: "Add authentication to endpoint"
Extracted Category: Security

Source: "Optimize database query"
Extracted Category: Performance

Source: "Add unit tests for user service"
Extracted Category: Testing

From Tags:

Source: "[security] Fix XSS vulnerability"
Extracted Category: Security

Source: "(perf) Reduce bundle size"
Extracted Category: Performance

8. Context and Rationale

Why the task matters.

Extraction Strategies:

From Explanatory Text:

Source: "Add rate limiting to prevent DDoS attacks and ensure service availability"
Extracted Context: Prevents DDoS attacks and ensures service availability

Source: "Refactor UserService because the current implementation is tightly coupled and hard to test"
Extracted Context: Current implementation is tightly coupled and hard to test

From Impact Statements:

Source: "Missing input validation allows SQL injection, potentially exposing user data"
Extracted Context: Allows SQL injection, potentially exposing user data

Source: "N+1 query causing 5-second page load times for users"
Extracted Context: Causing 5-second page load times

Context Signals:

• "because", "since", "in order to"
• "This will", "This prevents", "This enables"
• "Currently", "The problem is"
• "Impact:", "Risk:", "Benefit:"

Document Format Patterns

Code Review Reports

Structure Recognition:

# Code Review Report

## Critical Issues
- Issue 1
- Issue 2

## Warnings
- Warning 1

## Suggestions
- Suggestion 1

Extraction Pattern:

1. Map sections to priorities (Critical → P0, Warnings → P1, Suggestions → P2-P3) 2. Extract file paths from issue descriptions 3. Infer owner from file/module structure 4. Extract context from explanatory paragraphs

Example:

Source Section: "## Critical Issues"
Source Item: "**Security**: Remove hardcoded API key in auth.js:23. This exposes credentials in version control."

Extracted:
- Priority: P0
- Category: Security
- Task: Remove hardcoded API key
- File: auth.js:23
- Context: Exposes credentials in version control

Meeting Notes

Structure Recognition:

# Team Meeting - 2024-12-09

Discussion topics...

## Action Items
- @sarah will implement feature X by Friday
- Backend team to investigate performance issue
- Everyone: review PR #123 before next meeting

Extraction Pattern:

1. Focus on "Action Items", "Next Steps", "TODO" sections 2. Extract owner from @mentions or "X will Y" patterns 3. Extract deadlines from temporal phrases 4. Infer priority from urgency language

Example:

Source: "@sarah will implement OAuth2 authentication ASAP due to security concerns"

Extracted:
- Owner: Sarah
- Task: Implement OAuth2 authentication
- Priority: P0 or P1 (ASAP + security)
- Context: Security concerns

Audit Reports

Structure Recognition:

# Security Audit Report

## High Risk Findings
1. SQL Injection vulnerability in user search
   - File: search.php, line 45
   - Impact: Database compromise
   - Recommendation: Use parameterized queries

## Medium Risk Findings
...

Extraction Pattern:

1. Map risk levels to priorities (High → P0/P1, Medium → P2, Low → P3) 2. Extract recommendations as tasks 3. Extract file paths from "File:" or "Location:" fields 4. Extract impact as context

Example:

Source Finding: "SQL Injection vulnerability in user search"
Source File: "search.php, line 45"
Source Recommendation: "Use parameterized queries"
Source Impact: "Database compromise"

Extracted:
- Priority: P0
- Category: Security
- Task: Fix SQL injection in user search
- Sub-task: Use parameterized queries
- File: search.php:45
- Context: Risk of database compromise

Issue Trackers

Structure Recognition:

Issue #123: Add user authentication

Priority: High
Assignee: @backend-team
Labels: security, enhancement
Estimated: 8 hours

Description:
Current system lacks authentication...

Acceptance Criteria:
- [ ] Implement login endpoint
- [ ] Add session management
- [ ] Add logout endpoint

Extraction Pattern:

1. Issue title becomes main task 2. Acceptance criteria become sub-tasks 3. Priority maps directly 4. Assignee becomes owner 5. Description provides context

Project Plans

Structure Recognition:

# Q4 2024 Roadmap

## Phase 1: Foundation (High Priority)
- Set up CI/CD pipeline (DevOps, 2 weeks)
- Implement user authentication (Backend, 1 week)

## Phase 2: Features (Medium Priority)
- Add dashboard views (Frontend, 3 weeks)

Extraction Pattern:

1. Phase indicates priority grouping 2. Task description includes category and estimate 3. Owner often in parentheses 4. Timeline provides deadline context

Edge Cases and Special Handling

Ambiguous Priorities

When priority is unclear:

1. Use context clues (security → higher, cosmetic → lower) 2. Default to P2 (medium) and flag for review 3. Note: "Priority needs review" in context

Nested Action Items

When items have sub-items:

Source:
"Implement authentication:
  - Add login endpoint
  - Add session management
  - Add logout endpoint"

Extracted:
- [ ] Implement authentication
  - [ ] Add login endpoint
  - [ ] Add session management
  - [ ] Add logout endpoint

Duplicate Items

When same item appears multiple times:

1. Consolidate into single item 2. Combine context from all occurrences 3. Note multiple sources if from different documents

Completed Items

When item is marked complete in source:

1. Skip if creating new TODO list 2. Include with [x] if tracking existing progress 3. Note completion in context

Vague or Unclear Items

When item lacks specificity:

1. Extract as-is but flag for clarification 2. Add note: "Needs clarification" in context 3. Mark metadata as TBD where appropriate

Validation Checklist

After extraction, verify:

• [ ] All actionable items from source are included
• [ ] Priorities are consistently applied
• [ ] File paths are accurate and complete
• [ ] Owners are assigned or marked TBD
• [ ] Context explains why each task matters
• [ ] Nested relationships are preserved
• [ ] Tracking IDs are included where available
• [ ] Estimates are included or marked TBD

Examples by Document Type

Example 1: Dense Code Review Report

Source:

app/api/auth.ts:45 - Critical: Hardcoded credentials found. Remove immediately.
The SECRET_KEY variable contains production credentials. This poses severe
security risk if committed to version control. Estimate: 30 minutes.

app/utils/db.ts:89-102 - Warning: N+1 query in getUserPosts. This causes
performance issues when users have many posts. Consider using JOIN or eager
loading. Owner: backend team. Estimate: 2 hours.

Extracted:

- [ ] **Security: Remove hardcoded credentials** (#1)
  - [ ] Remove SECRET_KEY variable from code
  - [ ] Move to environment variables
  - [ ] Verify not in git history
  - **File**: `app/api/auth.ts:45`
  - **Owner**: TBD
  - **Estimate**: 0.5 hours
  - **Priority**: P0
  - **Context**: Production credentials in code pose severe security risk

- [ ] **Performance: Fix N+1 query in getUserPosts** (#2)
  - [ ] Refactor to use JOIN or eager loading
  - **File**: `app/utils/db.ts:89-102`
  - **Owner**: Backend Team
  - **Estimate**: 2 hours
  - **Priority**: P1
  - **Context**: Causes performance issues when users have many posts

Example 2: Unstructured Meeting Notes

Source:

Sarah mentioned we need to update the docs before launch. Mike said
the deployment script is broken and needs fixing urgently. Let's also
consider adding dark mode at some point.

Extracted:

- [ ] **DevOps: Fix broken deployment script**
  - **Owner**: Mike
  - **Estimate**: TBD
  - **Priority**: P0
  - **Context**: Blocking deployment (urgently needed before launch)

- [ ] **Documentation: Update docs before launch**
  - **Owner**: Sarah
  - **Estimate**: TBD
  - **Priority**: P1
  - **Context**: Required before launch

- [ ] **UI: Add dark mode**
  - **Owner**: TBD
  - **Estimate**: TBD
  - **Priority**: P3
  - **Context**: Future enhancement to consider

Conclusion

Effective metadata extraction requires:

1. Pattern recognition across document formats 2. Contextual inference when explicit data is missing 3. Consistent normalization of extracted data 4. Validation to ensure completeness 5. Clear marking of TBD items for follow-up

Use these patterns as a guide, but always apply judgment based on the specific document structure and domain context.

Priority Classification Framework

This document provides comprehensive guidance for classifying action items into priority levels (P0-P3) across different domains.

Core Priority Definitions

P0 - Blockers (Critical)

Items that MUST be resolved before proceeding with deployment, merge, or next phase.

Characteristics:

• Prevents critical functionality
• Poses immediate security threat
• Causes data loss or corruption
• Violates compliance requirements
• Blocks other team members
• Creates production outage risk

Time Sensitivity: Immediate (hours, not days)

Examples:

• Security vulnerability exposing user data
• Critical bug causing system crashes
• Missing authentication on public API
• Data corruption in production database
• Compliance violation (GDPR, HIPAA, etc.)
• Broken build preventing deployment

P1 - High Priority

Significant issues that should be addressed promptly but don't block immediate progress.

Characteristics:

• Major quality concerns
• Significant performance impact
• Important security concerns (not critical)
• Functional correctness issues
• High technical debt
• Affects user experience significantly

Time Sensitivity: Days to 1 week

Examples:

• SQL injection vulnerability in admin panel
• N+1 query problem causing slow page loads
• Missing error handling for critical operations
• Architectural issues affecting scalability
• Major code duplication across modules
• Incomplete test coverage for core features

P2 - Medium Priority

Important improvements that enhance the system but aren't urgent.

Characteristics:

• Code quality improvements
• Moderate refactoring needs
• Documentation gaps
• Minor performance optimizations
• Test coverage improvements
• Usability enhancements

Time Sensitivity: Weeks to 1 month

Examples:

• Refactor complex function into smaller units
• Add JSDoc comments to public API
• Optimize database query (not causing issues yet)
• Improve error messages for clarity
• Add integration tests for new feature
• Update dependencies to latest versions

P3 - Low Priority (Future)

Nice-to-have improvements and optimizations.

Characteristics:

• Code style and consistency
• Future enhancements
• Exploratory tasks
• Minor optimizations
• Cosmetic improvements
• Technical debt with low impact

Time Sensitivity: Months or backlog

Examples:

• Rename variables for consistency
• Add code comments for clarity
• Explore alternative libraries
• Micro-optimizations
• Refactor for future extensibility
• Update code style to match new standard

Domain-Specific Priority Guides

Security Issues

Performance Issues

Code Quality Issues

Testing Issues

Documentation Issues

Priority Decision Framework

When in doubt, use this decision tree:

Does this prevent deployment or cause production issues?
├─ Yes → P0
└─ No → Continue

Does this affect security, data integrity, or core functionality?
├─ Yes → P0 or P1 (based on severity)
└─ No → Continue

Does this significantly impact user experience or performance?
├─ Yes → P1
└─ No → Continue

Does this affect code quality, maintainability, or technical debt?
├─ Yes → P2
└─ No → P3

Priority Modifiers

Consider these factors that can adjust priority up or down:

Increase Priority If

• Affects production environment
• Impacts many users
• Blocks other team members
• Has compliance implications
• Creates security risk
• Difficult to fix later
• Causes data loss/corruption

Decrease Priority If

• Only affects development environment
• Rare edge case
• Internal tooling only
• Easy to fix later
• Low impact on users
• Workaround exists
• Not blocking any work

Common Priority Mistakes

Priority Inflation

Don't mark everything as P0. Reserve P0 for true blockers.

Bad: All 20 code review findings marked as P0 Good: 2 security issues are P0, rest distributed across P1-P3

Priority Deflation

Don't downplay serious issues to avoid work.

Bad: SQL injection marked as P3 because it's "internal only" Good: SQL injection is P0 or P1 regardless of scope

Ignoring Context

Consider the broader context, not just the code.

Bad: Missing tests marked P2 for critical payment processing Good: Missing tests marked P0 for critical payment processing

Inconsistent Standards

Apply the same priority criteria consistently.

Bad: Same issue is P0 in file A but P2 in file B Good: Same issue type gets same priority regardless of location

Multi-Dimensional Priority Scoring

For complex prioritization, consider scoring across dimensions:

Impact Score (1-5):
- How many users affected?
- How severe is the impact?
- What's the business risk?

Urgency Score (1-5):
- How time-sensitive is this?
- Is there a deadline?
- Is it blocking other work?

Effort Score (1-5):
- How complex to fix?
- What's the time estimate?
- What dependencies exist?

Final Priority:
- High Impact + High Urgency → P0
- High Impact + Medium Urgency → P1
- Medium Impact + High Urgency → P1
- Medium Impact + Medium Urgency → P2
- Low Impact or Low Urgency → P2 or P3

Priority Review Triggers

Re-evaluate priorities when:

• Approaching a release deadline
• Production incident occurs
• Business priorities shift
• New security vulnerability discovered
• Team capacity changes
• Dependencies are updated
• User feedback indicates different severity

Examples by Domain

E-commerce Application

P0:

• Checkout process broken
• Payment processing fails
• User authentication bypassed
• Prices displayed incorrectly

P1:

• Search results incomplete
• Product images not loading
• Email notifications not sent
• Admin panel slow to load

P2:

• Product sorting could be improved
• Missing product reviews
• Checkout flow could be smoother
• Analytics tracking incomplete

P3:

• UI polish and animations
• Additional product filters
• Admin UI improvements
• Code refactoring for maintainability

Internal Dashboard

P0:

• Data displayed is incorrect
• User cannot log in
• Dashboard completely broken
• Data export corrupts data

P1:

• Slow query affecting page load
• Missing error handling
• Critical feature not working
• Data refresh is slow

P2:

• UI could be more intuitive
• Additional filters needed
• Export format improvements
• Code organization

P3:

• Color scheme updates
• Additional chart types
• Keyboard shortcuts
• Code comments

Priority Communication

When communicating priorities to stakeholders:

P0 Communication: "This MUST be fixed before we can deploy. It poses immediate risk."

P1 Communication: "This should be addressed in the current sprint. It's important but not blocking."

P2 Communication: "This should be scheduled in the next 1-2 sprints. It improves quality."

P3 Communication: "This can be added to the backlog for future consideration."

Conclusion

Priority classification is both an art and a science. Use this framework as a guide, but always apply judgment based on:

• Business context
• Team capacity
• Project timeline
• Risk tolerance
• User impact

When in doubt, err on the side of higher priority and discuss with the team.

TO-DO List

Project: {{PROJECT_NAME}} Last Updated: {{DATE}} Owner: {{OWNER}}

---

Quick Stats

---

Active Tasks

P0 - Critical (Do First)

• [ ] {{TASK_TITLE}} {{LABEL}}
• Due: {{DATE}}
• Context: {{BRIEF_CONTEXT}}
• Blocked by: {{DEPENDENCY}} (if applicable)

P1 - High Priority

• [ ] {{TASK_TITLE}} {{LABEL}}
• Due: {{DATE}}
• Context: {{BRIEF_CONTEXT}}

P2 - Medium Priority

• [ ] {{TASK_TITLE}} {{LABEL}}
• Context: {{BRIEF_CONTEXT}}

P3 - Low Priority / Backlog

• [ ] {{TASK_TITLE}} {{LABEL}}
• Context: {{BRIEF_CONTEXT}}

---

In Progress

---

Blocked

---

Completed

{{WEEK_OR_SPRINT}}

• [x] ~~{{COMPLETED_TASK}}~~ {{LABEL}} - {{COMPLETION_DATE}}
• [x] ~~{{COMPLETED_TASK}}~~ {{LABEL}} - {{COMPLETION_DATE}}

Previous

<details> <summary>{{PREVIOUS_PERIOD}} ({{N}} tasks)</summary>

• [x] ~~{{TASK}}~~ - {{DATE}}
• [x] ~~{{TASK}}~~ - {{DATE}}

</details>

---

Labels

---

Notes

{{ADDITIONAL_CONTEXT_OR_DECISIONS}}

---

Archive Format

When archiving completed tasks, move to: /docs/archive/todos-{{YYYY-MM}}.md