FE-578 Fix Shift+Enter Line Breaks in Jira Descriptions (ADF Native Processing) #49

Jahteo · 2025-12-02T16:31:28Z

Problem

Users were losing Shift+Enter line breaks (hard breaks) within bullet lists when updating Jira issues through our MCP tools. This happened because the codebase was doing lossy round-trip conversions: ADF → Markdown , which stripped out hardBreak nodes that don't cleanly map to Markdown, then converting that back -> ADF & uploading to Jira.

Solution

Refactored the write-next-story to work directly with native ADF (Atlassian Document Format) for all data manipulation, eliminating conversions entirely. Markdown is now only used one-way for AI prompt generation (never converted back).

Changes

write-next-story/core-logic.ts uses new parseShellStoriesFromAdf() & addCompletionMarkerToStory() for epic updates
figma-screen-setup.ts returns ADF structures as well as Markdown now. Renames some of it's return values for clarity.
Preserved all ADF node types including hardBreak, nested lists, marks, inline cards, mentions, etc.

…. & Add ADF manipulation utilities to facilitate direct ADF operations

…nversion

- implement ADF to Markdown conversion utilities for AI prompt generation

…enhance prompt generation details

…pic updates

Copilot

Pull request overview

This PR refactors the codebase to work natively with ADF (Atlassian Document Format) instead of performing lossy Markdown round-trip conversions. The primary goal is to preserve hardBreak nodes (Shift+Enter line breaks) and other ADF formatting that gets lost when converting ADF → Markdown → ADF.

Key changes:

Renamed conversion functions to convertMarkdownToAdf_NewContentOnly() and convertAdfToMarkdown_AIPromptOnly() with clear usage constraints
Created comprehensive ADF manipulation utilities in adf-operations.ts
Implemented ADF-native shell story parser to replace Markdown-based parsing
Refactored business logic in write-next-story and write-shell-stories tools to use native ADF operations
Introduced AIPromptContext interface to enforce one-way Markdown conversion for AI prompts only

Benefits: Preserves all Jira formatting (hardBreaks, nested lists, marks, etc.), reduces AI token costs by 3-4x, prevents data corruption, and improves overall system reliability.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`specs/adf-native-processing-refactor.md`	Comprehensive implementation plan and design decisions for the ADF native refactor
`server/providers/atlassian/markdown-converter.ts`	Renamed conversion functions with usage warnings in JSDoc
`server/providers/atlassian/adf-operations.ts`	New pure ADF manipulation utilities (extract, remove, append, replace sections)
`server/providers/combined/tools/shared/shell-story-adf-parser.ts`	New ADF-based parser replacing Markdown parser, preserves all node types
`server/providers/combined/tools/shared/ai-prompt-context.ts`	Centralized AI prompt context conversion with _AIPromptOnly naming
`server/providers/combined/tools/writing-shell-stories/figma-screen-setup.ts`	Updated interface to return ADF fields instead of Markdown
`server/providers/combined/tools/writing-shell-stories/core-logic.ts`	Refactored to use ADF operations and AIPromptContext
`server/providers/combined/tools/write-next-story/core-logic.ts`	Refactored to use ADF operations for epic updates
`server/providers/combined/tools/write-next-story/prompt-story-generation.ts`	Updated to build prompts from parsed fields instead of rawContent
`server/providers/combined/tools/shared/screen-analysis-pipeline.ts`	Updated to use prepareAIPromptContext()
`server/providers/atlassian/test-fixtures/adf/*.json`	Test fixtures for ADF structures with hardBreaks, shell stories
`server/providers/combined/tools/shared/shell-story-adf-parser.test.ts`	Comprehensive test suite for ADF parser (733 lines)
`server/providers/atlassian/adf-operations.test.ts`	Comprehensive test suite for ADF operations (501 lines)
`server/providers/atlassian/markdown-converter.test.ts`	Updated function names in existing tests
Various tool files	Updated import statements to use renamed conversion functions

server/providers/combined/tools/shared/ai-prompt-context.ts

server/providers/combined/tools/write-next-story/core-logic.ts

server/providers/combined/tools/write-next-story/prompt-story-generation.ts

server/providers/combined/tools/shared/screen-analysis-pipeline.ts

server/providers/combined/tools/shared/shell-story-adf-parser.ts

…tests

…sing

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Jahteo · 2025-12-03T19:30:55Z

server/providers/combined/tools/writing-shell-stories/figma-screen-setup.ts

+    epicSansShellStoriesMarkdown,
+    epicSansShellStoriesAdf,
+    epicDescriptionAdf: description,
+    shellStoriesAdf,


epicContext, epicMarkdown & contentWithoutShellStories needed more explicit names & to clarify if they were markdown or adf. I think another file is misusing epicContent as if it was epicSansScopeAnalysis.

Nitpick:

personally I'd use epicSansShellStoriesMD instead of epicSansShellStoriesMarkdown (& epicSansShellStoriesADF), but I kept with repo conventions for now

I also think epicContent should be renamed across the entire repo, but for now only renamed it in select files

Jahteo · 2025-12-03T19:43:47Z

server/providers/combined/tools/writing-shell-stories/figma-screen-setup.ts

+    epicSansShellStoriesMarkdown,
+    epicSansShellStoriesAdf,
+    epicDescriptionAdf: description,
+    shellStoriesAdf,


Changes made here:

rename epicContent & contentWithoutShellStories for clarity

provide epicDescriptionAdf instead of epicMarkdown, so write-next-story can update adf directly & not have data loss

provide shellStoriesAdf so write-next-story doesn't have to duplicate the extraction. (shellStoriesAdf is already provided when contentWithoutShellStories are is extracted from the adfDoc)

Jahteo · 2025-12-03T19:50:52Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

 */
-export function parseShellStories(shellStoriesContent: string): ParsedShellStory[] {
-  const stories: ParsedShellStory[] = [];
+export function parseShellStories(shellStoriesContent: string): ParsedShellStoryMarkdown[] {


@justinbmeyer
parseShellStories & ParsedShellStoryMarkdown are only used in write-next-story-old.ts.
Can we delete that file and delete these?

justinbmeyer · 2025-12-03T20:38:41Z

server/providers/combined/tools/analyze-feature-scope/core-logic.ts

    yamlContent,
-    epicContext,
-    contentWithoutSection,
+    epicSansShellStoriesMarkdown: epicContext,


Use epicWithoutShellStoriesMarkdown

Without is more comman than Sans outside design contexts

Will do. updated in next commit.

That's what I initially had anyways, but then I over-optimized trying to make it shorter. I was also on the fence over it bc Sans isn't as quickly comprehended, didn't know that it was used in design contexts.

justinbmeyer · 2025-12-03T20:42:21Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+ *   "https://bitovi.atlassian.net/browse/PROJ-123"
+ * );
+ */
+export function addCompletionMarkerToStory(


This should probably be addCompletionMarkerToShellStory. It's probably good to distinguish between "stories" and "shell stories".

Agreed. Updated in next commit.

justinbmeyer · 2025-12-03T20:47:30Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+  // Convert entire listItem to markdown for AI prompts (preserves original formatting)
+  const rawContent = convertAdfNodesToMarkdown([listItem]);
+
+  return {


Is any of this actually needed?

We just needed to know if shell stories exist, I don't believe we needed any of this sort of information.

These were all added for parity with the original function, but you're right that some aren't needed.
I'm removing

timestamps

included

lowPriority

excluded

questions
and adding comments to the rest to point out where they're used

…logic - Deleted `write-next-story-old.ts` - Renamed variables and properties - removed unneeded returns from `parseShellStoryFromListItem`

…ions

justinbmeyer · 2025-12-04T18:19:26Z

server/providers/combined/tools/write-next-story/core-logic.ts

+
+  // Validate shellStoriesAdf data structure
+  if (!Array.isArray(setupResult.shellStoriesAdf)) {
+    throw new Error(`Epic ${setupResult.epicKey} has invalid shellStoriesAdf data (expected array, got ${typeof setupResult.shellStoriesAdf})`);


Users can see these errors we throw. I'm not sure this would be a good error for them to understand. Under what circumstances could this ever happen?

Unneeded & removed. I think this was a holdover from some other refactoring I reverted.

justinbmeyer · 2025-12-04T18:23:21Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

-  const storyBlocks = shellStoriesContent.split(/\n- /);
+  // Find the story's listItem
+  for (const node of newSection) {
+    if (node.type === 'bulletList' && node.content) {


Is there some way to clean up this?

I wonder if there's some sort of JSON-query type library we could bring in that would let us parse this more simply ...

const para = itemContent.find(node => node.type === 'paragraph') ?? null;
if (!para?.content) return null;

for (const textNode of para.content) {
if (textNode.type === 'text' && hasMarkType(textNode, 'code')) {
const match = textNode.text?.match(/^st\d+$/);
if (match) return match[0];
}
}

.find( [ {type: 'bulletList'}, {type: 'paragraph', index: 0}, {type: 'text'}, {text: /^st\d+$/}] )

for each main shell story list item check if it has the same id if it has the same id for each paragraph in the list item for nodes in the paragraph IF storyId, skip (but mark we found the id) IF title, turn node into a link IF separator, mark as found IF description check for `em` for date IF no date, add date at the end

findInSequence(p, [{type: 'text', marks: ['cide']}, {type: 'text'}]

forEachWithContent(newSection, {type: 'bulletList'}, (bulletedList) => { const id = extractStoryId(listItem.content); if (id === storyId) { forEachWithContent(listItem.content, {type: 'paragraph'}, (para) => { const {title, id, description, timestamp } = findTitleParts(para.content) const titleNode = findShellStoryTitleNodeFromParagraph(para.content); if(title) addLinkToNode( title, {url} ) if(!timestamp){ para.content.push({ type: 'text', text: ' ' }); para.content.push({ type: 'text', text: `(${new Date().toISOString()})`, marks: [{ type: 'em' }] }); } else{ timestamp.text = `(${new Date().toISOString()})`, } }) } }) function findTitleParts(){ }

justinbmeyer · 2025-12-05T02:59:40Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+      if (id !== storyId) return;
+      storyFound = true;
+      forEachWithContent(listItem.content!, { type: 'paragraph' }, (paragraph) => {
+        if (!paragraph.content) return;


forEachWithContent already ensures paragraph.content (hence the "WithContent" part of the helper). This check isn't needed.

fixed. Added the type-narrowing in forEachWithContent that was missing

justinbmeyer · 2025-12-05T03:03:41Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+}
+
+// Find title parts from a paragraph content: title nodes between ID and separator
+function findTitleParts(content: ADFNode[]): { titleNodes: ADFNode[] } {


Why doesn't this look more like: const {title, id, description, timestamp } = findTitleParts(para.content) as suggested in the comment?

This way it could be used also by extractStoryId and we can do an "upsert" more or less on the timestamp?

Also, part of the goal was to separate parsing and mutation. appendOrUpdateTimestamp is doing both still now.

This would but

Why doesn't this look more like: const {title, id, description, timestamp } = findTitleParts(para.content) as suggested in the comment?

updated. id & description aren't needed here though, so I left them out. findTitleParts became extractTitleParts & does return storyId & descriptionString, but those are only used in other functions

This way it could be used also by extractStoryId ...

extractStoryId needs to do a depth search, so I kept them separate.

part of the goal was to separate parsing and mutation. appendOrUpdateTimestamp is doing both still now.

resolved by doing them inline like the initial example instead of splitting appendOrUpdateTimestamp

justinbmeyer

See my comments

…ontent

…mp logic

justinbmeyer · 2025-12-08T21:27:33Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+  forEachWithContent(itemContent, { type: 'bulletList' }, (bulletList) => {
+    forEachWithContent(bulletList.content, { type: 'listItem' }, (listItem) => {
+      forEachWithContent(listItem.content, { type: 'paragraph' }, (paragraph) => {
+        const content = paragraph.content ?? [];


doesn't forEachWithContent mean paragraph.content will always exist and have one element?

justinbmeyer · 2025-12-08T21:28:03Z

server/providers/combined/tools/write-next-story/shell-story-parser.ts

+  forEachWithContent(itemContent, { type: 'bulletList' }, (bulletList) => {
+    forEachWithContent(bulletList.content, { type: 'listItem' }, (listItem) => {
+      forEachWithContent(listItem.content, { type: 'paragraph' }, (paragraph) => {
+        const content = paragraph.content ?? [];


same comments as above

Jahteo added 7 commits December 1, 2025 20:19

refactor: rename markdown conversion functions for clarity and safety…

5cf1f83

…. & Add ADF manipulation utilities to facilitate direct ADF operations

feat: add ADF-based shell story parser to eliminate lossy Markdown co…

6922fed

…nversion

clean: use structuredClone instead of diy'ing it

fd49384

step3: refactor figma-screen-setup

bd8b6f0

- implement ADF to Markdown conversion utilities for AI prompt generation

step4: refactor: update shell story processing to use ADF parser and …

9e1cd8d

…enhance prompt generation details

step5: refactor: integrate ADF processing for AI prompt context and e…

de0c1df

…pic updates

add tests

0d7097c

Jahteo temporarily deployed to test December 2, 2025 16:31 — with GitHub Actions Inactive

Jahteo requested review from Copilot and justinbmeyer December 2, 2025 16:31

Copilot started reviewing on behalf of Jahteo December 2, 2025 16:32 View session

Copilot finished reviewing on behalf of Jahteo December 2, 2025 16:34

Copilot AI reviewed Dec 2, 2025

View reviewed changes

Jahteo added 2 commits December 2, 2025 09:30

fix old import

78130ad

cleanup notes

46c8cd2

Jahteo temporarily deployed to test December 2, 2025 17:31 — with GitHub Actions Inactive

fix: update CI workflow to use npm ci and enhance type safety in API …

e08284b

…tests

Jahteo temporarily deployed to test December 2, 2025 17:47 — with GitHub Actions Inactive

Merge branch 'main' into FE-578-fix-shift-enter-via-native-adf-proces…

452e580

…sing

Jahteo temporarily deployed to test December 2, 2025 17:50 — with GitHub Actions Inactive

fix: update markdown converter import and adjust tsconfig exclusions

b4f7e1e

Jahteo temporarily deployed to test December 2, 2025 17:59 — with GitHub Actions Inactive

remove unused imports

f77399c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Jahteo temporarily deployed to test December 2, 2025 18:01 — with GitHub Actions Inactive

remove unused import

dd3cfb0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Jahteo temporarily deployed to test December 2, 2025 18:02 — with GitHub Actions Inactive

Jahteo commented Dec 3, 2025

View reviewed changes

justinbmeyer requested changes Dec 3, 2025

View reviewed changes

Jahteo added 2 commits December 4, 2025 08:19

refactor: remove deprecated write-next-story tool and update related …

4018561

…logic - Deleted `write-next-story-old.ts` - Renamed variables and properties - removed unneeded returns from `parseShellStoryFromListItem`

refactor: simplify paragraph extraction logic and remove unused funct…

c3f816f

…ions

Jahteo temporarily deployed to test December 4, 2025 16:26 — with GitHub Actions Inactive

justinbmeyer reviewed Dec 4, 2025

View reviewed changes

refactor: helper functions for better readability and maintainability

40e99b8

Jahteo temporarily deployed to test December 5, 2025 00:51 — with GitHub Actions Inactive

justinbmeyer reviewed Dec 5, 2025

View reviewed changes

justinbmeyer requested changes Dec 5, 2025

View reviewed changes

Jahteo added 3 commits December 5, 2025 08:36

add type narrowing to forEachWithContent so callback knows node has c…

3025dbe

…ontent

refactor: enhance shell story parsing by extracting title and timesta…

5056654

…mp logic

clean: title is only 1 node

14d6c00

Jahteo temporarily deployed to test December 8, 2025 18:57 — with GitHub Actions Inactive

clean: remove uneeded error, fix tests

12e5c09

Jahteo temporarily deployed to test December 8, 2025 19:27 — with GitHub Actions Inactive

Jahteo requested review from justinbmeyer December 8, 2025 19:33

justinbmeyer reviewed Dec 8, 2025

View reviewed changes

justinbmeyer approved these changes Dec 8, 2025

View reviewed changes

justinbmeyer merged commit 231899a into main Dec 8, 2025
4 checks passed

FE-578 Fix Shift+Enter Line Breaks in Jira Descriptions (ADF Native Processing) #49

FE-578 Fix Shift+Enter Line Breaks in Jira Descriptions (ADF Native Processing) #49

Uh oh!

Conversation

Jahteo commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinbmeyer Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinbmeyer Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinbmeyer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Jahteo commented Dec 2, 2025 •

edited

Loading

justinbmeyer Dec 4, 2025 •

edited

Loading

justinbmeyer Dec 4, 2025 •

edited

Loading