mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Clay Good
9b17c537c5
The first draft read #1834's "draft, not interrogate" literally and turned it into a contract: a scenario requiring the skill to ask only what it cannot infer and to show one complete draft rather than a sequence of questions. That forbids the thing most worth doing. A vague issue filed instantly is not cheaper than a good one filed a minute later — it is the same work, moved to a maintainer and made harder by the missing context. Split the contract by what the skill is asking about: - Facts are the skill's job to find. The version, the platform, the failing command, the agent and model are all observable, and asking for any of them is the interrogation users actually resent. This half of "draft, not interrogate" survives as a prohibition. - Judgements are the user's. What the report is really asking for, who it affects, what it excludes, whether the reported problem is the problem or a symptom. Each question carries a recommended answer so agreement costs a word, and questions are ordered by dependency so none is asked before the decision it rests on. Refinement ends by exhaustion rather than at a fixed count, and asking nothing at all is a valid outcome. The spec fixes the ordering rule and the recommendation, not the cadence, so the question technique can improve without a spec change. Also records why refinement cannot live in the CLI (a fixed question list asks a crash and a papercut the same five things), and why the skill has to stay one file: generateSkillContent returns a single string and every adapter writes one SKILL.md, so the progressive disclosure current skill-authoring practice assumes is not available without its own proposal. Leanness is therefore a constraint — explain the reasoning instead of stacking capitalised MUSTs, and phrase instructions positively. Part of #1834 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>