Appearance

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 ​

TypeDomain (Confluence) — intelligence leaf
PhaseOn-demand
Modelinherit
Colorcyan
ToolsBash, Read, Grep, Glob, Write
DisallowedEdit
SafetyRead-only at Confluence side; macro-aware walker prevents injection via custom macros
Never doesPage 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 ​

ScenarioWhat 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.

Released under the MIT License.

Built with MeowKit