thesoftwarehouse/copilot-collections/tsh-jira-task-formatting

Jira Task Formatting

This skill helps you transform an extracted task list (epics and user stories) into a Jira-ready format that can be directly pushed to Jira. It applies a consistent benchmark template to every task, preserves source traceability, validates completeness, and manages a two-gate review process before any issues are created.

Jira Task Formatting Process

Use the checklist below and track your progress:

Formatting progress:
- [ ] Step 1: Load the benchmark template and extracted tasks
- [ ] Step 2: Format each epic for Jira
- [ ] Step 3: Format each story for Jira
- [ ] Step 4: Validate completeness against benchmark
- [ ] Step 5: Flag uncertain fields and ask user
- [ ] Step 6: Formatting Review — User reviews formatted markdown
- [ ] Step 7: Save the Jira-ready tasks document
- [ ] Step 8: Push Approval — User approves Jira push
- [ ] Step 9: Create or update issues in Jira
- [ ] Step 10: Post-push verification against Jira
- [ ] Step 11: Archive session artifacts and refresh the project baseline

Step 1: Load the benchmark template and extracted tasks

Load two inputs:

• The benchmark template (./jira-task.example.md) which defines the expected structure and fields for Jira epics and stories
• The extracted tasks document (extracted-tasks.md) produced by the tsh-task-extracting skill

Review the benchmark template to understand:

• Required fields for epics and stories
• Formatting conventions
• How to handle optional fields
• The example tasks for reference quality and tone

Step 2: Format each epic for Jira

For each epic in the extracted tasks document, create a Jira-ready epic entry with:

Protected Status Guard: If an epic has a protected status (Done, Cancelled, PO APPROVE), preserve its content exactly as imported. Do not reformat, reword, or modify any fields. Mark it with 🔒 in the output and skip all formatting steps below for this epic.

• Summary (title): Follow the naming convention from the benchmark template
• Description: Structured using the benchmark epic description format, including:
• Business overview
• Business value statement
• Success metrics / criteria
• Acceptance criteria: Transferred from extracted tasks, formatted for Jira compatibility
• Labels: Suggest relevant labels based on the epic's domain (do not hardcode project-specific values)
• Priority: Map from the extracted task priority (Critical → Highest, High → High, Medium → Medium, Low → Low)

Step 3: Format each story for Jira

For each user story, create a Jira-ready story entry with:

Protected Status Guard: If a story has a protected status (Done, Cancelled, PO APPROVE), preserve its content exactly as imported. Do not reformat, reword, or modify any fields. Mark it with 🔒 in the output and skip all formatting steps below for this story.

• Summary (title): Follow the naming convention from the benchmark template
• Description: Structured using the benchmark story description format, including:
• Context paragraph linking to the parent epic
• Source Context section that preserves traceability from extracted tasks
• User story in "As a… I want… So that…" format
• Requirements as a numbered list
• High-level technical notes (only if present in extracted tasks)
• Acceptance criteria: Formatted as a checklist compatible with Jira markdown; scenario-style GIVEN / WHEN / THEN criteria are valid and should remain readable after formatting
• Story points guidance: Include a sizing suggestion (e.g., Small / Medium / Large) based on scope complexity — but note this is a suggestion, not an estimate. The team should estimate during refinement.
• Labels: Consistent with the parent epic's labels plus any story-specific labels
• Parent epic: Reference to the parent epic by title (will be linked by ID after creation)
• Priority: Mapped from extracted task priority

Step 4: Validate completeness against benchmark

Protected Status Guard: Skip completeness validation for tasks with a protected status (Done, Cancelled, PO APPROVE) — their content is preserved as-is and is not subject to benchmark compliance.

Cross-check every formatted task against the benchmark template:

• Are all required fields populated?
• Do descriptions follow the expected structure?
• Are acceptance criteria written as verifiable conditions?
• Is the language business-oriented (not technical jargon)?
• Are priorities and labels consistent across related tasks?

Create a summary table showing completeness status for each task.

Step 5: Flag uncertain fields and ask user

Protected Status Guard: Do not flag or ask the user about fields on tasks with a protected status (Done, Cancelled, PO APPROVE). These tasks are read-only and their fields cannot be changed.

For any task where:

• A required field could not be confidently filled from the source materials
• The priority is ambiguous
• The scope of a story is unclear
• Labels or categorisation is uncertain

Use askQuestions to get user input. Ask exactly one question per `askQuestions` call, each scoped to a single epic or story. The question must identify which task has the uncertain field and what field is missing (e.g., "[Epic 2: Payment Processing > Story 2.1: User can checkout] The priority for this story could not be determined from the workshop materials. Should it be High (core MVP) or Medium (post-MVP)?"). Do not proceed to the review gate until all flags are resolved.

Step 6: Formatting Review — User reviews formatted markdown

Present the formatted output to the user for review. If changes were made during formatting (e.g., rewording, priority adjustments), present each changed task individually using one askQuestions call per task, identifying the specific epic/story and the change made. Ask: "Is this change acceptable?"

After all individual changes are reviewed, ask one workflow-level question: "All formatting is complete. Are you happy with these tasks? Any final changes before I proceed to save and push?"

The user must explicitly approve before proceeding. If changes are requested, update and re-present the affected tasks individually.

Step 7: Save the Jira-ready tasks document

Generate the final output following the ./jira-task.example.md template format.

Include the Jira Key field for every epic and story. For newly formatted tasks (not yet pushed to Jira), set the Jira Key to — as a placeholder. For tasks imported from Jira or previously pushed, preserve their existing Jira key.

Save the file to specifications/<workshop-name>/jira-tasks.md.

Step 8: Push Approval — User approves Jira push

Before creating any issues in Jira, confirm with the user:

• Target Jira project key (e.g., "PROJ")
• Target board or backlog
• Whether to create all tasks at once or in batches
• Any final adjustments

This is the final gate — after this, issues will be created in Jira.

Step 9: Create or update issues in Jira

Before pushing, present a sync summary to the user:

• (a) Tasks to be CREATED (Jira Key is —) — list titles and count
• (b) Tasks to be UPDATED (Jira Key is populated, e.g., PROJ-123, and status is NOT protected) — list titles, keys, and count
• (c) Tasks SKIPPED (Jira Key is populated and status is Done, Cancelled, or PO APPROVE) — list titles, keys, statuses, and count
• Get explicit user approval before proceeding.

Using the Atlassian tools, process issues based on their Jira Key:

For tasks without a Jira Key (create):

1. Create all epics first (to get their Jira IDs)
2. After creating each epic, immediately update the corresponding entry in jira-tasks.md with the returned Jira issue key — do not wait until all issues are created
3. Create all stories linked to their parent epics
4. After creating each story, immediately update jira-tasks.md with its Jira key
5. Add any links between stories (blocked-by, related-to relationships)

For tasks with an existing Jira Key (update):

1. First, check the task's Status field. If the status is Done, Cancelled, or PO APPROVE, skip this task — do not send any update to Jira. It was already counted in the sync summary under category (c).
2. Update the existing Jira issue with the local content
3. Fields to update: Summary, Description, Acceptance Criteria, Priority, Labels
4. Fields NOT to update: Issue Type, Parent link (unless the user explicitly requests re-linking)
5. If an update fails because the issue no longer exists in Jira, inform the user and offer to create a new issue instead

After all issues are processed, report the final state back to the user — showing all Jira keys in jira-tasks.md and confirming which were created, updated, and skipped (with their statuses).

Step 10: Post-push verification against Jira

After the Jira sync succeeds, read back the created or updated issues and verify at least the following for each task:

• Summary/title
• Parent epic linkage for stories
• Acceptance criteria presence
• Relevant description sections
• Current status capture

If verification finds mismatches, surface them clearly and do not claim the push is fully verified until the differences are resolved or explicitly acknowledged by the user.

Step 11: Archive session artifacts and refresh the project baseline

When verification succeeds, archive the current session artifacts under specifications/projects/<project-name>/sessions/<YYYY-MM-DD>-<workshop-name>/.

• Use the workshop name as the fallback project key when no explicit project name exists
• Refresh specifications/projects/<project-name>/task-baseline.md
• Treat Jira Key as the primary identity when merging baseline entries
• Replace same-key entries with the latest synced content and status
• Add new entries for newly pushed tasks
• Preserve Jira as the external source of truth

If any issue creation or update fails, inform the user immediately and ask how to proceed.

Per-Change Modification Flow

When the user requests a change to a specific task outside of the main formatting workflow (e.g., "add acceptance criteria to Story 2.3" or "change the priority of Epic 1"):

1. Check the task's Status field. If it is Done, Cancelled, or PO APPROVE, inform the user that this task is protected and cannot be modified: _"This task has a protected status ([status]). Per the Protected Status Policy, tasks with status Done, Cancelled, or PO APPROVE cannot be modified. If this status is incorrect, please update it in Jira first, then re-import."_ Do not apply the change locally or in Jira. Stop here.
2. Update the local `jira-tasks.md` first — apply the requested change to the file
3. Ask the user: "Do you want to push this change to Jira now?" (using one askQuestions call)
4. If yes — use the task's Jira key to update the specific issue via Atlassian MCP. If the task has no Jira key (—), inform the user that the task has not been pushed yet and offer to create it
5. If no — the change remains local in jira-tasks.md until the next batch push

Jira Markdown Compatibility

When formatting descriptions and acceptance criteria for Jira:

• Use h2., h3. for headings (not ##, ###)
• Use *bold* for bold text (not **bold**)
• Use _italic_ for italic text (not *italic*)
• Use * item for bullet lists (with space after asterisk)
• Use # item for numbered lists
• Use {noformat} or {code} blocks for preformatted text
• Acceptance criteria should use (/) criterion for checklist items (Jira checkbox format)
• Scenario-style acceptance criteria remain valid when expressed as (/) GIVEN ... WHEN ... THEN ...

Note: The markdown file saved locally uses standard markdown. The Jira-specific formatting is applied only when creating the actual issues.

Import Mode: Jira → Local