skill-fix-it

# 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: ```bash # 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: ```bash 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: ```json { "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) ```json { "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: ```json { "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 ```bash 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 ```json { "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**: ```json { "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**: ```json { "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 ```json { "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`: ```json { "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}",