# Skill: jira-lifecycle

Full Jira ticket lifecycle management for ESIDEPAISY.

## Invoked by

🎫 JiraOps mode

## Required Inputs

| Input | Source | Example |
|-------|--------|---------|
| `TICKET_KEY` | Jira issue key | `ESIDEPAISY-12081` |

## Overview

This skill manages a Jira ticket through its full lifecycle, from initial setup through to final acceptance. It handles field validation, Smart Checklist management, status transitions, attachments, and structured comments.

## Steps

### 1. Validate mandatory fields

```python
ticket = retrieve_ticket_details(TICKET_KEY)
```

Check and fix:

| Field | ID | Required | How to resolve |
|-------|----|----------|---------------|
| Feature Link | `customfield_10001` | ✅ Mandatory | Look up parent Epic via JQL: `project = ESIDEPAISY AND issuetype = Epic AND summary ~ "<module>"` |
| Sprint | `customfield_10000` | ✅ Mandatory | Derive from active sprint: `get_agile_boards("ESIDEPAISY")` → `get_sprints_from_board(board_id, states="active")` |
| Assignee | `assignee` | Recommended | `ticket_assignment(TICKET_KEY, assignee="currentUser()")` |

If Feature Link is missing:
```python
# Find the parent Epic
epics = list_tickets(jql_search='project = ESIDEPAISY AND issuetype = Epic AND summary ~ "<module keyword>"')
# Update the ticket
update_ticket_fields(TICKET_KEY, fields={"customfield_10001": epics[0]["key"]})
```

### 2. Create Smart Checklist

Set up the standard PAISY pipeline checklist:

```python
update_checklist(TICKET_KEY, items=[
    {"name": "## Analyse & Planung"},
    {"name": "Assessment erstellt", "status": "-"},
    {"name": "Plan erstellt", "status": "-"},
    {"name": "Testplan erstellt", "status": "-"},
    {"name": "Plan Review bestanden", "status": "-!"},  # mandatory
    {"name": "GO erhalten", "status": "-!"},  # mandatory
    {"name": "---"},
    {"name": "## Implementierung"},
    {"name": "Code-Änderungen", "status": "-"},
    {"name": "Tests implementiert", "status": "-"},
    {"name": "Build grün", "status": "-!"},  # mandatory
    {"name": "---"},
    {"name": "## Security & Review"},
    {"name": "Security Review bestanden", "status": "-!"},  # mandatory
    {"name": "Code Review bestanden", "status": "-"},
    {"name": "---"},
    {"name": "## Dokumentation & Abschluss"},
    {"name": "Lösungsdokumentation", "status": "-"},
    {"name": "PDF generiert", "status": "-"},
    {"name": "Jira aktualisiert", "status": "-"},
])
```

### 3. Status transitions

Manage the ticket through the ESIDEPAISY workflow:

| Phase | Status | When |
|-------|--------|------|
| Start | `In Progress` | After worktree creation, before implementation |
| Review | `In Review` | After implementation + tests, before code review |
| Done | `Accepted` | After all checklist items complete |

```python
update_status(TICKET_KEY, status="In Progress")
```

### 4. Update checklist as work progresses

Update individual items as phases complete:

```python
# After assessment is done
update_checklist(TICKET_KEY, items=[
    {"name": "## Analyse"},
    {"name": "Assessment erstellt", "checked": True},
    {"name": "Plan erstellt", "status": "~"},  # in progress
    # ... rest unchanged
])
```

**Important:** `update_checklist` replaces ALL items. Always send the full checklist with updated statuses.

### 5. Add structured comments at phase boundaries

At each major phase transition, add a German comment:

```python
# After planning + plan review
add_comment_to_ticket(TICKET_KEY, comment="""
*Phase 1-1.5 abgeschlossen: Analyse & Planung*

Assessment, Plan und Testplan erstellt:
- Assessment: [TICKET_KEY-assessment.md]
- Plan: [TICKET_KEY-plan.md]
- Testplan: [TICKET_KEY-testplan.md] ({N} Testfälle)
- Plan Review: [TICKET_KEY-plan-review.md] — ✅ APPROVED

GO erhalten am {date}.
""")

# After implementation + security review
add_comment_to_ticket(TICKET_KEY, comment="""
*Phase 3-5.5 abgeschlossen: Implementierung, Tests & Security*

Branch: current/{type}/{module}/{TICKET_KEY}-{desc}
Änderungen: {N} Dateien geändert, {M} neu
Tests: {T} Tests, alle bestanden
Security Review: ✅ PASS — [TICKET_KEY-security-review.md]
""")

# After documentation
add_comment_to_ticket(TICKET_KEY, comment="""
*Phase 7-8 abgeschlossen: Dokumentation & Finalisierung*

Lösungsdokumentation als PDF angehängt.
Alle Checklist-Punkte erledigt.
""")
```

### 6. Upload attachments

```python
# Upload solution PDF
add_attachment_to_ticket(TICKET_KEY, file_path="/absolute/path/to/<TICKET_KEY>-solution.pdf")
```

### 7. Final checklist update

Mark all items as done:

```python
update_checklist(TICKET_KEY, items=[
    {"name": "## Analyse & Planung"},
    {"name": "Assessment erstellt", "checked": True},
    {"name": "Plan erstellt", "checked": True},
    {"name": "Testplan erstellt", "checked": True},
    {"name": "Plan Review bestanden", "status": "+!"},
    {"name": "GO erhalten", "status": "+!"},
    {"name": "---"},
    {"name": "## Implementierung"},
    {"name": "Code-Änderungen", "checked": True},
    {"name": "Tests implementiert", "checked": True},
    {"name": "Build grün", "status": "+!"},
    {"name": "---"},
    {"name": "## Security & Review"},
    {"name": "Security Review bestanden", "status": "+!"},
    {"name": "Code Review bestanden", "checked": True},
    {"name": "---"},
    {"name": "## Dokumentation & Abschluss"},
    {"name": "Lösungsdokumentation", "checked": True},
    {"name": "PDF generiert", "checked": True},
    {"name": "Jira aktualisiert", "checked": True},
])
```

### 8. Final status transition

```python
update_status(TICKET_KEY, status="Accepted")
```

## Language

- All Jira content (summary, description, comments, checklist items): **German**
- Technical terms (branch names, file paths, tool names): English as-is

## Conventions

- Feature Link (`customfield_10001`): always look up dynamically, never hardcode Epic keys
- Sprint: always derive from active sprint, never hardcode sprint IDs
- Comments: use Jira wiki markup (`*bold*`, `{code}`, etc.)
- Attachments: use absolute file paths
- Checklist: always send the FULL list (Railsware replaces all items on update)

## Partial Lifecycle

Not every ticket needs the full lifecycle. For quick fixes:

| Scenario | Skip |
|----------|------|
| Trivial bugfix (< 1 hour) | Skip assessment, testplan, review. Keep checklist minimal. |
| Documentation-only change | Skip implementation, tests, review phases. |
| Hotfix | Skip planning loop. Minimal checklist: Code → Test → Deploy. |

Adjust the checklist template accordingly when creating it.