a7b15298e0
Brings 47 local-only files from backup-local-main into the merge-upstream
branch at their pre-rename paths. Subsequent steps will rename these to
the ce-* convention and port shared-file merges.
Includes:
- Custom skills: john-voice, jira-ticket-writer, hugo-blog-publisher,
weekly-shipped, proof-push, ship-it, story-lens, sync-confluence,
excalidraw-png-export, python-package-writer, fastapi-style,
upstream-merge
- Custom agents: design-conformance-reviewer, tiangolo-fastapi-reviewer,
zip-agent-validator, python-package-readme-writer, lint
- Custom commands: essay-edit, essay-outline, pr-comments-to-todos,
resolve_todo_parallel, workflows/{plan,review,work}
- Local mods to ce-review/SKILL.md + review-output-template.md (will be
ported to ce-code-review in a later step)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# 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)
|