Merge upstream v2.40.0 with local fork additions preserved
Incorporates 163 upstream commits (origin/main) while preserving all local skills, agents, and commands. Metadata descriptions updated to reflect actual component counts (30 agents, 56 skills, 7 commands). file-todos/SKILL.md merged with both upstream command rename and local assessment fields. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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