ticket-drafting-guidelines

created	2025-12-16T00:00:00.000Z
modified	2026-08-15T00:00:00.000Z
reviewed	2026-04-25T00:00:00.000Z
name	ticket-drafting-guidelines
description	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.
user-invocable	false
allowed-tools	Read, Grep, WebFetch

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:

## 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:

## 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:

## 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:

## 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:

## What
### Subsection if needed

Links:

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

Lists:

- Simple bullet points
- One item per line
- Clear and actionable

Code blocks:

```language
code example here
```

Emphasis:

**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:

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:

✅ 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:

✅ Use environment variables for configuration
✅ Validate input before processing
✅ Handle errors with clear messages

Neutral Tone

Maintain factual, objective language:

✅ "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:

## 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:

✅ Concrete steps or tasks
✅ Components to implement
✅ Dependencies between tasks

Keep scope factual and concrete:

✅ Concrete steps or tasks
✅ Measurable acceptance criteria
✅ Observable behavior changes
✅ Verifiable outcomes

Example:

## How

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

Complete Examples

Feature Request

## What

Add dark mode support to the web interface. This provides an alternative
color scheme that reduces eye strain in low-light conditions. Related to
[#789](https://github.com/owner/repo/issues/789).

Reference: [CSS color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)

## Why

Users requested dark mode in the feedback survey. Many users work in
low-light environments where bright interfaces cause discomfort. Dark mode
is standard in modern web applications.

## How

- Add theme toggle component to navigation
- Create CSS custom properties for color scheme
- Implement system preference detection
- Store user preference in localStorage
- Update documentation with theme customization guide

Example implementation: [theme-switcher](https://web.dev/prefers-color-scheme/)

Bug Report

## What

Authentication token expires before refresh occurs. Users see login prompt
during active sessions. Occurs in [#234](https://github.com/owner/repo/issues/234).

See [JWT best practices](https://tools.ietf.org/html/rfc8725) for reference.

## Why

Token refresh logic waits until expiration before requesting new token.
Network latency causes gap between expiration and refresh completion. This
interrupts user workflows and creates poor experience.

## How

- Update refresh trigger to occur before expiration
- Add buffer time of 60 seconds before token expires
- Implement retry logic for failed refresh attempts
- Log refresh timing for monitoring
- Add unit tests for refresh timing edge cases

Reference: [Auth0 token refresh](https://auth0.com/docs/secure/tokens/refresh-tokens)

Refactoring Task

## What

Migrate build system from webpack to Vite. This updates the development
tooling and build configuration. Related to [PR #567](https://github.com/owner/repo/pull/567).

See [Vite guide](https://vitejs.dev/guide/) for migration details.

## Why

Current webpack configuration requires significant maintenance. Vite provides
faster development server and simpler configuration. The team approved
tooling modernization in the Q4 planning discussion.

## How

- Install Vite and remove webpack dependencies
- Create `vite.config.ts` based on current webpack config
- Update package.json scripts for dev and build
- Migrate environment variable handling
- Update CI/CD pipeline build commands
- Document new development workflow

Migration guide: [webpack to Vite](https://vitejs.dev/guide/migration.html)

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

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

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

Listing Steps

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

Code References

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