# ISS-0022: Jira v3 response requires explicit fields in POST body

## Background

Discovered in workspace `ws-1776139348995-a7101b3a3` (O11Y-2392287) on dev environment. Closely related to ISS-0021 — same incident, same tool call sequence.

## What happened

After the agent switched from the deprecated v2 `/rest/api/2/search` to the v3 `/rest/api/3/search/jql` endpoint, it hit a second problem: the v3 response only contains the `id` field by default. Unlike v2 which returned all standard fields, v3 requires the caller to explicitly list desired fields in the POST body's `"fields"` array.

The agent's first v3 attempt looked like:

```bash
curl -s -u "$USERNAME:$TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/rest/api/3/search/jql?maxResults=50&fields=key,summary,status,created,updated" \
  -X POST \
  -d '{"jql": "project = O11Y AND text ~ \"cluster_id\" ..."}'
```

Note: `fields` was passed as a **query parameter**, not in the POST body. Jira v3 ignores query-param fields for the POST endpoint — they must be in the request body.

## Observed errors

The response was valid JSON with `total: 19` issues, but each issue only had:
```json
{"id": "7396931"}
```

The agent's parsing code expected `issue["key"]` → `KeyError: 'key'`. After the KeyError, it fell back to printing `?` for every field, producing 19 rows of `? | ? | ?`.

The agent then debugged:
```
first issue keys: ['id']
first issue: {"id": "7396931"}
```

And fixed it by passing fields in the POST body:
```json
{
  "jql": "project = O11Y AND ...",
  "fields": ["key", "summary", "status", "created", "updated"]
}
```

This returned correct results.

## Root cause

The existing `_search_jql()` function in `jira_api.py` already handles this correctly — it passes `fields` in the POST body:

```python
payload = {
    "jql": jql,
    "fields": fields,
    "maxResults": max_results,
}
```

The problem is that the **agent bypassed the script** and built raw curl commands that put `fields` in query params instead of the POST body. This is because:

1. No `search-issues --jql` generic subcommand exists (see ISS-0021)
2. The agent didn't know it could use `search-by-cluster` for this use case
3. When constructing raw curl, the agent followed v2 conventions (query params) which don't work for v3

## Fix plan

This issue is **fully addressed by ISS-0021's fix** — adding a generic `search-issues --jql` subcommand. Once the agent uses the script instead of raw curl, the `_search_jql()` function already handles field passing correctly.

### Additional hardening

Add a defensive check in `_search_jql()` to ensure `fields` is never empty:

```python
def _search_jql(jql, fields, max_results, next_page_token=None):
    if not fields:
        fields = ["key", "summary", "status", "created", "updated"]
    # ... rest of function
```

This prevents the "all `?`" output even if the caller forgets to pass fields.

### Update Jira SKILL.md

Add a note in the Jira skill documentation:

> **v3 API requirement**: When using `/rest/api/3/search/jql`, fields MUST be passed in the POST body `"fields"` array, NOT as query parameters. The existing `search-by-*` subcommands handle this automatically.

## Verification

```bash
# Should return key, summary, created (not just id)
python jira_api.py search-by-cluster --cluster-id 1234567 --project O11Y

# Generic search should also work
python jira_api.py search-issues --jql "project = O11Y AND created >= '2026-04-13'" --fields key,summary,created
```