aif-improve

Improve - Plan Refinement (Second Iteration)

Refine an existing plan by re-analyzing it against the codebase. Finds gaps, missing tasks, wrong dependencies, and enhances task quality.

Core Idea

existing plan + deeper codebase analysis + user feedback (optional)
    ↓
find gaps, missing edge cases, wrong assumptions
    ↓
enhanced plan with better tasks, correct dependencies, more detail

Workflow

Step 0: Load Config & Find the Plan

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.plan, paths.plans, paths.fix_plan, paths.research, paths.description, and paths.patches
• Language: language.ui for prompts
• Git: git.enabled, git.base_branch, git.create_branches

If config.yaml doesn't exist, use defaults:

• plan: paths.plan (default: .ai-factory/PLAN.md)
• plans/: .ai-factory/plans/
• fix plan: paths.fix_plan (default: .ai-factory/FIX_PLAN.md)
• research: .ai-factory/RESEARCH.md
• patches/: .ai-factory/patches/
• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• Language: en (English)

First parse arguments:

- --list    → list available plans only (read-only, then STOP)
- @<path>   → explicit plan file override (highest priority)
- remaining argument text → optional improvement prompt

When both are present, --list wins and no refinement is executed.

Step 0.list: List Available Plans (--list)

If $ARGUMENTS contains --list, run read-only discovery and stop.

1. Get current branch:
   git branch --show-current (git mode only)
2. Convert branch to filename: replace "/" with "-", add ".md" (git mode only)
3. Check existence of:
   - <configured plans dir>/<branch-name>.md
   - if git mode is off or branch creation is disabled: any `*.md` full-mode plan in `<configured plans dir>/`
   - <resolved fast plan path>
   - <resolved fix plan path>
4. Print availability summary and usage hints:
   - /aif-improve @<path> <optional prompt>
   - /aif-improve <optional prompt>      # automatic priority
5. If none found, suggest creating a plan via /aif-plan or /aif-fix
6. STOP.

Important: In --list mode:

• Do not execute refinement
• Do not modify files
• Do not update TaskList/plan content

Locate the active plan file using this priority:

1. If `$ARGUMENTS` contains `@<path>`:
   - Resolve the path (relative to project root; absolute paths allowed)
   - If file exists → use it
   - If missing → show "Plan file not found: <path>" and STOP
2. No explicit `@<path>` override → Check current git branch:
   git branch --show-current
   → Convert branch name to filename: replace "/" with "-", add ".md"
   → Look for <configured plans dir>/<branch-name>.md (from /aif-plan full)
   Example: feature/user-auth → .ai-factory/plans/feature-user-auth.md
3. If the branch-based plan is missing or git mode is off:
   → Check whether the configured plans dir contains exactly one `*.md` full-mode plan
   → If exactly one exists, use it
   → If multiple exist, ask the user to choose or require `@<path>`
4. No full-mode plan → Check the resolved fast plan path (from /aif-plan fast)
5. No full-mode plan and no resolved fast plan → Check the resolved fix plan path (from /aif-fix plan mode)

If NO plan file found at any location:

No active plan found.

To create a plan first, use:
- /aif-plan full <description>  — for a new feature (rich full plan; may also create a branch when git settings allow it)
- /aif-plan fast <description>  — for a quick task plan
- /aif-fix <bug description>    - for a bugfix plan (use the resolved fix plan path)

→ STOP here. Do not proceed without a plan file.

If plan file found → read it and continue to Step 1.

Step 1: Load Context

1.1: Read the plan file

Read the found plan file completely. Understand:

• Feature scope and goals
• Current tasks (subjects, descriptions, dependencies)
• Settings (testing, logging preferences)
• Commit checkpoints
• Which tasks are already completed (checkboxes - [x])

1.2: Read project context

Read .ai-factory/DESCRIPTION.md (use path from config) if it exists:

• Tech stack
• Architecture
• Conventions
• Non-functional requirements

Read .ai-factory/RESEARCH.md (use path from config) if it exists and is relevant to the plan being refined.

1.3: Read patches (limited fallback)

Use patches as fallback context, not the default source:

• If .ai-factory/skill-context/aif-improve/SKILL.md does not exist and the resolved patches dir exists:
  • Glob: <resolved patches dir>/*.md
  • Sort patch filenames ascending (lexical), then select the last 10 (or fewer if less exist)
  • Read those selected patch files only
  • Focus on reusable Prevention/Root Cause patterns that affect planning quality
• If skill-context exists, do not read all patches by default.
  • Optionally inspect a small targeted subset when refining around a known recurring issue.

Read .ai-factory/skill-context/aif-improve/SKILL.md — MANDATORY if the file exists.

This file contains project-specific rules accumulated by /aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
• CRITICAL: skill-context rules apply to ALL outputs of this skill — including the Plan Refinement Report and any plan modifications. If a skill-context rule says "tasks MUST include X" or "plan structure MUST have Y" — you MUST apply these when refining. Generating a refinement report that ignores skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

1.4: Load current task list

TaskList → Get all tasks with statuses

Understand what's already been created, what's in progress, what's completed.

Step 2: Deep Codebase Analysis

Now do a deeper codebase exploration than what /aif-plan did initially:

2.1: Trace through existing code paths

For each task in the plan, find the relevant files:

Glob + Grep: Find files mentioned in tasks
Read: Understand current implementation

Look for:

• Existing patterns the plan should follow
• Code that already partially implements what a task describes
• Hidden dependencies the plan missed
• Shared utilities or services the plan should use instead of creating new ones

2.2: Check for integration points

Look for things the plan might have missed:

• API routes that need updating
• Database migrations needed
• Config files that need changes
• Import/export updates
• Middleware or guards that apply
• Existing validation patterns

2.3: Check for edge cases

Based on the tech stack and codebase:

• Error handling patterns used in the project
• Null/undefined safety patterns
• Authentication/authorization checks needed
• Rate limiting, caching considerations
• Data validation at boundaries

Step 3: Identify Improvements

Compare the plan against what you found. Categorize issues:

3.1: Missing tasks

• Tasks that should exist but don't (e.g., migration, config update, index creation)
• Tasks for edge cases not covered

3.2: Task quality issues

• Descriptions too vague (no file paths, no specific implementation details)
• Missing logging requirements
• Missing error handling details
• Incorrect file paths

3.3: Dependency issues

• Wrong task order (task A depends on B but B comes after A)
• Missing dependencies (task C needs task A's output but isn't blocked by it)
• Unnecessary dependencies (tasks could run in parallel)

3.4: Redundant or duplicate tasks

• Two tasks doing the same thing
• Task that's unnecessary because the code already exists
• Task that duplicates existing functionality

3.5: Scope issues

• Tasks too large (should be split)
• Tasks too small (should be merged)
• Tasks outside the feature scope (gold-plating)

3.6: User-prompted improvements (if $ARGUMENTS provided)

If the user provided specific improvement instructions in $ARGUMENTS (excluding --list and @<path> tokens):

• Apply the user's feedback to the plan
• Look for tasks that need modification based on the prompt
• Add new tasks if the user's prompt requires them

Step 4: Present Improvements

Show the user what you found in a clear format:

## Plan Refinement Report

Plan: [plan file path]
Tasks analyzed: N

### Findings

#### 🆕 Missing Tasks (N found)
1. **[New task subject]**
   Why: [reason this task is needed]
   After: Task #X (dependency)

2. **[New task subject]**
   Why: [reason]

#### 📝 Task Improvements (N found)
1. **Task #X: [subject]**
   Issue: [what's wrong]
   Fix: [what should change]

2. **Task #Y: [subject]**
   Issue: [what's wrong]
   Fix: [what should change]

#### 🔗 Dependency Fixes (N found)
1. Task #X should depend on Task #Y
   Reason: [why]

#### 🗑️ Removals (N found)
1. **Task #X: [subject]**
   Reason: [why it's redundant/unnecessary]

#### 📋 Summary
- Missing tasks: N
- Tasks to improve: N
- Dependencies to fix: N
- Tasks to remove: N

AskUserQuestion: Apply these improvements?

Options:
1. Yes, apply all
2. Let me pick which ones
3. No, keep the plan as is

Based on choice:

• Yes, apply all → apply all improvements to the plan file
• Let me pick which ones → present each improvement individually for approv

Content truncated.