// Rules and checklist for creating work items on GitHub Issues or Azure DevOps. Use when you need to create issues, user stories, tasks, epics, or features on the board. Do not use for platform configuration (use board-config), managing workflow of existing tasks (use work-item-workflow), or for comments on work items.
Implementation finalization with PR. Use when implementation is complete and you need to commit, push, or open a pull request. Includes automated reviews and technical debt tracking. Do not use during implementation (use devsquad.implement), for standalone intermediate commits (use git-commit), or for branch creation (use git-branch).
Formatting and style rules for markdown documentation. Use when generating or editing any project markdown document. Do not use for source code, code comments, or commit messages. For work item content (titles, descriptions, comments on GitHub Issues or Azure DevOps), use the Content Style section of the `work-item-creation` skill.
Capture and consult codebase-specific learnings across the lifecycle. Use when an agent encounters a correction loop, review finding, test prerequisite, or recurring pattern that future sessions should know about. Also use at the start of implement, verify, or review to check for known patterns. Do not use for architecture decisions (use ADRs), for debugging the current failure (use debugging-recovery), or for one-time context that will not recur.
Verify and create SDD Framework configuration files (.github/copilot-instructions.md, instructions, coding-guidelines, markdownlint). Use when initializing a project or checking if configuration files are up to date. Do not use for documentation templates (use init-docs) or community files (use init-scaffold).
Verify and create SDD Framework documentation templates (feature spec, migration spec, envisioning, ADR templates). Use when initializing a project or checking if documentation templates are up to date. Do not use for configuration files (use init-config) or community files (use init-scaffold).
Label-based state machine for triaging issues and work items. Manages state transitions, generates durable triage artifacts, and supports resumable sessions. Use when triaging GitHub issues or Azure DevOps work items. Do not use for creating new work items from scratch (use work-item-creation) or for managing implementation workflow of already-triaged items (use work-item-workflow).
| name | work-item-creation |
| description | Rules and checklist for creating work items on GitHub Issues or Azure DevOps. Use when you need to create issues, user stories, tasks, epics, or features on the board. Do not use for platform configuration (use board-config), managing workflow of existing tasks (use work-item-workflow), or for comments on work items. |
Before creating ANY work item, verify:
.memory/board-config.md to identify GitHub or Azure DevOpsWork items live on the board, get rendered in GitHub/ADO UIs, and are read by humans and agents long after creation. Apply these rules to every title, description, comment, and acceptance criterion.
| Rule | Why | Example to avoid |
|---|---|---|
| No emojis or decorative Unicode (e.g., →, •, ★, ✓, 🎯, ✅, ⚠️, ❌) | Renders inconsistently across boards, screen readers, and exports | 🎯 Goal: ship X |
| No em-dash (—), en-dash (–), or hyphen as separator between concepts | Ambiguous in titles, breaks search, often AI-generated tell. Rewrite the sentence. | Auth flow — refactor → Refactor auth flow |
Never use #<number> in free text | Azure DevOps auto-converts to a work item link, breaking references and creating wrong cross-links. Use "first", "third option", or rephrase. | #1 priority → top priority |
| No contrastive constructions ("not just X, it's Y", "more than just", "goes beyond") | Generic AI framing that adds words without information | This is not just a fix, it's a rethink → Replace the retry logic |
| Direct active voice, no rhetorical questions | Work items are commands or descriptions, not essays | What if we cached responses? We should cache them. → Cache responses for 60 seconds |
| No promotional or exaggerated language | Work items track work, not pitch it | seamless, revolutionary, world-class |
| Keep titles short and concrete; bodies focused on observable behavior | Titles surface in lists; bodies are read once during planning and again during review | See Durability Rules for body content rules |
These rules apply to content sent to GitHub Issues, Azure DevOps work items, board comments, PR descriptions written from a work item, and triage artifacts. They do not replace the markdown rules in the documentation-style skill, which still govern files under docs/**/*.md.
All generated work items must include the tag/label ai-model:<model-name>.
grep -h "Using.*model" ~/.copilot/logs/*.log 2>/dev/null | tail -1
cat ~/.copilot/config.json 2>/dev/null | grep -i model
ai-model:unknownBefore applying labels to a work item, check if they exist in the repository:
github/list_label(owner, repo)
If any required label does not exist, create it automatically via github/label_write:
| Label | Color (hex) |
|---|---|
copilot-generated | 1d76db |
ai-model:* | 5319e7 |
type:user-story | 0e8a16 |
type:task | 0e8a16 |
type:adr | 0e8a16 |
type:tech-debt | d93f0b |
feature:* | c5def5 |
priority:p1 | b60205 |
priority:p2 | fbca04 |
priority:p3 | 0e8a16 |
phase:* | bfdadc |
severity:high | b60205 |
severity:medium | fbca04 |
severity:low | 0e8a16 |
epic | 3e4b9e |
feature | c5def5 |
parallel | d4c5f9 |
blocked | b60205 |
copilot-candidate | 1d76db |
needs-human | e4e669 |
scope:cross-cutting | bfdadc |
scope:feature-scoped | bfdadc |
Cache the list of existing labels to avoid repeated calls during the same creation session.
| Tag/Label | Required | Description |
|---|---|---|
copilot-generated | Always | Identifies item created by AI |
ai-model:<name> | Always | Model used |
| Tag/Label | Required |
|---|---|
type:user-story (GitHub) | Yes |
feature:<name> | Yes |
priority:<p1|p2|p3> | Yes |
| Tag/Label | Required |
|---|---|
type:task (GitHub) | Yes |
feature:<name> | Yes |
phase:<phase> | Yes |
| Tag/Label | Required |
|---|---|
epic (GitHub) | Yes |
| Tag/Label | Required |
|---|---|
feature (GitHub) | Yes |
priority:<p1|p2|p3> | Yes |
| Tag/Label | Required |
|---|---|
type:adr | Yes |
scope:cross-cutting or scope:feature-scoped | Yes |
feature:<name> | Yes (if feature-scoped) |
| Tag/Label | Required |
|---|---|
type:tech-debt | Yes |
severity:<high|medium|low> | Yes |
feature:<name> | No (optional) |
| Label | Usage |
|---|---|
parallel | Parallelizable task |
blocked | Task with unresolved dependencies |
copilot-candidate | Task delegable for autonomous agent execution |
needs-human | Task requiring human judgment, access, or approval |
[<feature>] <description>[Epic] <name>[Feature] <name>[ADR] <domain> or [<feature>][ADR] <domain>[Tech Debt] <description>NEVER create duplicate work items. If a similar item already exists, skip it and record it in the report.
Work items live longer than the code they reference. File paths, line numbers, and commit SHAs rot as the codebase evolves. Write descriptions that remain useful after major refactors.
| Do | Do not |
|---|---|
| Describe behavior and symptoms in domain language | Reference file paths or line numbers |
| "When a user submits a form with an expired session, the system silently drops the submission" | "In src/handlers/form.ts:247, the catch block swallows the SessionExpiredError" |
| Reference domain concepts and user-visible outcomes | Reference internal module names, class names, or variable names |
| Link implementation context in PRs and commits | Embed implementation details in the work item body |
Implementation-specific context (file paths, code snippets, stack traces) belongs in linked PRs, commits, and comments, not in the work item description.
Classify each task to indicate whether it can be completed by an AI agent autonomously or requires human judgment.
copilot-candidate)Add copilot-candidate to tasks that meet ALL criteria:
needs-human)Add needs-human to tasks that meet ANY criteria:
Read .memory/board-config.md to identify the platform, then read only the corresponding reference:
| Platform | Reference |
|---|---|
| GitHub Issues | Read references/github-format.md |
| Azure DevOps | Read references/azdo-format.md |