List Todos

Analyze the TODO items in TODOS.md and produce a prioritized list with implementation guidance.

Prerequisites

Before starting:

• Confirm TODOS.md exists in the current working directory. If it does not exist, STOP and ask the user where their project TODOs live.

Process

Copy this checklist and track progress:

List TODOs Progress:
- [ ] Step 1: Read TODOS.md
- [ ] Step 2: Read project context (optional)
- [ ] Step 3: Extract TODO items
- [ ] Step 4: Analyze each item
- [ ] Step 5: Sort by priority score
- [ ] Step 6: Research & Suggest (MEDIUM+ clarity items)
- [ ] Step 7: Output prioritized list
- [ ] Step 8: Interactive Q&A (if items need clarification)
- [ ] Step 9: Update TODOS.md with clarifications

1. Read TODOS.md from the project root
2. Read project context (optional) — Look for context files in this order of preference:
   • VISION.md (if exists, use for project alignment)
   • PRODUCT_SPEC.md (fallback if no VISION.md)
   • TECHNICAL_SPEC.md, AGENTS.md, EXECUTION_PLAN.md (additional context if they exist)
   • If none exist, proceed without project context — analyze based on TODO content alone
3. Extract TODO items — Parse all actionable items from TODOS.md
4. Analyze each item using the framework below
5. Sort by priority score (highest first), break ties by value to project
6. Research & Suggest — For the top 5 eligible items (MEDIUM+ clarity, not completed/deferred/removed), perform web research and generate actionable suggestions. See SUGGESTIONS_WORKFLOW.md for the full protocol.
7. Output the prioritized list

Analysis Framework

For each TODO item, evaluate:

Ranking Factors

Assessing Value to Project:

• If VISION.md or PRODUCT_SPEC.md exists, evaluate how strongly the item aligns with the stated vision and goals
• If no context files exist, assess value based on the TODO item's own description and apparent impact
• Items that directly advance the core vision/goals score higher than tangential improvements
• Consider both immediate utility and strategic alignment

Critical Rule: Do NOT Infer

If requirements clarity is LOW, do NOT attempt to infer what the item means.

• Do NOT guess the implementation approach
• Do NOT assume what problem it solves
• Set Ease and Value to "Cannot assess"
• Focus Open Questions on understanding the basic intent

A one-liner TODO like "Add feature X" with no additional context = LOW clarity, regardless of how obvious it might seem.

Priority Score Calculation

Priority = ((Clarity + Ease + (Value × 2)) / 4 × 10) × Personal Multiplier

Where each factor is scored 1-3 (Low=1, Medium=2, High=3). Value is weighted 2× because alignment with project goals is the strongest signal for prioritization.

Personal Priority Multiplier:

• Look for [priority: N] inline in the TODO item (e.g., [priority: 1.5])
• Valid range: 0.5 to 2.0
• If not specified, default to 1.0
• Examples:
  • [priority: 2] — User considers this twice as important
  • [priority: 0.5] — User considers this half as important
  • [priority: 1.5] — User considers this 50% more important

If Clarity is LOW, cap the Priority Score at 3/10 maximum (applied before multiplier).

Adjust score based on:

• Boost (+1-2): Blocks other work, security-related, frequently requested
• Reduce (-1-2): Speculative, already has workaround, external dependency

Output Format

For items with HIGH or MEDIUM requirements clarity:

## {N}. {TODO Title}

**Priority Score:** {N}/10 {if multiplier != 1.0: "(base {base}/10 × {multiplier})"}
**Ranking Factors:**
- Requirements Clarity: {Medium|High} — {one sentence explanation}
- Ease of Implementation: {Low|Medium|High} — {one sentence explanation}
- Value to Project: {Low|Medium|High} — {one sentence explanation}
{if multiplier != 1.0: "- Personal Priority: ×{multiplier}"}

**Implementation Notes:**
{2-4 sentences on how to implement: key files to modify, approach, dependencies, estimated scope}

**Suggestions:**
{Only for researched items with MEDIUM+ clarity. Omit this section entirely for LOW clarity or non-researched items.}
- **Approach:** {implementation approach from research}
- **Tools:** {specific tools/libraries with versions}
- **Pattern:** {architecture/design pattern recommendation}
- **Watch out:** {risks, gotchas, common pitfalls}
- **Reference:** {URL to relevant documentation}
{Include only categories with actual findings. If researched but nothing found: "No actionable suggestions found from research."}

**Open Questions:**
- {Question that would improve requirements clarity}
- {Another question, if applicable}

**Suggested Next Action:** {One of: "Ready to implement", "Needs research", "Consider deferring", "Consider removing"}

For items with LOW requirements clarity:

## {N}. {TODO Title}

**Priority Score:** {N}/10 (capped due to unclear requirements{if multiplier != 1.0: ", ×{multiplier} applied"})
**Ranking Factors:**
- Requirements Clarity: **Low** — {explain what's missing: no context, unclear intent, etc.}
- Ease of Implementation: Cannot assess
- Value to Project: Cannot assess
{if multiplier != 1.0: "- Personal Priority: ×{multiplier}"}

**What I understand:** {Brief statement of what little is clear, or "Only the title"}

**What I don't understand:**
- {Specific gap in understanding}
- {Another gap}

**Questions to clarify before proceeding:**
1. {Fundamental question about intent/purpose}
2. {Question about scope}
3. {Question about expected behavior}

**Suggested Next Action:** Clarify requirements first

Summary section:

# TODOS Analysis

**Generated:** {date}
**Items Analyzed:** {count}
**Project:** {project name from specs, or directory name}

---

{Individual item analyses, sorted by priority score}

---

## Summary

| Priority | Item | Score | Multiplier | Suggestions | Next Action |
|----------|------|-------|------------|-------------|-------------|
| 1 | {title} | {N}/10 | {×N or —} | {count or —} | {action} |
| 2 | {title} | {N}/10 | {×N or —} | {count or —} | {action} |
| ... | ... | ... | ... | ... | ... |

**Ready to implement:** {count}
**Needs clarification:** {count}
**Consider deferring:** {count}
**Items researched:** {N} of {M} eligible

Error Handling

If TODOS.md doesn't exist:

• Report: "No TODOS.md found in project root."
• Offer to create one with the standard template
• Suggest using /add-todo to add the first item

If TODOS.md is empty or contains no TODO items:

• Report: "TODOS.md exists but contains no actionable items"
• Show the file's current content (if any)
• Suggest using /add-todo to add items

If TODOS.md uses non-standard format:

• Attempt to parse what exists
• Report items that couldn't be parsed
• Show: "X items parsed, Y items skipped (non-standard format)"
• Offer to reformat to standard format

If context files (VISION.md, etc.) can't be read:

• Continue without that context
• Note in output: "Project context limited (VISION.md not found)"
• Score Value based on TODO content alone

If priority tag has invalid value:

• Use default multiplier (1.0)
• Report: "Invalid priority multiplier '{value}' ignored, using 1.0"
• Valid range reminder: 0.5 to 2.0

If Edit tool fails during Q&A updates:

• Report the edit failure
• Output the clarifications to terminal so they're not lost
• Suggest manually adding to TODOS.md

Notes

• Skip items that are clearly completed (checked boxes)
• Group related items if they should be tackled together
• Consider project phase — items relevant to current phase score higher

Interactive Q&A Phase

After displaying the prioritized list and summary, offer the user an interactive session to clarify requirements.

See QA_WORKFLOW.md for the detailed Q&A workflow:

1. Choose action (Clarify / Review suggestions / Done)
2. Select item to clarify
3. Summarize current state
4. Ask open questions one at a time
5. Update TODOS.md with clarifications
6. Summarize understanding
7. Check implementation readiness
8. Review suggestions (accept/reject research findings)
9. Continue or exit