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 & Parse Arguments

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

• Paths: paths.plan, paths.plans, paths.fix_plan, paths.research, paths.description, paths.patches, and paths.archive; derive research_bundles_dir = <parent directory of paths.research>/research/
• Language: language.ui for prompts and summaries, language.artifacts for plan artifact updates, and language.technical_terms for human-readable technical terminology in plan artifacts
• Git: git.enabled, git.base_branch, git.create_branches
• Workflow: workflow.plan_id_format (default: slug) — used by branch-based plan discovery. Active values: slug and sequential. A root *.md is a named full plan unless it is the resolved fast/fix path; a direct child */index.md is an ultra bundle entrypoint only when it contains exactly one <!-- aif:plan-mode:ultra -->. When sequential, search both [0-9]{4}_<branch-slug>.md and [0-9]{4}_<branch-slug>/index.md, then choose the highest prefix. timestamp and uuid are reserved values and currently behave like slug. Treat any unknown value as slug.

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
• ui_language: en
• artifact_language: en
• technical_terms_policy: keep
• workflow.plan_id_format: slug

Resolved language values:

• ui_language = language.ui || "en"
• artifact_language = language.artifacts || language.ui || "en"
• technical_terms_policy = language.technical_terms || "keep"

If technical_terms_policy is not one of keep, translate, or mixed, treat it as keep. Legacy values such as english also behave like keep.

All AskUserQuestion prompts, progress updates, refinement reports, summaries, and next-step guidance MUST be written in ui_language.

Any generated or updated plan artifact content under paths.plan, paths.plans, or paths.fix_plan MUST be written in artifact_language.

Exception: an existing ## Original Request section is raw source input, not generated artifact prose. Preserve its heading and body exactly as read from the plan file on every edit or regeneration, even when artifact_language differs. Do not translate, summarize, normalize, trim, or rewrite it.

Templates and examples define structure, not fixed English output. If artifact_language is not en, translate human-readable headings, labels, task prose, roadmap rationale, research summaries, improvement notes, and dependency notes before saving. Preserve markdown structure, checkbox syntax, task IDs, numeric prefixes, branch names, commit messages, commands, file paths, config keys, package names, API names, WARN/INFO labels, and raw errors unchanged. Keep ## Research Context, Source:, Active Summary, Updated:, and SHA256: exact because downstream research drift checks parse them as compatibility tokens. Apply technical_terms_policy to other human-readable terminology.

First parse arguments:

- --list    → list available plans only (read-only, then STOP)
- +check    → after refinement, validate findings via a fresh-context subagent
- @<path>   → explicit plan file, ultra directory, or ultra `index.md` override (highest priority)
- remaining argument text → optional improvement prompt

+check is orthogonal to the other flags and may appear anywhere in $ARGUMENTS. Strip it from the argument string before resolving @<path> and the improvement prompt.

When --list is present, it wins and no refinement is executed. +check is silently ignored in --list mode (there is nothing to validate before refinement runs).

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

If $ARGUMENTS contains --list, execute the procedure in references/LIST-MODE.md and STOP. That document is the single source of truth for the discovery rules, output shape, and read-only contract (no refinement, no file modifications, +check is silently ignored). Do not duplicate its content here.

Step 1: Resolve Active Plan

This step runs in the default (non---list) mode and picks one plan artifact for refinement using the priority chain below. The discovery-list logic for --list lives in references/LIST-MODE.md and is independent of this step.

Locate the active plan artifact using this priority:

1. If `$ARGUMENTS` contains `@<path>`:
   - Resolve the path (relative to project root; absolute paths allowed)
   - Accept a markdown file, an ultra directory containing `index.md`, or that `index.md`
   - If missing → show "Plan artifact not found: <path>" and STOP
   - Before normalizing a directory or treating an explicit `index.md` as ultra,
     Read `index.md` and require exactly one
     `<!-- aif:plan-mode:ultra -->`; otherwise STOP with a plan-integrity error
2. No explicit `@<path>` override → Check current git branch:
   git branch --show-current
   → Convert branch name to filename: replace "/" with "-" (this is <branch-slug>)
   → When `workflow.plan_id_format = sequential`, glob both:
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-slug>.md`
     `<configured plans dir>/[0-9][0-9][0-9][0-9]_<branch-slug>/index.md`
     Read every directory candidate and retain it only when `index.md` contains
     exactly one `<!-- aif:plan-mode:ultra -->`. Choose the highest-numbered
     valid artifact and emit `WARN [aif-improve]` when multiple valid candidates
     exist; if both shapes share the highest prefix, prefer ultra.
   → If no valid sequential match exists, or sequential mode is inactive, check
     `<configured plans dir>/<branch-slug>/index.md` and
     `<configured plans dir>/<branch-slug>.md`. Read the directory entrypoint
     before selection and ignore it unless it contains exactly one ultra marker;
     if both valid shapes exist, warn and prefer ultra.
   Example (slug):       feature/user-auth → .ai-factory/plans/feature-user-auth.md
   Example (sequential): feature/user-auth → .ai-factory/plans/0042_feature-user-auth.md
3. If the branch-based plan is missing or git mode is off:
   → Count root `*.md` full plans plus declared-ultra direct child `*/index.md`
     entrypoints; exclude resolved `paths.plan` and `paths.fix_plan`
   → If exactly one artifact exists, use it
   → Do not count ultra phase files as plans
   → If multiple exist, ask the user to choose or require `@<path>`
4. No named full/ultra plan → Check the resolved fast plan path (from /aif-plan fast)
5. No regular plan and no resolved fast plan → Check the resolved fix plan path (from /aif-fix plan mode)

Note: Plan discovery scans paths.plans/ only. Plans archived to paths.archive/plans/ by /aif-archive are excluded from discovery. Any automatically discovered */index.md candidate must be read before selection and ignored unless it contains exactly one <!-- aif:plan-mode:ultra -->. A marked ultra bundle with broken links is a blocking integrity error, not a fallback opportunity.

If NO plan file found at any location:

No active plan found.

To create a plan first, use:
- /aif-plan full <description>  — for a rich single-file feature plan
- /aif-plan ultra <description> — for an exhaustive multi-file plan bundle
- /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 artifact.

If a plan artifact is found → proceed to Step 2 (Load Context).

Step 2: Load Context

2.1: Read the plan artifact

Read the selected entrypoint completely. If it is an ultra index.md, validate its Phase Index links and read every linked phase file in order before analyzing or regenerating the bundle. Treat the bundle as one atomic plan. Understand:

• Feature scope and goals
• ## Original Request, when present: the original user intent and immutable scope anchor for the plan. Treat this section as raw source input and preserve it exactly on any plan edit or regeneration.
• Current tasks (subjects, descriptions, dependencies)
• Settings (testing, logging preferences)
• Commit checkpoints
• Which tasks are already completed (checkboxes - [x])
• For ultra: the exact paths/symbols, implementation steps, contracts, risks, acceptance criteria, and verification in every task's phase file

2.2: Read project context

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

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

If the plan contains ## Research Context, treat its embedded copy as the committed requirements snapshot. Parse the first Source: / Reference: line with canonical ^(?:Source|Reference):\s+\x60([^\x60]+)\x60\s+\( syntax; for older bare-path lines, fall back to ^(?:Source|Reference):\s+(.+?)\s+\(. Fall back to configured paths.research only when neither form identifies a usable path.

If the parsed source is inside research_bundles_dir, require its sibling INDEX.md to contain <!-- aif:research-mode:ultra --> exactly once and link that RESEARCH.md from ## Artifact Index; otherwise emit WARN [research-drift]. Valid sibling C4/ADR/dependency artifacts are rationale only and must not expand plan scope.

When SHA256: is present, extract the current source text strictly between <!-- aif:active-summary:start --> and <!-- aif:active-summary:end -->, remove HTML comment blocks, preserve line order and leading whitespace, trim trailing spaces from every line, use LF endings, and end with one newline. Hash through stdin with shasum -a 256 or sha256sum; the digest is authoritative. Use Updated: only as a legacy fallback when SHA256: is absent. A missing/invalid source or revision mismatch emits WARN [research-drift]; refine against the embedded Research Context unless the user explicitly requests a rebase.

When adding ## Research Context to an unlinked plan, use the same normalization algorithm and first output field as the SHA256: value. Calculate it through stdin / inline shell input without a temporary repository artifact.

Otherwise, select at most one relevant research source using the same conservative order as /aif-plan: an explicit source, one clearly matching direct child bundle whose INDEX.md contains <!-- aif:research-mode:ultra --> exactly once, declares Status: active, and links its RESEARCH.md from ## Artifact Index, then the configured legacy file. Do not merge multiple sources or choose by recency alone.

2.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.

2.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 3: Deep Codebase Analysis

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

3.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

3.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

3.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 4: Identify Improvements

Compare the plan against what you found. Use ## Original Request as the original intent / scope anchor when it exists, together with the current task list and any committed ## Research Context. A proposed refinement is in scope only when it supports that original request or an explicitly approved user refinement prompt; otherwise route it to 4.6 (out_of_scope) instead of adding it to the active plan. Categorize issues:

4.1: Missing tasks

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

4.2: Task quality issues

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

4.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)

4.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

4.5: Task size issues

• Tasks too large (should be split)
• Tasks too small (should be merged)
• Split/merge findings go into the "📝 Task Improvements" report section (improvements group, alongside 4.2) — they restructure existing tasks rather than add or remove them.

4.6: Out-of-scope tasks

• Tasks already in the plan that look useful in themselves but are unrelated to the feature this plan is about (gold-plating)
• On approval these are removed from the active plan — the same drop action as removals (see Step 6.4). The difference is the report only: an out-of-scope task goes to its own "💡 Out of scope" section instead of being lumped into "🗑️ Removals", so the user sees a useful-but-unrelated idea before it is dropped and can choose to capture it elsewhere. The skill itself does not persist out-of-scope items anywhere.

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

If the user provided specific improvement instructions in $ARGUMENTS (excluding --list, +check, 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

This is a dispatcher step, not a separate finding category. Each finding it produces is routed to its natural group based on its nature: a new task goes to 4.1 (missing), a rewording or expansion of an existing task goes to 4.2 (improvements), an explicit removal request goes to 4.4 (removals), and a "useful-but-out-of-scope" idea goes to 4.6 (out_of_scope). There is no separate 4.7 group in the Step 5 report or in +check validation.

Optional: +check validation between Step 4 and Step 5

When the +check flag is set (and --list is not), run the validation procedure from references/CHECK-MODE.md here, between Step 4 and Step 5. It re-reads cited files via a fresh-context subagent, then drops invented items, rewrites partially-correct ones, and recomputes dependencies on the filtered list. For ultra, the validator must receive the entrypoint plus all linked phase files as the plan artifact; validating index.md alone is incomplete. Without +check, skip this entirely — the output has no validator-related lines and the Summary block stays in its default shape without the two +check counter rows.

Step 5: Present Improvements

Show the user what you found in a clear format. The emoji-grouped sections are kept for scannability, but the items inside "🆕 Missing Tasks", "📝 Task Improvements", "🗑️ Removals", and "💡 Out of scope" all follow the same prose shape — no labeled Why: / Issue: / Fix: fields:

1. Behavioral impact — what breaks or becomes harder if the plan stays as-is (missing capability, vague task that will be misimplemented, redundant task that wastes effort).
2. Optional note — short citation from the codebase, an existing pattern the plan should match, or a consequence. Include only when it adds signal.
3. Plan anchor — Task #X reference (or "after Task #X" for new tasks).
4. Suggested edit — concrete change: what to add / how to reword / what to remove.

The "🔗 Dependency Fixes" group is not restated in this shape — it is always computed after the four other groups (and after +check filtering when the flag is set, see references/CHECK-MODE.md) and uses the short legacy form: Task #X should depend on Task #Y. Reason: …. The dependency entries reference only tasks that survived filtering.

The Step 5 report template below defines structure only. Render all human-readable text in this user-facing response in ui_language. Preserve command names, paths, task IDs, section structure, option structure, task counts, numeric counts, WARN/INFO labels, and raw errors unchanged.

## Plan Refinement Report

Plan: [plan artifact path]
Tasks analyzed: N

### Findings

#### 🆕 Missing Tasks (N found)
1. The plan currently leaves authenticated requests without a session refresh step — long-running clients silently lose access after the access-token TTL. The existing middleware in `src/middleware/auth.ts` already exposes a `refresh()` hook, so the plan should reuse it instead of inventing a new one. After Task #3. Add a new task: "Wire `authMiddleware.refresh()` into the login flow and cover the expired-token path with an explicit test."

#### 📝 Task Improvements (N found)
1. Task #4 ("Add validation") gives no field-by-field contract — implementer will either over-validate or skip the email format check that the rest of the codebase enforces via `validators/email.ts`. Task #4. Rewrite as: "Validate `email` (via `validators/email.ts`), `password` (min 12 chars), and `displayName` (1-64 chars) in `RegisterRequest`; return 422 with field-level errors when validation fails."

#### 🔗 Dependency Fixes (N found)
1. Task #5 should depend on Task #2. Reason: Task #5 consumes the session helper introduced in Task #2.

#### 🗑️ Removals (N found)
1. Task #7 ("Create UserRepository") duplicates `src/repos/user.ts:12` which already exposes the same query surface — keeping the task will lead to a parallel implementation. Task #7. Remove the task; rely on the existing repository and adjust Task #8 to import it.

#### 💡 Out of scope — for later (N found)
1. Task #11 ("Refactor the logging module") looks reasonable on its own but is unrelated to the login feature this plan is about — keeping it expands scope without any concrete trigger from the current code paths. Task #11. Drop it from the active plan; the idea is surfaced here so you can capture it elsewhere (issue tracker, backlog note) if it's worth revisiting as its own feature later.

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

When `+check` ran successfully, two extra rows (`Hidden by +check: N`, `Adjusted by +check: M`) are appended to the Summary block — the exact wording and failure-mode replacements live in `references/CHECK-MODE.md`.

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 approval
• No, keep the plan as is → exit without modifications

If no improvements found:

The completion templates below define structure only. Render all human-readable text in these user-facing responses in ui_language. Preserve command names, paths, task counts, and numeric counts unchanged.

## Plan Review Complete

The plan looks solid! No significant gaps or issues found.

Plan: [plan artifact path]
Tasks: N

Ready to implement:
/aif-implement

Step 6: Apply Approved Improvements

Based on user's choice:

6.1: Apply task improvements

For existing tasks that need better descriptions:

TaskGet(taskId) → read current
TaskUpdate(taskId, description: "improved description", subject: "improved subject")

6.2: Add missing tasks

For new tasks:

TaskCreate(subject, description, activeForm)
TaskUpdate(taskId, addBlockedBy: [...]) → set dependencies

6.3: Fix dependencies

TaskUpdate(taskId, addBlockedBy: [...])

6.4: Remove redundant or out-of-scope tasks

Both removals and out_of_scope translate to the same plan-file action — drop the task:

TaskUpdate(taskId, status: "deleted")

The difference between the two is the report only. removals are dead-weight duplicates: mentioned once and forgotten. out_of_scope items appear in the "💡 Out of scope" section so the user sees the idea was noticed and consciously dropped from this plan, not removed without a trace. The skill does not persist out-of-scope tasks anywhere — capturing the idea elsewhere (issue tracker, backlog) is the user's call.

6.5: Update the plan artifact

CRITICAL: After all changes, update the selected plan artifact to reflect the new state:

• Add new tasks to the correct phase with - [ ] checkboxes
• Update task descriptions if they changed
• Fix task ordering if dependencies changed
• Remove deleted tasks
• Update commit checkpoints if task count changed significantly
• Preserve any - [x] checkboxes for already completed tasks
• Preserve existing ## Original Request exactly, including heading, body text, whitespace, and line breaks. Do not translate, summarize, normalize, trim, or rewrite it; this section is raw source input and is exempt from artifact_language rewriting.
• Preserve existing ## Research Context and its Source: / revision marker exactly on any rewrite, unless the user explicitly asks to rebase the plan to current research
• If an unlinked plan is refined using current research, add ## Research Context by copying the relevant Active Summary and write Source: `<selected research path>` (Active Summary, Updated: <research Updated timestamp>, SHA256: <sha256 of copied Active Summary>)
• Compute that hash with the canonical drift normalization: remove HTML comment blocks, preserve line order and leading whitespace, trim trailing spaces from every line, use LF line endings, and end with exactly one final newline. Feed the normalized text to shasum -a 256 or sha256sum through stdin / inline shell input, never through a temp file, and copy the first output field.
• If a linked plan has research drift, keep the committed Research Context and source revision in the plan and include WARN [research-drift] in the refinement report
• For ultra, update index.md and the affected phase files atomically:
  • task checkboxes remain only in index.md
  • every task ID maps to exactly one phase section
  • add/remove/rename phase files only together with Phase Index and task-link updates
  • preserve completed task status while improving its detail
  • rerun link, orphan, dependency, and task-mapping integrity checks
  • maintain the ultra detail gate: exact paths/symbols, ordered edits, contracts, error/logging behavior, test policy, acceptance criteria, and verification

Use Edit to make surgical changes to a file, or Write to regenerate affected files when changes are extensive. Never regenerate only index.md when phase details have changed.

When editing or regenerating the plan artifact, keep all human-readable artifact content in artifact_language; the examples above are structural only. Preserve completed - [x] checkboxes exactly. The ## Original Request section is the explicit language-policy exception: keep it verbatim because it is the user's raw request, not generated artifact prose.

Identifier invariant: when the existing full-plan filename or ultra directory name matches ^[0-9]{4}_.*(\.md)?$, preserve the exact numeric prefix on rewrite. Never renumber a plan during an improve pass — the prefix is permanent and must survive any regeneration. Write back to the same file or bundle directory you read from.

6.6: Confirm completion

The Step 6.6 completion template below defines structure only. Render all human-readable text in this user-facing response in ui_language. Preserve command names, paths, task counts, and numeric counts unchanged.

## Plan Refined

Changes applied:
- Added N new tasks
- Improved N task descriptions
- Fixed N dependencies
- Removed N redundant tasks

Updated plan: [plan artifact path]
Total tasks: N

Ready to implement:
/aif-implement

Context Cleanup

Suggest the user to free up context space if needed: /clear (full reset) or /compact (compress history).

Artifact Ownership

• Primary ownership: the plan artifact being refined (resolved branch-plan path, named full-plan path, resolved fast plan path, or resolved fix plan path when explicitly targeted).
• Config use: resolve full-plan directory via paths.plans, fast/fix plans via paths.plan and paths.fix_plan, git behavior via git.enabled and git.create_branches, optional legacy/bundled research context from paths.research and its derived sibling research/ directory, and patch fallback via paths.patches.
• Read-only context: description, architecture, roadmap, rules, and research artifacts except where the active plan file itself is being updated.

Important Rules

1. Don't rewrite from scratch — improve the existing plan, don't replace it
2. Preserve completed work — never modify or remove - [x] completed tasks
3. Traceable improvements — every change must be justified by codebase analysis or user input
4. Respect settings — if testing is "no", don't add test tasks. If logging is "minimal", don't add verbose logging tasks
5. No gold-plating — don't propose adding tasks outside the feature scope unless critical. When you find a task already in the plan that drifts outside scope, route it to the "💡 Out of scope" report section, not to "🗑️ Removals" — the user should see useful-but-not-here ideas separately from dead-weight duplicates.
6. Minimal viable improvements — suggest only what matters, not every possible enhancement
7. User approves first — never apply changes without user confirmation
8. Keep plan file in sync — the plan file MUST match the task list after improvements
9. Original Request is immutable — when present, use ## Original Request to judge scope and preserve it verbatim on every plan edit or regeneration

Examples

Worked examples for the default, prompt-driven, no-plan, explicit-plan-file, and "plan looks solid" flows live in references/EXAMPLES.md. The --list mode example lives in references/LIST-MODE.md; the +check mode example lives in references/CHECK-MODE.md.