atlassian-hierarchy-discovery

name: atlassian-hierarchy-discovery description: | Bootstraps a Jira hierarchy snapshot before any multi-issue create / edit session. Disambiguates the parent input (issue key, spec URL, Confluence page URL, or greenfield), walks parents up (depth-cap 4), walks children down via JQL recursion (depth-cap 4, max 50 children per node), and returns a structured tree alongside the issue-type scheme and link-type metadata the caller needs to render a draft. Used primarily by atlassian-pm; secondary consumers (after the G2.5 retrofit) are the upstream Atlassian plugin skills spec-to-backlog and capture-tasks-from-meeting-notes. The skill does not render; rendering belongs to the caller (typically atlassian-pm rendering a markdown tree to chat). version: 1.0.0

atlassian-hierarchy-discovery

A pure read-side hierarchy discovery skill for the plugin-atlassian-atlassian MCP. The caller (typically atlassian-pm) hands in a parent reference; the skill returns a structured snapshot of what already exists, so the caller can prompt the user with a "this is what's there — what should we add?" tree before drafting writes.

Used by

Inputs schema

Outputs schema

status: ok | skipped | error
root_key: <KEY> | null                 # null when parent_input == greenfield
project_key: <KEY>
hierarchy:
  - key: <KEY>
    type: Initiative | Epic | Story | Task | Sub-task | <custom>
    summary: <string>
    parent: <KEY> | null
    depth: <int>          # 0 = root
    existing: true        # always true; "new" nodes are added by the caller
    url: <string>
    last_updated: <RFC3339>
existing_count: <int>
allowed_child_types_per_node:
  <type>:
    - <child_type>
required_fields_per_type:
  <type>:
    - <field_id>
link_types:
  - id: <id>
    name: <name>
    inward: <string>
    outward: <string>
warnings:
  - depth_cap_reached_at: <KEY>
  - max_children_truncated_at: <KEY> (count_seen=<int>, truncated=<int>)
  - cross_project_parent_blocked: <KEY>
error_message: <string> | null

Algorithm

1. cloudId resolution (caller-side)

The caller (typically atlassian-pm) MUST pre-resolve cloudId via getAccessibleAtlassianResources and atlassianUserInfo. This skill does NOT call those itself — it assumes the caller has already established auth and selected a cloud.

If the caller passes an empty/invalid cloudId, the skill returns { status: "error", error_message: "missing_cloud_id" }.

2. Parent disambiguation

3. Preflight auth check

Call getJiraIssue(<root_key>) (or getVisibleJiraProjects() for greenfield) once. Any 401/403 returns { status: "error", error_message: "auth_lost" } immediately — the caller surfaces re-auth instructions.

4. Walk parents up (depth-cap = depth_cap)

current = root_key
depth   = 0
while depth < depth_cap:
  issue = getJiraIssue(current)
  hierarchy.append({ key: current, type: issue.issuetype, ..., depth: depth, existing: true })
  if not issue.fields.parent: break
  if issue.fields.parent.project_key != project_key:
      warnings.append({ cross_project_parent_blocked: issue.fields.parent.key })
      break
  current = issue.fields.parent.key
  depth += 1
if depth == depth_cap and current still has parent:
    warnings.append({ depth_cap_reached_at: current })

The walk cuts off at the depth cap and at any cross-project boundary. Cross-project parents are recorded but not traversed (they break the project-key invariant).

5. Walk children down (depth-cap = depth_cap, breadth-cap = max_children_per_node)

JQL recursion against the highest ancestor we reached (i.e. the topmost member of the parents-up walk). For each ancestor, run:

jql = parent = <KEY> AND project = <PROJECT_KEY>
results = searchJiraIssuesUsingJql(jql, max_results = max_children_per_node + 1)

If len(results) > max_children_per_node, record { max_children_truncated_at: <KEY>, count_seen: len(results), truncated: len(results) - max_children_per_node } in warnings and keep only the first max_children_per_node. Recurse on each retained child until depth == depth_cap (record depth_cap_reached_at warning if children remain).

The walk is breadth-first so the caller sees a balanced tree. Order within a level is by key ascending for deterministic rendering.

6. Issue-type scheme + link-type fetch

• getJiraProjectIssueTypesMetadata(project_key) → populate allowed_child_types_per_node. Map each issue type to the child types that may live under it (Initiative → Epic; Epic → Story / Task; Story → Sub-task; etc., per the project's scheme — the skill does NOT hard-code Atlassian Cloud's defaults; it reads from the project).
• getJiraIssueTypeMetaWithFields(project_key, <type_id>) for each unique type encountered in the hierarchy + each type the caller plans to use → populate required_fields_per_type.
• getIssueLinkTypes() → populate link_types (caller uses this to pick Blocks / Relates / Implements etc. when drafting links).

7. Return

The skill returns the structured outputs object. The skill does NOT render the tree to chat — that is the caller's job. The caller (typically atlassian-pm) renders an ASCII / markdown tree using existing: true markers and adds ✚ <KEY> placeholders for new nodes the user will create.

Pre-validation

Before calling any MCP tool:

• cloudId is non-empty.
• project_key is non-empty and matches ^[A-Z][A-Z0-9_]+$.
• parent_input is greenfield OR a recognised shape from the disambiguation table.
• depth_cap ∈ [1, 6]. Default 4. Values outside the range → clamp + warnings.append({ depth_cap_clamped: <orig> }).
• max_children_per_node ∈ [10, 200]. Default 50.

Post-validation

After populating the outputs:

• status == "ok" requires error_message == null and at least one of: root_key != null (non-greenfield) OR parent_input == "greenfield".
• existing_count == len(hierarchy).
• For each entry in hierarchy, depth >= 0 and depth <= depth_cap.
• For each entry in hierarchy, parent is null OR present elsewhere in hierarchy OR flagged as a cross-project boundary in warnings.

If post-validation fails: return { status: "error", error_message: "post_validation_failed", warnings: [<details>] }.

Failure modes

The skill never auto-retries; the caller decides whether to retry, surface to the user, or proceed without hierarchy context.

What this skill does NOT do

• It does NOT render the hierarchy to chat. Rendering an ASCII / markdown tree to the user is the caller's responsibility.
• It does NOT create, edit, transition, or comment on any issue or page. It is read-only.
• It does NOT ask the user for clarification. If parent_input is ambiguous, the skill returns ambiguous_parent and the caller re-prompts.
• It does NOT auto-resolve cloudId. The caller pre-resolves auth before invoking.
• It does NOT walk across projects. Cross-project parents are recorded as warnings and not traversed.
• It does NOT apply audience-translation scrubbing. Returned summaries / titles are raw; if the caller chooses to render them, the caller applies its own scrubber (this skill returns existing: true Atlassian-side data verbatim apart from secret detection at the caller level).
• It does NOT retry on failure. The caller decides retry semantics.