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.

3e. Update metadata

• Update frontmatter fields:
  • updated → set to today's date
  • status → adjust if warranted (e.g., stale → drafted after refresh, complete → stale if significant drift found)
  • affects → add or remove paths to match what the spec actually describes
  • depends_on → add or remove entries if dependencies have changed
  • effort → re-estimate if scope changed significantly
• Fix file paths, function names, and code references in the body to match the codebase
• Ensure the spec's title and introduction still accurately describe the remaining work

3f. Apply user feedback

If feedback was provided in $ARGUMENTS (see Step 0), apply it now. Feedback may include directives such as:

• Add items: Add new work items the user describes; audit the codebase to fill in status, effort, and file references just like existing items.
• Remove/drop items: Remove specific items the user no longer wants, regardless of their codebase status.
• Reprioritize: Change the ordering, effort estimates, or dependencies.
• Restructure: Split, merge, rename, or reorganize sections.
• Scope changes: Narrow or expand what the spec covers.
• Style/tone: Rewrite prose to match a requested voice or level of detail.

When feedback conflicts with rules 3a–3e (e.g., "keep done items visible"), follow the feedback. When feedback is ambiguous, make a reasonable choice and flag it in the Step 5 summary.

Step 4: Write the updated spec

Use Edit (preferred) or Write to update the spec file in place. Preserve the original markdown style (heading levels, list format, code fence style).

Step 5: Summary

Report to the user:

• How many items were removed (done)
• How many items were updated (partially done)
• How many items remain unchanged (not started)
• How many items were removed as obsolete
• Any items where the status was ambiguous and you made a judgment call

Guidelines

• Always READ actual source code — never classify items based on memory or assumptions about what "should" exist
• When in doubt about whether something is "done", check for both the implementation AND tests/docs. Code without tests may be partially done.
• Preserve the spec's voice and structure — this is a refinement, not a rewrite from scratch
• Do not add new items to the spec unless the user explicitly asks
• If the spec references external systems (CI, release pipelines, etc.), check those too (e.g., read workflow YAML files for CI items)
• Keep the refined spec actionable — every remaining item should clearly state what needs to be built or changed