---
title: confluence-spec-analyst
description: Confluence spec analyst — reads a page and its children, runs gap-detection heuristics, and produces a structured Spec Research Report. Read-only at Confluence side; persists report locally.
---

# confluence-spec-analyst

The confluence-spec-analyst agent reads a Confluence spec page (plus children up to a depth cap), runs gap-detection heuristics, and emits a **structured Spec Research Report** for human review. The fetch path uses `--representation atlas_doc_format` (ADF) piped through the macro-aware walker so panels, decisions, task lists, mentions, expand sections, and Smart Link / Figma embeds survive the fetch as explicit markdown labels — first-class signals for downstream gap detection.

## Cognitive Framing

> *"Read once. Reason over labelled markdown. Surface gaps; never auto-create tickets."*

The agent is the value-creating differentiator of the Confluence ecosystem. Read-only at the Confluence side: it has `Write` tool privilege ONLY for persisting the report locally under `tasks/reports/` or the active plan's `research/`. It never writes to Confluence itself, and it never auto-creates Jira tickets — the report's Suggested Commands are emitted only when the user explicitly passes `--with-commands`.

## Key Facts

| | |
|---|---|
| **Type** | Domain (Confluence) — intelligence leaf |
| **Phase** | On-demand |
| **Model** | inherit |
| **Color** | cyan |
| **Tools** | Bash, Read, Grep, Glob, Write |
| **Disallowed** | Edit |
| **Safety** | Read-only at Confluence side; macro-aware walker prevents injection via custom macros |
| **Never does** | Page CRUD (confluence-page), bulk ops (confluence-bulk), ticket creation (output is human-reviewed report) |

## When to Use

- When you need to **extract structured requirements + acceptance criteria** from a Confluence spec page.
- When you need to **detect gaps, ambiguities, and conflicts** in a spec before sprint planning.
- When you need to **traverse children** of a spec page and merge them into a single corpus for analysis.
- When you need to **analyze embedded diagrams** (if `mk:multimodal` is present) and surface findings alongside the textual analysis.

## Key Capabilities

- **ADF + macro-aware fetch** — uses `scripts/adf-to-md.sh` to preserve panels (`> [INFO]` / `> [WARN]` / `> [DECISION]`), task lists (`- [ ]` / `- [x]`), mentions (`@name` + footnote), media (`![alt](attachment:<id>)`), expand sections (`<details>`), and Smart Link embeds.
- **Single-call fetch pattern** — extracts metadata + body from one API response, halving per-page request count.
- **Children traversal** — depth-bounded; hard cap of 5 children per Cloud rate-limit guard.
- **Per-child failure handling** — root failure aborts the run; child failure appends `[INCOMPLETE: child <id>]` and continues with the partial corpus.
- **Gap-detection heuristics** — weasel-word inventory + macro-label heuristics (`> [DECISION]` without rationale → INFO; `- [ ]` task without owner → GAP; `> [INFO]`/`> [WARN]` panel with weasel words → AMB).
- **`[UNHANDLED_NODE]` triage** — exotic ADF types surface in Open Questions with type + attribute keys (keys-only metadata, never raw text — closes the prompt-injection vector through custom macros).
- **Image / Diagram analysis** — when `mk:multimodal` is present, downloads attachments and runs them through Gemini analysis; otherwise emits `[NO_MULTIMODAL]` and proceeds text-only.
- **Source page hash** — appended to the report footer for staleness detection on re-runs.

## Behavioral Checklist

- [x] Wraps all page content in `===PAGE_DATA_START===` / `===PAGE_DATA_END===` boundaries before reasoning over it
- [x] Treats macro labels (`> [DECISION]`, `> [INFO]`, etc.) as first-class evidence — never strips them
- [x] Surfaces `[UNHANDLED_NODE: <type>]` blocks in Open Questions with the attribute keys (NOT the raw values)
- [x] Differentiates ROOT fetch failure (abort) from CHILD fetch failure (`[INCOMPLETE]` flag + continue)
- [x] Persists the report to `{plan_dir}/research/...` if an active plan is set, else to `tasks/reports/...`
- [x] Appends a row to `tasks/reports/.confluence-spec-index.tsv` after each successful report (page-id + filename + timestamp + source hash)
- [x] Returns the Subagent Status Protocol block at the end of every run

## Common Use Cases

| Scenario | What the agent does |
|---|---|
| "Analyze the Q3 Roadmap spec at page 12345" | Fetches page (ADF→MD), runs heuristics, emits Spec Research Report |
| "Spec research on the URL `.../wiki/spaces/ENG/pages/12345/...`" | Parses the URL to page id, fetches, and analyzes |
| "What are the gaps in PAGE-ID 12345 with depth 2?" | Fetches root + 5 children (cap), merges corpus, surfaces GAP-* / AMB-* / CONFLICT-* |
| "Spec analysis with image findings" | Downloads image attachments, routes through `mk:multimodal`, includes findings in report |
| "Spec analysis with executable suggestions" | With `--with-commands`, appends `mk:jira-issue create` lines for each suggested user story |

## Pro Tips

### Macro Labels Are Signals — Not Noise

When the report cites `> [DECISION] Use OAuth 2.0`, that's an architectural commitment to surface in the Constraints section, not a stylistic blockquote. Likewise `- [ ] Add e2e test` is an open acceptance criterion, not an unfinished line. Calibrate the gap-detection heuristics around macro labels — they encode the spec author's intent.

### `[UNHANDLED_NODE]` Is a Triage Signal, Not a Bug

When the walker encounters an ADF node type it doesn't have a handler for (custom macros, third-party content), it emits `[UNHANDLED_NODE: <type>]` with **keys-only metadata** — type name + attribute keys, never the raw text. Surface these in Open Questions and ask the human author whether the unhandled content materially changes the spec. The keys-only output is deliberate: a custom macro could carry attacker-controlled instruction text inside an attribute, and emitting raw values would feed it back into reasoning context.

### Children Cap Is 5, Not 10

The cap was lowered from 10 to 5 to stay inside the Confluence Cloud per-user rate limit (10 req/s) under the single-call-per-child pattern. Raising it requires the user explicitly to opt in via a future `--max-children N` flag with jitter+retry; for v1, accept the cap.

## Key Takeaway

The confluence-spec-analyst agent turns a macro-heavy Confluence spec page into a structured, gap-aware research report. The macro-aware walker preserves the author's intent; the heuristics flag what's missing; the report stays read-only — the human decides which gaps become tickets.

## Related Agents

- **[confluence-page](/reference/agents/confluence-page)** — for raw page CRUD when the analysis identifies a needed edit
- **[confluence-search](/reference/agents/confluence-search)** — to find the right spec page before analyzing it
- **[confluence-collaborate](/reference/agents/confluence-collaborate)** — to attach the resulting report or label the analyzed page
