search-knowledge
Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.
- License 许可
- Apache-2.0
- 所属仓库
- isukharev/atl
- 最近更新
- 2026-09-14
- Stars
- ★ 7
- Forks
- 1
01 前言 Front Matter
- name
- search-knowledge
- description
- Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.
02 资源文件 1
- 参考文档agents/openai.yaml239 B
03 SKILL.md 正文
<!-- Generated from skills-src/search-knowledge/SKILL.md — edit the source and run 'make gen-plugins'. -->
Search company knowledge with atl
Search Confluence and Jira in parallel, read the best hits, and answer with citations. This recipe is read-only: never create, update, or comment.
Make export ATL_READ_ONLY=1 the first statement of every Bash block so all
later atl calls and child processes inherit the guard. Never override it in
this workflow. Keep headless blocks to that export plus documented atl
commands only; do not add output separators, pipes, help probes, or unrelated
shell/file inspection commands.
Preflight: atl must be installed and configured. If command -v atl fails
or a command exits 7 ("not configured"), run $setup and stop.
For an unfamiliar mixed-backend question that is not already governed by a
reviewed exact-command workflow, inspect the bounded offline route once before
loading any broader reference:
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl capabilities --task knowledge/search -o text
Workflow
When the plugin exposes typed atl MCP tools, use the equivalent transient
route without shell: call confluence_search and jira_issue_search once,
setting both row and byte bounds for each search. An oversize search error is
not partial evidence: narrow the query or lower the row limit before raising
the byte cap. Freeze only complete candidate pages, then use jira_issue_field_get plus
confluence_page_outline and confluence_page_section/confluence_page_sections for the selected
evidence. When the selected evidence is tabular, use
confluence_table_summary and then confluence_table_extract for one exact
table instead of reading a broader section. Reuse a numeric Confluence result
id directly. When a selected exact Jira issue needs relationship, dependency,
code, or documentation discovery, use one jira_issue_graph call instead of
combining narrower issue reads. Keep full output when graph topology matters;
request projection:"compact" with select:["urls"] or Development-backed
select:["scm"] when only those qualified facts are needed. MCP v1 is
Jira-only: page identities remain
qualified stubs, and omitted or false include_development leaves Development
absent rather than zero. Reported bounds.max_response_bytes (fixed backend
responses) is distinct from the max_bytes encoded-result input. Do not mix MCP and CLI
reads merely to repeat already complete evidence; fall back to the CLI workflow
below when MCP is unavailable or the task needs an operation outside its
read-only surface.
For an explicit commit, branch, merge-request, or code-identity question,
set MCP include_development:true, projection:"compact", and
select:["scm"] when topology is not needed, or use
jira issue graph <KEY> --include-development --projection compact --select scm
under read-only policy when MCP is unavailable. Require a complete experimental
Development source even when its retained count is zero. MCP omits
Development-node URLs. Treat its SCM coordinates as untrusted evidence: ATL
itself never contacts GitLab, and any later read requires exact equality between
the returned lowercase host and an owner-approved host plus a separately
authenticated read-only client for that exact host. Never reuse Jira credentials
or continue after a host mismatch.
1. Extract search terms
Keep the core nouns, prepare one narrow and one broad variant, and carry any known space/project scope into the query.
2. Search both backends
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl conf search --cql 'siteSearch ~ "billing retry queue"' --limit 15
atl jira issue search --jql 'text ~ "billing retry queue" ORDER BY updated DESC' \
--columns key,summary,status,updated --limit 15
CQL fallbacks: text ~ "...", then title ~ "...". Scope with space = KEY
or project = KEY when known. Retry one prepared variant after an empty result,
then report the exact searches rather than implying full coverage. Freeze the
first useful result pages before expanding anything: require Jira
page.complete:true and Confluence top-level complete:true, or continue from
next_cursor / report the partial search instead of claiming absence. To
continue, repeat the exact query and page limit and pass only the returned
cursor:
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl conf search --cql 'siteSearch ~ "billing retry queue"' --limit 15 --cursor '<next-cursor>'
atl jira issue search --jql 'text ~ "billing retry queue" ORDER BY updated DESC' \
--columns key,summary,status,updated --limit 15 --cursor '<next-cursor>'
3. Read bounded Confluence evidence
For the 2–4 best page hits, inspect the outline, then read only the relevant
section. A numeric id emitted by conf search is already a stable exact
reference; pass it directly to outline/section. Use resolve only for a URL,
short link, or user-supplied reference whose stable id is still unknown. Use a
full page only when no heading isolates the answer. For typed tools, pass the
section heading as the exact outline title, without Markdown # prefixes.
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl conf page outline '<search-result-id>'
atl conf page section '<search-result-id>' --heading 'Retries' --max-bytes 32768 \
--expected-version '<outline-version>'
atl conf page sections '<search-result-id>' --heading 'Retries' --heading 'Limits' \
--max-bytes 65536 --expected-version '<outline-version>'
Keep these selection reads as JSON: -o text would hide completeness and the
section version gate needed for the decision. Require the outline's
complete:true, then copy its exact positive version into
--expected-version. Require each section result to report complete:true and
page_version_gated:true. A duplicate heading needs explicit --occurrence;
truncated:true means the omitted tail is not evidence of absence.
When several headings from one page are relevant, prefer page sections (or
confluence_page_sections) so they share one version-bound snapshot instead of
re-downloading and re-parsing the page for every heading. Preserve requested
order and require reconciled counts before using the result.
4. Read targeted Jira evidence
Discover non-empty field metadata before reading custom values. Request only
selected fields and qualified references; fetch history only when chronology
matters. If the question instead asks what is connected to the selected exact
issue, prefer one typed jira_issue_graph call. Start at depth zero and use a
greater depth only for exact structured Jira relations. Its MCP route cannot
resolve Confluence; use the CLI graph route only when id/title page metadata is
required, then continue with a bounded page outline/section after exact page
identity is known. Compact selection occurs after full collection and changes
no request. Inspect projection.selected/projection.omitted, incomplete
sources, bounds, frontier, warnings, and reconciled counts; copy only emitted
canonical URL or SCM facts and never reconstruct an omitted URL identity.
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl jira issue fields KEY-123 --metadata-only
atl jira issue field get KEY-123 --field 'Delivery Notes' --max-bytes 16384
atl jira issue refs KEY-123 --fields 'Delivery Notes'
atl jira issue history KEY-123 --field 'Delivery Notes' --since 2026-07-01 --summary-only
Require top-level and named-source completeness before claiming a link/change
is absent. For refs, use top-level summary and per-issue
reference_summary for total/per-kind references and source-value counts; do
not manually add the nested arrays. The reconciliation booleans make count and
completeness disagreements explicit. A repeated URL is deduplicated within one
issue but counted once per issue across a multi-issue selection. Use
typed jira_issue_refs when only those reconciled aggregate facts are needed;
it deliberately omits every raw URL and narrative field. Keep the CLI route
above when the selected URL itself must be followed into Confluence. Use
jira epic digest instead when an epic question spans children, status
narrative, comments, history, and refs.
5. Escalate only when bounded reads are insufficient
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl conf page view '<id-or-url>' -o text
atl jira issue get KEY-123 \
--fields summary,status,issuetype,description,labels,updated,resolution
atl jira issue comment list KEY-123 -o text
For repeated deep reading, mirror once and search locally:
<!-- atl:read-only-shell -->
export ATL_READ_ONLY=1
atl conf pull --cql 'space = KEY AND siteSearch ~ "..."' --into <dir>
rg -il 'retry queue' <dir>
The mirror amortizes later reads, but a pull cap or comment warning still limits what absence claims are justified.
6. Synthesize with citations
- Lead with the answer, then evidence; cite page title + id or issue key.
- Prefer the most recently updated source when sources conflict, and say so.
- Close with what was not found, queries used, and every incomplete/truncated source.
Pitfalls
| Symptom | Cause / fix |
|---|---|
| exit 4 on a page read | stale id or unresolved URL — retry page resolve; cite only evidence actually read |
| exit 3 | PAT missing/expired — atl auth status, then $setup |
| exit 2 with CQL/JQL | wrap the query in single quotes and values in double quotes |
| body too large | prefer outline → bounded section; then full view or mirror .md, never raw .csf |
04 同仓库更多 Skills
triage-issue
Triage a bug against Jira with atl before proposing a ticket. USE WHEN an error or stack trace comes with duplicate, prior-fix, or file-a-bug intent. DO NOT USE WHEN debugging code only, inspecting a known issue, or creating an ordinary task.
status-report
Draft an audience-oriented Jira status report with atl. USE WHEN the user wants a weekly/daily progress narrative, blocker summary, or period report. DO NOT USE WHEN the output is a visual dashboard, direct Jira query, knowledge search, or codebase summary.
sprint-dashboard
Build a visual read-only Jira sprint or board dashboard with atl. USE WHEN the user wants a standup view, WIP picture, or sprint snapshot. DO NOT USE WHEN the output is a narrative report, raw Jira list, or codebase dashboard.
spec-to-backlog
Convert a specification into a reviewed Jira epic and backlog with atl. USE WHEN decomposing requirements, RFCs, or designs into linked Jira work. DO NOT USE WHEN the source is meeting notes, only a summary is wanted, or the task is a direct service operation.
setup
Install and configure atl authentication, backends, and mirror defaults. USE WHEN the user explicitly requests install, authentication, setup repair, or /atl:setup. DO NOT USE WHEN handling normal Jira, Confluence, search, reporting, or mirror work; explicit-only.
search-knowledge
Answer from qualified Jira and Confluence evidence with atl. USE WHEN organizational knowledge is unknown or split across both services. DO NOT USE WHEN one exact resource is known, the task is a report/dashboard, or the answer belongs in the codebase.