# Ticket Drafting Guidelines

> What/Why/How prose structure and neutral, positive register for issues, PR descriptions, and tick…

What/Why/How prose structure and neutral, positive register for issues, PR descriptions, and tickets. Use when wording a ticket body, tightening prose, or applying house tone.

- Page: https://ss33.ai/skills/laurigates/ticket-drafting-guidelines-52781739543
- Publisher: laurigates
- Category: [Software Development](https://ss33.ai/skills/category/software-development-t44z8z) › [Source control & code review](https://ss33.ai/skills/category/software-development-t44z8z/source-control-and-code-review-jebezw)
- License: MIT
- Source: https://github.com/laurigates/claude-plugins/blob/f8dc5cd452a2ed3af86ab7e65949e0653e88127f/communication-plugin/skills/ticket-drafting-guidelines/SKILL.md

## Skill

SKILL.md: https://ss33.ai/api/v1/ss33/download/laurigates/ticket-drafting-guidelines-52781739543

# Ticket Drafting Guidelines

Expert guidance for drafting clear, concise, and well-structured tickets for GitHub issues, pull requests, and technical documentation.

## When to Use This Skill

| Use this skill when... | Use google-chat-formatting instead when... |
|---|---|
| Drafting a GitHub issue, bug report, or feature request with What/Why/How structure | Posting a status update or announcement to a Google Chat channel |
| Writing a PR description or technical ticket with reference links | Converting Markdown headers and bold to Google Chat's single-asterisk syntax |
| Structuring a refactoring task or migration plan with concrete steps | Reformatting meeting notes or release notes for chat consumption |
| Wording the body text — What/Why/How sections, tone, reference links | Use `git-plugin:github-issue-writing` for the GitHub issue artifact itself: `[Type] Component:` title format, bug/feature templates, `gh issue create` |

## Core Expertise

- **Structured Format**: What/Why/How organization for clarity
- **Concise Writing**: Brief descriptions with reference links
- **Markdown Standards**: Proper formatting and link syntax
- **Positive Framing**: Affirmative language without negative phrasing
- **Neutral Tone**: Factual communication without claims or estimates
- **Reference Integration**: Links to official documentation

## Ticket Structure

### Main Headings

Every ticket uses three primary sections:

```markdown
## What

[Concise description of the subject]

## Why

[Context and motivation]

## How

[Implementation approach or resolution steps]
```

### What Section

**Purpose**: Describe the subject clearly and concisely.

**Guidelines:**
- State what the ticket addresses in 1-3 sentences
- Include relevant technical terms
- Link to related issues or PRs using `[#123](URL)` format
- Reference official documentation where applicable

**Example:**
```markdown
## What

Add support for TypeScript configuration in the build pipeline. This enables type checking during CI/CD runs and improves code quality. Related to [#456](https://github.com/owner/repo/issues/456).

See [TypeScript compiler options](https://www.typescriptlang.org/tsconfig) for configuration reference.
```

### Why Section

**Purpose**: Explain the motivation and context.

**Guidelines:**
- Describe the problem or opportunity
- Explain benefits of addressing this
- Include relevant background information
- Link to discussions or requirements docs

**Example:**
```markdown
## Why

Current build pipeline only validates JavaScript syntax. TypeScript type checking catches errors earlier in development and provides better IDE support. This reduces runtime errors and improves developer experience.

The team adopted TypeScript in [#234](https://github.com/owner/repo/pull/234) but hasn't enabled type checking in CI yet.
```

### How Section

**Purpose**: Outline the approach or solution.

**Guidelines:**
- Use simple bullet points
- List concrete steps or components
- Include technical details as needed
- Reference implementation examples or patterns

**Example:**
```markdown
## How

- Add TypeScript compiler to CI workflow
- Configure `tsconfig.json` with strict mode
- Update GitHub Actions workflow to run `tsc --noEmit`
- Document type checking process in CONTRIBUTING.md

Reference implementation: [GitHub Actions TypeScript](https://github.com/actions/typescript-action)
```

## Formatting Standards

### Markdown Elements

**Headings:**
```markdown
## What
### Subsection if needed
```

**Links:**
```markdown
[#123](https://github.com/owner/repo/issues/123)
[PR #456](https://github.com/owner/repo/pull/456)
[Official docs](https://example.com/docs)
```

**Lists:**
```markdown
- Simple bullet points
- One item per line
- Clear and actionable
```

**Code blocks:**
````markdown
```language
code example here
```
````

**Emphasis:**
```markdown
**bold** for important terms
`code` for technical names
```

### Reference Links

Include links to:
- Official documentation
- Related issues and PRs
- Relevant examples or patterns
- API references or specifications

**Format:**
```markdown
See [TypeScript Configuration](https://www.typescriptlang.org/tsconfig) for details.
Related: [#123](https://github.com/owner/repo/issues/123)
Example: [typescript-action](https://github.com/actions/typescript-action)
```

## Writing Style

### Positive Framing

**Use affirmative language:**
```markdown
✅ Enable TypeScript type checking in CI
✅ Add validation for user input
✅ Implement caching for API responses
```

**Describe what to do rather than what not to do:**
```markdown
✅ Use environment variables for configuration
✅ Validate input before processing
✅ Handle errors with clear messages
```

### Neutral Tone

**Maintain factual, objective language:**

```markdown
✅ "This adds TypeScript support to the build pipeline"
❌ "This amazing feature will revolutionize our build process"

✅ "Enables type checking during CI runs"
❌ "Dramatically improves code quality by 80%"

✅ "Reduces configuration complexity"
❌ "Makes configuration incredibly simple and super easy"
```

**Key principles:**
- State facts without exaggeration
- Describe capabilities objectively
- Provide context without making claims
- Use measured language

### Concise Descriptions

**Keep content brief:**
- 1-3 sentences per paragraph
- Simple bullet lists
- Direct language
- Essential details only

**Expand with links:**
```markdown
## What

Add Redis caching layer for API responses. This reduces database load and
improves response times. See [Redis documentation](https://redis.io/docs/)
for architecture details.
```

### Progress and Estimates

**What to include:**
```markdown
✅ Concrete steps or tasks
✅ Components to implement
✅ Dependencies between tasks
```

**Keep scope factual and concrete:**
```markdown
✅ Concrete steps or tasks
✅ Measurable acceptance criteria
✅ Observable behavior changes
✅ Verifiable outcomes
```

**Example:**
```markdown
## How

- Configure Redis connection
- Implement cache middleware
- Add cache invalidation logic
- Update API handlers to use cache
```

## Complete Examples

Full What/Why/How tickets for a feature request, a bug report, and a refactoring task: [references/complete-examples.md](references/complete-examples.md). Open it when drafting one of those ticket types from scratch.

## Integration with Other Skills

This skill works alongside:

- **Git Commit Workflow** - Consistent commit messages for ticket work
- **Git Branch PR Workflow** - PR descriptions match ticket structure
- **Release Please Protection** - References to automated changelog updates
- **GitHub Actions** - CI/CD workflow integration in tickets

## Best Practices

### Before Writing

- Understand the full context
- Identify relevant documentation
- Find related issues or PRs
- Note technical requirements

### While Writing

- Follow What/Why/How structure
- Keep descriptions concise
- Add reference links
- Use positive framing
- Maintain neutral tone

### After Writing

- Verify all links work
- Check markdown rendering
- Ensure clarity and completeness
- Confirm positive language throughout

## Common Patterns

### Linking Issues and PRs

```markdown
Related to [#123](https://github.com/owner/repo/issues/123)
Fixes [#456](https://github.com/owner/repo/issues/456)
Implements [#789](https://github.com/owner/repo/issues/789)
See [PR #234](https://github.com/owner/repo/pull/234)
```

### Linking Documentation

```markdown
See [official docs](https://example.com/docs)
Reference: [API documentation](https://api.example.com)
Guide: [configuration reference](https://example.com/config)
```

### Listing Steps

```markdown
- Single action per bullet
- Clear and specific
- Actionable items
- Logical order
```

### Code References

```markdown
Update `config.ts` with new options
Modify the `handleRequest` function
Add tests in `auth.test.ts`
```

## Agentic Optimizations

| Context | Command |
|---------|---------|
| List open issues for context | `gh issue list --state open --json number,title,labels --limit 10` |
| View existing issue for reference | `gh issue view N --json number,title,body` |
| Create issue from drafted content | `gh issue create --title "title" --body "body"` |
| Find related issues | `gh search issues "keyword" --repo owner/repo --json number,title --limit 5` |
| View PR template | `cat .github/PULL_REQUEST_TEMPLATE.md` |

## Skill Configuration

Located in `exact_dot_claude/skills/ticket-drafting-guidelines/` which becomes
`~/.claude/skills/ticket-drafting-guidelines/` after `chezmoi apply`:

- `SKILL.md` - This file (skill definition and guidelines)

## Success Indicators

This skill is working properly when:

✅ Tickets follow What/Why/How structure consistently
✅ Descriptions remain concise with reference links
✅ Language uses positive framing throughout
✅ Tone stays neutral without claims or estimates
✅ Markdown formatting renders correctly
✅ All links point to valid resources