Granular Visibility

Creating Granular Items

1. Map discrete deliverables: One todo item per concrete output or decision point, not one per phase
2. Be specific: "Read config file" is not granular; "Read config file, identify auth settings, determine if migration needed" is
3. Avoid nesting: Don't hide sub-steps under parent tasks; make them visible
4. Start with the full list: Granularity from the beginning creates accurate expectations

Maintaining Visibility

1. Update status in real-time: Mark items in_progress, completed, or pending as they change
2. Add blockers immediately: If an item is blocked, note it — don't wait for the user to notice
3. Communicate what changes: If scope shifts, show how the list evolves
4. Never pre-compress: Let the user ask for a simpler view; don't offer it unprompted

Responding to "Too Long"

If the user says the todo list feels long:

• Confirm that length reflects complexity, not bloat
• Offer to reorganize (by phase, by urgency) without removing items
• Ask if they want a compressed summary in addition to the granular list
• Never delete items to make the list shorter

Best Practices

What to Track Granularly

• Discrete deliverables (read file, analyze results, generate output)
• Decision points (determine eligibility, choose approach, validate direction)
• Quality gates (test results, review findings, check integrity)
• Coordination steps (wait for user input, get approval, resolve blocking issue)

What to Consolidate

• Trivial sub-steps (opening a file is part of "read file," not a separate item)
• Steps that must happen together (if A always requires B immediately, they're one item)
• Repeated boilerplate (don't create 20 "read file X" items; group similar reads)

Tone and Clarity

• Use imperative form: "Read config file" not "Reading the config file"
• Be specific about scope: "Parse JSON and extract auth settings" not "Process data"
• Make status clear: distinguish between "pending" (waiting for decision), "in_progress" (actively working), and "blocked" (waiting for external factor)

Quality Checklist

• Each todo item represents one discrete deliverable or decision point
• Status is updated in real-time as work progresses
• The list length matches the actual complexity of the work
• Truly trivial sub-steps (e.g., "read file X") are not individually tracked
• User has not been asked to accept or approve a compressed view
• Blocking issues are flagged immediately with reason and impact
• If scope changes, the list evolves to reflect it
• Items are specific enough that their status is unambiguous

Common Pitfalls

Pre-Compression

Pitfall: "The list is getting long, I should simplify it before showing the user." Reality: Length reflects work complexity. Compression removes steering ability. Fix: Show the full list. If the user wants fewer items, they'll ask.

Hiding Sub-Steps

Pitfall: Creating high-level items like "Phase 1: Analysis" to keep the list short. Reality: The user can't see what needs to happen in Phase 1 until you show up with new items mid-stream. Fix: Break Phase 1 into discrete items from the start. It's okay if that creates 8 items instead of 1.

Assuming Simplicity Preference

Pitfall: Assuming all users prefer simplified views and offering compression unprompted. Reality: Many users explicitly choose granular tracking and will ask if they want less detail. Fix: Default to granular. Compression is opt-in, not default.

Updating Retrospectively

Pitfall: Waiting until the phase is done to update the todo list. Reality: The user sees stale status and loses confidence in the progress tracking. Fix: Update as items change. Mark things in_progress before you start them, completed immediately after.

Related Skills

• handoff-protocol: Clean handoffs require visible progress context; granular tracking provides it
• workspace-navigation: Navigating shared work benefits from detailed status visibility
• decision-propagation: Decisions surface faster when progress is visible and granular
• agent-teaching: Teaching another agent requires understanding where work stands — visibility enables this

Output

• A structured todo list with one item per discrete deliverable or decision point, each in imperative form with unambiguous scope
• Real-time status markers (pending, in_progress, completed, blocked) updated as work changes state
• Blocker annotations on any item that cannot proceed, including the reason and what is needed to unblock

Examples

Scenario 1: User asks to migrate a codebase across 14 files with 3 decision points → skill produces a 17-item list (14 file items + 3 decision items), each named specifically (e.g., "Parse auth settings in config.go and determine if migration required"), updated to in_progress before work starts and completed immediately after.

Scenario 2: User says "the todo list feels too long" on a 22-item task → skill confirms length reflects actual complexity, offers to reorganize items by phase without removing any, and asks whether the user wants a compressed summary alongside the full list — not instead of it.

Edge Cases

• If the user explicitly requests compression and accepts the tradeoff of reduced steering visibility, provide a phased summary view but preserve the full granular list internally and offer to restore it at any time.
• If scope changes mid-task (new requirements added or items dropped), update the list visibly — add new items, mark removed items as cancelled with a reason — do not silently restructure.

Anti-Patterns

• Grouping multiple deliverables under a single "Phase N" item to keep the count low — this hides complexity and breaks real-time status accuracy because the phase item cannot be marked complete until all sub-work finishes.
• Updating todo status in batch at the end of a work block rather than in real-time — the user sees stale data and cannot steer during execution.