new jira ticket writing skill and details on paying attention to names
Some checks failed
CI / test (push) Has been cancelled
Some checks failed
CI / test (push) Has been cancelled
This commit is contained in:
John Lamb
@@ -465,6 +465,22 @@ end
|
||||
|
||||
### 6. Final Review & Submission
|
||||
|
||||
**Naming Scrutiny (REQUIRED for any plan that introduces new interfaces):**
|
||||
|
||||
When the plan proposes new functions, classes, variables, modules, API fields, or database columns, scrutinize every name:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Should private helpers be private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match existing codebase conventions? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? (`data`, `manager`, `handler` = red flags) |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
Bad names in plans become bad names in code. Catching them here is cheaper than catching them in review.
|
||||
|
||||
**Pre-submission Checklist:**
|
||||
|
||||
- [ ] Title is searchable and descriptive
|
||||
@@ -472,6 +488,7 @@ end
|
||||
- [ ] All template sections are complete
|
||||
- [ ] Links and references are working
|
||||
- [ ] Acceptance criteria are measurable
|
||||
- [ ] All proposed names pass the naming scrutiny checklist above
|
||||
- [ ] Add names of files in pseudo code examples and todo lists
|
||||
- [ ] Add an ERD mermaid diagram if applicable for new model changes
|
||||
|
||||
|
||||
@@ -179,6 +179,30 @@ Complete system context map with component interactions
|
||||
- Engineering best practices
|
||||
- Technical documentation quality
|
||||
- Tooling and automation assessment
|
||||
- **Naming accuracy** (see Naming Scrutiny below)
|
||||
|
||||
#### Naming Scrutiny (REQUIRED)
|
||||
|
||||
Every name introduced or modified in the PR must pass these checks:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Are private helpers actually private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match every other instance in the codebase? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? (`data`, `manager`, `handler` = red flags) |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? (`auth` = authentication or authorization?) |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
**Common anti-patterns to flag:**
|
||||
- False optionality: `save_with_validation()` when validation is mandatory
|
||||
- Leaked implementation: `create_batch_with_items()` when callers just need `create_batch()`
|
||||
- Type encoding: `word_string`, `new_hash` instead of domain terms
|
||||
- Structural naming: `input`, `output`, `result` instead of what they contain
|
||||
- Doppelgangers: names differing by one letter (`useProfileQuery` vs `useProfilesQuery`)
|
||||
|
||||
Include naming findings in the synthesized review. Flag as P2 (Important) unless the name is actively misleading about behavior (P1).
|
||||
|
||||
#### Business Value Angle
|
||||
|
||||
|
||||
@@ -137,14 +137,30 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Follow project coding standards (see CLAUDE.md)
|
||||
- When in doubt, grep for similar implementations
|
||||
|
||||
4. **Test Continuously**
|
||||
4. **Naming Scrutiny (Apply to every new name)**
|
||||
|
||||
Before committing any new function, class, variable, module, or field name:
|
||||
|
||||
| # | Check | Question |
|
||||
|---|-------|----------|
|
||||
| 1 | **Caller's perspective** | Does the name describe what it does, not how? |
|
||||
| 2 | **No false qualifiers** | Does every `_with_X` / `_and_X` reflect a real choice? |
|
||||
| 3 | **Visibility matches intent** | Are private helpers actually private? |
|
||||
| 4 | **Consistent convention** | Does the pattern match every other instance in the codebase? |
|
||||
| 5 | **Precise, not vague** | Could this name apply to ten different things? |
|
||||
| 6 | **Complete words** | No ambiguous abbreviations? |
|
||||
| 7 | **Correct part of speech** | Functions = verbs, classes = nouns, booleans = assertions? |
|
||||
|
||||
**Quick validation:** Search the codebase for the naming pattern you're using. If your convention doesn't match existing instances, align with the codebase.
|
||||
|
||||
5. **Test Continuously**
|
||||
|
||||
- Run relevant tests after each significant change
|
||||
- Don't wait until the end to test
|
||||
- Fix failures immediately
|
||||
- Add new tests for new functionality
|
||||
|
||||
5. **Figma Design Sync** (if applicable)
|
||||
6. **Figma Design Sync** (if applicable)
|
||||
|
||||
For UI work with Figma designs:
|
||||
|
||||
@@ -153,7 +169,7 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Fix visual differences identified
|
||||
- Repeat until implementation matches design
|
||||
|
||||
6. **Track Progress**
|
||||
7. **Track Progress**
|
||||
- Keep TodoWrite updated as you complete tasks
|
||||
- Note any blockers or unexpected discoveries
|
||||
- Create new tasks if scope expands
|
||||
@@ -424,6 +440,7 @@ Before creating PR, verify:
|
||||
- [ ] Tests pass (run project's test command)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] All new names pass naming scrutiny (caller's perspective, no false qualifiers, correct visibility, consistent conventions, precise, complete words, correct part of speech)
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Before/after screenshots captured and uploaded (for UI changes)
|
||||
- [ ] Commit messages follow conventional format
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
name: jira-ticket-writer
|
||||
description: This skill should be used when the user wants to create a Jira ticket. It guides drafting, pressure-testing for tone and AI-isms, and getting user approval before creating the ticket via the Atlassian MCP. Triggers on "create a ticket", "write a Jira ticket", "file a ticket", "make a Jira issue", or any request to create work items in Jira.
|
||||
---
|
||||
|
||||
# Jira Ticket Writer
|
||||
|
||||
Write Jira tickets that sound like a human wrote them. Drafts go through tone review before the user sees them, and nothing gets created without explicit approval.
|
||||
|
||||
## Reference
|
||||
For tickets pertaining to Talent Engine (Agentic App), TalentOS, Comparably, or the ATS Platform: Use the `ZR` Jira project
|
||||
When creating epics and tickets for Talent Engine always add the label `talent-engine` and prefix the name with "[Agentic App]"
|
||||
When creating epics and tickets for the ATS Platform always add the label `ats-platform` and prefix the name with "[ATS Platform]"
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Validate Scope
|
||||
|
||||
Before drafting anything, confirm two things:
|
||||
|
||||
1. **What the ticket is about.** Gather the ticket contents from the conversation or the user's description. If the scope is unclear or too broad for a single ticket, ask the user to clarify before proceeding.
|
||||
|
||||
2. **Where it goes.** Determine the Jira project key and optional parent (epic). If the user provides a Jira URL or issue key, extract the project from it. If not specified, ask.
|
||||
|
||||
To look up the Jira project and validate the epic exists, use the Atlassian MCP tools:
|
||||
- `mcp__atlassian__getAccessibleAtlassianResources` to get the cloudId
|
||||
- `mcp__atlassian__getJiraIssue` to verify the parent epic exists and get its project key
|
||||
|
||||
Do not proceed to drafting until both the content scope and destination are clear.
|
||||
|
||||
### Phase 2: Draft
|
||||
|
||||
Write the ticket body in markdown. Follow these guidelines:
|
||||
|
||||
- **Summary line:** Under 80 characters. Imperative mood. No Jira-speak ("As a user, I want...").
|
||||
- **Body structure:** Use whatever sections make sense for the ticket. Common patterns:
|
||||
- "What's happening" / "What we need" / "Context" / "Done when"
|
||||
- "Problem" / "Ask" / "Context"
|
||||
- Just a clear description with acceptance criteria at the end
|
||||
- **Code snippets:** Include relevant config, commands, or file references when they help the reader understand the current state and desired state.
|
||||
- **Keep it specific:** Include file paths, line numbers, env names, config values. Vague tickets get deprioritized.
|
||||
- **"Done when" over "Acceptance Criteria":** Use casual language for completion criteria. 2-4 items max.
|
||||
|
||||
### Phase 3: Pressure Test
|
||||
|
||||
Before showing the draft to the user, self-review against the tone guide.
|
||||
|
||||
Read `references/tone-guide.md` and apply every check to the draft. Specifically:
|
||||
|
||||
1. **Patronizing scan:** Read each sentence imagining you are the recipient, a specialist in their domain. Flag and rewrite anything that explains their own expertise back to them, tells them how to implement something in their own system, or preemptively argues against approaches they haven't proposed.
|
||||
|
||||
2. **AI-ism removal:** Hunt for em-dash overuse, bullet-point-everything formatting, rigid generated-feeling structure, spec-writing voice, and filler words (Additionally, Furthermore, Moreover, facilitates, leverages, streamlines, ensures).
|
||||
|
||||
3. **Human voice pass:** Read the whole thing as if reading it aloud. Does it sound like something a developer would type? Add moments of humility where appropriate ("you'd know better", "if we're missing something", "happy to chat").
|
||||
|
||||
4. **Kindness pass:** The reader is a human doing their job. Frame requests as requests. Acknowledge their expertise. Don't be demanding.
|
||||
|
||||
Revise the draft based on this review. Do not show the user the pre-review version.
|
||||
|
||||
### Phase 4: User Approval
|
||||
|
||||
Present the final draft to the user in chat. Include:
|
||||
- The proposed **summary** (ticket title)
|
||||
- The proposed **body** (formatted as it will appear)
|
||||
- The **destination** (project key, parent epic if any, issue type)
|
||||
|
||||
Ask for sign-off using AskUserQuestion with three options:
|
||||
- **Create it** — proceed to Phase 5
|
||||
- **Changes needed** — user provides feedback, return to Phase 2 with their notes and loop until approved
|
||||
- **Cancel** — stop without creating anything
|
||||
|
||||
### Phase 5: Create
|
||||
|
||||
Once approved, create the ticket:
|
||||
|
||||
1. Use `mcp__atlassian__getAccessibleAtlassianResources` to get the cloudId (if not already cached from Phase 1)
|
||||
2. Use `mcp__atlassian__createJiraIssue` with:
|
||||
- `cloudId`: from step 1
|
||||
- `projectKey`: from Phase 1
|
||||
- `issueTypeName`: "Task" unless the user specified otherwise
|
||||
- `summary`: the approved title
|
||||
- `description`: the approved body
|
||||
- `parent`: the epic key if one was specified
|
||||
3. Return the created ticket URL to the user: `https://discoverorg.atlassian.net/browse/<KEY>`
|
||||
@@ -0,0 +1,34 @@
|
||||
# Reference Documentation for Jira Ticket Writer
|
||||
|
||||
This is a placeholder for detailed reference documentation.
|
||||
Replace with actual reference content or delete if not needed.
|
||||
|
||||
Example real reference docs from other skills:
|
||||
- product-management/references/communication.md - Comprehensive guide for status updates
|
||||
- product-management/references/context_building.md - Deep-dive on gathering context
|
||||
- bigquery/references/ - API references and query examples
|
||||
|
||||
## When Reference Docs Are Useful
|
||||
|
||||
Reference docs are ideal for:
|
||||
- Comprehensive API documentation
|
||||
- Detailed workflow guides
|
||||
- Complex multi-step processes
|
||||
- Information too lengthy for main SKILL.md
|
||||
- Content that's only needed for specific use cases
|
||||
|
||||
## Structure Suggestions
|
||||
|
||||
### API Reference Example
|
||||
- Overview
|
||||
- Authentication
|
||||
- Endpoints with examples
|
||||
- Error codes
|
||||
- Rate limits
|
||||
|
||||
### Workflow Guide Example
|
||||
- Prerequisites
|
||||
- Step-by-step instructions
|
||||
- Common patterns
|
||||
- Troubleshooting
|
||||
- Best practices
|
||||
@@ -0,0 +1,53 @@
|
||||
# Tone Guide for Ticket Writing
|
||||
|
||||
## Core Principle
|
||||
|
||||
A human will read this ticket. Write like a teammate asking for help, not an AI generating a spec.
|
||||
|
||||
## Pressure Test Checklist
|
||||
|
||||
Review every sentence against these questions:
|
||||
|
||||
### 1. Patronizing language
|
||||
|
||||
- Does any sentence explain the reader's own domain back to them?
|
||||
- Would you say this to a senior engineer's face without feeling awkward?
|
||||
- Are you telling them HOW to implement something in their own system?
|
||||
- Are you preemptively arguing against approaches they haven't proposed?
|
||||
|
||||
**Examples of patronizing language:**
|
||||
- "This is a common pattern in Kubernetes deployments" (they know)
|
||||
- "Helm charts support templating via {{ .Values }}" (they wrote the chart)
|
||||
- "Why X, not Y" sections that dismiss alternatives before anyone suggested them
|
||||
|
||||
### 2. AI-isms to remove
|
||||
|
||||
- Em dashes used more than once per paragraph
|
||||
- Every thought is a bullet point instead of a sentence
|
||||
- Rigid structure that feels generated (Ask -> Why -> Context -> AC)
|
||||
- Spec-writing voice: "When absent or false, existing behavior is preserved"
|
||||
- Overuse of "ensures", "leverages", "facilitates", "streamlines"
|
||||
- Unnecessary hedging: "It should be noted that..."
|
||||
- Filler transitions: "Additionally", "Furthermore", "Moreover"
|
||||
- Lists where prose would be more natural
|
||||
|
||||
### 3. Human voice check
|
||||
|
||||
- Does it sound like something you'd type in Slack, cleaned up slightly?
|
||||
- Are there moments of humility? ("you'd know better than us", "if we're missing something")
|
||||
- Is the tone collaborative rather than directive?
|
||||
- Would you feel comfortable putting your name on this?
|
||||
|
||||
### 4. Kindness check
|
||||
|
||||
- Frame requests as requests, not demands
|
||||
- Acknowledge the reader's expertise
|
||||
- Offer context without over-explaining
|
||||
- "Happy to chat more" > "Please advise"
|
||||
|
||||
## What to keep
|
||||
|
||||
- Technical detail and specifics (the reader needs these)
|
||||
- Code snippets showing current state and desired state
|
||||
- File references with line numbers
|
||||
- Clear "done when" criteria (but keep them minimal)
|
||||
Reference in New Issue
Block a user