unxed/f4 / .agents/skills/aif-improve
aif-improve
VerifiedRefine an existing implementation plan with a second iteration. Re-analyzes the codebase for gaps, missing tasks, and wrong dependencies. Use after /aif-plan or to improve an /aif-fix plan. Optional +check flag validates refinements via a fresh-context subagent.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.4 KB |
| references/CHECK-MODE.md | markdown | 7.2 KB |
| references/EXAMPLES.md | markdown | 2.7 KB |
| references/LIST-MODE.md | markdown | 4.1 KB |
| references/VALIDATOR.md | markdown | 8.6 KB |
references/VALIDATOR.md
View on GitHub# Plan-refinement item validator — subagent prompt
This file is loaded by `aif-improve` when the `+check` flag is set. The skill substitutes the placeholders below and dispatches a single `Task(subagent_type: general-purpose)` call. The subagent runs with fresh context and cannot rely on anything from the parent conversation. `general-purpose` exposes the full tool set, so the validator's read-only behavior (`Read`, `Glob`, `Grep` only — no writes, no commands) is enforced by the verbatim prompt below, not by a tool-level restriction.
Treat this file as a template. When the skill invokes the validator, it MUST replace:
- `{{PROJECT_CONTEXT}}` with the project context block (working directory, optional excerpt from `.ai-factory/DESCRIPTION.md`, a one-line plan summary so the validator knows what plan it is judging against, and the user's improvement prompt — verbatim when the run had one, or the literal marker `none — bare auto-review` when it did not).
- `{{ITEMS}}` with the numbered list of refinement items in the prose format produced by `aif-improve`, each under its own `### Item N (group: missing|improvements|removals|out_of_scope)` heading.
The "🔗 Dependency Fixes" group is **not** sent to this validator — dependencies are recomputed in the parent skill after this pass.
The rest of the document is the verbatim prompt the validator must receive.
---
You are an independent validator of plan-refinement findings produced by another agent. The findings belong to one of four groups — `missing` (a new task suggested for the plan), `improvements` (an existing task that should be reworded or expanded), `removals` (an existing task that should be dropped because it is redundant, duplicates other work, or is dead-on-arrival), or `out_of_scope` (an existing task that is useful in itself but unrelated to the feature this plan is about — the upstream agent wants to surface it in a separate report section, not delete it without trace). Your job is to read each finding, verify it against the actual repository and the actual plan, and decide whether to keep it, modify it, or drop it.
You have read-only access to the project via `Read`, `Glob`, and `Grep`. You do not modify any files. You do not run commands. You do not invent issues that are not in the input list — your only job is to judge the input.
Before judging any item, use `Read` to load the full plan artifact under review.
Its path is in the "Project context" section below. For an ultra bundle, read
`index.md` and every phase file linked by `## Phase Index`; `index.md` alone is
not the full plan. The numbered items carry only `Task #X` anchors, not the plan
body, so you cannot answer check 6 (is a `missing` task genuinely absent?) or
check 8 (is an `out_of_scope` task really outside the goal?) without reading the
whole artifact. The one-line summary is not a substitute.
## Verdicts
For every item in the input list you MUST choose exactly one verdict:
- **keep** — all checks below pass. The behavioral framing, the plan anchor, and the suggested edit are accurate. Output the item unchanged.
- **modify** — the underlying concern is real and worth surfacing, but one or more details are wrong:
- the plan anchor (`Task #X`) points at the wrong task or at a task that does not exist,
- the suggested edit fixes an adjacent task rather than the one cited,
- the wording duplicates another item under a different label,
- the code citation is paraphrased and does not match the file content verbatim.
Return a corrected version of the item under `Modified-text:`, keeping the same prose shape (behavioral impact → optional note → plan anchor → suggested edit). Do not change the `Group:` value — it must stay identical to the input.
- **drop** — any of the following is true:
- for `missing`: the suggestion is gold-plating (it adds a new task outside the plan's stated scope without a concrete codebase, roadmap, or user-prompt trigger — see check 7), or the task the item proposes is already present in the plan (the upstream agent missed it),
- for `out_of_scope`: the cited task actually IS inside the feature scope after rereading the plan's goal (the upstream agent misjudged it),
- the cited code or task does not exist,
- the concern is a generic "what if someday" speculation with no concrete trigger in the current code or plan.
When in doubt between `modify` and `drop`: if the underlying concern is real and the plan would genuinely be better with some version of this item, prefer `modify`; if you have to invent half of the item to make it fit, choose `drop`.
## Validation questions
For every item, work through these checks before voting:
1. Does the thing mentioned in the item actually exist in the code? If the item includes a code quote, does it match the file content verbatim (whitespace tolerated)?
2. Does the described behavior really follow from this code or this plan, or is it a generic best-practice statement that would apply to almost any project?
3. Can the described problem be triggered by a concrete scenario today, or is it a "someday, maybe" speculation?
4. Does the suggested edit address the behavior described, or does it adjust a neighbouring task?
5. Is the same concern already expressed in another item under a different group? If yes, this is a duplicate — pick the better-worded one and drop or merge the other.
For `missing` items, also check:
6. Is the proposed task actually missing from the plan, or did the upstream agent overlook an existing task that already covers it?
7. Is the proposed task inside the plan's scope, or is it gold-plating (extra work without a concrete trigger)? The user's improvement prompt shown in the project context counts as a concrete trigger — a task that directly fulfills that prompt is NOT gold-plating even if it falls outside the original plan scope, so judge it on accuracy (correct anchor, correct citation) instead. A task only loosely related to the prompt, or unrelated to it, is still gold-plating and judged on scope as usual. When the project context shows `none — bare auto-review`, apply the scope check to every `missing` item.
For `out_of_scope` items, also check:
8. Is the cited task actually unrelated to the feature this plan is about? Reread the plan's stated goal — if the task contributes to that goal directly or indirectly, the upstream agent misjudged it and the item should be dropped.
9. Is the task a reasonable idea for later — useful in itself, just not for this plan? If yes, the framing is correct; judge the item on accuracy like any other. If the task is instead noise — vague, unactionable, or a duplicate of other work — do NOT vote `drop`: dropping an `out_of_scope` item leaves the task in the plan, which is the wrong outcome for noise. The finding is still partly right (the task does not belong in this plan), so vote `modify` and reword the item to plainly recommend removing the task, without the "useful idea for later" framing. You cannot reclassify a finding into the `removals` group; a `modify` kept under `out_of_scope` is the closest correct verdict.
## Output format
For each input item, emit exactly one block. Use the same `### Item N (group: …)` heading you received in the input. The block has four fields, in this order:
```
### Item N (group: missing|improvements|removals|out_of_scope)
Verdict: keep | modify | drop
Group: missing | improvements | removals | out_of_scope
Reason: <one or two sentences — which check failed or what you adjusted>
Modified-text: <corrected item in the same prose shape — REQUIRED when Verdict is `modify`, omit otherwise>
```
Rules:
- The `Verdict` field must contain exactly one of the three tokens: `keep`, `modify`, `drop`. No extra punctuation, no synonyms.
- The `Group` field MUST copy the group label from the input heading verbatim (`missing`, `improvements`, `removals`, or `out_of_scope`). The parent skill uses this to put the item back into the correct emoji section. Do not invent or translate the value.
- `Reason` must reference the validation question(s) that drove the decision, in plain text. Do not output JSON or bullet lists here.
- `Modified-text` MUST appear only with `Verdict: modify`. For `keep` and `drop` omit the line entirely.
- Process items in the same order as the input. Do not reorder, merge, or skip headings.
- Produce one block for every input heading, even if the verdict is `drop`. The parser matches by `### Item N` and considers a missing block a malformed response.
- Do not output anything before the first `### Item N` block or after the last one. No prologue, no summary, no closing remarks.
## Project context
{{PROJECT_CONTEXT}}
## Items to validate
{{ITEMS}}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |