home / skills / oimiragieo / agent-studio / bug-handling-with-todo-comments

bug-handling-with-todo-comments skill

/.claude/skills/_archive/dead/bug-handling-with-todo-comments

This skill helps you improve code quality by enforcing todo comment guidelines to surface, describe, and track bugs across JavaScript and TypeScript projects.

npx playbooks add skill oimiragieo/agent-studio --skill bug-handling-with-todo-comments

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.6 KB

---
name: bug-handling-with-todo-comments
description: Specifies the usage of TODO comments to outline problems or bugs encountered in existing code, regardless of file type.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/*.*'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Bug Handling With Todo Comments Skill

<identity>
You are a coding standards expert specializing in bug handling with todo comments.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- TODO Comments: If you encounter a bug in existing code, or the instructions lead to suboptimal or buggy code, add comments starting with "TODO:" outlining the problems.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for bug handling with todo comments compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill teaches how to use TODO comments to document bugs, unclear logic, and remaining work directly in source code. It focuses on concise, actionable TODOs that guide future fixes and reduce knowledge loss. The guidance applies across file types, with examples tailored for JavaScript projects.

How this skill works

The skill inspects code for places where behavior is incorrect, brittle, or undocumented and recommends adding TODO comments that describe the problem, impact, and next steps. It also checks existing TODOs for clarity, ownership, and actionable details. Finally, it suggests minimal refactors or test ideas to accompany each TODO so the issue is easier to address later.

When to use it

When encountering a bug or unexpected behavior in existing code
When leaving a partial fix or workaround that needs further work
When design decisions are unclear or likely to change
When adding a temporary hack to satisfy deadlines
When code lacks tests or proper error handling

Best practices

Start each note with "TODO:" followed by a short summary of the problem
Include context: why it’s a problem, reproducible steps, and observed vs expected behavior
Suggest concrete next steps (fix approach, files to change, tests to add) and a priority level
Add an owner or team tag if possible (e.g., TODO: @frontend) and a timestamp
Avoid vague language; prefer short actionable sentences over long paragraphs

Example use cases

Found unstable numerical comparison in JavaScript — add TODO describing precision issue, expected range, and plan to use tolerant comparison with unit tests
Left a try/catch swallowing errors — add TODO noting lost errors, impact, and target to rethrow or log with context
Temporary performance workaround — add TODO specifying the bottleneck, measurement data, and plan to replace with optimized algorithm
Incomplete feature flag handling — add TODO describing inconsistent state transitions and list affected components and tests to cover

FAQ

Should TODOs replace issue tracker tickets?

No. TODOs are lightweight in-code notes to guide immediate work and future maintainers. For prioritized tracking and cross-team visibility, also create a ticket in your issue tracker and reference its ID in the TODO.

How detailed should a TODO be?

Be concise but specific: one-line summary, one sentence on impact, and one or two actionable next steps. Link to related tickets or tests when helpful.