create-spec
Turn a backlog card, a GitHub issue or a free-text idea into a grounded, unrefined requirements.md in specs/unrefined/<name>/, ready for /refine-spec, and sync the card to specced
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- create-spec
- description
- Turn a backlog card, a GitHub issue or a free-text idea into a grounded, unrefined requirements.md in specs/unrefined/<name>/, ready for /refine-spec, and sync the card to specced
- argument-hint
- <MH-n | issue-number | issue-url | "feature description">
03 SKILL.md 正文
Create Spec
Captures an idea as the first document of a spec: specs/unrefined/<name>/requirements.md. It front-loads the context that /refine-spec and /spec would otherwise reconstruct, and it grounds every claim the source makes about the code before anything is built on it.
Input
$ARGUMENTS, one of:
- a backlog card,
MH-<n>, fromproduct/backlog.md; - a GitHub issue of this repository:
123,#123or its URL; - a free-text description of the change.
Invocation contexts
- Slash command: runs every step and writes the requirements file; stops at step 4 when a claim is refuted.
- Model-invoked: the same.
- Non-interactive: the same. A missing input (step 1) or a refuted claim (step 4) ends the run and returns the questions or the refutation as the result; nothing is written. The card sync of step 7 only files approval requests, which needs no pre-approval.
Steps
- Read the source (input step). For a card,
python3 scripts/pm/pm.py show MH-<n>: its Summary and Source are the source, together with its linked issue, read as below. A card that is alreadyspeccedor later has its spec: report the spec its Spec field names and stop. Adroppedcard is an escalation. For an issue, read it withgh issue view <n> --json number,title,body,labels,comments,url. It is read-only; this skill never comments on, labels or edits an issue. For a description, use the text. If$ARGUMENTSis empty, ask for an issue or a description. - Name the spec. Derive a short kebab-case name from the subject, not from the issue number: "Doctor reports state directory usage" becomes
doctor-state-report. - Check for an existing spec.
- For an issue, search every state for a spec that cites it:
grep -rlE "issues/<n>([^0-9]|$)" specs/. For a card, also search for the card:grep -rlE "MH-<n>([^0-9]|$)" specs/. When an issue is linked from a card (python3 scripts/pm/pm.py list --json), proceed as for that card. - Check the name with
scripts/harness/spec-lifecycle.sh resolve <name>, which looks in the working tree and the index. Exit 0 means a spec of that name exists; a refusal naming several copies or an index-only copy is an escalation (.claude/skills/spec-resolution/SKILL.md). - If a spec already covers this issue or subject, report its path and state and stop;
/evaluate-specupdates an existing spec. If only the name clashes with an unrelated spec, append-2and resolve again until the name is free.
- For an issue, search every state for a spec that cites it:
- Ground the premise (
.claude/rules/spec-premise-grounding.md; escalation step). List the load-bearing claims in the source: the mechanism it describes, each file or behaviour it cites, whether the failure is reachable today, and whether an acceptance check could be made to fail today. Open the source for each and record one verdict:HOLDS,PARTIAL(write down the drift),REFUTEDorUNVERIFIABLE.- Any
REFUTED: stop. Write nothing. Report the claim, the source that refutes it (file:line), and a corrected statement the author can put in the issue. UNVERIFIABLE: carry it into Open Questions.- Failure not reachable: the spec either binds its criteria to a path that can fail today or sequences behind the blocker; say which under Dependencies.
- Optional second reader (advisory): when a vendor is available, run
/vendor-consultwith thepremise-groundstage on the same claims (knowledge/vendors.md). Your verdicts govern; where the vendor disagrees, re-open the source before keeping yours. Anunavailableresult is recorded and skipped.
- Any
- Gather engineering context.
knowledge/invariants.mdand the current master-spec sections the change touches (resolve the revision throughdocs/spec/README.md).knowledge/domains.md: the domains and agents the change will involve.- Decision records under
docs/decisions/in the same area. - Specs in
specs/in-progress/andspecs/todo/that touch the same packages (possible conflicts), and inspecs/done/that this extends or supersedes. - Name the packages and files involved; leave exact signatures to
/spec's investigation.
- Write
specs/unrefined/<name>/requirements.md, followingknowledge/spec-authoring.md§ requirements.md, with these additions for an unrefined spec:- a status line under the title:
> Unrefined. Run /refine-spec <name> before /spec.; ## Context: a- **Backlog card**: MH-<n>line when the source is a card (the lifecycle sync finds the card through it), the issue link (or "from a description"), the problem in two to four paragraphs, and the grounding verdicts from step 4, one line per claim;- rough
FR-N/AC-N.Mcriteria, already tagged with invariant, gate and section IDs where known; ## Open Questions(each with what it blocks and the options),## Dependencies(prerequisite, conflicting and superseded specs) and## Impacted components(packages and files, cited).
- a status line under the title:
- Sync the card (card sources only). Run §Lifecycle sync of
.claude/skills/pm-sync-core/SKILL.mdfor<name> --to specced, passing the step 4 verdicts as--premise "<date> — <claim> HOLDS; …". It files the card's status change for a maintainer's approval and never writesproduct/itself. For a description or an issue that no card links, suggest/backlog addin the report instead. - Report.
Output
Created: specs/unrefined/<name>/requirements.md
Source: <issue URL | description>
Card: MH-<n> → specced (requests <ids>) | none (suggest /backlog add)
Grounding: <N> claims, <n> HOLDS, <n> PARTIAL, <n> UNVERIFIABLE
Requirements: <N> FRs, <N> acceptance criteria; open questions: <N>
Next: /refine-spec <name>
Or, when stopped at step 4: the refuted claims with their source evidence and the proposed correction, and no file written.
04 同仓库更多 Skills
mythhelm-deliver-backlog
Coordinate a MYTHHELM backlog run with the shared stage checks and maintainer checkpoints.
mythhelm-bootstrap
Orient a Grok Build session in the MYTHHELM repository before task or spec work.
vendor-consult
Run one advisory stage consult (premise-ground, spec-validate, task-review, change-review, stuck-oracle, dossier) with an optional external vendor, then adjudicate the answer at its anchors
update-docs
Bring README, docs/, knowledge/, WORKFLOW.md and CLAUDE.md in line with what a shipped spec or a merged change actually did — find every statement the change made stale, fix it where readers look, and add only the new facts they need
triage
Score an idea or a GitHub issue against the master spec's stages, gates and commitments, check it for duplicates, and recommend whether it becomes a backlog card; read-only
test-driven-development
Red-green-refactor for Go — use when implementing any feature, bug fix or behaviour change, before writing implementation code