docs: add TODO checker workflow to docs/ai/ci-ops.md#19075
Conversation
sebastianst
left a comment
sebastianst
left a comment
There was a problem hiding this comment.
Tested the workflow locally with Claude. It's happy with it and there currently aren't any open TODO failures, so this part of the workflow couldn't be tested without creating a dummy failed TODO check, which I don't think is necessary.
I suggest we also make this an actual Claude skill by creating file .claude/skills/fix-todo/SKILL.md and add necessary context to it and point to file ci-ops.md for the actual workflow.
Adds detailed operational instructions for resolving TODO checker CI failures in a dedicated file following the docs/ai/ pattern. The workflow includes: - CircleCI API commands to find the latest scheduled pipeline - Parsing job output to identify closed issues - GitHub API commands to find who closed the issue - Proper reopening comment format with attribution and traceability This enables natural language commands like "fix the latest TODO checker failure" to work automatically via AGENTS.md/CLAUDE.md guidance that Claude Code reads. References the new ci-ops.md file from AGENTS.md alongside other topic-specific documentation.
Updates the TODO checker workflow with two key fixes: 1. Remove CIRCLECI_TOKEN requirement - CircleCI API is publicly accessible for this repository, so no authentication needed 2. Fix "who closed the issue" detection - Use GraphQL to find the most recent person who closed the issue from the timeline, not just the closing PR author. This correctly handles cases where an issue was closed via PR, then reopened, then closed directly by a different user. Also improves Step 2 to search through recent scheduled pipelines to find one with the actual "scheduled-todo-issues" workflow, since the latest may only contain a "setup" workflow. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
ajsutton
force-pushed
the
add-claude-md-todo-checker
branch
from
2e84a25 to
42fa4ea
Compare
|
@sebastianst When Claude creates the skill it wound up duplicating quite a bit of the info from ci-ops.md. I committed that in 8b49af0 but then switched it the other way around so the ci-ops.md has a simple, clear summary of what to do that a human could read and the skill has the details of commands etc. ci-ops.md references the skill file so non-claude AIs should still pick it up fine. I have a slight preference for doing it this way around, mostly because ci-ops.md is likely to include instructions for multiple things over time and would get really long otherwise. Happy to go with either version though. |
github-merge-queue
bot
removed this pull request from the merge queue due to no response for status checks
3 participants
Summary
Adds automated TODO checker failure resolution workflow to the AI agent documentation.
Changes
docs/ai/ci-ops.md- Detailed workflow for resolving TODO checker CI failuresAGENTS.md- References the new ci-ops.md fileMotivation
The repo runs a scheduled CircleCI job every 4 hours that validates TODO comments don't reference closed GitHub issues. When failures occur, manually investigating and reopening issues is time-consuming.
This documentation enables Claude Code to automatically handle TODO checker failures when users say phrases like "fix the latest TODO checker failure".
How It Works
The workflow:
Documentation Pattern
Follows the existing
docs/ai/structure:docs/ai/ci-ops.md- CI/CD operationsdocs/ai/contract-dev.md- Smart contract developmentdocs/ai/go-dev.md- Go service developmentdocs/ai/rust-dev.md- Rust developmentExample Usage
After merging, Claude Code will automatically handle requests like:
The workflow ensures issues are reopened with: