Fabrico Jira Task Formatting

---
name: fabrico-jira-task-formatting
description: Transform extracted epics and user stories into Jira-ready format following a benchmark template. Handles field mapping, formatting for Jira markdown compatibility, two-gate user review, and guidance for Jira issue creation via Atlassian tools.
---

# 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 `fabrico-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 the **AskUserQuestion** tool to get user input. Ask exactly **one question per AskUserQuestion 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 **AskUserQuestion** 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"):

0. **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.
1. **Update the local `jira-tasks.md` first** — apply the requested change to the file
2. **Ask the user**: "Do you want to push this change to Jira now?" (using one **AskUserQuestion** call)
3. **If yes** — use the task's Jira key to update the specific issue via the Atlassian MCP server. If the task has no Jira key (`—`), inform the user that the task has not been pushed yet and offer to create it
4. **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

This is an alternative entry point for the skill. Instead of formatting extracted tasks, the agent fetches existing Jira issues and converts them into the `jira-tasks.md` format with Jira keys pre-populated. This enables iterating on existing Jira backlogs using the agent's skills.

### Import Process

```
Import progress:
- [ ] Step I-1: Identify import target
- [ ] Step I-2: Fetch issues from Jira
- [ ] Step I-3: Map Jira fields to benchmark template
- [ ] Step I-4: Generate jira-tasks.md
- [ ] Step I-5: Present imported tasks for user review
- [ ] Step I-6: Save to specifications directory
```

**Step I-1: Identify import target**

Ask the user to specify what to import. Accept any of these:
- A **Jira project key** (e.g., `PROJ`) — imports all epics and their linked stories
- **Specific epic keys** (e.g., `PROJ-10, PROJ-15`) — imports those epics and their child stories
- A **JQL query** — imports issues matching the query

Use one **AskUserQuestion** call to determine the import scope if the user hasn't specified it.

**Step I-2: Fetch issues from Jira**

Using the Atlassian MCP server tools:
1. Fetch the targeted epics and stories from Jira
2. For each epic, fetch its child stories (linked via parent field)
3. Collect all fields: Summary, Description, Acceptance Criteria, Priority, Labels, Issue Key, Parent link

**Step I-3: Map Jira fields to benchmark template**

Convert each fetched issue into the benchmark template format:

| Jira Field | Template Field | Notes |
|---|---|---|
| Summary | Title (Summary) | Direct mapping |
| Description | Description sections | Parse into structured sections (Overview/Value/Metrics for epics; Context/User Story/Requirements/Technical Notes for stories). If the Jira description does not follow a structured format, restructure it to match the template as closely as possible. |
| Priority | Priority | Direct mapping (Highest/High/Medium/Low) |
| Labels | Labels | Direct mapping |
| Issue Key | Jira Key | Populate directly (e.g., `PROJ-123`) |
| Parent link | Parent epic reference | Map to parent epic title |
| Story Points | Story Points / Sizing Guidance | If estimated, include; otherwise mark as TBD |
| Status | Status | Direct mapping of the Jira workflow status (e.g., To Do, In Progress, Done). Used to enforce the Protected Status Policy. |

If an imported description cannot be cleanly restructured into the benchmark format, flag it for user review using one **AskUserQuestion** call per flagged task.

> **Protected Status Handling on Import**: After mapping all fields, check each imported task's Status. If the status is Done, Cancelled, or PO APPROVE, mark the task as read-only by adding a `🔒` indicator next to its title. These tasks are imported for visibility but must never be modified locally or pushed back to Jira. Preserve their content exactly as fetched.

**Step I-4: Generate jira-tasks.md**

Create the `jira-tasks.md` file with all imported tasks in the benchmark template format. Every task must have its `Jira Key` field populated with the actual Jira issue key.

**Step I-5: Present imported tasks for user review**

Present each imported task to the user for review using one **AskUserQuestion** call per task. Highlight any descriptions that were restructured or fields that could not be mapped cleanly. Ask: "Does this imported task look correct?"

**Step I-6: Save to specifications directory**

Save the final file to `specifications/<project-or-topic>/jira-tasks.md`.

After import, the user can modify the local file. For each change, the agent asks whether to push it to Jira immediately (using the Per-Change Modification Flow above). The user can also batch-push all local changes later using the standard push flow (Step 8 → Step 9).

## Connected Skills

- `fabrico-task-extracting` - provides the extracted tasks used as input for formatting