Docs: Jira column missing from reference.md promptTemplate variables table; integration.md has wrong value for {{.Number}}

[kelos-bot]

🤖 Kelos User Agent @gjkim42

Summary

Two related documentation inaccuracies affect users trying to write promptTemplate for the Jira source:

1. reference.md promptTemplate variables table is missing the Jira column

The promptTemplate Variables section in reference.md has columns for GitHub Issues, GitHub Pull Requests, GitHub Webhook, Linear Webhook, Generic Webhook, and Cron — but no Jira column. A user setting up a Jira TaskSpawner and looking at the canonical reference to understand what template variables are available will find nothing.

The integration.md does have a Jira column in its template variables table, but:

• reference.md is the canonical reference — the README links there for the full spec
• The integration.md table has at least one inaccuracy (see below)

2. integration.md documents {{.Number}} as 0 for Jira — but the code returns the numeric key suffix

The integration.md table says:

| {{.Number}} | ... | 0 (Jira) | ... |

However, internal/source/jira.go calls extractIssueNumber(issue.Key) which returns the trailing number from the Jira key:

func extractIssueNumber(key string) int {
    parts := strings.SplitN(key, "-", 2)
    if len(parts) == 2 {
        if n, err := strconv.Atoi(parts[1]); err == nil {
            return n
        }
    }
    return 0
}

For a key like ENG-42, {{.Number}} renders as 42, not 0. Users who see the 0 in the docs will avoid using {{.Number}} in branch templates (e.g., branch: "jira-{{.Number}}") when it would actually work correctly.

What the Jira source actually populates

Based on internal/source/jira.go:

Variable	Value
{{.ID}}	Full Jira issue key (e.g., ENG-42)
{{.Number}}	Numeric suffix of the key (e.g., 42 for ENG-42)
{{.Title}}	Issue summary
{{.Body}}	Empty (tracked separately in #990)
{{.URL}}	Jira browse URL (e.g., https://your-org.atlassian.net/browse/ENG-42)
{{.Labels}}	Comma-separated labels
{{.Comments}}	Concatenated comment bodies
{{.Kind}}	Jira issue type name (e.g., "Bug", "Story"), or "Issue" if empty

Fix

1. reference.md: Add a Jira column to the promptTemplate Variables table (between GitHub Webhook and Linear Webhook, to match integration.md ordering).
2. integration.md: Correct {{.Number}} from 0 to Numeric key suffix (e.g., 42 for ENG-42).

Note: {{.Body}} is always empty due to bug #990 — the Jira source does not fetch the description field. The docs should reflect this until #990 is fixed.

[kelos-bot]

🤖 Kelos Task Status

Task kelos-triage-issues-9f482a6e729f has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs
Priority: priority/important-soon — integration.md actively documents a wrong value ({{.Number}} shown as 0 for Jira), which discourages users from a template variable that does work; combined with the missing Jira column in the canonical reference.md, this is a real adoption blocker for Jira users.
Actor: actor/kelos — concrete, objectively verifiable docs change in two files; no API surface or design decisions involved.

Status: STILL VALID

Evidence:

• docs/reference.md:271-272 — the promptTemplate Variables table columns are: GitHub Issues, GitHub Pull Requests, GitHub Webhook, Linear Webhook, Generic Webhook, Cron. No Jira column, confirming the gap.
• docs/integration.md:406 — the Jira cell for {{.Number}} is literally `0`.
• internal/source/jira.go:86,97 populate Number: extractIssueNumber(issue.Key), and extractIssueNumber (internal/source/jira.go:202-209) returns the trailing integer from the key (e.g., 42 for ENG-42), only returning 0 when the key has no -N suffix. So the issue body's correction is accurate.
• docs/integration.md:408 is additionally inaccurate: it lists {{.Body}} for Jira as "Issue description", but internal/source/jira.go never sets WorkItem.Body — this is the same bug tracked in Bug: Jira source {{.Body}} always empty — description field not fetched from API #990. Fix should reflect reality (Empty) until Bug: Jira source {{.Body}} always empty — description field not fetched from API #990 lands.
• No merged PR references this issue. Open PR docs: document Jira TaskSpawner fields #1068 ("docs: document Jira TaskSpawner fields") addresses Docs: Jira source fields nearly absent from reference.md — only pollInterval documented, required fields missing #1061 and part of Docs: Jira source type undocumented in reference — only pollInterval field appears #777, but only adds reference rows for baseUrl/project/jql/secretRef; it does not touch the promptTemplate Variables table or the integration.md {{.Number}} cell, so Docs: Jira column missing from reference.md promptTemplate variables table; integration.md has wrong value for {{.Number}} #1193 is not subsumed.

Duplicates found:

• Docs: Jira source type undocumented in reference — only pollInterval field appears #777 — overlaps partially: its point (4) calls out the same missing Jira column in the promptTemplate Variables table, but Docs: Jira source type undocumented in reference — only pollInterval field appears #777 is a broader gap report (TaskSpawner field rows, secret format, example manifest) and does not flag the {{.Number}}=0 inaccuracy in integration.md. Recommend keeping both: Docs: Jira column missing from reference.md promptTemplate variables table; integration.md has wrong value for {{.Number}} #1193 is the focused, immediately actionable docs fix; Docs: Jira source type undocumented in reference — only pollInterval field appears #777 is the umbrella.
• Docs: Jira source fields nearly absent from reference.md — only pollInterval documented, required fields missing #1061 — related but distinct: missing TaskSpawner field rows (baseUrl, project, etc.) in reference.md, not the template variables table. Already has open PR docs: document Jira TaskSpawner fields #1068.
• Bug: Jira source {{.Body}} always empty — description field not fetched from API #990 — related: tracks the underlying {{.Body}}-empty bug; Docs: Jira column missing from reference.md promptTemplate variables table; integration.md has wrong value for {{.Number}} #1193 should align the doc with reality (mark Empty + reference Bug: Jira source {{.Body}} always empty — description field not fetched from API #990) until Bug: Jira source {{.Body}} always empty — description field not fetched from API #990 is fixed.

Recommendation: KEEP OPEN — small, well-scoped docs fix that complements (does not duplicate) #1068. Safe for actor/kelos to take after #1068 lands (to avoid table-edit conflict) or in parallel since the two PRs touch different tables.