Jira Standards and Guidelines
This document consolidates Path2Response’s Jira standards, issue requirements, and workflow guidelines. It serves as the authoritative reference for creating and managing issues in the PATH (Development) and PROD (Product Management) projects.
Source: Adapted from Confluence documentation:
- Development (PATH) Ticket Guidelines and Process
- Process for Product Management and Development Issues
- Backlog Grooming Process
Projects Overview
| Project | Owner | Purpose |
|---|---|---|
| PATH | John Malone | Development work (Engineering & Data Science) |
| PROD | Karin Eisenmenger | Product Management work (pre/post-development) |
When to Use Each Project
Use PATH when:
- It’s a bug in existing functionality
- It’s a clearly-defined technical task
- Requirements are complete and understood
- No significant product discovery needed
Use PROD when:
- Requirements need definition
- Business case/ROI needs analysis
- Stakeholder alignment needed
- Pre-development or post-development work
Issue Types
Epic
The Epic is the level at which Product Owners and Stakeholders track work. It represents a well-scoped, concise statement of a problem to be solved.
Scope:
- Analogous to an Agile “User Story” at the feature level
- Can span single or multiple sprints
- Should be specific and well-understood
- NOT a bucket of loosely-related work
Requirements for Triage (PATH Epic Requirements):
-
The “Why?” - Problem, not solution
- Written from persona’s perspective
- Captures: Who, What they want, Why they want it
- Uses: “As a [persona], I [want to], [so that]”
- Includes performance expectations when relevant
-
Acceptance Criteria - Clear and testable
- Clear to everyone involved
- Can be tested or verified
- Binary (passes or fails, not 50% complete)
- Outcome-focused, not implementation-focused
- As specific as possible
-
Source of Truth - For any new data/fields
- Where does the data come from?
- Salesforce? User input? Automated gathering?
-
Impact Analysis
- Effects on other products/systems
- Integration points and dependencies
-
Priority & Stakeholders
- Business value and ROI
- Explicit stakeholder identification
- Who accepts work as complete
-
Release Parameters
- Patch ASAP or standard release schedule?
- Deployment constraints
Writing the “Why?” Correctly
Problem-focused, not solution-focused:
| Wrong | Right |
|---|---|
| “As a registrar, I want to search for a student when a family member calls.” | “As a registrar, I want to connect a family member and student quickly in an emergency so I don’t have to search while they get upset waiting.” |
From persona’s perspective, not creator’s:
| Wrong | Right |
|---|---|
| “As a data scientist, I want to create a batch utility so production can run jobs more seamlessly.” | “As a production team member, I want to reduce the 3 hours I spend setting up cheeseburger jobs. What can we do to streamline this?” |
Story
A piece of development work representing changes or additions to code to achieve a specific outcome.
Scope:
- Addresses a subset of Epic’s Acceptance Criteria
- May exist outside an Epic for small, one-off work
- “Purely technical” work that doesn’t change product behavior
Requirements for Triage:
- Well-defined Acceptance Criteria
- Clear “Why?”
- Test Plan describing verification steps
- May include more “how” than Epics when meeting specific contracts
Bug
A problem which impairs or prevents the functions of a product.
Scope:
- Problems with existing functionality as originally defined
- Features that used to work but aren’t working correctly
- Should fit in a sprint with room for other work
Requirements for Triage:
| Field | Description |
|---|---|
| Bug Summary | Brief summary of the issue |
| Steps to Reproduce | Specific steps to make the problem happen |
| Expected Behavior | What should happen |
| Actual Behavior | What is actually happening (and why it’s wrong) |
| Workaround | Any temporary workarounds available |
Note: A bug may convert to Stories/Epics if scope is unexpectedly large.
Task
A relatively small piece of work that typically does not involve code development.
Examples:
- Research/SPIKE (time-limited investigation)
- Configuration changes
- Patch tracking
- Third-party conversations
- Documentation writing
- Feature idea capture
Workflow States
PATH Triage Workflow
| State | Description |
|---|---|
| Under Construction | Issue still being defined, not ready for consideration |
| Considering | Being evaluated for completeness and agreement |
| Open | Deemed complete and of sufficient priority for work |
Considering Checklist:
- Is it the right issue type?
- Is it descriptive with clear Summary and Description?
- Does it have Acceptance Criteria?
- Does it have a Test Plan?
- Does it have a stakeholder different from the implementer?
- Is there agreement (technical, product, stakeholder)?
Important: Issues should only be in “Considering” when actively being considered. Move back to “Under Construction” if discussion stalls.
Jira Fields
Standard Fields
| Field | Purpose |
|---|---|
| Summary | Issue title (brief, descriptive) |
| Description | Detailed explanation of the “why” |
| Issue Type | Epic, Story, Bug, Task |
| Priority | Business priority |
| Fix Version | Target release version |
| Sprint | Sprint assignment |
| Assignee | Person doing the work |
| Reporter | Person who created the issue |
Path2Response Custom Fields
| Friendly Name | Field ID | Type | Description |
|---|---|---|---|
| story-points | customfield_10004 | Number | Effort estimate |
| sprint | customfield_10007 | Sprint | Sprint assignment |
| epic-link | customfield_10008 | Epic Link | Parent epic |
| acceptance-criteria | customfield_12700 | ADF Textarea | What must be true when done |
| test-plan | customfield_15023 | ADF Textarea | How to verify acceptance criteria |
| stakeholders | customfield_15006 | Multi-User | People with interest in outcome (names, emails, or account IDs) |
| strategic-value | customfield_15067 | Select | Strategic business value |
| product-value | customfield_15068 | Select | Product business value |
| technical-value | customfield_15069 | Select | Technical business value |
| demo | customfield_12600 | Multi-Checkboxes | Demo requirements |
| flagged | customfield_10002 | Multi-Checkboxes | Impediment flag |
Business Value Options
For strategic-value, product-value, and technical-value fields:
| Option | Description |
|---|---|
low-low | Low Value / Low Urgency |
high-low | High Value / Low Urgency |
low-high | Low Value / High Urgency |
high-high | High Value / High Urgency |
Definition of Done
Before marking work as complete, verify:
Before Work Begins:
- Stakeholders and developers agreed on Acceptance Criteria
During/After Development:
- Each Acceptance Criteria is met
- Stakeholder accepted that needs have been met
- Possible regressions looked for and addressed
- Existing automated tests all passing
- Code reviewed and approved (via Pull Requests)
- Deployment plan established (patch or standard release)
- New automated tests added (or follow-up stories created)
- CI/CD in place for the project
Acceptance Criteria Guidelines
Checklist for Writing Acceptance Criteria
- Clear to everyone involved
- Can be tested or verified
- Binary - passes or fails (not 50% complete)
- Outcome-focused, not implementation-focused
- As specific as possible
Examples
Vague (Bad):
“Page loads fast”
Specific (Good):
“Page loads in under 3 seconds on standard broadband connection”
Implementation-focused (Bad):
“Add a dropdown menu with options A, B, C”
Outcome-focused (Good):
“User can select from available options without typing”
Test Plan Guidelines
The Test Plan describes how to verify that Acceptance Criteria are met.
Structure:
- Prerequisites/setup steps
- Actions to perform
- Expected results to verify
- Edge cases to check
Example:
1. Navigate to the Orders page
2. Click "New Order" button
3. Enter customer name "Test Customer"
4. Select product "Path2Acquisition"
5. Click "Submit"
6. Verify: Order confirmation displays with order number
7. Verify: Order appears in Orders list with status "Pending"
8. Edge case: Submit with empty customer name
9. Verify: Validation error displays
Issue Creation Quick Reference
Creating an Epic
Summary: [Brief problem statement]
Description:
## Persona Statement
As a [persona], I [want to], [so that].
## Current Context / Situation
[What exists today, what's wrong or missing]
## Desired Situation / Behavior
[What should happen after implementation]
Acceptance Criteria: [Use customfield_12700]
- Given [context], when [action], then [result]
- [Additional criteria...]
Test Plan: [Use customfield_15023]
- [Verification steps...]
Creating a Story
Summary: [Specific outcome to achieve]
Description:
[What this story accomplishes and why]
Acceptance Criteria:
- [Specific, testable criteria]
Test Plan:
- [How to verify]
Epic Link: [Parent epic key]
Creating a Bug
Summary: [Brief description of the problem]
Description:
## Bug Summary
[What is broken]
## Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Expected Behavior
[What should happen]
## Actual Behavior
[What is happening instead]
## Workaround
[Any temporary workaround, or "None"]
Related Documentation
- PROD-PATH Process - High-level interaction process
- User Story Template - Story writing guide
- Development Process - Sprint and development workflow
- jira-cli Tool - CLI for Jira operations