paqad-ai/runtime/base/skills/diff-minimizer/SKILL.md

Spec-driven development framework — AI agents that think before they type

---
name: diff-minimizer
description: 'Classifies each planned implementation step against the acceptance criteria so scaffolding and over-build are dropped before code is written. Use when a graduated or full lane change sits between acceptance criteria and the solution write-up.'
metadata:
  model_tier: reasoning
  cacheable: 'false'
  output_format: markdown
  paqad-meta: skill.meta.yaml
---

## What It Does

Evaluates a proposed implementation outline step-by-step against the acceptance criteria. Classifies each step as `ac-satisfying`, `necessary-setup`, `scaffolding`, or `over-build` and recommends which scaffolding and over-build steps to drop before any code is written.

The goal is to move scope-creep detection upstream from post-implementation review into the planning phase.

## Use This When

Between `acceptance-criteria-gen` and the Story Designer's solution write-up, in the graduated and full lanes. Skip in the fast lane: the overhead is not justified for low-complexity work.

## Inputs

- Read the acceptance criteria artifact first; identifiers must be `AC-{fr}.{n}` so each step's mapped AC is unambiguous.
- Read the proposed solution outline (steps, files to modify, abstractions introduced).
- Read canonical module docs at the module paths listed in `module_doc_paths`. Patterns declared there are project conventions and cannot be classified as `over-build`.
- Read `references/classification-guide.md` before assigning any classification so the rubric stays consistent.

## Procedure

1. Run `scripts/extract-ac-ids.sh <ac-file>` to load the canonical AC id set; cross-check every cited id against this set.
2. Parse the proposed solution into discrete steps (one new file, one function, or one significant edit each).
3. Classify each step using `assets/classifications.txt` (`ac-satisfying`, `necessary-setup`, `scaffolding`, `over-build`).
4. For `scaffolding` / `over-build` steps, propose a leaner alternative or deletion.
5. List ACs with no satisfying step under `### Open Questions` (or write the literal `Open Questions: none`).
6. Format per `assets/output.template.md`; validate with `scripts/lint-output.sh`.

## Output Contract

- Return a heading named `Diff Minimization`.
- Provide a `Step Map` table with columns `#`, `Step`, `Classification`, `Mapped AC`, `Action` where:
  - `#` is the 1-based step index from the proposed solution.
  - `Classification` is exactly one of `ac-satisfying`, `necessary-setup`, `scaffolding`, `over-build`.
  - `Mapped AC` is the AC id when the step is `ac-satisfying`, the dependent step number when `necessary-setup`, and `-` otherwise.
  - `Action` is `keep` for `ac-satisfying` and `necessary-setup`, or `drop: <one-line reason>` for `scaffolding` and `over-build`.
- Provide a `Recommended Drops` section listing dropped step numbers with a one-line reason each.
- Provide a `Necessary Setup (justified)` section listing setup steps and the dependent step numbers.
- End with `Open Questions` listing AC ids with no satisfying step, or `Open Questions: none` exactly.

See `assets/output.template.md` for the canonical shape; the lint script enforces it.

## Escalate / Stop Conditions

- Ask when a step's classification depends on a product decision (e.g., whether a validation rule is required or polish).
- Warn when removing a `scaffolding` step would silently remove error handling the spec implied but did not state: flag for the requirement analyst rather than auto-drop.
- Do not classify a step as `over-build` if the canonical module docs at any provided path declare that abstraction as project convention.
- Do not invent AC ids; cross-check every cited AC id against the acceptance criteria artifact and emit unknown ids under `Open Questions`.

## Resources

- `references/classification-guide.md`
- `scripts/extract-ac-ids.sh`
- `scripts/lint-output.sh`
- `assets/output.template.md`
- `assets/classifications.txt`
- `agents/openai.yaml`