refine

name	refine
description	Use when the user prompts "refine design".

Run an interactive refinement session for an existing feature design document.

This command is for clarifying and tightening a proposal that already exists. It is not a one-shot rewrite. The workflow may span multiple user turns.

The normal behavior is:

• read the proposal carefully
• identify what looks unclear, ambiguous, or under-specified
• discuss questions with the user
• record only user-confirmed questions in a ## Refinement section
• record only user-confirmed conclusions under those questions
• keep the main design above ## Refinement synchronized with every confirmed conclusion

Input

This workflow can start in two ways:

1. Directly from the user

   The prompt argument should identify:

   • a feature or change folder
   • an idea number or idea title
   • optionally, a file name to refine

   If the user does not specify a file, default to:

   changes/<feature-name>/<NUMBER-idea-name>/selected-variant.md

   Examples:

   • /refine 611-row-level-security-integration 2
   • /refine row-level-security-integration "Run work inside an explicit RLS context"
   • /refine row-level-security-integration 2 variants.md

2. From another workflow

   If the calling workflow already knows the input file, use that file directly instead of re-resolving it.

   By default, update that same file in place.

   Only write to a different output path when the caller or the user explicitly instructs you to do so.

Goal

Make the design document more reliable for later work by resolving important questions collaboratively and keeping both:

• the main design
• the refinement log

in sync throughout the session.

The refinement log is part of the artifact. It should help a later reader understand which questions mattered and what was decided.

Steps

1. Resolve the input file

   If another workflow already provided the input file path, use it.

   If the user initiated the workflow directly:

   • find the best matching folder in changes/
   • resolve the idea folder inside changes/<feature-name>/
   • default the input file name to selected-variant.md unless the user specified another file

   Matching rules:

   • prefer an exact change-folder match
   • prefer an exact idea number match from folders such as 2-run-work-inside-an-explicit-rls-context
   • otherwise match the idea title against the folder suffix or ideas.md

   If multiple folders or ideas are plausible, ask one focused clarifying question. Do not guess.

   If the resolved input file does not exist, stop and tell the user. Do not create the starting design file in this command.

2. Read the proposal and supporting context

   Read the full input file before commenting on it.

   Understand:

   • the goal
   • the proposed approach
   • the explicit assumptions
   • what is still implied rather than stated
   • which statements depend on existing orchid-orm behavior or external facts

   Read only the extra context that is needed to understand or verify the design:

   • relevant orchid-orm docs in docs/src/.vitepress/dist/llms.txt
   • external sources when needed for technical accuracy or when the user asks you to research

   When researching online, prefer official docs and trustworthy primary sources.

3. Ensure the document has a refinement section

   If the input file does not already contain ## Refinement, append an empty ## Refinement section at the end of the file immediately.

   If ## Refinement already exists, preserve it and continue working inside it.

   There must be exactly one top-level ## Refinement section in the final document.

4. Give the user your initial assessment

   After you understand the proposal, tell the user:

   • whether the design looks clear overall
   • which parts seem ambitious, risky, vague, or incomplete
   • whether anything important appears to be missing

When all tracked questions are answered, make sure the document is coherent as a whole.

The refinement log should still remain in the file unless the user explicitly asks to remove it.

Quality check

Before finishing, verify:

• the correct input file was chosen
• direct invocations defaulted to selected-variant.md unless the user chose another file
• delegated invocations used the already-known input file unless explicitly told otherwise
• the full proposal was read before assessment
• ## Refinement exists exactly once
• proposed questions were not written unless the user confirmed them
• duplicate questions were not added
• every recorded answer was user-confirmed
• every recorded answer includes the conclusion and why or supporting basis when available
• temporary options or notes were replaced once a final answer was recorded
• the design above ## Refinement was updated after each confirmed conclusion
• the main design and the refinement log do not contradict each other

Guardrails

• Do not invent questions and silently write them into the log
• Do not answer ergonomics decisions on the user's behalf
• Do not leave the main design stale after recording a confirmed answer
• Do not rely on memory for technical claims that should be checked in code, docs, or official external sources
• Do not dump raw research notes into the document
• Do not remove earlier refinement history unless the user asks
• Do not create the initial proposal file here if it does not already exist
• Ask a focused clarifying question whenever the target change, idea, or file is ambiguous