ticket-drafting-guidelines

# 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 ### Feature Request ```markdown ## 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 ```markdown ## 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 ```markdown ## 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 ```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