---
name: refine-jira-ticket
description: Use when the user shares a Jira ticket (issue + expected behavior) and wants to refine it before implementing, or when asked to "refinar el ticket" or "armar el plan". Always asks for the module first; then refines and validates "Expected behavior"; only then produces REFINEMENT-*.md with technical context, plan, and acceptance criteria. Does not implement code.
---

# Skill: Refine Jira Ticket

When the user provides a **Jira ticket** (issue + expected behavior) or asks to **refine** or **plan how to develop** a ticket, produce a refinement document **before** any implementation. Follow this flow.

## Path conventions

Paths depend on the editor running this skill:

| Resource | Cursor | Claude Code |
|----------|--------|-------------|
| Rules | `rules/` | `.claude/rules/` |
| Templates | `templates/` | `.claude/templates/` |
| Refinements | `.refinements/` | `.refinements/` |

Use the correct base path throughout this skill based on your context.

## When to use

- User pastes or describes a Jira ticket (problem + expected behavior).
- User says they want to "refinar" the ticket, "armar el plan", or "trabajar el ticket punto por punto".
- Rule **jira-ticket-refinement** applies (see `rules/workflows/jira-ticket-refinement.mdc`).

## Steps

### 1. Get the module first, then understand the ticket

- **Always ask the user** which **module** (and, if they can, screen or flow) the ticket refers to before doing any codebase search. Example: "Which module does this ticket apply to? (e.g. Employee Lifecycle, Learning, Chats)". With the module known from the start, no time is lost figuring out where to search.
- Once the module is clear, extract **Issue** (current bug or gap) and **Expected behavior** from the user's message.
- Get the ticket number for later use on PRs and branch creation.
- If something else is unclear, ask once before searching.

### 2. Refine and validate "Expected behavior" first

- **Before** advancing to technical context, components, or implementation plan, the **Expected behavior** must be refined and validated with the user.
- Propose a refined version of the expected behavior: clarify ambiguities, split into concrete bullet points, and state what the user will see or do (outcomes, not implementation).
- **Do not** search the codebase or fill "Technical context", "Components / libraries", or "Implementation plan" until the user has confirmed the refined expected behavior.
- Invite the user to adjust or approve. Only when they confirm (or explicitly ask to continue) proceed to step 3.

### 3. Stress-test scope with grill-me

Before touching the codebase, apply the **grill-me** skill to sharpen the scope:

- Ask one question at a time about what exactly needs to change, which flows and screens are in scope, what is explicitly out of scope, and any edge cases or dependencies the user may not have mentioned.
- For each question, provide your recommended answer and let the user confirm or correct.
- Goal: leave this step knowing precisely where to search — no broader than necessary.

### 4. Read project rules and conventions

- **Before** searching the codebase, read all rules in `rules/` — especially `file-types/` — to understand module structure, coding standards, and patterns.
- Use these conventions as constraints when writing the technical context and the implementation plan. The plan **must** align with the project's established structure (e.g. where types, services, and queries go).
- If a convention contradicts what exists in the codebase (legacy code), follow the convention (it represents the target state).

### 5a. Read module READMEs

- For each module identified during the grill, read `src/pages/dashboard/<Module>/README.md` if it exists.
- Extract screens, flows, key file paths, and any architectural notes documented there.
- Use this as a map before touching the codebase — avoid searching for things already covered in the README.

### 5b. Search the codebase

- Using the map from 5a and the scope defined in the grill, search only the relevant areas.
- Find **components, forms, hooks, or services** involved (grep / codebase search by feature name, UI text, or file paths).
- Note where **validations**, **translations**, or **API** touch the feature.
- Identify which **design system / library** components are used.

### 6. Produce the full refinement document

Create or propose a single file **`.refinements/REFINEMENT-<ticket-number>.md`** (all refinements live in the centralized `refinements/` folder). Use the structure from **`templates/REFINEMENT-TEMPLATE.md`** and fill each section:

| Section | Content |
|---------|---------|
| **Ticket (summary)** | Issue + **refined** expected behavior (as validated in step 2). |
| **Technical context** | Table: Module, Flow, Components, Affected block/files, data source if applicable. Short paragraph for root cause if it's a bug. |
| **Components / libraries** | Which UI or design-system components to use; no new ones if existing ones suffice. Concrete API (props, keys) if relevant. |
| **Implementation plan** | Numbered steps. Each step: objective, what to do, where (file/folder), and **how to verify it** (what the user can do in the app to confirm it works). No code yet. |
| **Refinement checklist** | Open questions or decisions to close with the user (copy, scope, translations, testing, etc.). |
| **Acceptance criteria** | Short list ready to copy into Jira. |

- Prefer **English** for the doc. Use **English** for code identifiers and file paths.
- If the ticket touches **multiple modules or forms**, mention all and split the plan by area.
- **New block/section in a form:** If the ticket adds a new UI block or section to an existing form, plan from the start to implement it as a **dedicated `XSection` component** (e.g. under the form's `components/` folder) with `{ disabled, fields }` props — same pattern as `AssigneeDescriptionSection`, `DueDateSection`, etc. — instead of inlining it in `content.tsx`. This applies even when the block has no queries: if it groups visually distinct fields (e.g. info alert + selector + helper text + dynamic list), it deserves its own component. Mention this in the plan so the form stays lean and the logic is easy to change later.
- **User-facing text and hu-translations:** Any new copy (labels, buttons, messages, placeholders) must use i18n keys and the keys/translations must be added to **hu-translations**. Include a translations step in the plan when the ticket adds or changes UI text. **Also include helper texts** — short descriptive lines below selectors or inputs (e.g. "Los archivos que podrá subir el colaborador serán en formato PDF, PNG o JPG.") — they appear in designs but are easy to miss when listing keys during refinement.
- **Vertical slices:** Each implementation step must leave the app in a working, testable state. A step that only adds types or creates files without connecting them to the UI is not a good stopping point unless it's truly foundational (e.g. step 1 of a large feature). Design steps so that by the end of each one, the user can open the app and verify something new works. Include a "✔ How to verify" line per step. Avoid plans where 4–5 steps are needed before anything is visible.

### 7. Do not implement yet

- Output only the refinement document (create the file or show the full content for the user to save).
- Invite the user to review and adjust the plan, then implement **point by point** when they say so (see jira-ticket-implementation workflow).

## Helpful context for building a good refinement

The user **does not have to** specify the exact component to modify (e.g. the file name); that is discovered through the codebase search. What does help is:

| Data | Purpose |
|------|---------|
| **Module** (and, if possible, screen or flow) | Always ask the user at the start. Narrows down the search. |
| **Where they see it in the UI** | "The modal that opens when editing the action", "the main button in the drawer", "the survey config screen". Helps search by text, paths, or flow. |
| **What's wrong or what they want** | "The button currently does X and I want it to do Y instead". Defines the scope without requiring technical names. |

If the user already knows the component or file, they can mention it to speed things up; but it's not required. With **module + where in the app it happens + what's expected**, a good context can be built.

---

## Template reference

The exact structure and placeholder text are in **`templates/REFINEMENT-TEMPLATE.md`**. Use it as the skeleton; replace placeholders with concrete module names, components, and steps.

## Example flow

1. User: "Here's a task description… [Issue] … [Expected behavior]"
2. Agent: **always** asks first: "Which module does this ticket apply to? (e.g. Employee Lifecycle, Learning, Chats)". Once the user answers, extracts Issue + Expected behavior and proposes a **refined** Expected behavior (bullet points, clear outcomes). Does **not** yet search codebase or write technical sections.
3. Agent: "Does this expected behavior look right? Once we confirm it, I'll proceed to the technical context and plan."
4. User: "Yes, looks good" (or suggests changes).
5. Agent: applies **grill-me** — asks one question at a time to sharpen scope: which flows/screens are in, what's out, edge cases, dependencies. Updates understanding before searching.
6. Agent: reads `rules/` (conventions, workflows), then searches only the relevant areas identified in step 5 → writes full `REFINEMENT-<ticket-id>.md` aligned with project conventions.
7. Agent: "Done. Review the plan; when you're ready we'll implement it point by point."
