skill-fix-it

name	skill-fix-it
description	Scan codebase for FIX:/NOTE:/TODO:/QUESTION: tags and create structured tasks with interactive selection. Invoke for /fix-it command.

Fix-It Skill (Direct Execution)

Direct execution skill for scanning files, presenting findings interactively, and creating user-selected tasks. Replaces the previous delegation-based approach with synchronous execution and AskUserQuestion prompts.

Key behavior: Users always see tag scan results BEFORE any tasks are created. Users select which task types to create via interactive prompts.

Context References

Reference (do not load eagerly):

• Path: @specs/TODO.md - Current task list
• Path: @specs/state.json - Machine state

---

Execution

Step 1: Parse Arguments

Extract paths from command input:

# Parse from command input
paths="$ARGUMENTS"

# Default to project root if no paths specified
if [ -z "$paths" ]; then
  paths="."
fi

Note: The --dry-run flag is no longer supported. The interactive flow is inherently "preview first" - users always see findings before any tasks are created.

Step 2: Generate Session ID

Generate session ID for tracking:

source .claude/scripts/lib/common.sh
session_id="$(common_session_id)"

Step 3: Execute Tag Extraction

Scan for all four tag types (FIX:, NOTE:, TODO:, QUESTION:) using file-type-specific comment patterns:

File Type	Comment Prefix	Includes
Lua	--	*.lua
LaTeX	%	*.tex
Markdown	<!--	*.md
Script	#	*.py, *.sh, *.yaml, *.yml

For each tag type, grep across all file types with -rn and collect matches. Parse each match into: file path, line number, tag type, tag content.

Categorize into arrays: fix_tags[], note_tags[], todo_tags[], question_tags[].

Step 4: Display Tag Summary

Present findings to user BEFORE any selection:

## Tag Scan Results

**Files Scanned**: {paths}
**Tags Found**: {total_count}

### FIX: Tags ({count})
- `{file}:{line}` - {content}
- ...

### NOTE: Tags ({count})
- `{file}:{line}` - {content}
- ...

### TODO: Tags ({count})
- `{file}:{line}` - {content}
- ...

### QUESTION: Tags ({count})
- `{file}:{line}` - {content}
- ...

Step 5: Handle Edge Cases

No Tags Found

If no tags found:

## No Tags Found

Scanned files in: {paths}
No FIX:, NOTE:, TODO:, or QUESTION: tags detected.

Nothing to create.

Exit gracefully without prompts.

Only Certain Tag Types

Only show task type options for tag types that exist:

• FIX: tags exist -> offer "fix-it task"
• NOTE: tags exist -> offer "fix-it task" AND "learn-it task"
• TODO: tags exist -> offer "TODO tasks"
• QUESTION: tags exist -> offer "Research tasks"

Step 6: Task Type Selection

If tags were found, prompt user to select task types:

{
  "question": "Which task types should be created?",
  "header": "Task Types",
  "multiSelect": true,
  "options": [
    {
      "label": "fix-it task",
      "description": "Combine {N} FIX:/NOTE: tags into single task"
    },
    {
      "label": "learn-it task",
      "description": "Update context from {N} NOTE: tags"
    },
    {
      "label": "TODO tasks",
      "description": "Create tasks for {N} TODO: items"
    },
    {
      "label": "Research tasks",
      "description": "Create research tasks for {N} QUESTION: items"
    }
  ]
}

Important: Only include options where the tag type exists:

• Include "fix-it task" only if FIX: or NOTE: tags exist
• Include "learn-it task" only if NOTE: tags exist
• Include "TODO tasks" only if TODO: tags exist
• Include "Research tasks" only if QUESTION: tags exist

If user selects nothing, exit gracefully:

No task types selected. No tasks created.

Step 7: Individual TODO Selection

If "TODO tasks" was selected AND there are TODO: tags:

Standard Case (<=20 TODOs)

{
  "question": "Select TODO items to create as tasks:",
  "header": "TODO Selection",
  "multiSelect": true,
  "options": [
    {
      "label": "{content truncated to 50 chars}",
      "description": "{file}:{line}"
    },
    ...
  ]
}

Large Number of TODOs (>20)

Add a "Select all" option at the top:

{
  "question": "Select TODO items to create as tasks:",
  "header": "TODO Selection (many items)",
  "multiSelect": true,
  "options": [
    {
      "label": "Select all ({N} items)",
      "description": "Create a task for every TODO tag"
    },
    {
      "label": "{content truncated to 50 chars}",
      "description": "{file}:{line}"
    },
    ...
  ]
}

If "Select all" is chosen, include all TODOs. Otherwise, only selected items.

Step 7.5: Topic Grouping (Shared Algorithm)

This grouping algorithm applies to both TODO items (Step 7.5) and QUESTION items (Step 7.7). Skip if only 1 item selected.

Topic Indicator Extraction per item:

• Key Terms: Significant words (nouns, verbs), ignoring stop words
• File Section: Group by file path prefix
• Action Type: Inferred from content (Add/Create -> implementation, Fix -> fix, Document -> docs, Test -> testing, Refactor -> improvement). For QUESTION items, action_type is always "research".

Clustering Algorithm:

1. Start with first item as initial group
2. For each remaining item: add to existing group if shares 2+ key terms OR shares file_section + action_type; otherwise start new group
3. Generate topic label from most common shared terms
4. Single-item groups are kept as-is

Store result: topic_groups[] with {label, items[], shared_terms[], action_type}

Step 7.5.4: Topic Group Confirmation

Condition: At least one group has 2+ items (otherwise skip -- no grouping benefit).

Present via AskUserQuestion (multiSelect: false):

• "Accept suggested topic groups" -- Creates {N} grouped tasks
• "Keep as separate tasks" -- Creates {M} individual tasks
• "Create single combined task" -- Creates 1 task with all items

Store: grouping_mode = "grouped" | "separate" | "combined"

Step 7.6: Individual QUESTION Selection

Condition: User selected "Research tasks" in Step 6 AND QUESTION: tags exist.

Same pattern as Step 7 (TODO selection): AskUserQuestion with multiSelect, "Select all" option when >20 items.

Step 7.7: Topic Grouping for QUESTION Items

Condition: Selected more than 1 QUESTION item.

Apply the same algorithm as Step 7.5 with these differences:

• action_type is always "research"
• Store result in question_topic_groups[]
• Confirmation prompt uses "research tasks" wording

Store: question_grouping_mode = "grouped" | "separate" | "combined"

Step 8: Create Selected Tasks

For each selected task type, create the task. Important: When NOTE: tags exist and both fix-it and learn-it tasks are selected, create learn-it FIRST so fix-it can depend on it.

8.1: Get Next Task Number

next_num=$(jq -r '.next_project_number' specs/state.json)

8.2: Dependency-Aware Task Creation Order

Check for NOTE: dependency condition:

has_note_dependency = (NOTE: tags exist) AND (user selected both "fix-it task" AND "learn-it task")

If has_note_dependency is TRUE:

• Create learn-it task FIRST (Step 8.2a)
• Store learn-it task number as learn_it_task_num
• Create fix-it task SECOND with dependency (Step 8.2b)

If has_note_dependency is FALSE:

• Create fix-it task first (if selected)
• Create learn-it task second (if selected)
• No dependency relationship

8.2a: Learn-It Task (when created first for dependency)

Condition: has_note_dependency is TRUE

{
  "title": "Update context files from NOTE: tags",
  "description": "Update {N} context files based on learnings:\n\n{grouped by target context}",
  "task_type": "meta",
  "effort": "1-2 hours"
}

Store the task number: learn_it_task_num = next_num Increment: next_num = next_num + 1

8.2b: Fix-It Task (with dependency when has_note_dependency)

Condition: User selected "fix-it task" AND (FIX: or NOTE: tags exist)

When has_note_dependency is TRUE:

{
  "title": "Fix issues from FIX:/NOTE: tags",
  "description": "Address {N} items from embedded tags:\n\n{list of items with file:line references}\n\n**Important**: When making changes, remove the FIX: and NOTE: tags from the source files. Leave TODO: tags untouched (they create separate tasks).",
  "task_type": "{predominant task_type from source files}",
  "effort": "2-4 hours",
  "dependencies": [learn_it_task_num]
}

When has_note_dependency is FALSE:

{
  "title": "Fix issues from FIX:/NOTE: tags",
  "description": "Address {N} items from embedded tags:\n\n{list of items with file:line references}\n\n**Important**: When making changes, remove the FIX: and NOTE: tags from the source files. Leave TODO: tags untouched (they create separate tasks).",
  "task_type": "{predominant task_type from source files}",
  "effort": "2-4 hours"
}

Language Detection:

if majority of tags from .lean files -> "lean"
elif majority from .tex files -> "latex"
elif majority from .claude/ files -> "meta"
else -> "general"

8.2c: File Footprint Overlap Check (Component 4a)

In addition to the hardcoded NOTE-before-fix-it dependency rule above (8.2), run the shared Multi-Task Creation Standard Component 4a overlap check across topic_groups[] (each group already carries a file_section from Step 7.5's clustering):

1. Derive file_scope per group: union the file:line paths of every item in the group (dropping the :line suffix) into a file_scope array for that group's would-be task.
2. Run the shared overlap algorithm (.claude/context/patterns/file-footprint-overlap.md, referenced by path — not restated here) pairwise across all groups that will become separate tasks (grouped or separate mode; combined mode produces a single task, so no pairwise check applies).
3. Auto-add a serializing dependency for every overlapping pair with no existing edge (in addition to the fix-it/learn-it edge from 8.2), so two groups whose file_scope overlaps never land in the same task creation batch without a dependency between them.
4. Never silent: annotate any auto-added edge in the Step 9 task summary/confirmation with "(auto: file overlap)" per Component 7 of the Multi-Task Creation Standard.

8.3: Learn-It Task (when created without dependency)

Condition: User selected "learn-it task" AND NOTE: tags exist AND has_note_dependency is FALSE

{
  "title": "Update context files from NOTE: tags",
  "description": "Update {N} context files based on learnings:\n\n{grouped by target context}",
  "task_type": "meta",
  "effort": "1-2 hours"
}

8.4: Todo-Tasks (if selected)

Condition: User selected "TODO tasks" AND user selected specific TODO items

Check grouping_mode (from Step 7.5.4, defaults to "separate" if Step 7.5.4 was skipped):

8.4.1: Grouped Mode (grouping_mode == "grouped")

For each topic group in topic_groups:

{
  "title": "{topic_label}: {item_count} TODO items",
  "description": "Address TODO items related to {topic_label}:\n\n{item_list}\n\n---\n\nShared context: {shared_terms_description}",