--- name: refine-with-docs description: Help a user refine an idea, plan, requirements, process, or draft through focused questions, concrete scenarios, and evolving documentation. Use when the user wants an iterative refinement interview with written outcomes; direct edits and factual questions do not require this workflow. metadata: version: 1.0.0 updated: 2026-10-14 status: stable --- # Refine with docs ## Overview Help the user turn an unclear or incomplete subject into a useful, documented result. Combine an adaptive interview with evidence checks and revisions as answers arrive. Apply this to everyday plans, proposals, requirements, policies, creative briefs, operating processes, and technical designs as well as skills. Keep the interview proportional to the decision. Seek enough clarity for the user's next step; deferred choices may remain open. Use constructive challenge with concrete consequences rather than exhaustive interrogation. This package is self-contained and does not require other interview or documentation skills. ## Steps 1. **Identify the outcome.** Establish the subject, audience, intended result, constraints, and what the user needs to do next. Reuse information already supplied. If the subject is missing, ask for it first. Read the provided material and relevant existing instructions before asking detailed questions. If the request is already precise, make the requested refinement directly. 2. **Choose the working document.** Use the user's existing document and format when suitable. Otherwise create a concise working note in the established project or personal documentation location once the subject is known. If no destination is available, keep a clearly labeled working draft in the conversation and state that it has not been saved. Follow the host's artifact workflow for the chosen format. Keep private evidence in the user's store; never copy it into a public workflow package. Create documents only when they have content, and avoid parallel copies of the same current decisions. 3. **Map what remains unclear.** Separate established facts, the user's explicit decisions, candidate interpretations, and open questions. Check source material for authorship and intent: an agent-generated example, inherited process, or current implementation is evidence, not automatic endorsement. Look up accessible facts independently. State contradictions between sources and the user's account, and establish whether they describe current behavior or a desired change. Do not silently merge conflicting claims. 4. **Ask a focused round.** Select the smallest useful set of questions whose prerequisites are settled, usually one to three. Prioritize decisions that change the outcome, cost, scope, or ability to proceed. Include a recommendation and its practical consequence where there is a real choice, while leaving room for the user's own answer. Wait for answers before making dependent decisions. Research and document independent findings while waiting; elapsed time or silence does not confirm a proposal. 5. **Test answers with examples.** Turn abstract preferences into a concrete situation: who does what, with which inputs, producing what result? Probe a relevant failure, exception, or competing priority. Use a small example, sketch, sample passage, or reversible experiment when it would resolve an uncertainty faster than more questions. Confirm what the example establishes and what remains uncertain. Avoid turning a local choice into a universal rule or treating the assistant's recommendation as the user's answer. 6. **Revise as decisions settle.** Update the working document after each round with accepted decisions, reasons, examples, and remaining questions. Preserve useful source references and distinguish user decisions from observations and proposals. Use the user's terminology and clarify ambiguous terms when they affect the result. Add a glossary only when shared vocabulary needs one; use a formal decision record only when an enduring trade-off warrants it. Prefer a readable current draft over a verbatim interview transcript. 7. **Reassess and finish at a useful point.** Recompute the remaining questions from the latest answers. Continue while uncertainty blocks the agreed next step. Stop when the result is usable, the user asks to pause, or further questions would only expand scope. If something remains unresolved, record its impact and next action rather than claiming agreement. Summarize the refined result, document location, decisions, and outstanding issues. Carry forward explicit approvals without requiring a blanket final confirmation. Refining a plan does not itself authorize executing it or publishing it. ## Working document Adapt the existing document rather than forcing a template. For a new note, use only the following parts that help the reader: - **Purpose and success:** the intended outcome, audience, and observable result. - **Current draft:** the refined plan, requirements, process, or other artifact. - **Accepted decisions:** the choice, reason, and relevant evidence or scenario. - **Proposals and open questions:** unsettled choices, dependencies, and impact. - **Next step:** what can happen now and what needs an answer first. Record enough context to resume after an interruption. Keep interview evidence separate from an authoritative artifact when mixing them would confuse accepted requirements with unfinished discussion. Promote only accepted content into that artifact, within the user's authorized editing scope. ## Examples > Help me refine a volunteer event plan and keep the plan updated as we talk. Read the draft, clarify the intended attendance and success criteria, then work through responsibilities, scheduling, and realistic contingencies in focused rounds. Capture accepted choices and unresolved constraints in the event plan. > This handover process keeps failing. Help me improve it with written outcomes. Inspect the current process and available examples. Distinguish observed failures from assumed causes, walk through a missed handover, and refine ownership and completion criteria. Document proposed changes separately from accepted ones. > Help me clarify my writing preferences from these mixed-author drafts. Ask which passages the user endorses and test candidate preferences against contrasting examples. Record confirmed choices without attributing every passage to the user. Packaging those choices as a skill is a separate authoring step. ## Completion checks - The refined result serves the stated audience and agreed next step. - Relevant evidence and authorship were checked; facts, decisions, proposals, and unresolved questions remain distinguishable. - Questions followed their prerequisites and did not reopen settled choices. - Concrete examples tested consequential ambiguities at an appropriate depth. - Documentation reflects the latest answers and can support resuming the work. - The saved location or unsaved status, remaining uncertainties, and next action are explicit. No deferred choice is presented as agreement. - Editing, execution, and publication remain within the user's requested scope.