Menu
Back to Blog

Building an AI research command for documentation tickets

·5 min read

Tech writers spend a lot of time researching before they can start writing. Gathering context for a single ticket might mean jumping between several Jira tickets, existing documentation, internal wiki pages with PRDs or technical specs… Some tickets might have whole discussions with back and forths between stakeholders. And then, after you compiled all the relevant information and identified what information is already publicly available in the docs, you can then finally start writing a draft before passing it to the respective stakeholders.

What if we could automate the research part of the equation?

What I built: the /research command

To help me out with the research phase of the work, I created an OpenCode command that takes a Jira ticket ID and does all the research automatically. This means that the command will:

  • Fetch all the details from the ticket, including comments, linked issues, related engineering tickets, etc
  • Search the internal wiki for any documents related to the ticket, like PRDs, architecture docs, engineering notes
  • Read the live current docs pages to understand the existing content and find all related pages

The command itself is product-agnostic; it identifies the product from the ticket, not from a hardcoded list. This started out as something for myself, but then I thought that it could also be useful for my colleagues. So while my personal version has a stakeholder reference table for the products I own, the generic version I shared with my colleagues relies on the ticket to surface contacts (reporter, commenters, engineering ticket assignees, wiki doc authors).

The tool compiles all the information available in an easy and accessible way. Then if you want help with creating a draft, the command loads a couple of skills. Skills are reusable definitions that provide the AI specific domain knowledge, context, or instructions on demand:

  • A tech writer skill: This skill has writing workflow knowledge, like product docs paths, partial conventions, style quick reference, branch naming, and a pre-review checklist.
  • A docs framework skill: Framework-generic knowledge covering components, content type values, frontmatter rules, and partial rendering conventions.

The skills will only load if we ask the AI for help with writing a draft, since they only contain information relevant to writing the docs.

Real-world example

To test out the command, I fed it one of my tickets. The reporter was saying that a GraphQL API page had a few issues: missing parameter descriptions, no sample response, and an incomplete example.

The command did a few things:

  • Pulled the Jira ticket with all its comments and linked issues Scanned the internal wiki for information about the product, and found a PRD
  • Discovered the associated engineering tickets for the feature and their statuses
  • Read the current live pages to compare with what the ticket was saying was missing
  • Produced a structured research brief with questions for me to review

After reviewing the research presented, I asked it a few follow-up questions, and then asked it to write a draft. This was when the command loaded the skills to help out with this. These skills help the AI read from the local repo, understand the structure of the docs, and use our conventions for the style guide and component usage.

What worked well

  • Speed: The entire research + draft cycle took a fraction of the time it would take manually.
  • Thoroughness: We all know how hard it is to search for content scattered across internal tools. The AI was able to find a lot of related and useful information, like the PRD, the engineering tickets, related doc tickets, and internal engineering notes.
  • Context retention: The AI was able to hold the full picture in memory and could answer follow-up questions with specifics.
  • Style consistency: By reading the existing similar pages in the docs, it matched the established pattern.

The MCP integrations are the real enabler: Jira, the internal wiki, and docs search all in one session worked really well and were able to help find a lot of information for this task.

What to watch out for

Even though this tool helps accelerate the work of tech writers, it doesn't mean it's flawless. We still need to review the information and tap the knowledge from stakeholders to make sure the draft is accurate.

Key takeaways

Formalizing AI workflows into reusable commands makes them more reliable and consistent than having to write a prompt every time we need help with something. When I run this command, it follows the same research steps in the same order, which means it's easier to find everything relevant and not forget about something.

The two-phase approach (research first, writing second) is also worth the extra step, I think. Someone might want to just research a ticket and not write a draft. Also, this way the command works for other colleagues in the team who aren't tech writers.

MCP integrations are what make this a powerful tool. The ability to pull data from multiple internal tools in a single session is the foundation everything else is built on.

And as always: AI doesn't replace the tech writer's judgment. It replaces the tedious context-gathering so we can spend more time on the parts of the job that actually require expertise: deciding what customers need to know and how best to explain it.

If you want to try building something similar, OpenCode supports custom commands and agent skills. The setup takes a few minutes: define a command file with your research steps, create skill files with your docs framework conventions, and you have a reusable workflow. The OpenCode docs cover how to create commands and agent skills.