task-specification
Turn a repository change request into a grounded, actionable task with a clear outcome and verifiable acceptance criteria. Use when asked to draft or complete a new or sparse issue, ticket, story, bug report or epic; use task-review to assess existing work-item text.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- task-specification
- description
- Turn a repository change request into a grounded, actionable task with a clear outcome and verifiable acceptance criteria. Use when asked to draft or complete a new or sparse issue, ticket, story, bug report or epic; use task-review to assess existing work-item text.
02 资源文件 7
- 参考文档examples/bug-task.md1.9 KB
- 参考文档examples/feature-task.md2.1 KB
- 参考文档examples/fill-existing-issue.md2.0 KB
- 参考文档examples/split-epic.md1.4 KB
- 参考文档references/task-quality.md4.6 KB
- 参考文档references/task-template.md2.6 KB
- 参考文档skill.yaml737 B
03 SKILL.md 正文
Task specification
When to use
When a request, idea, bug report or epic must become work items someone can implement,
or when an item already exists with only a title or a few lines and must be filled in.
To judge a task that is already written use task-review. To plan the implementation of a
task that is already specified use feature-development or the workflow for its type.
Required context
None is required. Read what exists: the product and domain context for vocabulary and users, the feature map to locate the affected area, the architecture context for boundaries, and the verification profile to know which checks could prove a criterion. Where a context area is absent, fall back to the code and say so in the task.
Preconditions
- The request says, or the user can say, what should change for whom. If the expected result is unclear, ask one question about it before drafting.
- To fill in an existing item, its current text is available: read through a tracker integration when the user gives a link or identifier and the agent has one, or pasted by the user. Otherwise ask for it.
- The request concerns this repository. If the code it describes is elsewhere, say so and write only what the repository can support.
Procedure
- Start from what exists. For an existing item, read its title, body, labels and
comments; what they say is input, kept unless the repository contradicts it. Choose
the template as
references/task-template.mdsays (addendum, then the repository's own issue template, then the default) and tell the user which one applies. - Classify the request as one of the types in the template: Feature, Bug, Improvement or Technical debt, or the template's own equivalents.
- Clarify only what changes the task: who is affected, the expected result, and, for a bug, how to reproduce it. Ask one question at a time and never ask what the repository answers. When the repository shows several plausible readings, offer them as short options, with the one the code favors first, and let the user choose.
- Ground it in the repository. Locate the affected area with
core.repository.structureand read it withcore.repository.files; activatecontext-discoverywhen the area is unfamiliar. Find the sibling that does something similar and the rules and boundaries that apply. For a bug, confirm the described flow exists in the code. Record each premise the repository contradicts, and each it cannot confirm, before writing. - Size it with the split criteria in
references/task-quality.md. When the request is too large, propose vertical slices: one task per independently usable outcome, ordered, with dependencies stated and the uncertain part first. - Write each task in the chosen template. Acceptance criteria are observable conditions, one per line, including the failure cases the request implies and what must keep working. Nothing enters the text that the user, the item or the repository did not supply: a missing fact becomes an open question, never a plausible guess.
- Check each task against
references/task-quality.mdand fix what fails. Every criterion must name how it would be verified, even when that is a manual check. - Show it in the preview, not in the chat. Write every draft, including a single
short task, as Markdown under
.paved/generated/tasks/: the text ready to paste, then the contradicted premises and open questions. One task is one file; split tasks go in one folder, one file per task plus an overview with their order and dependencies, so the reviewer moves between them. Open the file or folder withpaved preview start <file-or-folder> --jsonand give the user the URL with a summary of at most three lines; do not print the draft in the chat. Follow the preview loop in the workflow instructions: keep waiting, apply each comment to its file and resolve it with a reply, until the user says the review is finished. Print the full text in the chat only when the user asks for it or the preview cannot start, and then say why. - Ask to write. The preview approves nothing: ask in the chat whether to create or update the items, naming them. Only after an explicit yes, and only when a tracker integration is available, create new items or replace the existing item's body. Never change its title, state, assignee or labels unless the user asked for it.
Tools
core.repository.structure to find the affected area and its siblings;
core.repository.files to read the code, context and rules the task depends on. A
tracker integration, when the agent has one, is used only after the user confirms.
Rules
core.quality.unknowns-stay-unknown governs steps 4 and 6: a fact the repository and the user
do not support becomes an open question in the task. core.architecture.follow-existing-patterns
decides which sibling the technical context points at.
Verification
The skill changes no code, so no check is required. Each acceptance criterion states how it would be verified, so whoever implements the task can plan its proof.
Evidence
None required. The delivered tasks list the repository sources that informed them.
Completion criteria
- Every task has a type, description, expected result and acceptance criteria.
- Every acceptance criterion is observable and names how it would be verified.
- Every path, component or endpoint named exists in the repository or is marked as new.
- A bug has steps to reproduce with a starting state, actual and expected result.
- A request too large for one task is delivered as ordered, independently usable tasks.
- Contradicted premises and open questions are listed, not silently resolved.
- An existing item keeps its author's content unless the repository contradicts it, and
the template used is the one the precedence in
references/task-template.mdselects. - The draft was presented in the preview, or the reason it was not is stated.
- Nothing was written to the tracker without the user's confirmation.
Failure modes
| Failure | Signal | Response |
|---|---|---|
| Invented grounding | A path or component in the task is not in the repository | Remove it or mark it as new |
| Solution posing as outcome | Expected result describes code, not behavior | Restate what the user or system observes |
| Horizontal split | Tasks named after layers that cannot ship alone | Re-slice by outcome |
| Guessed requirement | A criterion no one asked for and the code does not imply | Turn it into an open question |
| Code lives elsewhere | The request names flows this repository does not contain | Say so; specify only what this repository can support |
| Draft dumped in the chat | The task text was printed instead of previewed | Write it to the file, open the preview, reply with the URL |
| Filler content | A section holds text no source supports, just to look complete | Replace it with an open question or omit the section |
| Ignored template | The repository has its own issue template and the task uses the default | Rewrite it in the repository's template |
| Template conflict | The project addendum and the template disagree | Follow the addendum |
References
references/task-template.md: which template applies, sections, types and omissions.references/task-quality.md: quality bar, verifiable criteria, split criteria and grounding.examples/feature-task.md,examples/bug-task.md,examples/split-epic.md: synthetic results.examples/fill-existing-issue.md: a sparse existing item filled in the repository's own template.
04 同仓库更多 Skills
sample-skill
Does a sample task. Use when a sample is needed.
unexplained-contract
Does a sample task. Use when a sample is needed.
shell-block
Does a sample task. Use when a sample is needed.
project-identifier
Does a sample task. Use when a sample is needed.
oversized
Does a sample task. Use when a sample is needed.
no-activation
Does a sample task.