The part before writing is the slowest part — so I automated it

The other day I closed a P1 ticket that asked me to review a 5-lesson internal training course and figure out what was missing from our developer docs. The scope was big: compare the training material against hundreds of existing pages, identify content gaps, draft new conceptual documentation, and create follow-up tickets for anything out of scope.

Normally, this kind of work takes the better part of a week. Research alone (reading the training, cross-referencing existing docs, searching the wiki, identifying stakeholders) can easily take a few days at least before you write a single word. This was exactly why I've created a while back the /research command in OpenCode. Recently, I got to put it to the test for the first time with a big task, and the whole thing went from ticket to merged PR in about two working days.

Here is what happened, and what I learned along the way.

The problem

The ticket was straightforward in theory: my manager created it asking me to review an internal training course and determine what content gaps existed in our developer docs. Specifically:

• What is in the training that is not in our docs?
• What is explained so an everyday user could understand it?
• What cross-product workflows are covered? Are they in our docs?

The catch was timing. I was in the middle of a large product renaming project across the entire docs site. That consumed most of my time for several days. I could not properly start writing for this ticket until a week later, when the rename work was done.

Scoping the work while blocked

Even though I could not start writing, I did not want to go into this ticket blind. Between rename batches, I ran /research with the ticket ID twice to understand what I was dealing with. Each session took a few minutes. The command pulled the ticket from our issue tracker, searched the internal wiki for the training course and related architecture docs, mapped the existing developer docs, and identified stakeholders, all automatically.

Those two sessions gave me a first pass at the gap analysis. I could see which parts of the training course were already covered in our docs and which were not. I knew the rough shape of the work before I had time to do it. This turned out to be valuable for two reasons: I could plan my sprint knowing what was ahead, and when I finally sat down to write, I did not have to start from scratch.

The reason for running the command twice wasn't because it didn't work properly or didn't have enough information. It was because I was doing so much at the same time that I lost track of the OpenCode sessions with the conclusions. And, to be honest, those initial runs were only to have a general idea of the scope of work that would be waiting for me when I finally started it.

Picking it back up

A week later, I opened a new session and ran /research again. The command did the same research steps:

1. Pulled the ticket: full description, all comments (including the discussion about prioritization), linked issues, and the parent epic.
2. Searched the wiki: found related internal documentation, architecture docs, and the training course itself.
3. Mapped existing documentation: identified the relevant docs paths, existing pages that would need cross-linking, and shared partials already in use.
4. Identified stakeholders: pulled potential reviewers from the ticket participants, wiki authors, and code owners.

Within minutes, I had a fresh research brief. But this time I also asked the AI to review the conclusions from the two earlier sessions and merge them with the current state of the docs, which had changed significantly after the rename. Product names were different, URLs had moved, and some pages I had flagged as gaps in the first pass were no longer relevant.

From research to gap analysis

The consolidated gap analysis identified the biggest missing piece: there was no conceptual page explaining WAN transformation: why a customer would want to transform their wide area network, what problems it solves, and what the migration journey looks like. Our docs explained how to configure things, but not why someone would go through the process in the first place.

This was the kind of insight that is hard to arrive at by just reading individual pages. You need to see the full picture (what the training says, what the docs say, and what the gap between them looks like) all at once. Having the research brief in front of me made this comparison much faster.

Transitioning to writing

Once the gap analysis was clear, I told the AI to proceed with writing a first draft. At this point, the /research command loaded a custom skill file (our canonical source of truth for all docs conventions) and prepared a working branch.

The plan was to:

• Create 3 new files: a shared partial with all the content, plus two wrapper pages so the same content appears in two different sections of the docs site
• Edit 6 existing files: overview pages, index pages, a related resources section, and sidebar ordering

The AI produced a complete first draft covering:

• What traditional WANs look like and why they create bottlenecks
• Four reasons to transform your WAN (cost, security, vendor lock-in, operational complexity)
• A comparison table of different WAN approaches
• A 4-step incremental migration path
• Next steps with cross-links to related docs

The iteration loop

This is where the real value showed up. The first draft was solid, but the back-and-forth between me and the AI caught several issues that needed work. For example, the AI assumed readers know what WAN transformation means. The link from the overview page had no context, but I knew we needed some to help readers understand the difference between traditional and modern WAN approaches. We rewrote it to draw a concrete contrast instead of assuming the terminology was self-explanatory.

The outcome

By the end of the next morning, I had:

• A complete conceptual page published in two sections of the docs site
• Six existing pages updated with cross-links and improved framing
• A PR opened, reviewed, and merged
• Three follow-up tickets created for remaining gaps
• A detailed comment on the original ticket summarizing everything that was done

The ticket was closed as Done.

What I learned

The research phase is where the most time is saved

I used to spend a lot of time manually gathering context before I could start writing. Open the ticket, read the comments, search the wiki, check what docs already exist, figure out who to ask for review. With /research, all of that happens in one step. The structured brief it produces also forces you to think about the work systematically before diving in: which stakeholders to loop in if needed, what open questions remain, and what existing pages need updating.

You can scope work before you have time to do it

The two preliminary sessions cost me a few minutes each, but they meant I walked into the writing phase already knowing the shape of the work. I did not have to re-read the training course from scratch or wonder how big the task was. If you have a ticket in your backlog that you cannot start yet, running /research on it is a low-cost way to understand what you are getting into.

One session, one source of truth

I named the final session "source of truth" deliberately. By keeping all the research, gap analysis, planning, drafting, and iteration in a single session, I never lost context. The AI remembered the gap analysis when we were writing, remembered the stakeholder list when we needed to comment on the ticket, and remembered the file structure decisions when we were fixing build errors. No tab-switching, no re-explaining.

The AI gets better as you work with it

Every time I corrected something (a casing inconsistency, a component misuse, a missing acronym expansion), the AI adapted for the rest of the session. More importantly, when the correction pointed to a gap in our skill files (the instruction sets that guide the AI), we fixed the skill right there. This means the next person who runs /research or /draft benefits from those fixes automatically.

Advice: When you catch the AI doing something wrong, do not just fix the output. Ask if the rule exists in the relevant skill. If it does not, update the skill. This compounds over time.

It is not a replacement; it is a multiplier

The AI did not write the page by itself. I directed every decision: which gaps to prioritize, how to frame the content, what tone to strike, when the language was too marketing-heavy, where to add cross-links. What the AI did was handle the mechanics (fetching context, producing structured drafts, making bulk edits across multiple files, checking for broken links, creating tickets) so I could focus on the editorial judgment that actually matters.

The /research command

The /research command is a custom OpenCode slash command I built for our documentation team. It automates the research phase of a documentation project by pulling context from multiple sources (issue trackers, wikis, existing docs, and code repositories) and producing a structured research brief. When you are ready to write, it loads the relevant style guide rules and prepares a working branch.

If you use OpenCode, you can build something similar. The command is essentially a detailed prompt file that tells the AI what steps to follow: fetch the ticket, search the wiki, map existing docs, identify stakeholders, and present a structured brief. OpenCode's custom commands make this reusable across sessions and shareable with a team.