How to Teach an AI Agent to Read & Write a Report Based on Any Topic in Jira

A guide for non-technical people who want to ask an AI, "Tell me everything we did on Feature X over the last six months."

Imagine you are a manager or team lead. You want to know: "What has my team done about Feature X over the last six months? What features did we ship, what bugs did we fix, and where do things stand today?"

Your team tracks all their work in Jira — a popular project management tool where tickets (called "issues") live on boards organized into time-boxed work cycles called "sprints" (an agile development cycle methodology). But going through hundreds of issues by hand, reading every comment, and piecing together a timeline would take you all day. Maybe all week. And maybe even Jira inhouse agent doesn't give you the full picture with all the details that you want.

This article explains how to set up guidelines — a step-by-step instruction manual — that you can give to an AI agent so it can do all of that for you automatically. The agent will log into Jira, find the right boards, search for issues related to your topic, read the comments, organize everything by sprint, summarize what happened, and hand you a polished report.

Think of it like writing a recipe for a very capable assistant who has never been to your kitchen before. If you give them clear, step-by-step instructions, they can cook the meal perfectly every time.

If you want a different meal, you can simply change your request a bit to make another meal still based on the guidelines you already gave it (your allergies, food preferences, temperature preferences etc). Similarly, with this guildine, you can change what feature you want to know about and what timeline you need and your agent will used the rest of what's in this guide to create another standard report.

Why You Need a Structured Set of Guidelines

When someone says, "Summarize everything we did on Feature X this quarter," that isn't one single action. It's actually a chain of about ten separate steps that have to be taken to get the data you need, sort through it, and present it well. The agent needs to:

1. Log into your Jira account
2. Find the right project boards
3. Identify which boards are the ones you care about
4. Pull all the issues (tickets) off those boards
5. Filter those issues down to just the ones related to your topic
6. Go back and fetch detailed information on each of those issues — including comments, sub-tasks, and sprint history
7. Read and make sense of all the comments in the conversation threads
8. Sort everything in chronological order by sprint
9. Write a clear summary for each issue
10. Generate a final report

If the agent tries to do this without a playbook, it will guess, make mistakes, miss issues, or get confused by formatting. All this does is waste tokens, generate reports that look different from one another, and cause you to have to give a super long prompt to ensure that your agent does exactly what you want each time you want a report about another topic. A structured set of guidelines ensures the agent does the same proven steps every single time, in the same order, with the same logic — producing a reliable, accurate report you can trust.

Before You Start: What You Need

Think of these as the ingredients and tools you need before you begin cooking.

There are also two golden rules to include in your guidelines:

• Read-only: The agent should only read information from Jira. It should never move, change, comment on, or delete anything. It is a researcher, not an editor.
• Exact titles: When the agent writes the report, every issue title must match what Jira says — no abbreviations, no shortening, no creative rewording.

Step 1: Verify the Agent Can Log In

Before the agent does anything else, it needs to prove it can successfully connect to your Jira account. Think of this like checking that your keys work before you drive somewhere.

The agent tries to connect to Jira using the access token (that special password). If the connection works, Jira sends back basic information about who the agent is logged in as — their name, email, and account ID. If the connection fails, Jira sends back an "unauthorized" message, which means the token is wrong or expired.

What to include in your guidelines: Tell the agent that if it can't log in, it should stop immediately and ask a human for a fresh token. It should not keep trying or move on to the next step.

Step 2: Discover the Scrum Boards

In Jira, work is organized into boards. A board is like a bulletin board where all the team's tickets are pinned up, organized into columns like "To Do," "In Progress," and "Done." A Scrum board is a specific type of board used by teams that work in sprints (fixed-length work cycles, usually 2 weeks).

The agent's job in this step is to ask Jira for a list of every board that exists in your account. Jira will return a list with each board's name, type, and a unique ID number.

What to include in your guidelines: Tell the agent to look specifically for boards where the type is "scrum." Tell it to ignore other types and take note of their unique ID number for each scrum board — the agent will need those numbers later when fetching the data through API calls.

Step 3: Identify the Target Boards

Not every scrum board is relevant to your report. If your company has fifteen scrum boards but you only care about the "Sprint Planning" board, the agent needs to figure out which board(s) to focus on.

The agent matches board names against what you (the user) asked for. For example:

• If you said "Sprint Planning," the agent finds the board with that name
• If you said "all boards," the agent goes through every scrum board one by one
• If you said a specific board name, the agent matches it exactly

What to include in your guidelines: Include a simple mapping — "If the user says X, look for Y." Also tell the agent that in Jira, closed or past sprints don't live on a separate board. They are part of the same board's history. So if someone asks for "past sprints," the agent should look at the same scrum board's closed sprint history, not go hunting for a different board.

Step 4: Pull All Issues from the Board

Now the agent knows which board(s) to look at. The next step is to download every issue (ticket) from that board.

Jira doesn't hand over all the issues at once — it gives them in batches, like dealing cards from a deck. The agent asks for the first batch (usually 100 issues at a time), and if there are more, it asks for the next batch, and so on until it has everything. Most sprint boards have somewhere between 200 and 400 issues, so this typically takes about 3 to 5 rounds of asking.

What to include in your guidelines: Tell the agent to keep fetching batches until it has collected every single issue. It should not stop early or assume there are no more just because the first batch came back. The agent should also grab basic information about each issue at this stage: the title, the status (Done, In Progress, etc.), the type (Bug, Story, Task, Epic), who it's assigned to, when it was created, and when it was last updated.

Step 5: Filter Issues by Your Topic Keyword

At this point the agent might be holding 400 issues, but you only care about the ones related to your topic. Let's say your keyword is "Feature X." The agent goes through every issue title and keeps only the ones that contain that word.

This is a simple text search — if "Feature X" appears anywhere in the issue title, it's a match. The search should not care about capital letters — "Feature X," "FEATURE X," and "feature x" should all count as matches.

What to include in your guidelines: Tell the agent to search the issue title (the "summary" field in Jira) for the keyword, ignoring uppercase and lowercase differences. Save the unique key for every issue that matches (Jira gives each issue a key like "PROJ-123"). The agent will need those keys in the next step.

Step 6: Fetch Detailed Information on Each Matching Issue

Now the agent has a list of, say, 25 issues related to "Feature X." But so far, the agent only has basic information — the title, status, and type. To write a meaningful report, the agent needs much more detail.

The agent goes back to Jira and asks for full details on each of those 25 issues. Specifically, it asks for:

• Comments — the entire conversation thread on each issue, including who said what and when they said it
• Sub-tasks — smaller tasks that are part of a bigger issue (for example, an epic called "Build Feature X Login Page" might have sub-tasks for "Design the form," "Write the backend code," and "Test on mobile")
• Sprint membership — which sprint each issue belongs to, including the sprint name and start date
• Fix versions — which software release version the issue was fixed in
• Labels and components — tags that help categorize the work

What to include in your guidelines: Tell the agent to use the issue keys it collected in Step 5 to fetch full details. Make sure the agent specifically requests the comments, sub-tasks, and sprint fields — Jira does not include these by default. If the agent forgets to ask for them, they won't be included and the report will be incomplete.

Step 7: Extract and Make Sense of the Comments

This is where the real gold is. Most of the story of what happened on an issue lives not in the issue title, but in the conversation that happened in the comments. Comments are where people discuss what went wrong, propose fixes, link to code changes, report test results, and share updates.

However, Jira comments are not clean, simple text. They can contain special formatting (like code blocks, quotes, and links formatted in Jira's own markup language), automated emails from release tools, and links to GitHub pull requests. The agent needs to clean these up — strip away the formatting junk — so the comments read like normal, readable text.

What to include in your guidelines: Tell the agent to:

1. Sort comments by the date they were created (oldest first) so the conversation reads in order
2. Strip out Jira's special formatting so the text is clean and readable
3. Skip any comment that starts with "Outgoing Email" — these are automated release-check notifications that add noise but no useful information
4. If the same GitHub pull request link appears multiple times, only keep the first one — avoid duplicates

From the cleaned-up comments, the agent should look for and extract three key pieces of information:

• Root cause: Any comment that mentions "Root Cause" or discusses why a bug happened
• Fix applied: Pull request links and merge messages that show what code was changed
• QA test results: Any "PASSED" or "FAILED" verdicts from testers

Step 8: Sort Everything Chronologically by Sprint

Now the agent has all the information it needs — but it's a big pile of issues and comments. To turn it into a timeline, the agent needs to organize everything in chronological order.

Each sprint in Jira has a human-readable name (like "Sprint 47 (Apr 25)") and a start date. The agent sorts all the issues by their sprint's start date, from oldest to newest. This puts the earliest work at the top and the most recent work at the bottom — exactly how a timeline should read.

Issues that are in the backlog (not assigned to any sprint yet) get sorted to the very end with a label that says "No Sprint (Backlog)."

What to include in your guidelines: Tell the agent to sort by the sprint start date, going from oldest to newest. Issues with no sprint should be grouped at the end, clearly labeled as backlog items so they don't get lost or confused with completed work.

Step 9: Summarize Each Issue

Now the agent writes a clear, structured summary for each issue. Think of this as the agent being a reporter who has done all the research and now writes the article.

For every issue, the agent produces the following sections:

What to include in your guidelines: Tell the agent to use this six-section structure for every single issue, every time. Consistency is key — if every issue summary follows the same format, the report is easy to read and compare. Also tell the agent to color-code the status (green for Done, gray for In Progress, blue for Selected for Development, amber for Backlog) so the reader can scan the report quickly.

Step 10: Generate the Final Report

The agent has done all the research, organized everything, and written all the summaries. Now it puts everything into a single, polished document — ideally a PDF that looks professional and is easy to read.

The report should contain:

1. A cover page — with the topic name, date, and some basic metadata (who requested it, which boards were searched)
2. An executive summary — a high-level overview paragraph plus a quick-stats table showing the total number of issues found, how many were bugs vs. features, the status breakdown, the sprint range covered, and who the developers and QA analysts were
3. A summary timeline table — one row per issue, in chronological order, showing the issue ID, sprint, title, type, and status
4. Detailed issue summaries — the full six-section write-up for each issue, in chronological order
5. An analysis section — the agent's observations about patterns: how many bugs vs. features, recurring themes, and notable trends
6. A methodology appendix — a behind-the-scenes section that documents exactly which boards were searched (by name and ID), how many issues were found total, all the issue keys included in the report, and a reminder that the agent only read data and never modified anything

What to include in your guidelines: Give the agent a clear checklist for what the report must contain. Emphasize that the visual design should be consistent — same fonts, same colors, same layout for every issue summary. The report represents your team's work, so it should look clean and professional.

Common Pitfalls: Teaching the Agent to Self-Correct

Even with perfect guidelines, the agent will sometimes run into problems. Jira is a complex system, and things don't always go smoothly. The key is to anticipate the most common issues and include instructions in your guidelines for how the agent should handle each one — so it can self-correct without stopping and waiting for a human to fix things.

Here are the most common pitfalls and what to tell your agent:

1. "I Can't Log In" (401 Unauthorized)

What happens: The agent tries to connect to Jira and gets an "unauthorized" error.

Why it happens: The access token is wrong, expired, or was never set up correctly.

What to include in your guidelines: Tell the agent: "If you get a 401 error, do not keep retrying. Stop, report the error to the human, and ask them to generate a new API token in their Atlassian account settings."

2. "I Can't Find the Board" (404 Not Found)

What happens: The agent tries to access a board and gets a "not found" error.

Why it happens: The board ID is wrong, or the account the agent is using doesn't have permission to view that board.

What to include in your guidelines: Tell the agent: "If you get a 404, double-check the board ID against the list you fetched in Step 2. If the ID is correct, the issue is likely a permissions problem — report it to the human and explain that the Jira account may not have access to that board."

3. "The Sprint Field Is Empty"

What happens: The agent pulls issue details, but the sprint information is completely blank — the agent can't tell which sprint an issue belongs to.

Why it happens: Different Jira accounts use different internal ID numbers for the "Sprint" field. The ID that works on one company's Jira might be different on another company's Jira.

What to include in your guidelines: Tell the agent: "If sprint data is missing, don't assume there are no sprints. Instead, query Jira's field list to find the correct custom field ID for 'Sprint' for this specific Jira account, then retry." This is a self-correction step — the agent diagnoses the problem and fixes it without human intervention.

4. "Jira Won't Give Me More Than 100 Issues at Once"

What happens: The agent asks for 500 issues in one request, and Jira rejects it.

Why it happens: Jira's agile API caps each request at 100 issues. This is a hard limit that can't be overridden.

What to include in your guidelines: Tell the agent: "Never request more than 100 issues per call. If there are more issues to fetch, increment your starting point and make another request. Keep going until you have collected all issues." This is essentially teaching the agent how to paginate — fetch in batches, not all at once.

5. "Sub-Tasks Are Missing from the Results"

What happens: The agent fetches issues, but the sub-tasks are nowhere to be found.

Why it happens: Jira's search doesn't automatically expand sub-tasks — you have to explicitly ask for them.

What to include in your guidelines: Tell the agent: "Always include subtasks in your fields list when fetching issue details. If sub-tasks are still missing, run a separate search using the parent issue keys — search for issues where the parent is one of the issue keys you already found."

6. "Duplicate GitHub Links Are Cluttering the Comments"

What happens: The same pull request link appears three or four times across different comments because every time someone merges code, an automated notification gets posted.

Why it happens: Jira integrations with GitHub post a comment every time a PR is referenced, updated, or merged, leading to repeats.

What to include in your guidelines: Tell the agent: "Deduplicate GitHub pull request links by their PR number. Only keep the first occurrence of each unique PR. Skip subsequent mentions of the same PR."

7. "Automated Email Comments Are Adding Noise"

What happens: Some comments are clearly not written by humans — they start with "Outgoing Email" and contain automated release-check notifications.

Why it happens: Certain tools (like release management or deployment systems) automatically post status updates to Jira issues.

What to include in your guidelines: Tell the agent: "Skip any comment whose body starts with 'Outgoing Email.' These are automated notifications that don't contain useful information for your report."

8. "The Description Field Breaks the Report"

What happens: When the agent tries to write the issue description into the report, the formatting is garbled — there are weird symbols, HTML tags, or layout code that makes the text unreadable.

Why it happens: Jira stores issue descriptions in a special format called Atlassian Document Format, which is not plain text. If the agent doesn't clean it up, it gets passed through raw and looks broken.

What to include in your guidelines: Tell the agent: "Always strip Jira markup and formatting from text fields before writing them into the report. Convert the text to clean, plain, readable text first."

9. "Emojis or Special Characters Crash the Report"

What happens: The report generation process crashes or errors out because someone used an emoji or a special character in a comment or issue title.

Why it happens: Some report-generation tools can't handle certain Unicode characters (like emojis) and will crash when they encounter them.

What to include in your guidelines: Tell the agent: "When reading JSON data from Jira, open it with error handling turned on so that problematic characters are replaced rather than causing a crash. Strip out any non-standard ASCII characters before writing them into the report."

Putting It All Together: The Big Picture

Here's how the entire process flows, from start to finish:

1. Verify credentials — Make sure the agent can log in to Jira
2. Discover boards — Get the full list of all boards in the account
3. Identify target boards — Pick the scrum boards that match what the user asked for
4. Pull all issues — Download every issue from those boards
5. Filter by keyword — Keep only the issues related to your topic
6. Fetch details — Go back and get full details on each matching issue (comments, sub-tasks, sprint info)
7. Extract and parse comments — Clean up the conversation threads and pull out root causes, fixes, and test results
8. Sort by sprint — Organize everything in chronological order
9. Summarize each issue — Write a structured summary for every issue
10. Generate the report — Compile everything into a polished PDF

Log in → Find boards → Pick the right ones → Download issues
                                                    |
                                                    v
        Build report ← Summarize each ← Sort by sprint ← Extract comments ← Fetch details ← Filter by keyword

The End Goal: What You Get to Ask

When all of these guidelines are in place, you get to ask your agent something like this:

"Find all epics, sprints, issues, and subtasks regarding the Feature X topic over the last six months. Give me a timeline of all the work we've done on Feature X — the features we released and the bugs we fixed. Summarize where we are at today based on that work."

And the agent will:

1. Log into your Jira account
2. Find every scrum board
3. Pull every issue from those boards
4. Filter down to just the ones mentioning "Feature X"
5. Fetch all the detailed information — comments, sub-tasks, sprint history
6. Read through every comment and extract the key insights
7. Organize everything chronologically by sprint
8. Write a clean, structured summary for each issue
9. Generate a professional PDF report with a cover page, executive summary, timeline table, detailed issue summaries, and an analysis section

All you did was ask a question. The agent did the rest — following the guidelines you gave it, step by step, self-correcting when it hit snags, and handing you a finished report you can share with your team or your stakeholders.

The beauty of this approach is that it's reusable. The next time you want a report on a different topic — "PushPay," "Honeywell," "login redesign," anything — you just swap the keyword. The same ten-step playbook runs again, with the same reliable results. You write the guidelines once, and your agent can summarize any topic, any sprint, any board, any time you ask.

Simplified from the Jira Agent Summary Blog (July 7, 2026). All Jira queries are read-only — the agent never modifies, comments on, or transitions any issue. The output is a report only.