refine-spec

refine-spec: Specification Refinement Through Dialogue

Core Philosophy

The provisional specification is NOT the true specification. The true specification lives in the user's mind—as intentions, assumptions, and constraints they've never fully articulated. This skill surfaces it through structured dialogue.

Key insight: Every difference between code behavior and user intent is a "Finding"—the most valuable output of this process. We're not validating the provisional spec; we're using it as a scaffold to uncover what was actually intended.

---

Workflow Overview

Provisional Spec (from extract-spec)
    ↓
[STEP 1] Translate to natural language
    ↓
[STEP 2] Structured dialogue by category
    ├─ A: Questions (code seems wrong)
    ├─ B: Implicit specs (inferred from tests)
    ├─ C: Missing specs (no code exists)
    └─ D: Provisional confirmations (routine items)
    ↓
[STEP 3] Classify each dialogue result as Finding
    ↓
[STEP 4] Generate confirmed spec from Findings
    ↓
[STEP 5] Check convergence (all tagged items resolved)
    ↓
[STEP 6] Generate Findings Report (structured output)

---

STEP 1: Natural Language Translation

Purpose

Transform VDM-SL abstractions into plain language the user can evaluate without training in formal methods.

Process

1. Extract elements from provisional spec:

   • State space (data structures, invariants)
   • Operations (pre/post conditions, behavior)
   • Rules and constraints
   • Implicit assumptions from tests/comments

2. Translate each element into plain English + Japanese:

   • Avoid formal syntax; use concrete examples
   • Group related items logically
   • Include type information but keep language accessible

3. Tag each item with confidence and source:

   [PROVISIONAL] {confidence: high|medium|low} {source: code|tests|comments}
   
   Example:
   [PROVISIONAL] {confidence: high} {source: code}
   When a customer requests a refund, their account balance increases by the refund amount.