diff --git a/.cursor/skills/create-jira-card/SKILL.md b/.cursor/skills/create-jira-card/SKILL.md index 0a5d38b78..4db102a61 100644 --- a/.cursor/skills/create-jira-card/SKILL.md +++ b/.cursor/skills/create-jira-card/SKILL.md @@ -146,13 +146,50 @@ Write a clear summary and description before calling any create API. Keep summaries under ~100 characters when possible. +### Description Format + +**CRITICAL:** When building the Jira description body, use labeled sections with a trailing colon (`:`) on their own line, followed by the content on the next line(s). This matches how `Scope of change:` is formatted. + +**Standard pattern:** +```markdown +Description: +[Main description content] + +Scope of change: +[Scope details] +``` + +**Common section labels** (use only what the user provides or the issue needs): +- `Description:` — Primary card content when the user gives a standalone description +- `Background:` — Context or problem statement +- `Scope of change:` — What will change +- `Documents:` — Links or references + +**Rules:** +- Always include the colon after the label (`Description:`, not `Description`) +- Put each label on its own line +- Put content on the line(s) immediately after the label +- Leave a blank line between sections when there are multiple sections +- If the user provides both a description and scope of change, format as: +```markdown +Description: +show and tell + +Scope of change: +tell me more +``` +- If the user provides `Background:` and `Scope of change:` (without a separate Description), use those labels instead: +```markdown +Background: +[background content] + +Scope of change: +[scope content] +``` + ### Description Templates -Use templates from `references/field-templates.md` based on issue type. At minimum include: - -- **Context** — Why this work exists -- **Requirements or steps** — What needs to happen -- **Acceptance criteria** — How to know it's done (for Stories/Tasks) +For fuller cards, use templates from `references/field-templates.md` based on issue type. Section headers in those templates also use trailing colons when rendered as plain-text Jira descriptions. ### Optional Metadata diff --git a/.cursor/skills/create-jira-card/references/field-templates.md b/.cursor/skills/create-jira-card/references/field-templates.md index 1ca2847e9..56db0e01c 100644 --- a/.cursor/skills/create-jira-card/references/field-templates.md +++ b/.cursor/skills/create-jira-card/references/field-templates.md @@ -2,6 +2,22 @@ Copy and adapt the template that matches the issue type. +## Labeled Section Format + +When the user provides short, structured content (description, background, scope, documents), use labeled sections with a trailing colon on each label: + +```markdown +Description: +[Main description content] + +Scope of change: +[Scope details] +``` + +Other common labels: `Background:`, `Documents:` + +Each label goes on its own line. Content follows on the next line(s). Leave a blank line between sections. + --- ## Story Template @@ -114,14 +130,18 @@ As a [user type], I want [goal] so that [benefit]. Use when the user provides little detail and you need a lightweight card: ```markdown -## Summary +Description: [Restate the work in 1-2 sentences] -## Acceptance Criteria -- [ ] [Primary done condition] +Scope of change: +[What will change, if known] +``` -## Notes -[Source: conversation / request on DATE] +If the user only provides a description with no scope, still use the `Description:` label: + +```markdown +Description: +[Content provided by user] ``` ---