From 4818abc8abea756f5b5685174974fa4eb61aa03e Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 22 Jun 2026 14:28:06 +0000
Subject: [PATCH] Card Skill: use Jira heading format for description sections

Require Background, Scope of change, and Questions as ADF level-1 headings
instead of plain text labels when creating cards via MCP.

Co-authored-by: ScottGits <ScottGits@users.noreply.github.com>
---
 .cursor/skills/card-skill/SKILL.md | 62 ++++++++++++++++++++++--------
 1 file changed, 46 insertions(+), 16 deletions(-)

diff --git a/.cursor/skills/card-skill/SKILL.md b/.cursor/skills/card-skill/SKILL.md
index 4ea5111e6..297b76ef7 100644
--- a/.cursor/skills/card-skill/SKILL.md
+++ b/.cursor/skills/card-skill/SKILL.md
@@ -103,23 +103,47 @@ Draft a clear, professional Jira summary from the user's purpose.
 
 ## Description Format
 
-**CRITICAL:** Description uses exactly these two labeled sections with trailing colons:
+**CRITICAL:** Section labels MUST be Jira **heading** elements (not plain text). Use ADF `heading` nodes at level 1 when creating or editing via MCP.
 
+**Required sections:**
+- `Background:` — heading
+- `Scope of change:` — heading (lowercase "change")
+
+**Optional section** (include when user requests open questions or outstanding items):
+- `Questions:` — heading at the bottom of the description
+
+**ADF pattern for each section header:**
+```json
+{
+  "type": "heading",
+  "attrs": { "level": 1 },
+  "content": [{ "type": "text", "text": "Background:" }]
+}
+```
+
+**Markdown fallback** (if ADF is not used): prefix with `#` so Jira renders a header:
 ```markdown
-Background:
+# Background:
+
 [Content from the user's purpose — context and why this work exists]
 
-Scope of change:
+# Scope of change:
+
 [Content from the user's purpose — what will change or be delivered]
+
+# Questions:
+
+[Outstanding questions, when applicable]
 ```
 
 **Rules:**
-- Use `Background:` and `Scope of change:` (lowercase "change")
-- Each label on its own line; content on following line(s)
-- Blank line between sections
+- NEVER use plain-text labels like `Background:` on their own line without heading formatting
+- Put section content in paragraphs and bullet lists immediately after each heading
+- Blank line between sections when using markdown fallback
 - Do NOT use `Description:` in Card Skill cards
 - Do NOT put acceptance criteria in the description — use the AC field (below)
 - Use the user's purpose to populate both sections: expand into Background (context/why) and Scope of change (deliverables/what changes). If the purpose is a single short sentence, place it under Scope of change and write a brief Background derived from it
+- When calling `createJiraIssue` or `editJiraIssue`, pass `contentFormat: "adf"` for the description field to preserve headings
 
 ---
 
@@ -140,6 +164,7 @@ AC3: [Testable outcome]
 - Generate 2–5 ACs from the purpose when the user does not provide them
 - If the user provides explicit ACs, use their wording with AC1/AC2 labels
 - One AC per line; blank line between ACs is optional
+- Pass `customfield_10025` as ADF (one paragraph per AC) via `editJiraIssue` with `contentFormat: "adf"` if plain text is rejected
 
 **Example:**
 ```text
@@ -172,17 +197,19 @@ createJiraIssue(
   projectKey="CASH",
   issueTypeName="Story",
   summary="[drafted summary]",
-  description="Background:\n[background]\n\nScope of change:\n[scope]",
+  description={ ADF doc with heading nodes for Background: and Scope of change: },
+  contentFormat="adf",
   parent="CASH-1559",
   additional_fields={
     "customfield_10008": "CASH-1559",
     "customfield_14823": { "accountId": "557058:6c212fb7-af94-48db-91a9-99ba87ceb3c5" },
-    "customfield_13100": { "accountId": "712020:1bf3c7f2-bc3b-4bab-bc48-d01e99358978" },
-    "customfield_10025": "AC1: ...\n\nAC2: ..."
+    "customfield_13100": { "accountId": "712020:1bf3c7f2-bc3b-4bab-bc48-d01e99358978" }
   }
 )
 ```
 
+Then set acceptance criteria via `editJiraIssue` with ADF paragraphs for AC1, AC2, …
+
 ### CONT example
 
 ```
@@ -191,13 +218,13 @@ createJiraIssue(
   projectKey="CONT",
   issueTypeName="Story",
   summary="[drafted summary]",
-  description="Background:\n[background]\n\nScope of change:\n[scope]",
+  description={ ADF doc with heading nodes for Background: and Scope of change: },
+  contentFormat="adf",
   parent="CONT-905",
   additional_fields={
     "customfield_10008": "CONT-905",
     "customfield_14823": { "accountId": "557058:6c212fb7-af94-48db-91a9-99ba87ceb3c5" },
-    "customfield_13100": { "accountId": "712020:4c9751b9-2abd-4280-b1e0-983334853223" },
-    "customfield_10025": "AC1: ...\n\nAC2: ..."
+    "customfield_13100": { "accountId": "712020:4c9751b9-2abd-4280-b1e0-983334853223" }
   }
 )
 ```
@@ -220,13 +247,16 @@ Here's the Card Skill card I'll create:
 **System Analyst:** Scott Phillips
 **UAT Tester:** Tim Gosnik
 
-**Description:**
-Background:
+**Description:** (section labels shown as headings)
+# Background:
 [background]
 
-Scope of change:
+# Scope of change:
 [scope]
 
+# Questions: (if applicable)
+[questions]
+
 **Acceptance Criteria:**
 AC1: ...
 AC2: ...
@@ -261,7 +291,7 @@ When the user asks to **update Card Skill** (change defaults, add fields, change
 |------|-------|
 | Invoke | `/card-skill` or "create using Card Skill" |
 | Boards | CASH, CONT |
-| Description | `Background:` + `Scope of change:` |
+| Description | Heading format: `# Background:`, `# Scope of change:`, optional `# Questions:` (use ADF headings via MCP) |
 | Acceptance Criteria | `customfield_10025` as AC1:, AC2:, … |
 | System Analyst | Scott Phillips (both boards) |
 | UAT (CASH) | Tim Gosnik |