diff-minimizer

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

Use this 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.