StoryDoc

• 

  StoryDoc working in a command line.

Inspiration

Every Salesforce developer has the same problem. After a pull request is merged, we spend a lot of time writing documentation. We have to explain what changed for Jira, Confluence, testing, release management, and production support.

It is repetitive, time-consuming, and often gets skipped because of deadlines.

I kept thinking, the pull request already shows what changed, and the Jira story already explains why it changed. Why can't AI create the documentation for us? That idea became StoryDoc.

What it does

StoryDoc is a CLI tool that generates technical documentation grounded in JIRA requirements, technical design and git pull request.

With a single command, it reads the Jira story, technical design, and pull request, then uses Codex SDK and GPT-5.6 to understand the implementation and generate documentation.

Instead of manually writing pages of notes, developers get implementation details, changed Salesforce components, testing information, deployment notes, and manual steps in minutes.

How we built it

We built StoryDoc using TypeScript, the OpenAI Codex SDK, GPT-5.6 Terra and Luna, the Jira REST API, and the GitHub CLI.

Terra reads the Jira story and extracts the requirements and design details.

Luna then looks at the Salesforce pull-request changes and compares them with the Jira Technical Design. It only reports differences that are supported by real evidence from the pull request.

A second Luna step creates the short Solution Overview.

We also added strict validation. Every update created by the AI must point to a file that was actually changed in the pull request. When it refers to the Jira design, the referenced text must also exist in the original design.

Challenges we ran into

The biggest challenge was preventing unsupported AI conclusions.

We addressed this by preserving the Jira Technical Design instead of asking AI to replace it. Luna can only propose targeted pull-request updates, and StoryDoc rejects those updates if their cited files are not in the PR or their Jira references are not present in the supplied design.

Another major challenge was the size and noise of Salesforce metadata pull requests. A single feature can include large XML metadata files, generated sidecar files, profiles, permission sets, translations, and long Git diff context. Sending all of that directly to an LLM would increase token usage, cost, and analysis time.

To solve this, we introduced a trimming methodology before Luna analyses the PR. StoryDoc filters low-value Salesforce noise such as metadata sidecars, profiles, permission sets, translation files, and lock files. It also extracts only changed Git hunks and keeps a maximum of two unchanged context lines around each change. The original and compressed inputs are recorded in a compression audit file, so the process remains transparent and reviewable.

This gave Luna a smaller, higher-signal input while preserving the implementation changes that matter.

Accomplishments that we're proud of

Built a working local-first CLI that connects a Salesforce pull request with its Jira story and Technical Design.

Reduced token usage for large Salesforce pull requests by filtering metadata noise and trimming Git diff context before AI analysis.

Added Jira rich-text table support, so field inventories remain readable Markdown tables without requiring an AI formatting call.

What we learned

We learned that AI-generated documentation works best when it is based on trusted information and given a very specific job.

Instead of asking AI to create the full technical design from scratch, StoryDoc keeps the original Jira Technical Design and only checks the pull request for important differences. This makes the final document much easier to review and trust.

We also learned that Salesforce metadata needs special handling. Some metadata files and Git diffs can be very large and contain a lot of unnecessary information.

So, StoryDoc filters out low-value files and keeps only the relevant parts of the diff. This helps reduce token usage, speeds up the analysis, and improves the quality of the output.

What's next for StoryDoc

Next, we want to improve the quality of the documentation even further by testing StoryDoc with many different Salesforce stories, technical designs, and pull requests. This will help us understand how well it performs across different types of implementations and continue improving the output.

We also want to explore using a more powerful model, like GPT-5.6 Sol, for more complex implementations where higher accuracy is needed, while still keeping an eye on token usage and overall cost.

Finally, we'd like to expand StoryDoc beyond GitHub by supporting other source control and DevOps platforms, such as GitLab, Bitbucket, and Azure DevOps, so more development teams can use it without changing their existing workflow.

Built With

• node.js
• typescript