JIRA
Jira Project Management
Jira, by Atlassian, is a powerful project management and issue-tracking tool used by teams to plan, track, and release work, especially for software development, though adaptable for IT, marketing, and other departments. Its core concepts are issues (tasks, bugs, stories), projects (collections of issues), and boards (visual workflows like Scrum/Kanban). Jira enables agile methodologies, offers extensive customization, integrates with other tools, and provides reporting, making work transparent and efficient across organizations.
The core Jira issue types we use.
1 Epic
What it means
- A large, coherent body of work
- Typically spans multiple sprints
- Often maps to:
- one large MDX document
- or one major chapter / subsystem
In the system
- One Epic per:
- big spec doc
- or big chapter (if docs are huge)
Example
- ZYZ-120 – ZARA Validation Engine v1
MDX
- Epic is usually declared in frontmatter, not via
<JiraNeed type="Task" needId="JIRA#1-epic#1" jiraKey="ZYZ-661" />
2 Story (the default, most important one)
What it means
- A unit of intended functionality
- Something that delivers user, system, or platform value
- Should be:
- understandable
- testable
- demonstrable
In spec-driven docs
- A section that describes something that must exist
- “The system shall…”
Examples
- Implement rule registry with versioning
- Validate supplier data against ESRS schemas
- Compute Scope 3 emissions via PEF factors
MDX usage <JiraNeed type="Story" needId="JIRA#2-story-the-default-most-important-one#2" jiraKey="ZYZ-660" />
Rule of thumb
If the spec describes what the system does, it’s a Story.
3 Task
What it means
- Pure implementation or operational work
- No standalone “value” on its own
- Often technical or internal
In spec-driven docs
- Supporting work that exists because of a Story
- Often sub-sections that are clearly implementation details
Examples
- Add database migration for rule registry
- Refactor validation pipeline for performance
- Add caching layer for emission factors
MDX usage <JiraNeed type="Task" needId="JIRA#3-task#2" jiraKey="ZYZ-658" />
Rule of thumb
If removing it wouldn’t change what the system does, only how, it’s a Task.
4 Bug
What it means
- The system does not behave as specified
- Something contradicts an existing spec
In spec-driven docs
- Rarely authored proactively
- Usually linked after the fact to a section that defines correct behavior
Examples
- Validation incorrectly accepts invalid ESRS metric
- Monte Carlo engine returns non-deterministic results
MDX usage <JiraNeed type="Bug" needId="JIRA#4-bug#2" jiraKey="ZYZ-656" />
Rule of thumb
Bugs point back to a spec section — they don’t define new requirements.
5 Spike (important for architecture-heavy work)
What it means
- Time-boxed research or investigation
- Output is knowledge, decision, or prototype
- Not guaranteed to ship code
In ZAYAZ This is very relevant for:
- regulatory interpretation (CSRD edge cases)
- performance modeling
- data model uncertainty
- vendor / API evaluation
Examples
- Evaluate best approach for ESRS XBRL tagging
- Investigate verifier network trust scoring
- Compare Bayesian vs Monte Carlo for risk propagation
MDX usage <JiraNeed type="Spike" needId="JIRA#5-spike-important-for-architecture-heavy-work#2" jiraKey="ZYZ-654" />
Rule of thumb
If the outcome is learning or a decision, not a feature, it’s a Spike.
6 Validation / Test
For explicit traceability between spec and verification.
What it means
- A formal verification activity
- Test, rule, or audit logic tied to a spec section
Examples
- Validate rule registry against 1000 sample datasets
- ESRS E1 metric cross-check validation
- Auditor reproducibility test
MDX usage <JiraNeed type="Validation" needId="JIRA#6-validation-test#2" jiraKey="ZYZ-652" />
Why this is powerful
- We can later prove: “Every material spec section has at least one validation artifact”
This is gold for assurance and audits.
For ZAYAZ, we use these:
| Type | Use it when… |
|---|---|
| Epic | Big initiative / doc / subsystem (used in the Frontmatter) |
| Story | The spec defines required behavior |
| Task | Internal or supporting work |
| Bug | Behavior deviates from spec |
| Spike | Research / decision / exploration |
| Validation | Verification / audit / test logic |
That’s it. No more.
In Jira Cloud, some of these might not exist as actual Issue Types in our project (especially Spike, Validation).
So we implement a robust mapping layer:
| JiraNeed type | Jira issue type used | Labels added |
|---|---|---|
| Epic | Epic (only if allowed) else Story | need:epic |
| Story | Story (fallback Task) | need:story |
| Task | Task | need:task |
| Bug | Bug | need:bug |
| Spike | Task (or Story) | need:spike |
| Validation | Task | need:validation |
7. How this looks in MDX (clean and minimal)
Rule registry
<JiraNeed type="Story" needId="JIRA#rule-registry-rule-registry#1" jiraKey="ZYZ-650" sectionHeading="Rule registry {#rule-registry}" />
Version migration logic
<JiraNeed type="Task" needId="JIRA#version-migration-logic#1" jiraKey="ZYZ-649" sectionHeading="Version migration logic" />
Validation rules
<JiraNeed type="Validation" needId="JIRA#validation-rules#1" jiraKey="ZYZ-647" sectionHeading="Validation rules" />
At the top:
And later to aggregate multiple epics under one chapter:
Result:
- Docusaurus shows:
- progress bar
- number of Stories done vs total
- optional breakdown by type
- Jira stays clean and meaningful
- Humans don’t invent categories ad hoc
Final mental model (this matters)
- Story = what must exist
- Task = how we build it
- Bug = where it violates the spec
- Spike = what we need to learn first
- Validation = how we prove it works
For additional information we can do:
<JiraNeed type="Bug" summary="Fix slug normalization for × character" needId="JIRA#validation-rules#4" jiraKey="ZYZ-645" />
or...
<JiraNeed type="Task" needId="JIRA#validation-rules#2" jiraKey="ZYZ-641" />
8. Epic linking field (important Jira detail)
To link a Story/Task/Bug to an Epic, Jira uses a special field:
- often called “Epic Link” on company-managed projects
- sometimes “Parent” depending on project type/settings
So we will do the following:
- auto-discover field id from /rest/api/3/field
- OR allow you to set an env override:
✅ JIRA_EPIC_LINK_FIELD_ID=customfield_XXXXX
This is the one field id that typically must be provided if Jira doesn’t expose it clearly.