[gashcrumb]

Summary

Supersedes #119 (which could not be reopened after rebasing due to GitHub's force-push limitation on closed PRs).

Based on day-to-day dogfooding and agent interaction observations, defaulting to acli for all operations introduces several operational hurdles where the host Atlassian MCP adapter is cleaner, faster, and more reliable:

• Silent 30-row truncation on search results when using acli without pagination flags (the fix: use CLAUDE_PLUGIN_ROOT for CLI path in skills #1 documented trap).
• Silent empty custom fields on single issue reads unless --fields '*all' is explicitly passed, which models frequently miss.
• Two-step workarounds for issue creation (setting priority and components requires a secondary REST call because acli create rejects those flags).
• Missing operations entirely — remote link attachment (linking PRs to issues), worklog authoring, and comment visibility restrictions are not available in acli at all.

Conversely, acli remains the superior choice for bulk operations (batch transitions/edits by JQL, multi-page auto-walk) and board/sprint inspection.

Solution

Replace the acli-first default with an explicit adapter decision table covering the full Jira surface. This makes the operational tradeoffs explicit so coding agents select the right tool predictably:

Host adapter (MCP) is preferred for:

• Single-issue reads with custom fields (fields: ["*all"], avoiding the silent empty-field trap)
• Single-issue reads + comments in one call
• Issue creation with priority and components in a single operation
• Custom field writes (Story Points, Size, Team, Release Note Type) via native fields dictionaries rather than raw REST fallbacks
• Remote links / PR web-link attachments (acli has no equivalent)
• Comment visibility restrictions, worklogs, Confluence, and Teamwork Graph links

acli remains preferred for:

• Batch transitions and edits by JQL (--jql ... --yes)
• Board and sprint reads (exposing no MCP tools)
• All-pages auto-walk (--paginate)
• Saved filter lookup and attachment list/delete

Field Experience

We have been dogfooding and using these guidelines extensively in day-to-day agent workflows over the past several weeks. In practice, having the skill guide the agent toward native MCP tools for single-issue operations and custom-field writes has made Jira interactions significantly smoother, faster, and more reliable, eliminating empty-field bugs and multi-step fallback calls.

Files Changed

• SKILL.md — adds an "Adapter choice" section and scopes the two silent-failure traps to acli only
• references/auth.md — adds a 17-row adapter decision table covering operations, preferred adapters, and rationale
• references/graphql-queries.md — reorders capability gate and updates fallback rules table with explicit MCP tool names
• references/rest-api-fallback.md — updates capability gate to check auth.md first and prefer native MCP tools before REST fallbacks

[gashcrumb]

/fs-review