Plan A Feature To Confluence

Step 5: Rewrite Cross-Links to Title Macros, Then Publish the Tree

Publishing is a single create pass: rewrite the cross-file links into title-based page-link macros first, then create each page once with its final body. No second update pass is needed, because the macros resolve by title and do not depend on any page URL or ID.

Decide every page's final title up front. The title is used in two places — as the page's create-title, and as the ri:content-title in every macro that links to that page — so pick each title once and reuse it in both, so they can never drift apart:

• Spec (the parent page): the feature name.
• Decision log: <Feature Name> — Decision Log.
• Team findings: <Feature Name> — Team Findings.
• Technical notes (only if the file exists): <Feature Name> — Technical Notes.

These titles must be distinct within the target space for the macros to resolve unambiguously. A ri:content-title macro resolves against the whole space, not just this tree, so a title that collides with a page that already exists in the destination space is a real hazard: the link can resolve to the wrong page, and the create call may fail or be rejected for a duplicate title. The feature-name prefix keeps the four titles distinct from each other; pick a spec title specific enough that it is unlikely to already exist in the space, and if you have any signal that one does (for example the user pointed at a page that already carries the feature name), choose a more specific title before publishing.

1. Rewrite cross-file links to title macros, leaving the /tmp/ originals intact. Write the rewritten copies to a dedicated subfolder (for example /tmp/<feature-slug>/.confluence-publish/) so the originals the user reviewed in Step 3 keep their working local markdown links. For each file, read it once and rewrite only the cross-file links:

   • Resolve each relative markdown link target against the directory of the file being rewritten. If it resolves to another file in the published set, replace the whole markdown link [text](target#fragment) with a Confluence title-based page-link macro pointing at that file's pre-decided title:

     <ac:link><ri:page ri:content-title="TARGET PAGE TITLE"/><ac:plain-text-link-body><![CDATA[text]]></ac:plain-text-link-body></ac:link>

     Omit ri:space-key — the whole tree lands in one space, so a same-space title reference resolves without it. Keep the original link text inside the link body. If that text contains the sequence ]]>, it would close the CDATA section early and produce malformed storage XML, so split it across two CDATA sections (]] in the first, > in the next) or drop the CDATA wrapper and XML-escape the text instead. Plain markdown emphasis in the link text (**bold**) is not rendered inside a plain-text link body; it posts as literal characters.

   • Drop the #fragment (the #d4-..., #t3-..., or section anchor). Confluence Cloud generates its own heading anchors with a scheme that does not match these slugs, so the link lands the reader at the top of the correct page, not the exact heading. (The macro form leaves the door open to add an explicit ri:anchor later if a space's heading-anchor scheme is pinned down; do not emit anchors now.)

   • Leave every other link, and all other content, exactly as written. Do not touch links that point outside the published set (external URLs, code references).

2. Publish the tree in one create pass. Use the Skill tool for every call, and apply the publish mode the user chose in Step 4 to all of them — state it explicitly so han-atlassian:markdown-to-confluence does not re-ask.

   • Publish the spec (the parent page) first, from its rewritten copy. Invoke han-atlassian:markdown-to-confluence, forwarding the rewritten spec copy's path, the Confluence destination the user provided in Step 1 (passed through verbatim), the publish mode from Step 4, and the spec title decided above. Capture the resulting spec page's URL and page ID — the parent for the artifact pages, and needed for the final report.
   • Publish each existing artifact as a child of the spec page, from its rewritten copy. For each artifact file that exists (decision-log.md, team-findings.md, and feature-technical-notes.md only if it was created), invoke han-atlassian:markdown-to-confluence again, forwarding the rewritten artifact copy's path, the spec page's URL as the destination with the intent to create a new child page under it (state this explicitly so the publisher does not ask whether to update the spec page), the same publish mode, and the artifact's pre-decided title. Publish the artifacts one at a time so each create resolves against the same parent.

   han-atlassian:markdown-to-confluence owns location resolution, the create call, and Mermaid handling for each file. Because every body already carries its final title-macro links, each page is created exactly once — there is no update pass.

Mermaid still posts as source. As han-atlassian:markdown-to-confluence reports, Mermaid diagrams publish as fenced code blocks, not rendered diagrams, unless the space has a Mermaid macro. This is not something to silently fix.

Relay the result to the user: the spec parent page's URL, every artifact child page's URL, whether the tree went live or was saved as drafts, and the caveats: cross-page links resolve by page title and land at the top of the target page (heading-level anchors are not preserved); because they resolve by title, renaming a published page in Confluence may break inbound cross-page links; and the Mermaid note. If any create fails partway through the tree, report which file failed and its error, and note which pages were already created. Warn the user that those already-created pages carry title-macro links pointing at the pages that did not get created, so those links dangle until the missing pages exist under their intended titles — and that simply re-running the whole skill would re-create the pages that already succeeded, producing duplicate-title pages that break title resolution for the tree. Recommend they create the missing page(s) by hand under the intended titles, or delete the partial tree and re-publish from clean. Confirm the /tmp/ originals are unchanged and intact either way.

Step 6: Verification

1. Inputs validated: the Atlassian server was reachable, a feature to plan was present, and a Confluence location was provided — or the skill stopped before doing any work.
2. Plan produced to /tmp: han-planning:plan-a-feature ran with the full forwarded context and wrote its files under a /tmp/ folder whose paths were captured, including whether the lazily-created technical-notes file exists.
3. User reviewed: the /tmp/ paths were shown to the user before any publish.
4. Explicit choice obtained: the user chose draft, live, or local-only.
5. Tree published in a single pass: when the user chose to publish, titles were decided up front, cross-file links were rewritten into title-based page-link macros in copies under .confluence-publish/ (fragments dropped, /tmp/ originals untouched), the spec was posted as the parent page and each existing companion artifact as a child page in the chosen mode, and each page was created exactly once with its URL captured.
6. Reported: every page URL was relayed with the publish mode, the resolve-by-title and land-at-page-top caveat, the rename caveat, and the Mermaid note; when the user declined, only the /tmp/ files exist.