feat: add REST API/GraphQL fallback to rhdh-jira skill

rhdh-jira skill:
- Add REST API fallback for custom field updates (Story Points, Size, Team,
  Release Note Type) when acli silently fails
- Add GraphQL query patterns for complex reads (issueSearchStable with JQL,
  single-issue with all custom fields, pagination)
- Add auth.md as single-sourced token/credential reference (no transitive
  loading between REST and GraphQL references)
- Add OpenAPI spec discovery and GraphQL introspection for dynamic schema
  discovery
- Add .jira-token capability gate with setup.py validation (format, permissions)
- Add Getting Started guide link for acli setup
- Add 4 new gotchas (redhat-developer#9-redhat-developer#12): custom field failures, sprint JSON wrapping,
  GraphQL beta header, token format
- Update setup.py: token file check, permission warnings, multi-line detection

skill-maker:
- Add references/api-skill-patterns.md: credential handling, API schema
  discovery, live validation, instance-specific values
- Add Reference Architecture section to spec-guide.md: agent-only audience,
  transitive loading anti-pattern, error placement, decision tables
- Update Phase 1 interview: new question about external services/APIs
- Update Phase 5 checklist: reference architecture and API skill checks

Author: schultzp2020

skills/rhdh-jira/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rhdh-jira
 description: |
-  Interact with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using the Atlassian CLI (acli). Use when the user needs to search, create, view, edit, transition, comment on, or link Jira issues for Red Hat Developer Hub. Also use when the user asks about Jira workflows, exit criteria, issue templates, custom fields, boards, sprints, or JQL queries in the RHDH context. Trigger when the user mentions Jira issue keys like RHIDP-1234, RHDHPLAN-567, RHDHBUGS-890, or any RHDH project key. Also trigger for support case bug filing, feature request creation, or release planning in Jira. Covers acli setup, authentication, and troubleshooting.
+  Interacts with RHDH Jira projects (RHIDP, RHDHPLAN, RHDHBUGS, RHDHSUPP) using the Atlassian CLI (acli), with REST API and GraphQL fallback for custom field updates and complex queries. Use when the user needs to search, create, view, edit, transition, comment on, or link Jira issues for Red Hat Developer Hub. Also use when the user asks about Jira workflows, exit criteria, issue templates, custom fields, boards, sprints, JQL queries, or Jira API schema discovery. Trigger when the user mentions Jira issue keys like RHIDP-1234, RHDHPLAN-567, RHDHBUGS-890, or any RHDH project key. Also trigger for support case bug filing, feature request creation, release planning, or acli setup and installation.
 compatibility: "acli (Atlassian CLI) on PATH. Python 3 for scripts. Windows, macOS, Linux."
 ---
 
@@ -20,9 +20,17 @@ python scripts/setup.py
 The script checks:
 1. `acli` binary on PATH
 2. Jira API token auth configured (`~/.config/acli/jira_config.yaml`)
-3. Smoke test against `redhat.atlassian.net`
+3. `.jira-token` file next to `acli` executable (for REST API fallback)
+4. Smoke test against `redhat.atlassian.net`
 
-If `acli` is not installed, download from [Atlassian CLI](https://developer.atlassian.com/cloud/acli/). Authenticate with `acli auth login` or configure an API token.
+If `acli` is not installed, download from [Atlassian CLI](https://developer.atlassian.com/cloud/acli/) and follow the [Getting Started guide](https://developer.atlassian.com/cloud/acli/guides/how-to-get-started/) for installation and authentication setup. Use API token authentication, not OAuth — OAuth sessions expire and `acli auth status` gives false negatives with token auth (see Gotchas).
+
+### REST/GraphQL capability gate
+
+Before attempting any REST API or GraphQL call:
+1. Run `python scripts/setup.py --json` and check `token_file_found`
+2. If missing, state: "REST API/GraphQL fallback unavailable — `.jira-token` not configured. Run `setup.py` for instructions." Continue with acli-only workflow.
+3. If the user needs REST/GraphQL, load `references/auth.md` for setup instructions
 
 ## Scripts
 
@@ -64,6 +72,9 @@ Load only what the current task requires.
 | `references/templates.md` | Creating new issues. Also load `references/workflows.md` for required fields at entry status. |
 | `references/support.md` | Handling support cases, filing bugs from customer cases, or creating feature requests from support. |
 | `references/jql-patterns.md` | Building a JQL query, finding a board ID, or looking up sprint information. JQL cookbook with 23+ tested queries. |
+| `references/auth.md` | Setting up authentication for REST API or GraphQL calls. Token file format, path discovery, security, instance config, common auth errors. |
+| `references/rest-api-fallback.md` | `acli` failed to update a custom field (Team, Size, Story Points, Release Note Type). Curl examples, response handling, OpenAPI spec discovery. |
+| `references/graphql-queries.md` | Complex read queries needing multiple fields, relationships, or custom field data in one call. Schema introspection, JQL search via GraphQL, field type fragments. |
 
 ## Common Gotchas
 
@@ -75,19 +86,23 @@ Load only what the current task requires.
 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. **`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.
+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.
+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.
 
 ## Error Handling
 
 | Error | Action |
 |-------|--------|
-| `acli` not on PATH | Run `scripts/setup.py`. Install from Atlassian if missing. |
+| `acli` not on PATH | Run `scripts/setup.py`. Install from Atlassian if missing. See [Getting Started](https://developer.atlassian.com/cloud/acli/guides/how-to-get-started/). |
 | "unauthorized" from `auth status` | Ignore. Check `jira_config.yaml` exists. Run smoke test. |
 | "required flag(s) not set" | Command syntax wrong. Run `acli jira <subcommand> --help`. |
 | "field X is not allowed" | Use `--json` instead of `--fields` for that field. |
 | "the value X does not exist for the field 'project'" | Project key is wrong or project is archived (e.g., RHDHPAI). |
 | 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. |
 
 ## Common Workflows
 
@@ -106,7 +121,18 @@ Load only what the current task requires.
 2. Verify required fields are set before transitioning
 3. Run `acli jira workitem transition --key KEY --status "X" --yes`
 
+### Complex queries (many fields, relationships)
+1. Load `references/graphql-queries.md`
+2. Use `issueByKey` for single issues or `issueSearchStable` (beta) for JQL search
+3. Fall back to `acli` + `parse_issues.py --enrich` if GraphQL returns errors
+
+### Discovering unknown fields or endpoints
+1. For REST: load `references/rest-api-fallback.md` — use the OpenAPI spec or `/rest/api/3/field` endpoint
+2. For GraphQL: load `references/graphql-queries.md` — use `__type` introspection queries
+3. Do not guess field IDs or types — always verify against the live schema
+
 ## When NOT to Use
 
 - **Non-RHDH Jira projects** — this skill's field mappings, workflows, and JQL patterns are specific to RHIDP/RHDHPLAN/RHDHBUGS/RHDHSUPP
-- **Jira REST API directly** — this skill covers `acli` CLI only
+- **Jira REST API directly** — use `acli` first. REST API is a fallback for custom field updates and schema discovery when `acli` cannot handle the operation (see Gotcha #9)
+- **GraphQL for simple lookups** — use `acli` for single-issue views and simple searches. GraphQL is for complex queries needing relationships or many custom fields in one call, and for schema introspection

skills/rhdh-jira/references/auth.md

@@ -0,0 +1,63 @@
+# Authentication and Token Setup
+
+Shared authentication for REST API and GraphQL calls. Both use the same `.jira-token` file with basic auth.
+
+**Never read the `.jira-token` file into context.** Pass it to `curl -u` via shell substitution.
+
+## Token File
+
+The `.jira-token` file lives next to the `acli` executable (same directory). Format is a single line:
+
+```
+email@example.com:your-api-token
+```
+
+Use the same API token you used to authenticate `acli`.
+
+## Token Discovery (Shell)
+
+```bash
+ACLI_DIR="$(dirname "$(readlink -f "$(which acli)" 2>/dev/null || which acli)")"
+TOKEN_FILE="$ACLI_DIR/.jira-token"
+if [ ! -f "$TOKEN_FILE" ]; then
+  echo "ERROR: .jira-token not found next to acli at $ACLI_DIR"
+  echo "Create it with: echo 'your-email@example.com:your-api-token' > $TOKEN_FILE"
+  echo "Then: chmod 600 $TOKEN_FILE"
+  exit 1
+fi
+AUTH=$(cat "$TOKEN_FILE")
+```
+
+The `AUTH` value is `email:api-token`, passed directly as basic auth credentials via `curl -u "$AUTH"`.
+
+## Security
+
+The `.jira-token` file contains plaintext credentials. Restrict permissions:
+- Unix/macOS: `chmod 600 .jira-token`
+- Windows: restrict access via file properties → Security tab
+
+The `setup.py` script warns when the file is group/world-readable.
+
+## Instance Config
+
+```bash
+CLOUD_ID="2b9e35e3-6bd3-4cec-b838-f4249ee02432"
+JIRA_BASE="https://redhat.atlassian.net"
+```
+
+### Discovering your cloudId
+
+The `cloudId` above is for `redhat.atlassian.net`. To discover it for any Jira Cloud instance:
+
+```bash
+curl -s -u "$AUTH" "$JIRA_BASE/_edge/tenant_info" | python -c "import json,sys; print(json.load(sys.stdin)['cloudId'])"
+```
+
+## Common Auth Errors
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| 401 on REST/GraphQL calls | `.jira-token` is bare token without email prefix | Format must be `email:token` |
+| 401 after token was working | API token expired or revoked | User must regenerate at Atlassian account settings |
+| `acli auth status` says unauthorized | False negative — `auth status` checks OAuth, not API tokens | Ignore. Use `acli jira project list --recent 1` as smoke test |
+| `.jira-token` not found | File is next to symlink, not the real binary | `setup.py` uses `resolve()` to follow symlinks — place file next to real binary |