read-confluence.md

name	read-confluence
description	Use when user says "read TDD <link>", "read design doc <link>", or provides a Confluence URL. Fetches the Technical Design Document from Confluence via acli to gather context before implementing.

Read Confluence TDD

Overview

Fetch a Technical Design Document (TDD) from Confluence using acli before starting implementation. The TDD is the source of truth for architecture decisions, requirements, and design constraints.

Trigger

Activate when user provides a Confluence page URL, in phrases like:

• "read TDD https://zalora.atlassian.net/wiki/spaces/..."
• "read confluence "
• bare Confluence URL paste

Prerequisites

acli must be installed. If a fetch fails because acli is not found, show the user:

acli is not installed. Install it with:

brew install atlassian/tap/atlassian-cli

Then authenticate:

acli confluence auth login

Re-run the command once setup is complete.

Do not run which acli before every fetch — only surface this if a command fails.

Extracting the Page ID

Confluence URLs follow this pattern:

https://<domain>/wiki/spaces/<SPACE>/pages/<PAGE_ID>/Page+Title
                                              ^^^^^^^^
                                         extract this number

Examples:

• https://zalora.atlassian.net/wiki/spaces/FE/pages/123456789/Hero+Banner+TDD → ID: 123456789
• https://zalora.atlassian.net/wiki/spaces/PLAT/pages/987654321 → ID: 987654321

Steps

1. Extract the page ID from the provided Confluence URL (the numeric segment after /pages/).

2. Fetch the page:

   acli confluence page view --id <PAGE_ID> --body-format view --include-labels

3. Extract and summarize the following:

   • Title — document name
   • Space — team/area
   • Status — current/draft
   • Labels — tags/categories
   • Body — full content: objectives, design decisions, acceptance criteria, diagrams described in text

4. Present a concise brief:

   TDD: <Title> · Space: <SPACE> · Status: <current|draft>
   
   Summary:
   <key objectives and decisions in 3-5 bullet points>
   
   Full content:
   <cleaned-up body>
   

5. Proceed directly to implementation or analysis. Ask one clarifying question only if critical context is missing.

Commands Reference

# Fetch page with rendered body + labels
acli confluence page view --id 123456789 --body-format view --include-labels

# Fetch as raw storage format (XML, useful for structured parsing)
acli confluence page view --id 123456789 --body-format storage

# Fetch with child pages listed (useful for multi-page TDDs)
acli confluence page view --id 123456789 --body-format view --include-direct-children

# JSON output
acli confluence page view --id 123456789 --json

Common Mistakes

Mistake	Fix
Asking for design context before reading the doc	Always fetch first, ask after
Using storage body format	Use view — it renders human-readable content
Ignoring draft status	Check status; drafts may have incomplete specs
Missing child pages	Use --include-direct-children for multi-page TDDs