libgraphql-plans

Manage project planning for the libgraphql workspace via plans.md files and code TODO comments.

Overview

The libgraphql project tracks work in two ways:

1. plans.md files — Structured planning documents at crate roots and workspace root
2. Code TODOs — Inline comments marking work to be done

This skill keeps these synchronized and helps prioritize work.

File Hierarchy

libgraphql/
├── plans.md                           # Workspace-level plans (items outside crates)
└── crates/
    ├── libgraphql-parser/plans.md     # Parser crate plans
    ├── libgraphql-core/plans.md       # Core crate plans
    └── libgraphql-macros/plans.md     # Macros crate plans

Rule: TODOs go to the nearest plans.md — if in a crate, use that crate's file; otherwise use the root.

Workflows

1. Sync TODOs from Codebase

When asked to sync or update plans:

1. Run .claude/skills/libgraphql-plans/scripts/scan_todos.py <repo-path> to find all TODOs
2. For each plans.md file, compare found TODOs against the "Appendix: Code TODOs" table
3. New TODOs: Present them to the user for review before adding to the appropriate section
4. Missing TODOs: If a TODO in the appendix no longer exists in code, it may have been completed or removed — investigate and update accordingly
5. Regenerate the "Appendix: Code TODOs" table
6. Update "Last Updated" date

2. Mark Work Complete

When asked to mark something done:

1. Locate the plan item by section number (e.g., "2.1") or description
2. Wholly complete:
   • Move to "Past Completed Work" section with title, terse description, and date
   • Check all "Definition of Done" boxes
3. Partially complete:
   • Leave in place
   • Update "Current Progress" to reflect what's done
   • Update description to reflect remaining work
4. NEVER re-number plan identifiers — IDs like 2.1, 4.3 must remain stable
5. Update "Last Updated" date

3. Add New Task

When asked to track a new task:

1. Determine the appropriate plans.md file based on which crate it affects
2. Determine the appropriate section (or create a new section if needed)
3. Draft the new plan item following the format in references/plans_format.md
4. Present to user for review before adding
5. Assign the next available ID within that section (never reuse IDs)
6. Update "Last Updated" date

4. Identify High-Impact Work

When asked what to work on next:

1. First, sync TODOs and update all plans.md files
2. Analyze by priority markers (HIGH/MEDIUM/LOW) in the Priority Summary
3. Consider dependencies (blocked items vs ready items)
4. Consider scope (quick wins vs large efforts)
5. Present top 3-5 recommendations with rationale

TODO Comment Patterns

Scan for these patterns in .rs files:

Explicit markers:

• // TODO: or // TODO — Standard TODO
• // FIXME: or // FIXME — Bug or broken code
• // NOTE: — May indicate future consideration. Exclude these if they only explain something but do not indicate a need to come back and change or otherwise take action on something.
• // HACK: — Temporary solution needing cleanup

Semantic patterns (use judgment):

• Comments mentioning "fix this", "clean up", "reconsider", "revisit"
• Comments about "temporary", "workaround", "should be changed"
• Comments with future tense about changes ("will need to", "should eventually")

Not every comment needs to become a plan item — only clear action items.

plans.md Format

See references/plans_format.md for the full template.

General style:

• All markdown table cells in a column should have consistent width for human-readability

Key sections:

• Current State Summary — Test counts, implementation status
• Numbered Sections — Grouped by category (Testing, Performance, etc.)
• Priority Summary — HIGH/MEDIUM/LOW categorization
• Past Completed Work — Archive of finished items
• Appendix: Code TODOs — Auto-generated table of inline TODOs

Each plan item includes:

• Purpose — Why this matters
• Current Progress — What's done
• Priority — HIGH/MEDIUM/LOW
• Tasks — Numbered subtasks
• Definition of Done — Checkboxes for completion criteria

Important Rules

1. Stable IDs: Never renumber plan items. If Section 2.1 is completed, the next item in Section 2 is 2.7 (or whatever follows), not 2.1.

2. Always regenerate Code TODOs appendix when updating any plans.md.

3. Ask before adding: New items from TODO scans should be presented for user review.

4. Update timestamps: Always update "Last Updated" date when modifying a plans.md.

5. Terse completions: When moving to "Past Completed Work", use only a title and one-line description.