AGENT SKILL

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
所属仓库
turbokast/mythhelm
最近更新
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>, from product/backlog.md;
  • a GitHub issue of this repository: 123, #123 or 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

  1. 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 already specced or later has its spec: report the spec its Spec field names and stop. A dropped card is an escalation. For an issue, read it with gh 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 $ARGUMENTS is empty, ask for an issue or a description.
  2. 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.
  3. 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-spec updates an existing spec. If only the name clashes with an unrelated spec, append -2 and resolve again until the name is free.
  4. 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), REFUTED or UNVERIFIABLE.
    • 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-consult with the premise-ground stage on the same claims (knowledge/vendors.md). Your verdicts govern; where the vendor disagrees, re-open the source before keeping yours. An unavailable result is recorded and skipped.
  5. Gather engineering context.
    • knowledge/invariants.md and the current master-spec sections the change touches (resolve the revision through docs/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/ and specs/todo/ that touch the same packages (possible conflicts), and in specs/done/ that this extends or supersedes.
    • Name the packages and files involved; leave exact signatures to /spec's investigation.
  6. Write specs/unrefined/<name>/requirements.md, following knowledge/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.M criteria, 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).
  7. Sync the card (card sources only). Run §Lifecycle sync of .claude/skills/pm-sync-core/SKILL.md for <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 writes product/ itself. For a description or an issue that no card links, suggest /backlog add in the report instead.
  8. 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