Unikit Improve

{{engine_name}} Improve - Feature Plan Refinement

Refine an existing feature plan by re-analyzing it against the codebase. Finds gaps, missing tasks, wrong assumptions, architectural issues, and enhances plan quality.

Language Awareness — BLOCKING PRE-REQUISITE

BEFORE producing ANY output, silently read .unikit/system/LANGUAGE_RULES.md and apply its rules to ALL subsequent output. If the file is missing or unreadable, fall back to English. Do not produce any user-facing output until language rules are loaded. Do not announce, confirm, or mention the language setting.

Subagent Delegation — BLOCKING PRE-REQUISITE

When the workflow reaches a step that requires a subagent (Agent), the assistant MUST automatically spawn the subagent if agent execution is supported by the current environment and not prohibited by higher-priority instructions.

Only if agent execution is unavailable or blocked, the assistant MUST ask the user before proceeding with any alternative.

Delegation agents

This skill uses named delegation aliases for Agent(...) calls. Each alias is the single place where its delegate's model is declared — call sites name the alias and never carry a model argument of their own.

• recon-agent — read-only parallel reconnaissance. Expands to:

  Agent(subagent_type: Explore, model: sonnet, prompt: "<focused question>")
  

  sonnet is a tier alias, never a version — the one model value that may be written into UniKit. A versioned model id goes stale silently and must never replace it.

  Fallback: if the Agent tool is unavailable, investigate inline with Glob/Grep/Read.

• recon-agent — read-only parallel reconnaissance. Expands to:

  Agent(subagent_type: Explore, prompt: "<focused question>")
  

  No model is named: this runtime either has no dispatch-time model argument or offers only versioned model ids, and a versioned id goes stale silently. The runtime's own configured default applies.

  Fallback: if the Agent tool is unavailable, investigate inline with Glob/Grep/Read.

• check-agent — fresh-context, read-only findings validator (+check). Expands to:

  Agent(subagent_type: Explore, model: sonnet, prompt: "<rendered VALIDATOR.md template>")
  

  Explore is read-only by construction — its tool set excludes Edit/Write, so the read-only contract is guaranteed by the dispatch, not merely requested in the prompt. sonnet is a tier alias, never a version — the one model value that may be written into UniKit. A versioned model id goes stale silently and must never replace it.

  Fallback: the validator is never replaced by inline analysis — see references/CHECK-MODE.md (WARN [+check]: validator failed).

• check-agent — fresh-context, read-only findings validator (+check). Expands to:

  Agent(subagent_type: Explore, prompt: "<rendered VALIDATOR.md template>")
  

  This runtime may offer no read-only-by-construction agent type, so the read-only contract rides on the prompt rather than on the dispatch: keep references/VALIDATOR.md's "You do not modify any files. You do not run commands." lines in whatever is sent. No model is named: this runtime either has no dispatch-time model argument or offers only versioned model ids, and a versioned id goes stale silently. The runtime's own configured default applies.

  Fallback: the validator is never replaced by inline analysis — see references/CHECK-MODE.md (WARN [+check]: validator failed).

• develop-agent — not used by this skill. It belongs to the code-writing skills (/unikit-implement, /unikit-fix, /unikit-verify); plan refinement reads and analyses code, it does not write it. Recorded here so the alias named in "Code Analysis Rules" can be looked up in the one place aliases are documented.

Core Idea

existing feature plan (the PLAN.md manifest)
    + project rules (Bootstrap: RULES_INDEX → core/stack rules)
    + deeper codebase analysis via Explore tasks (with doc references)
    + user feedback (optional)
        ↓
find gaps, missing edge cases, wrong assumptions, architectural issues
        ↓
enhanced plan with better tasks, correct dependencies, more detail

Code Analysis Rules

This skill is a plan refinement orchestrator, not a code writer. It loads project rules itself (Step 0.5 Bootstrap) and delegates codebase exploration to Explore tasks.

For deep code analysis, use the recon-agent alias:

• Launch 2-3 tasks in parallel for different aspects of the codebase
• Each task MUST receive references to project doc files in its prompt — paths to .unikit/ARCHITECTURE.md and relevant core/stack rule files loaded in Bootstrap

Do NOT use /unikit-devcontext or develop-agent — these are for code-writing skills (/unikit-implement, /unikit-fix, /unikit-verify). Plan refinement needs code reading and analysis, not code writing.

What you CAN do directly (without Explore tasks):

• Read any .md documentation files (the plan manifest, .unikit/*.md)
• Lightweight structural queries via Glob/Grep — checking if a file/folder exists, listing .asmdef names, counting files matching a pattern, verifying a namespace or class name is present

What you MUST delegate to Explore tasks:

• Reading .cs file contents for understanding logic or implementation details
• Finding code patterns, existing implementations, integration points
• Checking architectural consistency against actual code
• Verifying assumptions about class relationships, DI bindings, inheritance hierarchies

The distinction: use Glob/Grep when you need a yes/no structural fact (does this file exist? does this class name appear anywhere?). Delegate to Explore tasks when you need to understand how code works or evaluate architectural correctness.

Workflow

Step 0: Find the Feature

Parse $ARGUMENTS for special tokens first:

- --list    → list available plans only (read-only, then STOP)
- @<path>   → explicit plan folder override (highest priority)
- +check    → run the fresh-context findings validator (see Step 3.5); strip the token, remember check = true
- remaining text → feature name or improvement prompt

When both --list and @<path> are present, --list wins and no refinement is executed. Strip +check from $ARGUMENTS before extracting the feature name / improvement prompt so it is never mistaken for prompt text; +check together with --list is silently ignored (no refinement to validate).

Priority 1: @<path> — explicit path override

If $ARGUMENTS contains @<path>:

1. Resolve the path (relative to project root; absolute paths allowed)
2. If the path is a directory holding a plan manifest (<path>/PLAN.md) → use it
3. If the path is a directory containing TASKS.md (a pre-merge plan) → tell the user to run unikit-ai update and STOP. Do not read or convert it here — update is the sole migrator, the same refuse-over-autofix principle rules sync applies with exit 8.
4. If missing → show "Plan folder not found: <path>" and STOP

Remaining argument text (after removing @<path>) is the improvement prompt.

/unikit-improve @.unikit/code/plans/2026-03-08_customers-system добавь обработку ошибок
→ folder: .unikit/code/plans/2026-03-08_customers-system, prompt: "добавь обработку ошибок"

Priority 2: --list — show available plans

If $ARGUMENTS contains --list, run read-only discovery and STOP:

1. Check if .unikit/code/PLAN.md exists (fast-mode plan)
2. Check if .unikit/code/FIX_PLAN.md exists (bugfix plan from /unikit-fix)
3. Get current branch:
   git branch --show-current
4. Scan .unikit/code/plans/ for all feature folders (all three name formats — see Branch match)
5. For each, check if its .unikit/code/plans/<folder>/PLAN.md has uncompleted tasks (- [ ])
6. Mark which folder matches the current git branch (if any), by the three formats of Branch match
7. Print availability summary (sorted by the manifest's Updated: descending — newest first):

## Available Feature Plans

Current branch: feature/customers-system

💾 Fast plan: .unikit/code/PLAN.md (3 tasks remaining)
🔧 Fix plan:  .unikit/code/FIX_PLAN.md (2 tasks remaining)

  * 🔄 customers-system                   ← matches branch (4 tasks remaining)
    ✅ 2026-03-10_customers-service-pool   (completed)
    🔄 002-customer-config-refactor        (2 tasks remaining)

Use:
  /unikit-improve                                              # auto-detect (.unikit/code/PLAN.md → branch → latest)
  /unikit-improve customers-system                             # by name
  /unikit-improve @.unikit/code/plans/customers-system         # by path

8. STOP.

Important: In --list mode — do not execute refinement, do not modify files.

Priority 3: $ARGUMENTS contains a feature name

If $ARGUMENTS contains a feature name (e.g., 2026-03-08_customers-system, customers-system, or legacy 001-customers-system):

1. Look for .unikit/code/plans/$ARGUMENTS/ directory (exact match)
2. If not found by exact match → try partial match: scan .unikit/code/plans/ for folders whose name ends with _$ARGUMENTS (new format) or *-$ARGUMENTS (legacy DDD-* format)
3. If found → use it
4. If NOT found → tell the user:

Feature "$ARGUMENTS" not found in .unikit/code/plans/.

Available features:
- [list existing feature folders]

What would you like to do?
1. Choose one of the existing features
2. Create a new feature plan

→ STOP here. Wait for user response.

Priority 4: No arguments — auto-detect by fast plan, fix plan, git branch, then latest

If $ARGUMENTS is empty (no parameters):

1. Collect candidates:

   • Check if .unikit/code/PLAN.md exists (flat fast-mode plan)
   • Check if .unikit/code/FIX_PLAN.md exists (bugfix plan from /unikit-fix)
   • Get current git branch: git branch --show-current
   • If on a feature/* branch → extract the feature name part (e.g., feature/customers-system → customers-system)
   • Branch match. From branch <prefix><name>, collect every folder in .unikit/code/plans/ that matches any of the three name formats: (1) exactly <name> — the current format; (2) ending with _<name> — the YYYY-MM-DD_<name> format; (3) ending with -<name> and beginning with three digits — the legacy DDD-<name> format. Exactly one match → use it. More than one → ask the user which one, listing each with its Updated: — do not pick by format precedence: two folders for one feature is exactly the state the date used to prevent, and choosing silently is how the resolver starts finding the wrong one. No match → fall through to latest.
     • Example: branch feature/customers-system matches folder customers-system, 2026-03-08_customers-system or 001-customers-system
   • If no branch match → Latest. Read the Updated: line from each candidate's .unikit/code/plans/<folder>/PLAN.md and sort descending; ties break on Created: descending, then on folder name descending. A manifest with no Updated: is excluded and named — WARN [plan] <folder>: manifest has no Updated: — excluded; run unikit-ai update to backfill it — never guessed from the folder name and never from the file's mtime, which git checkout and a fresh clone rewrite. Note the winner as "latest folder plan". latest fallback is a guess, not a resolution: the branch named no plan. With two or more plans present, print the candidate table (folder, Updated:, tasks remaining) and ask — never auto-select. With exactly one plan present there is nothing to choose between: announce it with the branch miss named in the reason and continue.

2. Resolve ambiguity:

   • If no candidates found (no flat plans, no folder plans) → show "No plans found" message and STOP:

     ⚠️ No plans found in .unikit/code/plans/, .unikit/code/PLAN.md, or .unikit/code/FIX_PLAN.md.
     
     Create a plan first:
     - /unikit-plan <description>  — for a feature plan
     - /unikit-fix <bug description> — for a bugfix plan
     

   • If exactly one candidate → use it
   • If multiple candidates (e.g., PLAN.md + FIX_PLAN.md, or a flat plan + folder plans, or multiple flat plans + branch-matching folder) → ask the user which plan to improve via AskUserQuestion, listing all candidates. Print the candidate plans, each with its Updated: and tasks remaining, to the screen as plain markdown first — the question mechanism carries the options and nothing else

3. Use the resolved plan.

Announce the resolution. Whichever priority resolved the plan — @<path>, a feature name, the fast plan, the fix plan, a branch match or the latest fallback — print exactly one visible line, before Step 0.5 and before any other output:

INFO [plan] resolved: <path> (<reason>)

<reason> is exactly one of: explicit path · feature name · fast plan · fix plan · branch match: <branch> · latest fallback. This is plain output, never the payload of an interactive question. Without it the skill's first visible event is a question: Step 0.5 forbids narrating the Bootstrap, so nothing else here speaks.

Ultra bundle check. Read the first line of the resolved plan manifest. If it equals <!-- unikit:plan-mode:ultra -->, this is an ultra bundle: follow .unikit/system/ultra-plan-read.md for reading depth, integrity and mutability. Otherwise continue unchanged. Discovery itself does not change — the folder is found the way it always was; only what is read inside it differs.

Reading depth: read the manifest plus every phase file — improvement is not local, and moving a task between phases touches two of them.

Step 0.5: Bootstrap Context (MANDATORY)

Before any analysis — silently load the project knowledge base. Do NOT narrate the loading process to the user.

Required reads (always, every time, in parallel)

1. .unikit/DESCRIPTION.md — project description, tech stack, constraints
2. .unikit/ARCHITECTURE.md — architecture decisions, folder structure, module rules, dependency directions
3. Read .unikit/memory/code/RULES_INDEX.md. Load rules:
   • RULES.md: ALWAYS read .unikit/RULES.md first (highest priority)
   • Core: read the Core table. For EACH row where Required By = all or contains {{self_name}} — read that file from .unikit/memory/code/core/ using the Read tool. Do NOT skip any matching row. Always re-read at skill start, never rely on prior conversation cache
   • Stack: load dynamically when the current task or context matches "Load When" column, or when a need arises during work
4. .unikit/skill-context/{{self_name}}/SKILL.md — project-specific skill overrides (if exists)
5. .unikit/system/dev-principles.md — engine development principles, read on two levels (used in Step 2.3/2.4 architectural consistency checks and in the Guard B pass, Step 3.3a). Everything above the LAZY-READ BOUNDARY is read here, every time: the evidence contract, the claim-class → evidence-class lattice, the nine failure-class names, phase order, the lane, and the kind / area vocabularies. The section below the boundary — the nine detectors in full and the catalog checklist — is read once per session, on the first task that touches editor state, and read unconditionally: never gated on which rules happen to be installed, because that is exactly where the universal safety net would disappear (A9).
6. .unikit/system/ultra-plan-read.md — the reader contract for an ultra plan bundle: detection, per-consumer reading depth, what is mutable during execution, and the blocking integrity checks. Name it and follow it; never restate it here — one contract, one place. If .unikit/system/ultra-plan-read.md is missing or unreadable, do not block: treat every plan as a single-file plan and continue exactly as before — a project that predates the ultra port has no bundles to read.

Remember loaded rule file paths — pass them to Explore tasks in Step 2.

Step 1: Load Feature Plan

• Read the plan manifest — .unikit/code/plans/<folder>/PLAN.md for a folder plan, .unikit/code/PLAN.md for a flat fast-mode plan. In fast and full one file carries everything: ## Overview, ## Settings, the ## Checklist with phases and dependencies, and ## Technical Context (constraints, interfaces, key patterns, dependency graph, files, editor targets, DI bindings). In an ultra bundle it does not: the manifest carries the checklist and only the cross-phase part of ## Technical Context, while every task's own detail lives in its phase file — the reading depth is stated in .unikit/system/ultra-plan-read.md. For the full section list see unikit-plan/references/TASK-FORMAT.md → Plan Manifest Template; it is not restated here.
• If the manifest has a ## Based on section → parse all linked research entries (folder name + the recorded hash field for each — it may be absent, or it may be a legacy digest recorded against the retired brief field, see Step 1.5). Store as linked_researches list for Step 1.5. Also read each linked research's RESEARCH.md — ## Active Summary alongside the manifest's ## Technical Context (not instead of it) — both are needed for cross-referencing in Step 3.8.

Understand:

• Feature scope and goals
• Current phases and tasks
• Dependencies between tasks
• Which tasks are already completed (checkboxes - [x])
• Architecture decisions made
• Which researches are linked, and the Summary SHA256 recorded for each

Step 1.5: Research Check

Check whether research context has changed since the plan was created or if new relevant researches exist. This step is optional enrichment — if no research updates are found, proceed silently to Step 2.

Case A: Plan has linked researches (## Based on exists with entries)

1. For each entry in linked_researches:

   • Only when the entry carries a Summary SHA256, recompute the SHA256 of the region between the ## Active Summary markers of that research's RESEARCH.md, using the same procedure as /unikit-plan. An entry that carries no Summary SHA256 is resolved by the legacy bullet or the no-hash bullet below and nothing is recomputed for it — settling that first is what keeps a pre-manifest entry from being reported as drifted instead of unknown. Rule 0 — extract the text between <!-- unikit:active-summary:start --> and <!-- unikit:active-summary:end -->, excluding the marker lines themselves; both markers are matched as whole lines. Then the five normalization rules: strip a leading UTF-8 BOM, LF line endings, trailing spaces trimmed from every line, exactly one final newline, and no reformatting (line order and leading whitespace preserved). Feed the normalized text through stdin, never a temp file — … | shasum -a 256 | awk '{print $1}', falling back to sha256sum. Rule 0 runs on text already read; it needs no grant of its own.
   • Recomputed ≠ the recorded Summary SHA256 → emit WARN [research-drift]: <folder> — the linked Active Summary is no longer byte-identical to the one this plan was built from and mark research_updated = true. Say it that way and not "the research changed": the summary is rewritten wholesale whenever the research is saved, so the honest claim is about identity of the input, not about the intent of its author.
   • Recomputed == the recorded Summary SHA256 → unchanged, whatever any timestamp says.
   • The entry carries a Brief SHA256 and no Summary SHA256 → drift is unknown, and nothing is recomputed: the recorded digest describes the retired brief field, a different object, so comparing it against the summary would report "the research changed" where the honest answer is "there is no mechanism here". Emit WARN [research-drift]: <folder> drift unknown (recorded against the retired brief field) and offer the user a re-link, which replaces the dead line. This branch only asks — the write is Step 5.5 item 3.
   • No hash field of either name recorded (an older plan, or the hash tool was unavailable at planning time) → drift is unknown, not false. Emit WARN [research-drift]: <folder> drift unknown (no hash recorded) and offer the user a re-link, which records a hash from now on. This branch only asks — the write is Step 5.5 item 3, and an offer whose write step does not exist is worse than no offer: it leaves the user believing the state was cleared. Do NOT fall back to any older timestamp field. A reader that still parses a field nothing writes any more is a mechanism that rots silently and cannot be told apart from a working one — and it would make the negative half of guard RD-A impossible to assert, which is the only thing standing between this change and a half-applied replacement. The fallback is forbidden in the other direction too: never read a digest recorded against the retired brief field as if it were a Summary SHA256. The two name different objects, and comparing across them reports a change nobody made.
   • RESEARCH.md missing or unreadable, or its ## Active Summary markers absent or duplicated → emit WARN [research-drift]: <folder> source missing.
   • Neither shasum nor sha256sum available → emit WARN [research-drift]: no SHA256 tool available — drift checks skipped once for the whole run, and continue.

   The label WARN [research-drift] is canonical and shared with /unikit-implement and /unikit-verify; per-branch labels would make the outcomes indistinguishable when a log is grepped for drift. The two "unknown" branches are worded apart on purpose: one needs a re-link that replaces a dead line, the other one that records a first hash, and the log is the only place that difference is visible.

2. If any research_updated = true:

   • Re-read the updated research's ## Active Summary, and CONTRACTS.md when it exists
   • Compare new constraints, interfaces, and decisions against the current manifest — its ## Technical Context and its ## Checklist
   • Collect differences as research_improvements (these will appear in the report under a dedicated section)

3. After processing linked researches → check for new researches:

   • Read .unikit/code/researches/INDEX.md
   • The boundary for "researches newer than this plan" is the manifest's own Created: field — the header field the on-disk migration backfilled into every plan. It is not read from the folder name and not from the file's modification time: the folder name is losing its date prefix, and mtime is rewritten by git checkout and by a fresh clone, so both answer this question only by luck. The flat .unikit/code/PLAN.md uses the same field.
   • A manifest carrying no Created: is a plan the migration has not reached. Say so and skip this sub-step rather than guess a boundary: WARN [plan] <plan>: manifest has no Created — cannot bound "researches newer than this plan"; run unikit-ai update.
   • Filter the index for records whose Updated is newer than that boundary and whose Lifecycle is not superseded (a record carrying no Lifecycle line counts as active)
   • Log the drop, always, in the form /unikit-plan uses: INFO [research] index: <N> entries, <K> shown (<a> not newer than the plan, <b> superseded). A record with no Updated is excluded and named — WARN [research] <folder>: index row has no Updated — excluded; run /unikit-explore to redraw the index — never guessed at from another field.
   • Take up to 5 entries, check relevance against the plan's feature scope (compare Summary against plan Overview)
   • If relevant entries found → ask user:

     AskUserQuestion: Found new researches since the plan was created:
     
     1. <Title> (<Date>) — <Summary>
     2. <Title> (<Date>) — <Summary>
     
     Use them to improve the plan?
     
     Options:
     1. Yes — use all
     2. Let me pick (specify numbers)
     3. Skip — improve without new researches
     

   • If user selects researches → read their RESEARCH.md (## Active Summary first, then CONTRACTS.md when it exists), add findings to research_improvements, and prepare to attach them to ## Based on in Step 5

4. If no updates and no new relevant researches → proceed to Step 2 silently.

Case B: Plan has NO linked researches (no ## Based on or empty)

1. Check current session — look in the conversation history for results of /unikit-explore. If found and relevant to the plan → use as research context, add to research_improvements.

2. Check index — if no session context:

   • Read .unikit/code/researches/INDEX.md
   • Drop records whose Lifecycle is superseded (a record carrying no Lifecycle line counts as active), then take up to 5 entries — the first 5, because the index is sorted newest-first, so these are the most recent
   • Log the drop, always, in the same form as Case A: INFO [research] index: <N> entries, <K> shown (<c> superseded)
   • Check relevance against the plan's feature scope
   • If relevant entries found → ask user (same question format as Case A step 3)
   • If user selects → read their RESEARCH.md (## Active Summary first, then CONTRACTS.md when it exists), add to research_improvements, prepare to attach in Step 5

3. If nothing found or user skips → proceed to Step 2 silently.

After Step 1.5

Regardless of the outcome, always continue to Step 2 (Deep Codebase Analysis). Research improvements are collected separately and will be merged into the final report in Step 4, appearing in a dedicated section before the standard codebase analysis findings.

Step 2: Deep Codebase Analysis

Follow the delegation rules from Code Analysis Rules section above.

Formulate analysis questions based on the feature plan, then launch Explore tasks in parallel. Each task MUST receive references to project doc files in its prompt.

Doc references to include in every Explore task prompt:

• .unikit/ARCHITECTURE.md — always (module boundaries, dependency rules)
• Core rule files loaded in Bootstrap — pass the paths from RULES_INDEX.md relevant to the task's focus
• Stack rule files loaded in Bootstrap — pass if the task's focus involves that framework

Example: launching parallel tasks for a customer system feature:

Task 1 — Existing code & bindings:
recon-agent(prompt:
  "Before analysis, read these project docs:
   - .unikit/ARCHITECTURE.md
   - [core rule paths from RULES_INDEX.md Core table]

   Find all existing customer-related classes, interfaces,
   and installers. Show their relationships and Zenject bindings.
   Check for ICustomer, SimpleCustomer, CustomerInstaller, etc.
   Thoroughness: medium.")

Task 2 — Integration points:
recon-agent(prompt:
  "Before analysis, read these project docs:
   - .unikit/ARCHITECTURE.md
   - [core rule paths from RULES_INDEX.md Core table]

   Find all SignalBus events (ISignal structs) related to
   gameplay flow. Check how Bootstrap loading operations work
   and what integration points exist for new systems.
   Thoroughness: medium.")

Task 3 — Save & controller patterns:
recon-agent(prompt:
  "Before analysis, read these project docs:
   - .unikit/ARCHITECTURE.md
   - [core rule paths from RULES_INDEX.md Core table]

   Check existing SaveSerializer implementations.
   Find the pattern for adding new save data to the system.
   Look at existing GRASP controllers for reference patterns.
   Thoroughness: medium.")

Fallback: If Agent tool is unavailable, investigate directly using Glob/Grep for structural checks and Read for code understanding.

After tasks return, synthesize their findings with the project rules loaded in Bootstrap.

What to analyze (delegate these questions):

2.1: Trace existing code paths

• 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 reuse

2.2: Check integration points

• Zenject installer registrations needed
• SignalBus events that need declaring
• Addressable asset references
• SaveSystem serializers needed
• Bootstrap loading operations
• Module boundary violations (Modules → Game is FORBIDDEN)

2.3: Check architectural consistency

• Non-MonoBehaviour first principle adherence
• Model-View separation, GRASP controller patterns
• R3 reactive subscription cleanup (.AddTo())
• UniTask with CancellationToken on every async method
• Proper DI registration patterns (.NonLazy() for controllers/presenters)

2.4: Check edge cases

• Missing CancellationToken propagation
• Missing R3 subscription disposal
• Missing Odin [Required] attributes
• ZLinq usage instead of System.Linq in hot paths

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., installer registration, save serializer, signal declarations)
• Tasks for edge cases not covered
• Missing test tasks for new systems

3.2: Task quality issues

• Descriptions too vague (no file paths, no specific implementation details)
• Missing specific class names or namespaces
• Incorrect assumptions about existing code
• Missing reference to existing patterns that should be followed

3.3: Dependency issues

• Wrong task/phase order
• Missing dependencies between phases
• Tasks that could run in parallel but are sequential

3.3a: Guard B — a phase carrying an Editor: task must be serialized alone in its execution layer

This skill is the third writer of tasks (after /unikit-plan and /unikit-plan add), so it checks the constraint on a plan it did not write.

The unit of parallelism downstream is the phase: unikit-implement-coordinator builds the phase graph from the **Dependencies:** lines, computes execution layers (Layer 0 = phases with no dependencies; Layer N = phases whose dependencies all sit in layers 0..N-1) and runs every phase of one layer concurrently, while tasks inside a phase run in order.

Procedure:

1. Collect the phases carrying at least one Editor: line.
2. Recompute the execution layers from the plan's **Dependencies:** lines, exactly as the coordinator does.
3. A layer that holds an editor phase and any other phase is a finding.

Two things this check is not. It is not a rule about tasks — two Editor: tasks inside one phase are already sequential, and recommending they be split would manufacture the very collision the guard exists to prevent; never propose that fix. And it is not limited to editor-versus-editor conflicts — a neighbouring code phase writes a source file, the editor re-reads it, the domain reloads, and minutes of unavailability land in the middle of another phase's mutation. Any co-resident phase is the finding, whatever it is doing.

The fix is always on the dependency lines, never on the phase contents: make the editor phase depend on everything that must precede it, and make every remaining phase depend on it directly or transitively.

Each finding goes into the 🔄 Dependency Fixes group in the format below — it must name the layer, every phase sharing it, and the Editor: task that forces the serialization, because without those three the reader cannot tell which dependency line to add.

🔒 Layer <N> holds Phase <X> beside editor Phase <Y>
   Editor task: Phase <Y> / Task <n.m> — `Editor: [kind] <container> → <target> : <action>`
   Fix: add `Phase <Y>` to Phase <X>'s **Dependencies:** (or the reverse, if <X> must run first)

3.4: Redundant or duplicate tasks

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

3.5: Scope issues

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

3.6: Architectural issues

• Module boundary violations in the plan
• Wrong namespace assignments
• Missing SOLID/GRASP principle adherence
• Plan suggests patterns that contradict project conventions

3.7: User-prompted improvements (if specific feedback in $ARGUMENTS)

If the user provided improvement instructions beyond just a feature name:

• Apply the user's feedback to the plan
• Look for tasks that need modification
• Add new tasks if required

3.8: Research consistency (only when research_improvements is non-empty)

If Step 1.5 produced research_improvements (from updated or newly linked researches):

• Compare the research's ## Active Summary → Constraints: against the manifest's ### CONSTRAINTS — find mismatches
• Find interfaces defined in research but missing from plan tasks
• Find decisions in research that contradict plan tasks
• Flag research open questions that the plan resolved without justification
• Each finding goes into research_improvements list with source attribution (which research it came from)

Step 3.5: Validate Findings (+check only)

Run this step only when check = true (the +check flag was parsed in Step 0) and Step 3 produced at least one finding in a validated group. Otherwise skip it entirely — no validator lines appear anywhere in the output and the Step 4 / Step 5.8 Summary keeps its default shape.

Follow the full procedure in references/CHECK-MODE.md: it dispatches one fresh-context check-agent validator over the four codebase-traceable groups (missing, improvements, architectural, removals), applies each keep/modify/drop verdict, recomputes the 🔄 Dependency Fixes group on the filtered list (phase b), and tracks the hidden / adjusted counters. The Research-Based Findings (research_improvements) and the 🔄 Dependency Fixes group are not validated.

Fallback (do NOT inline-analyze): if the validator agent is unavailable/blocked or the dispatch fails, the procedure keeps all findings as-is and emits the single line WARN [+check]: validator failed (<reason>), all items kept as-is — it never re-does the validator's work with Glob/Grep/Read. This +check path is exempt from the ## Subagent Delegation — BLOCKING PRE-REQUISITE rule: an unavailable validator is silently skipped, the user is never asked.

The filtered findings (and recomputed dependencies) are what Step 4 renders.

Step 4: Present Improvements

Show the user what you found. When research_improvements is non-empty, the report has two sections: research-based findings first, then codebase analysis findings. When empty, only the standard section appears.

BLOCKING PRE-REQUISITE — the report reaches the screen before the question is asked. Render every group below in full as visible output — the findings themselves, not a count of them — and only then ask the decision question. Never ask about improvements the user has not seen: a bare "Apply improvements?" with nothing above it is the failure this rule exists to prevent. Print the findings to the screen as plain markdown first — the question mechanism carries the options and nothing else. The same holds for the Choose which follow-up below: its #N labels mean something only because the numbered report is already on screen.

## Plan Improvement Report

Feature: [feature folder name]
Files: <plan folder>/PLAN.md
Phases analyzed: N
Tasks analyzed: N
Researches checked: N (list names if any)

### Research-Based Findings (only if research_improvements is non-empty)

Source: [research folder name(s)]

#### Updated Constraints (N)
1. **[Constraint from research]**
   Change: [what changed in the research vs what the plan has]
   Action: [update the constraint in `## Technical Context` / update task description]

#### New/Changed Interfaces (N)
1. **[Interface name]**
   Change: [new method / changed signature / removed]
   Action: [add task / update existing task]

#### Research-Plan Contradictions (N)
1. **[Issue]**
   Research says: [X]
   Plan says: [Y]
   Recommendation: [which to follow and why]

#### New Researches to Attach (N) (only if new researches were selected in Step 1.5)
1. **[Research title]** (<date>)
   Relevant findings: [brief summary of what this research adds]

### Codebase Analysis Findings

#### ⚠️ Missing Tasks (N)
1. **[Task description]**
   Reason: [why this task is necessary]
   After: [dependency on phase/task]

#### 🔍 Task Improvements (N)
1. **Phase X, Task Y: [name]**
   Issue: [what's wrong]
   Fix: [what needs to change]

#### 🔄 Dependency Fixes (N)
1. Phase X should depend on Phase Y
   Reason: [why]
2. 🔒 Layer N holds Phase X beside editor Phase Y
   Editor task: Phase Y / Task n.m — `Editor: [kind] <container> → <target> : <action>`
   Fix: add `Phase Y` to Phase X's **Dependencies:** (or the reverse, if X must run first)

#### 🏗️ Architectural Notes (N)
1. **[Issue description]**
   Recommendation: [how to fix]

#### 🗑️ Removals (N)
1. **Task: [name]**
   Reason: [why it's redundant]

### Summary
- Research-based changes: N
- Missing tasks: N
- Tasks to improve: N
- Dependencies to fix: N
- Architectural notes: N
- Tasks to remove: N
- Hidden by +check: N      (only when +check ran successfully — see Step 3.5)
- Adjusted by +check: M    (only when +check ran successfully — see Step 3.5)

The decision question is asked after that report is on screen, as its own block. When it goes through an interactive question mechanism, that is a separate call issued once the report text has been emitted — never a replacement for it:

Apply improvements?
1. Yes, apply all
2. Choose which to apply
3. No, keep the plan as is

Based on choice:

• Apply all → apply all improvements to the manifest, proceed to Step 5
• Choose which → use AskUserQuestion with multiSelect: true to let the user pick items. Group options by category (Missing Tasks, Task Improvements, Dependency Fixes, Architectural Notes, Removals). Each option label = "#N: short description". After the user selects → proceed to Step 5, applying only the selected items. Unselected items are skipped without comment.
• No → keep plan as is → STOP

If no improvements found:

## Plan Review Complete

✅ The plan looks good! No significant issues found.

Feature: [feature folder name]
Phases: N, Tasks: N

Ready to proceed with implementation.

Step 5: Apply Approved Improvements

Based on user's choice, apply changes sequentially.

Use Edit for every change. Write over a plan manifest is forbidden — the file carries ## Technical Context (and, in an ultra bundle, ## Phase Index), and a regenerating write silently drops whatever the current pass did not reconstruct. When a change is too large for a single Edit, split it into several Edit calls; do not fall back to Write.

Editing an ultra bundle. The manifest and every affected phase file are edited together — never regenerate the manifest alone when phase detail changed, and never write a checkbox into a phase file. After the write, re-run the bundle integrity checks named in .unikit/system/ultra-plan-read.md; a bundle left inconsistent by an improvement blocks the next consumer that opens it.

5.1: Add missing tasks to the manifest's ## Checklist

For each new task from the report:

1. Determine the correct phase (create a new phase if needed)
2. Insert the task with - [ ] checkbox at the correct position within its phase
3. Include file paths, class name

…(truncated)