#464 Render ticket reference consistently in artifact headings

packages/agents/content/skills/create-ticket/SKILL.md

@@ -41,7 +41,7 @@ Create the ticket body describing WHAT needs to be done — problem, context, an
 {Optional enhancements}
 ```
 
-Also draft a short title (without ticket ID prefix) for use in step 5.
+Also draft a short title (without the `ticket_ref` prefix) for use in step 5.
 
 ### 3. Resolve platform
 
@@ -126,6 +126,11 @@ If `integrations.jira.enabled: true`, note that Jira creation needs additional c
 
 ### 6. Save local artifacts
 
+Compute `ticket_ref` for the heading from `ticket_id` and `ticket_ref_prefix` (both already in scope from step 1) using the same logic as `get-session-context`:
+
+- If `ticket_ref_prefix == '#'`: `ticket_ref = '#' + ticket_id`
+- Otherwise: `ticket_ref = ticket_id`
+
 Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
 
 `mkdir -p` the target directory before writing.
@@ -136,7 +141,7 @@ Save the ticket as a ticket-level artifact:
 {YYYYMMDD-HHMMZ}_{slug}_ticket.md
 ```
 
-The ticket artifact heading should include the ticket ID: `# {ticket_id}: {title}`.
+The ticket artifact heading should include the ticket reference: `# {ticket_ref}: {title}`. On a GitHub-style project (`ticket_ref_prefix: '#'`) with issue number `461`, this renders as `# #461: {title}`.
 
 Example: `20260226-2130Z_role-type-architecture_ticket.md`
 

packages/agents/content/skills/respond-to-review/SKILL.md

@@ -19,7 +19,7 @@ This skill bridges the gap between receiving a code review and implementing fixe
 
 ## Process
 
-1. **Get context** using `get-session-context` to obtain `ticket_id`, `project_slug`, and `artifact_base_dir`
+1. **Get context** using `get-session-context` to obtain `ticket_id`, `ticket_ref`, `project_slug`, and `artifact_base_dir`
 2. **Locate the review** per the [Locating the review](#locating-the-review) section
 3. **Read prior artifacts** in the run directory chronologically for full context
 4. **Parse findings**: extract all numbered findings (F{n}, W{n}, T{n}, R{n}, S{n}, and legacy variants with `-L` suffix). See [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix) for category definitions.
@@ -80,8 +80,10 @@ Per [artifact conventions](../_data/artifact-conventions.md#disposition-rules):
 
 ## Output format
 
+When `ticket_ref` is null (no ticket on the branch), omit the `{ticket_ref}: ` portion so the heading reads `# Change summary: {description}`.
+
 ```markdown
-# Change summary: {TICKET}: {description}
+# Change summary: {ticket_ref}: {description}
 
 Responding to: {filename of review being responded to}
 Timestamp: {YYYY-MM-DD HH:MM UTC}

packages/agents/content/skills/review-change/SKILL.md

@@ -16,7 +16,7 @@ Act as a conscientious code reviewer for changes in the current scope.
 
 ## Process
 
-1. **Get context** using `get-session-context` to obtain `default_branch`, `ticket_id`, `project_slug`, and `artifact_base_dir`
+1. **Get context** using `get-session-context` to obtain `default_branch`, `ticket_id`, `ticket_ref`, `project_slug`, and `artifact_base_dir`
 2. **Resolve ticket** _(branch scope only)_ — resolve the ticket source using this priority order:
    1. **Explicit argument** — if a `ticket` argument was provided, resolve it per the [Arguments](#arguments) table
    2. **Auto-resolve** — if no argument, scan `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` for the most recent `*_ticket.md` file and read it
@@ -60,10 +60,12 @@ Uniquely number all issues for easy reference. See [finding scheme](../_data/art
 
 ## Output format
 
+When `ticket_ref` is null (no ticket on the branch), omit the `{ticket_ref}: ` portion (or `{ticket_ref} ` for commit scope) so the heading reads naturally without it — e.g., `# Code review: {description}` or `# Commit review: [{WORK_TYPE}] - {description}`.
+
 ### Branch scope
 
 ```markdown
-# Code review: {TICKET}: {description in imperative mood}
+# Code review: {ticket_ref}: {description in imperative mood}
 
 Commit: {short hash of HEAD}
 Timestamp: {YYYY-MM-DD HH:MM UTC}
@@ -140,7 +142,7 @@ Extract criteria from whatever structure the ticket uses (numbered lists, checkb
 ### Commit scope
 
 ```markdown
-# Commit review: {TICKET} [{WORK_TYPE}] - {description in imperative mood}
+# Commit review: {ticket_ref} [{WORK_TYPE}] - {description in imperative mood}
 
 Commit: {short hash}
 Timestamp: {YYYY-MM-DD HH:MM UTC}

packages/agents/content/skills/summarize-change/SKILL.md

@@ -11,7 +11,7 @@ Analyze the current branch's changes since diverging from the default branch.
 ## Process
 
 1. **Gather context**:
-   - Use `get-session-context` to obtain `default_branch` and `ticket_id`; consult [work-types.md](../_data/work-types.md).
+   - Use `get-session-context` to obtain `default_branch`, `ticket_id`, and `ticket_ref`; consult [work-types.md](../_data/work-types.md).
 
 2. **Analyze changes**:
 
@@ -21,8 +21,8 @@ git diff $DEFAULT_BRANCH...HEAD
 
 Check commit messages for additional context.
 
-3. **Compose title**: `{ticket ID} {title}`
-   - Ticket ID appears in the change summary title (for identification) but must never appear in commit titles (per `commit` skill)
+3. **Compose title**: `{ticket_ref} {title}` (or just `{title}` when `ticket_ref` is null)
+   - The ticket reference appears in the change summary title (for identification) but must never appear in commit titles (per `commit` skill)
 
 4. **Write description** per the output format below
 
@@ -34,14 +34,14 @@ If expected information is missing, stop and ask the developer.
 
 ```markdown
 ---
-title: '{bare title without ticket ID}'
+title: '{bare title without `ticket_ref` prefix}'
 ticket_id: '{ticket ID from session context}'
 commit: '{short hash of HEAD}'
 scope: '{scope inferred from commit prefixes, or omitted if ambiguous}'
 type: '{work type inferred from commit prefixes, or omitted if ambiguous}'
 ---
 
-# {TICKET} {title}
+# {ticket_ref} {title}
 
 Commit: {short hash of HEAD}
 Timestamp: {YYYY-MM-DD HH:MMZ format}
@@ -103,6 +103,7 @@ Good: "Heavy-upload sessions were intermittently failing as users hit the upstre
 
 ## Guidance
 
+- When `ticket_ref` is null (no ticket on the branch), omit the `{ticket_ref} ` portion of the heading and the title so they read naturally without it.
 - The change summary follows **newspaper style** — progressive disclosure from most to least essential: `## What` is the headline (outcome in plain language), `## Why` is the context (motivation and background), `## Details` is the full story (implementation mechanics)
 - Ignore auto-formatter and lint-fix changes
 - Omit inapplicable Details subsections
@@ -114,7 +115,7 @@ Good: "Heavy-upload sessions were intermittently failing as users hit the upstre
 
 The YAML frontmatter provides machine-readable metadata for downstream consumers (e.g., `create-pr`).
 
-- **`title`**: The bare title without the ticket ID prefix. If the ticket is `#409` and the heading is `#409 Rationalize PR creation skills`, the title is `Rationalize PR creation skills`.
+- **`title`**: The bare title without the `ticket_ref` prefix. If `ticket_ref` is `#409` and the heading is `#409 Rationalize PR creation skills`, the title is `Rationalize PR creation skills`. When `ticket_ref` is null, the title is the entire heading text.
 - **`ticket_id`**: From `get-session-context`.
 - **`commit`**: Short hash of HEAD (`git rev-parse --short HEAD`).
 - **`scope`** and **`type`**: Infer from the commit message prefixes on the branch. Examine commits between the default branch and HEAD. If all (or the dominant majority of) commits share the same scope and type prefix (e.g., `agents|feat:`), use those values. If commits use mixed scopes or types with no clear dominant value, omit the ambiguous field entirely from the frontmatter. Omission is safe — downstream consumers treat missing fields as absent and skip the corresponding resolution step.