file-todos

The file-todos skill provides a robust, transparent, and persistent method for managing work items, feature requests, and technical debt. By utilizing a structured directory at .claude/todos/, the system turns markdown files with YAML frontmatter into a queryable database of project state. It is specifically designed for developers and agents working in environments that prioritize code-first documentation and auditability. This skill allows for the systematic capture of findings from investigations, code reviews, and PR feedback, ensuring that no complex task is lost during the development cycle.

• Enables creation of standardized todo files using issue IDs, status tracking, and priority levels for effective triage.

• Supports dependency management between issues to ensure tasks are completed in the correct logical sequence.

• Facilitates detailed work logging during active development, providing a chronological history of actions, learnings, and technical adjustments.

• Integrates with automated slash commands like /triage for rapid approval and prioritization workflows.

• Utilizes markdown and YAML for storage, making it fully version-controlled, searchable via standard tools like grep, and easily portable.

• Use this skill when a task requires more than 15-20 minutes of effort, research, or multi-step planning.

• To create a new todo, copy the assets/todo-template.md and populate the required sections including problem statements, proposed solutions, and acceptance criteria.

• Always keep the status field (pending, ready, complete) and dependency lists accurate to allow for automated filtering and pipeline integration.

• Rely on work logs to document file-level changes, executed commands, and key technical insights to provide context for future code reviews or debugging sessions.

• For trivial tasks under 15 minutes, standard immediate action is preferred over creating a formal tracking file.