sourcing-from-atlassian（来自 Atlassian 的采购）

Sourcing from Atlassian — MCP Retrieval Skill

Overview

This skill defines the exact procedures for retrieving documentation source material from Jira and Confluence via the Atlassian MCP server. It covers connection setup, query patterns, field extraction maps, pagination, and the canonical source bundle format consumed by the doc-engineer and c4-architect agents.

1. Connection Bootstrap

Before any retrieval, establish the Atlassian context. Do this once per session.

Step 1: Call getAccessibleAtlassianResources
  → Returns: list of { id (cloudId), name, url, scopes }
  → Select the cloudId that matches the user's workspace

Step 2: Call atlassianUserInfo
  → Confirms identity and available permissions
  → If permissions are insufficient, surface the specific missing scope to the user

Step 3: Store cloudId in working context for all subsequent calls

If the user provides a Jira URL (e.g., https://myorg.atlassian.net), extract the subdomain as the workspace identifier and confirm it matches a cloudId from step 1.

2. Jira Retrieval Patterns

2a. Fetch a Single Issue

Tool: getJiraIssue Input: {issueKey: "PROJ-123", cloudId} Extract these fields:

Acceptance Criteria extraction rules:

1. Check customfield_10016 first (standard AC field in many Jira configs)
2. If empty, scan the issue description for a section headed "Acceptance Criteria", "AC", "Given/When/Then", or a numbered list immediately following "Definition of Done"
3. If still empty, mark as [MISSING AC] in the gap report

2b. Search Issues by JQL

Tool: searchJiraIssuesUsingJql

Common JQL patterns for documentation sourcing:

-- All stories in an epic (classic projects)
"Epic Link" = PROJ-42 AND issuetype = Story ORDER BY created ASC

-- All stories in an epic (next-gen / team-managed)
issueType = Story AND parentEpic = PROJ-42

-- All issues in a sprint
project = PROJ AND sprint in openSprints() ORDER BY rank ASC

-- All issues for a release
project = PROJ AND fixVersion = "v2.1.0" ORDER BY issuetype ASC

-- Recent changes to a feature area
project = PROJ AND labels = "auth-service" AND updated >= -30d

-- Completed stories for release notes
project = PROJ AND issuetype = Story AND status = Done
  AND fixVersion = "v2.1.0" ORDER BY priority ASC

-- All bugs in scope
project = PROJ AND issuetype = Bug AND status != Done
  AND affectedVersion = "v2.0.0"

Pagination:

• Request maxResults: 50 per call
• If total > startAt + maxResults, increment startAt and repeat
• Cap total retrieval at 200 issues; if more exist, ask the user to narrow scope

Field projection: Always request fields=summary,description,status,priority,issuetype,customfield_10016,labels,issuelinks,assignee,reporter,created,updated,fixVersions,customfield_10014,parent

2c. Fetch an Epic with All Children

1. getJiraIssue(epicKey) → store epic summary, description, goal
2. searchJiraIssuesUsingJql('"Epic Link" = <epicKey>') → classic projects
3. searchJiraIssuesUsingJql('parentEpic = <epicKey>') → next-gen projects
4. Merge results, deduplicate by issue key
5. For each child story: extract fields per 2a

3. Confluence Retrieval Patterns

3a. Fetch a Single Page

Tool: getConfluencePage Input: {pageId: "123456", cloudId}

Extract:

Content cleaning:

• Strip HTML tags to markdown-equivalent structure: headings → ##, <table> → markdown table, <code> → fenced code block
• Preserve macro outputs (info panels, expand blocks) as blockquotes with > [INFO] prefix
• Remove navigation elements, breadcrumbs, footer macros
• Preserve all technical content verbatim — do not summarize

3b. Search Pages by CQL

Tool: searchConfluenceUsingCql

Common CQL patterns:

-- Find pages by title keyword in a specific space
type = page AND space = "ENG" AND title ~ "authentication"

-- Find recently modified pages in a space
type = page AND space = "ENG" AND lastModified >= "2024-01-01"

-- Find pages related to a Jira epic
type = page AND text ~ "PROJ-42"

-- Find pages with a specific label
type = page AND label = "api-design" AND space = "ENG"

-- Find all pages in a space updated this quarter
type = page AND space = "ENG" AND lastModified >= startOfQuarter()

-- Find design documents
type = page AND title ~ "design" AND space in ("ENG","ARCH")

Pagination:

• Use limit: 25 per call
• Check _links.next for additional pages
• Cap at 50 pages; if more exist, ask user to narrow

3c. Map Jira Issues to Confluence Pages

After retrieving Jira issues, find associated Confluence pages:

For each Jira issue key (e.g., PROJ-123):
  1. searchConfluenceUsingCql('text ~ "PROJ-123"')
  2. Also check issue links for "Confluence Page" remote links via getJiraIssueRemoteIssueLinks
  3. Add found pages to the traceability index

4. Field Mapping to Documentation Concepts

Use this table to map Atlassian fields to documentation sections:

5. Staleness and Quality Checks

Run these checks on every retrieved item before including in the bundle:

6. Source Bundle Format

Every invocation of this skill must produce output in exactly this format:

# Atlassian Source Bundle

**Generated:** <ISO 8601 timestamp>
**Cloud:** <cloudId> (<workspace name>)
**Scope:** <brief description of what was fetched>
**Total Jira issues:** <n>
**Total Confluence pages:** <n>

---

## Jira Sources

### Epic: <KEY> — <Summary>
- **Status:** <status>
- **Fix Version:** <version or "unset">
- **Description:**
  <cleaned epic description>
- **Business Goal:**
  <goal field or extracted from description>

---

### User Stories

#### <KEY>: <Summary>
- **Type:** <issuetype>
- **Status:** <status> | **Priority:** <priority>
- **Assignee:** <name or "unassigned">
- **Fix Version:** <version>
- **Labels:** <label1>, <label2>

**Acceptance Criteria:**
1. <criterion>
2. <criterion>

**Description:**
<cleaned description body>

**Linked Issues:** <KEY1 (Blocks)>, <KEY2 (Relates to)>

**Notes from Comments:**
<relevant resolved comments — skip trivial/status updates>

---

[Repeat per story]

---

## Confluence Sources

### <Page Title>
- **Space:** <SPACE_KEY> | **Page ID:** <id>
- **Last Modified:** <date> by <author name>
- **URL:** <full URL>
- **Version:** <n>

**Content:**

<cleaned, markdown-formatted page body>

---

[Repeat per page]

---

## Gap Report

| # | Severity | Location | Issue | Recommended Action |
|---|----------|----------|-------|--------------------|
| 1 | 🔴 Blocker | KEY-123 | No acceptance criteria | Request from Product Owner before drafting |
| 2 | 🟡 Warning | Confluence "Auth Design" | Not updated in 4 months | Verify still accurate with page owner |
| 3 | 🟡 Warning | KEY-456 vs "API Spec v3" | Contradiction: AC says JWT, spec says session cookie | Resolve before writing auth docs |
| 4 | ⚪ Info | KEY-789 | Status is "Done" — use for release notes only | Include in release notes section |

---

## Traceability Index

| Jira Key | Summary | Status | Confluence Pages |
|----------|---------|--------|-----------------|
| KEY-123 | User login | In Progress | "Auth Design", "Login Flow Spec" |
| KEY-456 | Dashboard | Done | — |

---

## Recommended Next Step

<One sentence recommending which doc-engineer action to invoke next and why.>
For example: "Pass this bundle to doc-engineer using authoring-user-docs — the acceptance criteria map directly to tutorial steps for the login flow."

7. Error Handling