Wf Spec Refine

Refine Spec

Update a spec file so it accurately reflects the current state of the project. Remove work that is already done, update partially-done items, and revise descriptions to match what actually exists in the codebase.

Step 0: Parse arguments

$ARGUMENTS has the form: <spec-file.md> [feedback...]

• The first token is the spec file path (e.g., specs/windows-support.md).
• Everything after the first token is feedback — free-form instructions from the user that guide the refinement. Feedback may request specific changes such as: removing certain sections, rewriting scope, changing priorities, splitting or merging items, adding new items, or adjusting tone/structure.

If feedback is present, apply it in addition to the standard codebase audit below. Feedback takes precedence over the default rules when they conflict (e.g., if feedback says "keep the done items as a checklist", do that instead of removing them per rule 3a).

Step 1: Read the spec

Read the spec file identified in Step 0. Parse YAML frontmatter to extract title, status, depends_on, affects, effort, created, updated, author, dispatched_task_id.

Note the current lifecycle state — this guides the refinement:

• vague → focus on fleshing out design, adding detail
• drafted → focus on accuracy, removing done items, updating references
• validated → focus on keeping the spec in sync with implementation reality
• complete → the spec should not normally need refinement; if it does, it may need to move to stale
• stale → the primary goal is to refresh the spec; may transition to drafted or validated after refinement

Parse the body into a list of proposed work items, features, or changes. For each item, note:

• What it proposes (the deliverable or change)
• Any acceptance criteria or sub-tasks
• Its stated priority or tier

Step 2: Audit each item against the codebase

For every item in the spec, determine its current status by searching the codebase. Use Grep, Glob, and Read to find evidence. Launch Agent subagents in parallel for independent items to speed this up.

Classify each item as one of:

• Done — fully implemented and working. Evidence: code exists, tests pass, docs updated.
• Partially done — some sub-tasks complete, others remain. Note exactly which parts are done and which are not.
• Not started — no evidence of implementation in the codebase.
• Obsolete — the item is no longer relevant due to architectural changes, new dependencies, or revised project direction.

For each classification, record the specific files, functions, tests, or commits that serve as evidence.

Step 3: Rewrite the spec

Apply these rules:

3a. Remove done items

Delete items that are fully implemented. Do not leave them as "completed" checkboxes — they clutter the spec. If the done work is context for remaining items, mention it briefly in a "Current State" or "Already Implemented" summary section at the top (keep this concise — a few bullet points, not a full recap).

3b. Update partially done items

For items that are partially complete:

• Strike or remove the finished sub-tasks
• Update descriptions to reflect the current starting point (e.g., "Add path translation" becomes "Add Windows drive-letter translation in ContainerSpec.Build(); runtime detection and mount-option filtering are already implemented")
• Update file/function references if they have changed

3c. Keep not-started items

Retain these, but revise their descriptions if the surrounding code has changed since the spec was written (new function names, moved files, changed APIs).

3d. Remove obsolete items

Delete items that no longer apply. If the reason for obsolescence is non-obvious, add a one-line note explaining why it was removed.