Panama/user/agents/skills/create-ticket/SKILL.md

---
name: create-ticket
description: Use when Gib is authoring a Jira ticket himself and wants it written for him, e.g. /create-ticket KACP-XXXXX pointing at an empty or placeholder-titled story, spike, or task that needs its summary, description, and acceptance criteria filled in.
---

# Create Ticket

Fills out a Jira ticket Gib is authoring: fetches the (usually empty) ticket, gathers
context from the epic and local docs, writes the content in the Ksense house format,
and updates the ticket in Jira. Invoked as `/create-ticket KACP-XXXXX`, with the key
as the skill's arguments. Multiple keys may be passed to fill several tickets in one
run, each processed fully before the next.

This is the authoring counterpart to the `/ticket` skill, which is for working
tickets assigned to Gib. This skill only writes ticket content, it never creates
branches, plans, or code.

The house formats below are extracted from the team's "Claude Project Manager"
prompt, which the rest of the team uses through claude.ai. Keeping these formats
identical is the point: a story written here must be indistinguishable in structure
from one written by the PM team. The chat-oriented parts of that prompt (workflow
classification tree, the Revise: loop, the questions-by-impact feedback table,
meeting agendas, email templates) are deliberately not part of this skill.

## Jira access

Same conventions as the `/ticket` skill:

- Always Gib's credentials: run `source ~/.bashrc 2>/dev/null` in the same Bash call
  before any Jira command, then check `JIRA_CREDENTIALS` is set. Never use staging
  Infisical's Jira credentials. `JIRA_BASE_URL` defaults to
  `https://ksense-tech.atlassian.net`.
- Fetch with `~/.agents/skills/ticket/scripts/jira-fetch-issue.sh <KEY> <OUT.json>`
  (rendered description, full field map) or plain curl against
  `/rest/api/3/issue/<KEY>`.
- Write with curl: `PUT /rest/api/2/issue/<KEY>` with a JSON body like
  `{"fields": {"summary": "...", "description": "..."}}`. The v2 endpoint accepts
  Jira wiki markup in `description`, which is the reliable scriptable path for
  tables and headings. Expect HTTP 204 on success.

## Process

1. **Fetch context.** Get the ticket, its parent epic, and the sibling summaries
   (`parent = <EPIC> ORDER BY created`). Read the local epic folder if one exists,
   `.claude/docs/epics/<EPIC-KEY>/`, including any deliverables, plans, or epic
   breakdown documents there. Those documents are usually where the real scope for
   each story has already been worked out, so the ticket should say what they say,
   not a fresh invention. If the repo is relevant (a rebuild of an existing page,
   a schema change), check the actual code before describing current behavior.
2. **Pick the artifact type.** Story is the default. Spike when the ticket is an
   investigation (title says Spike, or the goal is answering questions rather than
   shipping). Point task for a single trivial change. If genuinely ambiguous, ask
   Gib rather than guessing.
3. **Resolve open questions before writing.** The team prompt appends a
   questions-by-impact table for chat iteration. Here, do it live instead: if
   something high-impact is genuinely undecided and not answerable from the docs,
   epic, or code, ask Gib directly (AskUserQuestion) before drafting. Low-impact
   unknowns become numbered Notes on the story, kept few.
   Where the open question is not Gib's to answer, because it belongs to the PM, a
   designer, or the client, do not put it to him as though it were. Say who owns it,
   and offer to draft a questionnaire with `/to-questionnaire` so it can go to that
   person in one pass. If Gib would rather ship the story without waiting, the question
   becomes a numbered Note naming its owner.
   Where the scope of the story itself is unsettled, meaning the epic docs, the
   deliverables, and the code do not already say what this ticket covers, one question
   is not enough and drafting anyway is how invented scope gets in. Call the Skill tool
   with "grilling" and work its frontier with Gib until the scope is agreed, then draft.
   This is the exception rather than the default. Most stories have their scope already
   worked out in the epic docs, and those go straight to step 4.
4. **Draft the content** in the matching format below, in markdown first.
   Then call the Skill tool with "unslop" and apply its pattern detection to the
   draft: puffery, superficial -ing phrases, "not just X but Y", vague attributions,
   rule of three padding, alongside the punctuation rules above. Skip its "Adding soul"
   section entirely. The house formats are rigid templates and an AC table does not
   want voice, it wants to read as though a person wrote it plainly. Conrad reads these,
   and prose that reads as machine generated costs the ticket its credibility before
   anyone weighs what it actually says.
5. **Overwrite guardrail.** If the ticket already has a non-trivial description
   (anything beyond a placeholder), show what is there and confirm before
   replacing it. Empty or placeholder tickets are filled without asking.
6. **Write to Jira.** Convert the markdown to wiki markup (cheat sheet below) and
   PUT it. If the current summary is a placeholder or fake name, replace it with a
   real title, following whatever prefix convention the epic's siblings use (for
   example `UI - `, `Datamodel - `). Never touch tickets other than the ones asked
   for.
7. **Verify.** Refetch with `expand=renderedFields` and check the description
   rendered as intended, especially tables. Fix and re-PUT if anything rendered as
   literal markup.
8. **Keep a local copy.** Save the markdown version to
   `.claude/docs/epics/<EPIC-KEY>/<TICKET-KEY>/story.md` (or `spike.md` /
   `task.md`), creating directories as needed. These are personal docs, never
   committed.

## House rules for all content

- Spelling: always `Ksense` (not KSENSE or KSense), always `Knack` (transcripts
  often mis-transcribe it as NAC).
- Plain punctuation. No em dashes, en dashes, semicolons, or arrow glyphs.
- Acceptance criteria are user-focused, independent, and testable, phrased in third
  person present tense with the user as subject.
- Priorities are P1, P2, P3.
- Notes are numbered and referenced from the AC table's Referenced Note column by
  number. Drop any note that just restates an AC.
- If requirements came from a video or call recording, the Artifacts field is
  `See Video` and a note says `Requirements extracted from provided video
  walkthrough`. Never paste transcript text into the ticket.
- Do not invent scope. Everything in the ticket must trace to the epic docs, the
  deliverables, the code, or what Gib said. Thin ticket beats padded ticket.

## Story format

```
## **As a [type of user], I want to [perform some action] so that I can [achieve some goal or benefit].**

**Acceptance Criteria:**
| ID | Acceptance Criteria | Referenced Note | Priority | Completed |
| --- | --- | --- | --- | --- |
| AC-1 | [Requirement] | [Note number or blank] | P1 | |
| AC-2 | [Requirement] | | P2 | |

**Notes:**
1. [Detailed note]
2. [Detailed note]

**Technical Requirements:**
- **Work Type**: [Standard Knack/Knack + Custom Code/Full Custom]
- **Custom Code Components**: [None/JavaScript/CSS/External API/...]
- **Code Robustness**: [MVP/Standard/High]
- **Test Coverage**: [None/Basic/Comprehensive]
- **Security Level**: [Basic/Enhanced/Compliance-Required]

**Testing Requirements:**
- [Browser compatibility, mobile responsive, error handling, role testing, as applicable]

**Artifacts**
[See Video | links | None]
```

The Jira summary is the story title, so the description starts at the As-a
sentence. Command Center work is always `Full Custom` (Next.js/React); the Knack
work types and the `Knack Implementation Details` block (Objects Affected,
Views/Pages, Code Placement) exist only for Knack app tickets, include that block
only then. Technical Requirements and Testing Requirements are included for any
ticket involving custom code, which for KCC is all of them except pure-copy
changes.

Level definitions, used verbatim when choosing values:

- Code Robustness: MVP is happy path only, proof of concept. Standard handles
  common edge cases with user-friendly errors, production-ready. High handles all
  edge cases with detailed logging and graceful degradation.
- Test Coverage: None is manual developer testing. Basic covers critical paths
  with unit tests. Comprehensive is full unit plus integration coverage.
- Security Level: Basic is platform-standard. Enhanced adds role-based
  permissions, audit logging, or data protection concerns. Compliance-Required
  means HIPAA/PCI/government standards.

## Spike format

```
**Investigation Goal:**
[What question(s) need to be answered? What decision needs to be made?]

**Context:**
[Why is this investigation needed? What problem are we trying to solve?]

**Questions to Answer:**
| Priority | Question | Why It Matters |
| --- | --- | --- |
| High | [Question] | [Impact on architecture/design/timeline] |
| Medium | [Question] | [Impact] |

**Investigation Tasks:**
* [ ] Research [specific topic]
* [ ] Prototype [specific approach]
* [ ] Document findings

**Success Criteria:**
- All high-priority questions answered with data or evidence
- Clear recommendation documented for team decision
- Findings shared in [format]

**Time Box:** [X hours/days]

**Deliverables:**
- Written findings document
- Code prototype (if applicable)
- Recommendation with pros and cons

**Notes:**
[Constraints, risks, additional context]
```

Spikes measure success by answered questions and a recommendation, not shipped
functionality. Keep the questions table to what actually blocks or informs the
implementation decision.

## Point task format

```
**Location**: [Object/View/Form/route identifier]
**Action**: [Specific change required]
**Success Criteria**: [How to verify completion]
**Notes**: [Only if essential]
```

For a single trivial change. No story sentence, no AC table.

## Markdown to Jira wiki markup cheat sheet

For the v2 `description` field:

- `## Heading` becomes `h2. Heading` (h3. for deeper)
- `**bold**` becomes `*bold*`
- Table header row `| A | B |` becomes `||A||B||`, body rows stay `|A|B|`, one row
  per line, no separator row
- Numbered list items become `# item`, bullets become `* item`
- Checkboxes have no wiki syntax, so Investigation Tasks render as plain bullets
  and the Completed column stays blank (the team fills it in Jira)
- Code spans stay `{{monospace}}`, blocks become `{code}...{code}`
- Literal square brackets in prose must be avoided, wiki markup reads `[...]` as a
  link
- Checked boxes in team templates: `[ ]` renders literally and is fine to keep for
  unchecked options, but `[x]` renders as a red error span. Mark selected options
  with `(/)`, Jira's green check icon, instead

Send the description as one string with `\n` newlines. After the PUT, always do
the rendered-fields verification pass, wiki table syntax fails quietly when a row
has mismatched pipes.