ticket-grooming

What this skill does

# Ticket Grooming

Investigate one or more tickets, then post structured "Triaging Notes" as a comment. Notes are written for two audiences: PMs who need to understand the issue and prioritize it, and engineers who need to know where to start.

**Announce at start:** "Using ticket-grooming to investigate [ticket(s)]."

## Inputs

Extract from the user's message:
- **Ticket key(s) or URL(s)** (e.g., `DL-1234`, `https://zombie.atlassian.net/browse/DL-1234`, `#42`)
- OR a **verbal description** of the issue
- **Flags:**
  - `--dry-run` — preview without posting
  - `--full` — post the full report (no collapsed section)
- **Mode:** `--full` flag > `grooming-mode` in CLAUDE.md > default (`short`)

## Depth Calibration

Not every ticket needs the full pipeline. Match investigation depth to the ticket's complexity.

| Signal | What to run | Staff review? |
|--------|-------------|---------------|
| **Cosmetic** (label, copy, UI text) | Phases 0, 1 (shallow), 5. Skip root cause and risk assessment. | No |
| **Standard bug or feature** | Full pipeline (phases 0-5) | Yes |
| **Security / data integrity** | Full pipeline + security checklist in staff review | Yes |

**How to detect:** Classify during Phase 0 (understand the ticket). If the ticket is clearly cosmetic — no logic change, no data change, no authorization change — use the shallow path. When in doubt, use the full pipeline.

## Pre-Flight

Before dispatching sub-agents:

### 1. Check codebase index

If `codebase-memory-mcp` is available: call `index_status`, re-index if stale. Sub-agents verify via `index_status` but do NOT re-index.

### 2. Detect ticket system

Resolution order: CLAUDE.md config > URL pattern (`*.atlassian.net` = Jira, `github.com` = GitHub) > key pattern (`XX-1234` = Jira, `#1234` = GitHub) > ask user.

| System | Read | Search | Post |
|--------|------|--------|------|
| Jira | `getJiraIssue` | `searchJiraIssuesUsingJql` | `addCommentToJiraIssue` |
| GitHub | `gh issue view` | `gh issue list`, `gh pr list` | `gh issue comment` |

**acli fallback:** Use `acli` CLI when MCP lacks a capability (deleting comments, bulk edits). `acli --body-file` accepts ADF JSON only.

### 3. Resolve GitHub remote info

For each repo: extract org/repo from `git remote get-url origin`, get HEAD SHA via `git rev-parse HEAD`, verify pushed. Fallback: relative paths instead of permalinks.

### 4. Backend tickets: resolve both API repos

| Repo | Path | GitHub |
|------|------|--------|
| `cobalt-pentest-api` | `~/Documents/dev/cobalt-pentest-api` | `cobalthq/cobalt-pentest-api` |
| `cobalt-admin-api` | `~/Documents/dev/cobalt-admin-api` | `cobalthq/cobalt-admin-api` |

`cobalt-admin-api` is mid-migration into `cobalt-pentest-api` (under `components/admin/`). Search both, fix only in `cobalt-pentest-api`. Skip for frontend-only tickets.

### 5. Multi-ticket: detect shared context

When grooming 2+ tickets: read all, check for overlapping components. If overlap found, run shared investigation once and pass as context. Otherwise dispatch independently.

### 6. Dispatch sub-agents

- 1 sub-agent per ticket (two-level only — sub-agents don't spawn their own)
- Max 3 concurrent. Queue additional as slots free.
- Each gets fresh context — no shared state between tickets.

## Investigation

Dispatch each sub-agent using the template in **[references/investigation-prompt.md](references/investigation-prompt.md)**. The prompt assembles content from these reference files:

| File | What it covers |
|------|---------------|
| [accuracy-rules.md](references/accuracy-rules.md) | 7 rules for grounding findings in actual code (no hallucinating names, verify mechanisms, challenge hypotheses, label verified vs speculative, stay on the reporter's problem, respect framework behavior, leave verification trails) |
| [pipeline.md](references/pipeline.md) | Investigation phases: understand the ticket, investigate the code, check history, find root cause, assess risks, write notes |
| [output-templates.md](references/output-templates.md) | Writing style rules (PM-readable, plain language, technical terms in context) and templates for short, full, and non-code tickets |
| [estimation-priority.md](references/estimation-priority.md) | T-shirt sizing table and P1-P3 priority matrix |

## Staff Engineer Review

After the investigation sub-agent returns, dispatch a review sub-agent using **[references/staff-review-prompt.md](references/staff-review-prompt.md)** with `model: "sonnet"`.

The review checks:
- Is the note about the reporter's actual problem? (highest priority)
- Are all named entities verified in the codebase?
- Are hypotheses backed by evidence with counterarguments?
- Are visible sections PM-readable? (no unexplained jargon, plain language)
- Correctness, security, and pattern adherence

**Skip staff review only for cosmetic tickets** (per depth calibration above).

## Post the Notes

After staff review:

| Verdict | Action |
|---------|--------|
| **PASS** | Post as-is |
| **PASS WITH NOTES** | Post as-is, mention notes to user |
| **NEEDS FIXES** | Apply fixes, post corrected version, report what changed |

**Posting rules:** See [output-templates.md](references/output-templates.md) for full posting and iteration tracking details.
- **Jira (full mode):** Set `contentFormat: "markdown"` on `addCommentToJiraIssue`. Omitting it breaks rendering.
- **Jira (short mode):** MUST use ADF JSON — markdown cannot produce the expand node. Construct the full ADF document (visible sections + expand node), write to `/tmp/triaging-notes-{TICKET_KEY}.json`, post via `acli --body-file`. See [adf-posting.md](references/adf-posting.md) for the exact procedure and skeleton template. NEVER use HTML `<details>` tags — Jira does not render them.
- **GitHub:** Post markdown directly.

**After posting:**
1. Add `has_notes` label to the ticket
2. Set priority field based on the Priority section in the notes

**`--dry-run`:** Show notes in conversation. Ask "Post to ticket?" before posting.

**Multi-ticket progress:**
```
Grooming 3 tickets...
  - DL-1234: Posted (review: PASS)
  - DL-1235: Posted (review: NEEDS FIXES -- 2 corrections applied)
  - DL-1236: In progress -- staff review
```

## No Ticket? No Problem.

When the user describes an issue verbally (no ticket key):
1. Run the investigation pipeline (default to standard depth unless the description is clearly cosmetic)
2. Present findings in conversation
3. Ask: "Should I create a ticket with these notes?" (respect project rules about ticket creation)

## Reference Files

| File | Contents |
|------|----------|
| [investigation-prompt.md](references/investigation-prompt.md) | Sub-agent prompt template with placeholder assembly |
| [accuracy-rules.md](references/accuracy-rules.md) | 7 investigation accuracy rules |
| [pipeline.md](references/pipeline.md) | Investigation phases 0-5 |
| [output-templates.md](references/output-templates.md) | Writing style rules and output templates (short, full, non-code) |
| [estimation-priority.md](references/estimation-priority.md) | T-shirt estimation table and P1-P3 priority matrix |
| [staff-review-prompt.md](references/staff-review-prompt.md) | Staff engineer review prompt and checklist |
| [adf-posting.md](references/adf-posting.md) | ADF expand node reference and posting details |
| [error-handling.md](references/error-handling.md) | What to do when things fail |
| [framework-detection.md](references/framework-detection.md) | Framework detection logic and per-framework investigation rules |
| [configuration.md](references/configuration.md) | CLAUDE.md configuration options |

## Skills Referenced

| Skill | When |
|-------|------|
| `systematic-debugging` | Root cause analysis (phases 1-3 only, no implementation) |
| `dispatching-parallel-agents` | Multi-ticket invocations (max 3 concurrent) |