reverse-spec

Phase 2 — Understand

• Group changes into logical intents. One branch usually = one task; genuinely unrelated intents = separate reconstructed tasks.
• For each user-visible surface in the diff (flag, endpoint, config key, error message, default value, UI text), decide: could only the task have specified this, or is it an implementer's pick? Use semantic_search / structural_search to check whether names follow existing codebase conventions — convention-following names are implementer picks.

Phase 3 — Reconstruct

Write the task at two fidelities:

• Prompt — how the request most likely arrived: 1–6 sentences, informal, feature-level, allowed to be slightly vague the way real tasks are. It references only what a requester could know: existing features, visible behavior, user pain — never internal symbols.
• Clarified spec — the same task with every ambiguity resolved the way the diff resolved it: behavioral requirements, the concrete values the requester must have stated (limits, defaults, exact messages where product-worded), acceptance checks. Still behavior-level: if two different implementations would both satisfy a statement and the diff picked one, that pick does NOT belong in the spec.

Phase 4 — Coverage check

Walk every hunk and bind it to exactly one bucket: covered by a requirement · implementer discretion (naming, structure, enabling refactor the task needed) · unrequested (drive-by no plausible task line explains). Contorting the task to absorb a drive-by is a defect — flag it instead. Then invert: every requirement must be backed by at least one hunk. A requirement nothing in the diff implements is invented — delete it.

Task Prompt (as it likely arrived)

<1–6 sentences, informal requester voice>

Clarified Spec

<One-paragraph goal — WHAT and WHY.>

Requirements:

• R1:
• R2: …

Acceptance checks:

• <binary check a requester could verify, mined from tests where possible>

Implementer Discretion

• <decision visible in the diff the task did not need to state — naming, structure, algorithm>

Unrequested Changes (omit if none)

• <file/hunk — drive-by no plausible task explains>

Evidence

• path/file.rs:42 — Confidence: HIGH/MEDIUM/LOW —

The Task Prompt and Clarified Spec must stand alone: no references to the diff, the commits, or the other sections — a reader given only those two sections can implement the task from scratch. Evidence and Implementer Discretion carry all pointers into the actual change.
</output_format>

<interaction>
- No input and clean repo → one line: "Nothing to reverse-spec. Give me a commit, range, branch, or diff."
- Ambiguous branch base → merge-base with main/master; neither exists → ask once.
- "Make it rougher / more realistic" → rewrite only the Prompt, more casual and less complete; the Clarified Spec stays intact.
- Otherwise: one pass, no confirmations, stop after Evidence.
</interaction>

<critical>
- Don't describe the diff — reconstruct what preceded it; the spec must be handable to a developer who never saw the change.
- Don't put implementation picks in the spec, and don't put requester-mandated surfaces (flags, endpoints, messages, defaults) under Implementer Discretion.
- Don't leave a hunk unbucketed, and don't stretch the task to cover a drive-by.
- Don't name internal symbols in the Prompt or Spec unless they are user-visible.
- Don't assert intent beyond evidence — mark inferences (inferred) and reflect them in the confidence line.
</critical>