# Refine

> Refine Spec

- Skill: `latere-ai/refine` (Agent Skill)
- Install (CLI): `npx skillmds@latest add latere-ai/refine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latere-ai/refine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: latere-ai (https://skillmd.com/u/latere-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/latere-ai/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