fix(rhdh-jira): address 7 issues found during 2.1 candidate refinement session

- Add Gotcha redhat-developer#13: acli search silently truncates at 30 results
- Rewrite Gotcha redhat-developer#9: acli cannot set custom fields (no --custom flag)
- Expand Gotcha redhat-developer#8: labels also missing from basic field output
- Fix error table: REST search returns 410, not a valid fallback
- acli-commands.md: add warning about default page size, update examples to --limit 200
- graphql-queries.md: operation names are mandatory now, not future
- rest-api-fallback.md: document 410 Gone on /rest/api/3/search
- jql-patterns.md: cross-project parent=KEY only works via acli
- refine.md: add refinement context (pre-release prep vs freeze triage)

Author: schultzp2020

skills/rhdh-jira/SKILL.md

@@ -132,11 +132,12 @@ Load only what the current task requires.
 5. **Team field has two JQL syntaxes.** `customfield_10001` cannot be used in JQL WHERE clauses. However, `"Team[Team]" = {teamId}` (using the team UUID, not display name) works. Use the UUID syntax for JQL filtering; use `customfield_10001.name` in post-processing only when you need the display name from JSON output.
 6. **ADF vs plain text.** Reading descriptions via `--json` returns Atlassian Document Format (nested JSON). Creating/editing with `--description` accepts plain text. Don't try to round-trip ADF through `--description`.
 7. **Acceptance Criteria field is almost always null.** Scan the description for "Requirements", "Acceptance Criteria", or bullet-style criteria instead of checking `customfield_10718`.
-8. **`--enrich` is MANDATORY for custom fields.** Both `acli search --json` and `acli view KEY --json` (without `--fields "*all"`) return only basic fields (assignee, issuetype, priority, status, summary). Story points, team, sprint, and size will appear as empty/null — looking like the data isn't set when it actually is. Always use `scripts/parse_issues.py --enrich` to get custom field data. Skipping `--enrich` is the #1 cause of false "missing data" reports.
-9. **Custom fields may fail to update via `acli`.** `acli jira workitem edit` can silently fail or error when setting custom fields (Team, Size, Story Points). When an `acli edit` for a custom field fails, fall back to the Jira REST API. Find the token file at `.jira-token` next to the `acli` executable (discover the path with `readlink -f "$(which acli)"` or `where acli`). Read `references/rest-api-fallback.md` for curl examples and payload formats. Never read the token file into context.
+8. **`--enrich` is MANDATORY for custom fields AND labels.** Both `acli search --json` and `acli view KEY --json` (without `--fields "*all"`) return only basic fields (assignee, issuetype, priority, status, summary). Labels, story points, team, sprint, size, and components will all appear as empty/null — looking like the data isn't set when it actually is. Always use `scripts/parse_issues.py --enrich` to get custom field data. Skipping `--enrich` is the #1 cause of false "missing data" reports.
+9. **`acli` cannot set arbitrary custom fields.** `acli jira workitem edit` does not have a `--custom` flag. Fields like Team, Size, Story Points, and Release Note Type can only be updated via the Jira REST API. Use `PUT /rest/api/3/issue/{key}` with the field payload (see `references/rest-api-fallback.md` for curl examples and payload formats). Find the token file at `.jira-token` next to the `acli` executable (discover the path with `readlink -f "$(which acli)"` or `where acli`). Never read the token file into context.
 10. **`acli sprint list-workitems --json` wraps results in `{"issues": [...]}`.**  The output is NOT a flat array — it's an object with an `issues` key. Extract the array before piping to `parse_issues.py`. See `references/acli-commands.md` for the workaround command.
 11. **GraphQL search is beta.** `issueSearchStable` requires `X-ExperimentalApi: JiraIssueSearch` header. Load `references/graphql-queries.md` before attempting GraphQL queries.
 12. **`.jira-token` format is `email:token`, not bare token.** A file containing only the API token without the email prefix will cause 401 errors on REST/GraphQL calls. The `setup.py` script validates the format.
+13. **`acli search` silently truncates results.** The default page size is 30. If your JQL matches more than 30 issues, you get the first 30 with no warning. Always pass `--limit 200` for bulk queries, or use `--count` first to check the total, then `--paginate` to fetch all pages. This is the #2 cause of incorrect reports after skipping `--enrich`.
 
 ## Error Handling
 
@@ -150,7 +151,7 @@ Load only what the current task requires.
 | Rate limiting (429) | Wait 5 seconds, retry once. |
 | Interactive prompt hangs | Missing `--yes` flag on a mutating command. |
 | Custom field update fails via `acli` | Fall back to Jira REST API using `.jira-token` file. See Gotcha #9. |
-| `issueSearchStable` returns errors | Fall back to REST API search (`/rest/api/3/search`) with the same JQL. Warn that the beta API failed. |
+| `issueSearchStable` returns errors | Fall back to `acli` search (not REST — `/rest/api/3/search` returns 410 Gone on this instance). Warn that the beta API failed. |
 
 ## Team Conventions
 

skills/rhdh-jira/references/acli-commands.md

@@ -14,18 +14,20 @@ Cheat sheet for `acli jira` commands. For full flag details, run `acli jira <sub
 
 ### Search
 
+> ⚠️ **Default page size is 30 results.** Results beyond 30 are silently dropped with no warning. Always pass `--limit 200` or `--paginate` for bulk queries. Use `--count` first to verify the total matches before fetching.
+
 ```bash
-# JQL search with field selection
-acli jira workitem search --jql "project = RHIDP AND status = 'In Progress'" --fields "key,summary,status,assignee" --limit 50
+# JQL search with field selection (always set --limit for bulk)
+acli jira workitem search --jql "project = RHIDP AND status = 'In Progress'" --fields "key,summary,status,assignee" --limit 200
 
 # JSON output for full field data
-acli jira workitem search --jql "project = RHIDP" --limit 20 --json
+acli jira workitem search --jql "project = RHIDP" --limit 200 --json
 
-# Count only
+# Count only (check total before fetching)
 acli jira workitem search --jql "project = RHDHBUGS AND status not in (Closed)" --count
 
 # CSV export
-acli jira workitem search --jql "project = RHIDP" --fields "key,summary,status" --csv
+acli jira workitem search --jql "project = RHIDP" --fields "key,summary,status" --csv --limit 200
 
 # Fetch all results (paginated)
 acli jira workitem search --jql "project = RHIDP AND sprint in openSprints()" --paginate

skills/rhdh-jira/references/graphql-queries.md

@@ -154,10 +154,10 @@ If you discover stable mutations in the future via introspection, verify they do
 ## Caveats
 
 1. **`issueSearchStable` is beta.** Requires `X-ExperimentalApi: JiraIssueSearch` header. May break without notice. If you get a `BetaHeaderOptInException` error, add this header.
-2. **Team field values on issues are limited.** `JiraTeamViewField` on issues exposes `selectedTeam.jiraSuppliedName` and `fullTeam.members` but not all sub-fields. For direct team roster lookup (without going through an issue), use `team.teamV2(id, siteId)` — see the Team Roster Query pattern below.
-3. **`cloudId` is required on every query.** Use `2b9e35e3-6bd3-4cec-b838-f4249ee02432` for redhat.atlassian.net. Discover it via `/_edge/tenant_info` (see Authentication section).
-4. **Rate limiting is cost-based.** 10,000 points per user per minute. HTTP 429 with `RETRY-AFTER` header when exceeded. Do not retry on 5xx.
-5. **Operation names are mandatory.** Every query must have a name (e.g., `query GetIssue { ... }`). Unnamed queries will be rejected in the future.
+2. **All queries MUST have an operation name.** Anonymous queries (`query { ... }`) are rejected with "An operation name must be provided to the query to augment observability." Always use named operations: `query MyQueryName { ... }`. This is enforced now, not "in the future."
+3. **Team field values on issues are limited.** `JiraTeamViewField` on issues exposes `selectedTeam.jiraSuppliedName` and `fullTeam.members` but not all sub-fields. For direct team roster lookup (without going through an issue), use `team.teamV2(id, siteId)` — see the Team Roster Query pattern below.
+4. **`cloudId` is required on every query.** Use `2b9e35e3-6bd3-4cec-b838-f4249ee02432` for redhat.atlassian.net. Discover it via `/_edge/tenant_info` (see Authentication section).
+5. **Rate limiting is cost-based.** 10,000 points per user per minute. HTTP 429 with `RETRY-AFTER` header when exceeded. Do not retry on 5xx.
 6. **No spec file to download.** Unlike REST (which has an OpenAPI spec), GraphQL schema is discovered via introspection queries only. Use `__type` or the full `__schema` query. See Schema Discovery section.
 
 ## Team Roster Query

skills/rhdh-jira/references/jql-patterns.md

@@ -76,6 +76,8 @@ project = RHIDP AND issuetype = Story AND 'Parent Link' is EMPTY AND 'Epic Link'
 
 Use `parent = KEY` for all new queries. `Epic Link` and `parentEpic` are legacy.
 
+> ⚠️ Cross-project `parent = KEY` queries (e.g., finding RHIDP Epics under a RHDHPLAN Feature) work reliably via `acli` but may fail via GraphQL `issueSearchStable` or REST search (410 Gone). Always use `acli jira workitem search --jql "parent = KEY" --limit 200` for hierarchy lookups.
+
 ## Release & Planning Queries
 
 ```jql

skills/rhdh-jira/references/refine.md

@@ -6,6 +6,18 @@ Uses GraphQL for bulk reads (skip acli). Writes follow the API preference order
 
 Authentication setup: see `references/auth.md`. All examples below assume `AUTH`, `CLOUD_ID`, and `GRAPHQL_URL` are set per that file.
 
+## Refinement Context
+
+Before generating the report, determine the refinement context. Ask or infer from conversation.
+
+| Context | Goal | Urgency framing |
+|---------|------|------------------|
+| **Pre-release prep** | Features are ready to start work when the release kicks off | "Ready for a clean start" |
+| **Mid-release hygiene** | In-flight features are on track, no blockers | "On track for delivery" |
+| **Feature freeze triage** | All features must be complete or descoped | "Must close or descope before freeze" |
+
+The context affects report tone, Slack messages, and which checks matter most. Pre-release prep cares about sizing + child epics + Refinement transition readiness. Freeze triage cares about completion + blockers + descope candidates.
+
 ## Input
 
 The caller provides one of:

skills/rhdh-jira/references/rest-api-fallback.md

@@ -4,6 +4,18 @@ Use the Jira REST API when `acli` cannot update a custom field. This is a fallba
 
 Authentication setup: see `references/auth.md`. All examples below assume `AUTH` is set per that file.
 
+## JQL Search via REST
+
+The REST API v3 search endpoint (`/rest/api/3/search`) returns **HTTP 410 Gone** on the Red Hat Jira instance (both POST and GET). This is an Atlassian-side deprecation — do not attempt REST search as a fallback.
+
+**Search priority order:**
+
+1. `acli jira workitem search` (with `--limit 200` or `--paginate`)
+2. GraphQL `issueSearchStable` (beta, requires experimental header)
+3. REST search is **not available** on this instance
+
+REST remains valid for single-issue reads (`GET /rest/api/3/issue/{key}`) and field updates (`PUT /rest/api/3/issue/{key}`).
+
 ## Schema Discovery
 
 The REST API v3 has a published OpenAPI spec. Use it to discover endpoints, field formats, and payload shapes.