Merge step (c): converge to ce-* convention for agents and skills
Some checks failed
CI / pr-title (push) Has been cancelled
CI / test (push) Has been cancelled
Release PR / release-pr (push) Has been cancelled
Release PR / publish-cli (push) Has been cancelled

Aligns local custom agents, skills, and modified shared agents with upstream's
flat ce-<name>.agent.md + ce-<skill>/ convention introduced in upstream v3.x.

Changes:
- Delete 9 upstream-renamed agents for locally-dropped agents (design/*, rails
  reviewers, ankane-readme-writer, data-migration-expert, performance-oracle,
  security-sentinel)
- Delete ce-dhh-rails-style skill (local dropped dhh-rails-style entirely)
- Move 5 custom agents to flat ce-<name>.agent.md paths:
  * python-package-readme-writer, design-conformance-reviewer,
    tiangolo-fastapi-reviewer, zip-agent-validator, lint
- Rename 12 custom skill directories with ce- prefix:
  * 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
- Port local Python/FastAPI edits into upstream's flat ce-best-practices-
  researcher.agent.md and ce-kieran-python-reviewer.agent.md
- Update frontmatter name: fields in all 17 renamed files to match new paths

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
John Lamb
2026-04-24 12:53:31 -05:00
parent a7b15298e0
commit 5d4377338e
56 changed files with 35 additions and 3550 deletions

View File

@@ -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

View File

@@ -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)