jira-issue-refine

Jira Issue Refinement

Turn one issue into a concise contract that an engineer or coding agent can implement and verify without guessing. Preserve confirmed intent, resolve discoverable facts, and expose decisions that still require a person.

Establish the issue boundary

1. Read the complete draft or existing issue, including structured fields, comments, links, attachments, parent or child issues, and user-supplied context when available.
2. Identify the affected actor or system, current behavior, required outcome, business or operational reason, and requested issue type.
3. Separate confirmed requirements from observations, assumptions, implementation suggestions, and unrelated follow-up ideas. Do not silently promote an engineering suggestion into required behavior.
4. Preserve the author's confirmed intent and terminology. Change meaning only when evidence or an explicit user decision requires it.
5. Keep Jira access read-only unless the user explicitly authorizes creating or updating an issue. Do not implement the requested product or engineering change under this skill.

Assess what the issue still needs

Check each concern only to the depth material to delivery:

• Behavior: State the observable result, inputs or preconditions, boundaries, failure behavior, and unchanged behavior. Do not reward detail that merely prescribes an implementation.
• Evidence: For a bug, capture observed and expected behavior, reproduction, environment, diagnostics, and regression evidence. For a feature, capture concrete scenarios and constraints. For infrastructure or data work, capture current and target state, ordering, idempotency, recovery, and rollback constraints.
• Ownership: Identify the owning repository and component from authoritative evidence. Record a multi-repository dependency explicitly; do not force uncertain ownership into one repository.
• Verification: Define deterministic evidence that will prove success and important failure or regression behavior. Prefer established repository tests, builds, static checks, and CI. Do not demand a new exact-value test for a simple declarative or version update when native checks already prove the contract.
• Scope: Keep one coherent outcome with a clear completion boundary. Separate an epic, open-ended investigation, rewrite, or independently deliverable changes into linked issues when they do not need one atomic delivery.
• Independence: Expose unresolved product decisions, unavailable inputs, other-team actions, external systems, sequencing, credentials, or access that can block delivery.
• Safety: State relevant trust boundaries, state changes, compatibility constraints, rollout, rollback, and recovery needs. Treat authentication, authorization, tenant isolation, billing, personal data, migrations, public contracts, infrastructure, secrets, and destructive actions conservatively.
• Environment: Confirm that a coding workflow can make the change and obtain credible verification locally or through established CI. Name essential runtimes, services, platforms, test data, or privileged capabilities only when they materially apply.
• Effort: Keep the issue small enough for one focused delivery. Split work whose exploration, implementation, or validation has independent completion boundaries.