Initial brain dump (unstructured)

Project 27: “The Checklist Manager” — Task Management

Attribute	Value
File	`KIRO_CLI_LEARNING_PROJECTS.md`
Main Programming Language	Markdown
Coolness Level	Level 2: Practical
Difficulty	Level 1: Beginner
Knowledge Area	Task Management

What you’ll build: Use /todo to turn a brain dump into executable steps.

Why it teaches Structured Execution: It enforces a real work queue.

Success criteria:

Items are executed and checked off by Kiro.

Real World Outcome

You’ll use Kiro’s /todo feature to convert unstructured brain dumps into structured, executable task lists. Kiro will work through the list systematically, checking off completed tasks and reporting progress.

Example Workflow:

# Initial brain dump (unstructured)
$ kiro "I need to add user authentication to the API. Also fix the CORS issues. And we should add logging. Oh, and update the README."

[Kiro responds with a plan, but it's not tracked]

# Better: Use /todo for structured execution
$ kiro "/todo Create tasks for: add JWT auth, fix CORS, add Winston logging, update README"

✓ Created todo list:
[ ] 1. Implement JWT authentication for API endpoints
[ ] 2. Fix CORS configuration to allow frontend domain
[ ] 3. Add Winston logging with log rotation
[ ] 4. Update README with new auth flow and setup instructions

# Kiro works through the list
[Working on task 1...]
✓ 1. Implement JWT authentication for API endpoints (DONE)
   - Created /auth/login and /auth/register endpoints
   - Added JWT middleware for protected routes
   - Tests passing

[ ] 2. Fix CORS configuration to allow frontend domain
[ ] 3. Add Winston logging with log rotation
[ ] 4. Update README with new auth flow and setup instructions

# Continue with next task
[Working on task 2...]
✓ 2. Fix CORS configuration to allow frontend domain (DONE)
   - Updated Express CORS config to whitelist https://app.example.com
   - Added preflight OPTIONS handling

[...continues until all tasks complete...]

Final status:
✓ 1. Implement JWT authentication for API endpoints (DONE)
✓ 2. Fix CORS configuration to allow frontend domain (DONE)
✓ 3. Add Winston logging with log rotation (DONE)
✓ 4. Update README with new auth flow and setup instructions (DONE)

All tasks completed! 🎉

Visual progress tracking:

$ kiro "/todo status"

Progress: [████████░░] 80% (4/5 tasks complete)

✓ 1. Set up CI/CD pipeline (DONE)
✓ 2. Add unit tests for auth service (DONE)
✓ 3. Implement rate limiting (DONE)
✓ 4. Add API documentation with Swagger (DONE)
⏳ 5. Deploy to staging environment (IN PROGRESS)
   - Current step: Running database migrations...

Key benefits:

No tasks forgotten (explicit checklist)
Clear progress visibility (X of Y tasks done)
Prioritization (numbered order)
Context preservation (Kiro remembers what’s next)
Audit trail (what was done, when)

You’re using the same task management system that agile teams use (sprint backlogs, kanban boards).

The Core Question You’re Answering

“How do you ensure complex multi-step tasks are executed completely and in order, without forgetting steps or getting distracted by tangents?”

Before you use /todo, understand this: Human working memory holds 7 ± 2 items. When you ask Kiro to do 10 things in one prompt, some will be forgotten or deprioritized. A todo list externalizes the task queue, ensuring systematic execution.

The todo system transforms “do these 10 things” (vague) into “here are 10 explicit steps, execute in order” (structured).

Concepts You Must Understand First

Stop and research these before using /todo:

Task Decomposition and Prioritization
- How do you break down a large goal (“add authentication”) into atomic tasks?
- What makes a task “atomic” (single responsibility, verifiable completion)?
- How do you prioritize tasks (dependencies, critical path, quick wins)?
- Book Reference: “The Pragmatic Programmer” by Hunt & Thomas - Ch. 2 (Orthogonality)
Markdown Checklists and Syntax
- What is the GitHub-flavored markdown syntax for checklists (- [ ] vs. - [x])?
- How do you represent task states (pending, in-progress, done, blocked)?
- Can you nest sub-tasks (hierarchical checklists)?
- Book Reference: “The Markdown Guide” by Matt Cone - Ch. 4 (Extended Syntax)
Workflow State Machines
- What are the valid state transitions (pending → in-progress → done)?
- Can you skip states (pending → done without in-progress)?
- How do you handle task failures (done → failed → retry)?
- Book Reference: “Designing Data-Intensive Applications” by Kleppmann - Ch. 7 (Transactions)
Context Preservation Across Tasks
- How does Kiro remember task N while working on task N+1?
- What happens if a task requires information from a previous task?
- Should tasks be independent (stateless) or can they build on each other (stateful)?
- Book Reference: “Clean Code” by Robert C. Martin - Ch. 3 (Functions)
Interruption and Resumption
- What happens if you interrupt Kiro mid-task (Ctrl+C)?
- Can you resume from the last completed task?
- Should incomplete tasks be marked as “blocked” or deleted?
- Book Reference: “The Mythical Man-Month” by Frederick Brooks - Ch. 10 (Tracking Progress)
Audit Trail and Accountability
- How do you track who completed each task (user vs. Kiro)?
- Should you log timestamps for task start and completion?
- Can you export the completed checklist as a report?
- Book Reference: “Accelerate” by Forsgren, Humble, Kim - Ch. 4 (Measurement)

Questions to Guide Your Design

Before creating a todo list, think through these:

Task Granularity
- Should tasks be small (< 5 minutes each) or large (> 1 hour)?
- Do you group related tasks (all database tasks together)?
- Should each task have acceptance criteria (how do you know it’s done)?
- What’s the optimal number of tasks (3-5 vs. 20-30)?
Ordering and Dependencies
- Do tasks have dependencies (task B requires task A to complete first)?
- Should Kiro enforce dependency order or just suggest it?
- Can tasks be parallelized (run tests while fixing linting)?
- How do you represent blocked tasks (waiting on external input)?
State Management
- Where is the todo list stored (.kiro/todos.md, in-memory, database)?
- How does Kiro update task states (mark as done, add notes)?
- Can you manually edit the todo list (add/remove tasks mid-execution)?
- Should tasks persist across Kiro sessions (resume later)?
Error Handling
- What happens if a task fails (mark as failed, retry, skip)?
- Should Kiro stop execution on first failure (fail-fast)?
- How do you handle partial completion (task 50% done)?
- Can you rollback completed tasks if a later task fails?
Reporting and Visibility
- How do you show progress (X of Y tasks done, percentage)?
- Should Kiro report estimated time remaining (based on historical velocity)?
- Can you generate a summary report (what was done, time taken)?
- How do you visualize the task graph (dependencies, critical path)?

Thinking Exercise

Convert a Brain Dump to a Structured Todo List

Before using /todo, manually trace how you would decompose a vague request:

Scenario: “Improve the app’s performance”

Unstructured brain dump: “The app is slow. We should optimize the database queries, add caching, compress images, minify JavaScript, enable CDN, and maybe use a load balancer. Also fix memory leaks.”

Structured todo list (atomic, prioritized, verifiable):

## Performance Improvement Tasks

### Critical Path (do these first)
- [ ] 1. Profile the app to identify bottlenecks
      - Use Chrome DevTools Performance tab
      - Identify the slowest 3 operations
      - Expected outcome: Waterfall chart showing blocking operations

- [ ] 2. Optimize database queries (N+1 problem detected)
      - Add indexes to `users.email` and `posts.author_id`
      - Replace eager loading with joins
      - Expected outcome: Query time < 50ms (currently 2s)

- [ ] 3. Add Redis caching for user sessions
      - Install redis, configure connection
      - Cache user profile lookups (TTL 5 minutes)
      - Expected outcome: 90% cache hit rate

### Quick Wins (easy, high impact)
- [ ] 4. Enable gzip compression on API responses
      - Add compression middleware to Express
      - Expected outcome: Response size reduced by 70%

- [ ] 5. Minify and bundle JavaScript (Webpack production build)
      - Run `npm run build:prod`
      - Expected outcome: Bundle size < 200KB (currently 1.5MB)

### Nice-to-Have (defer if time limited)
- [ ] 6. Set up CDN for static assets (CloudFront)
      - Configure S3 bucket with CloudFront distribution
      - Expected outcome: Asset load time < 100ms globally

- [ ] 7. Investigate memory leaks (long-term monitoring)
      - Add heap snapshot capture on production
      - Review weekly for memory growth trends

Questions while decomposing:

Which tasks are prerequisites for others (profiling before optimization)?
Which tasks are independent and can be done in parallel (caching + minification)?
Which tasks have measurable outcomes (query time, bundle size)?
Which tasks are risky and need checkpoints (database migration)?
Which tasks can be deferred if the deadline is tight (CDN setup)?

Manual test:

# 1. Create the todo list
$ kiro "/todo Improve app performance: profile, optimize queries, add caching, compress assets"

# Kiro generates the structured list above

# 2. Execute tasks in order
$ kiro "/todo execute"

# Kiro starts with task 1 (profiling)

# 3. Check progress mid-execution
$ kiro "/todo status"
# Progress: [███░░░░] 40% (2/7 tasks complete)

# 4. Mark a task as blocked (waiting for DBA approval)
$ kiro "/todo block 2 --reason 'Waiting for DBA to approve index creation'"

# 5. Skip to next unblocked task
$ kiro "/todo next"

The Interview Questions They’ll Ask

Prepare to answer these:

“What is the difference between a task list and a kanban board for managing development work?”
“How do you decompose a large, vague requirement (‘make the app faster’) into atomic, executable tasks?”
“What makes a task ‘atomic’? What are the characteristics of a well-defined task?”
“How would you handle task dependencies in a todo system (task B requires task A to complete first)?”
“What state transitions are valid for a task (e.g., pending → in-progress → done)?”
“How do you measure progress when some tasks are large (1 day) and others are small (5 minutes)?”

Hints in Layers

Hint 1: Start with a Brain Dump First, tell Kiro everything you want to accomplish (unstructured). Then ask Kiro to convert it into a structured /todo list.

Hint 2: Use Verifiable Outcomes Each task should have a clear “done” condition: “Add unit tests” (vague) vs. “Add tests until coverage is > 80%” (verifiable).

Hint 3: Prioritize with Numbers Prefix tasks with numbers to enforce execution order: “1. Set up database”, “2. Run migrations”, “3. Seed test data”.

Hint 4: Separate “What” from “How” The task describes what to achieve, not how to do it. “Add JWT auth” (what) not “Install jsonwebtoken library, create /auth/login endpoint, add middleware…” (how).

Books That Will Help

Topic	Book	Chapter
Task Decomposition	“The Pragmatic Programmer” by Hunt & Thomas	Ch. 2 (Orthogonality)
Markdown Syntax	“The Markdown Guide” by Matt Cone	Ch. 4 (Extended Syntax)
State Machines	“Designing Data-Intensive Applications” by Kleppmann	Ch. 7 (Transactions)
Function Design	“Clean Code” by Robert C. Martin	Ch. 3 (Functions)
Progress Tracking	“The Mythical Man-Month” by Brooks	Ch. 10 (Tracking Progress)
Measurement	“Accelerate” by Forsgren, Humble, Kim	Ch. 4 (Measurement)

Common Pitfalls & Debugging

Problem 1: “Tasks are too vague (‘improve the code’)”

Why: No clear acceptance criteria or measurable outcome.
Fix: Rewrite as “Increase test coverage from 60% to 80%” or “Reduce cyclomatic complexity of auth.js to < 10”.
Quick test: Ask “How do I know when this task is done?” If unclear, the task is too vague.

Problem 2: “Too many tasks (30+), feels overwhelming”

Why: Tasks are too granular or not grouped.
Fix: Group related tasks into phases: “Phase 1: Auth (3 tasks)”, “Phase 2: API (5 tasks)”.
Quick test: Can you complete the entire list in a single work session? If no, it’s too long.

Problem 3: “Kiro forgot to complete a task from the list”

Why: Task was not explicitly tracked or Kiro lost context.
Fix: Use /todo status to verify all tasks are tracked, and /todo execute to enforce systematic execution.
Quick test: Review the final checklist—all tasks should be marked as done.

Problem 4: “Task order matters but Kiro did them out of order”

Why: Dependencies weren’t explicit.
Fix: Number tasks explicitly (1, 2, 3) or use “Prerequisites: Task 1 must complete first”.
Quick test: Can task 3 complete before task 1? If yes, there’s a dependency issue.

Problem 5: “A task failed mid-execution, but the todo list shows it as done”

Why: Kiro marked it as done based on attempting it, not succeeding.
Fix: Use stricter “done” criteria: tests must pass, manual verification required.
Quick test: Run tests after each task completion.

Problem 6: “Todo list disappeared after restarting Kiro”

Why: The list was only in-memory, not persisted.
Fix: Save the todo list to a file (.kiro/todos.md) and load it on session start.
Quick test: Restart Kiro and run /todo status (should show previous list).