agentic-qe 2.0.0 → 2.1.0

package/.claude/skills/technical-writing/SKILL.md

@@ -1,211 +1,163 @@
 ---
 name: technical-writing
-description: Write clear, engaging technical content from real experience. Use when writing blog posts, documentation, tutorials, or technical articles.
+description: "Write clear, engaging technical content from real experience. Use when writing blog posts, documentation, tutorials, or technical articles."
+category: communication
+priority: medium
+tokenEstimate: 800
+agents: [qe-quality-analyzer, qe-api-contract-validator]
+implementation_status: optimized
+optimization_version: 1.0
+last_optimized: 2025-12-03
+dependencies: []
+quick_reference_card: true
+tags: [writing, documentation, communication, blogs, tutorials]
 ---
 
-# Technical Writing Skill
+# Technical Writing
 
-## Purpose
-Write clear, engaging technical content that practitioners actually want to read. No corporate fluff, no vendor speak. Real insights from real experience.
+<default_to_action>
+When writing technical content:
+1. LEAD with value (what will reader learn/gain?)
+2. SHOW, don't tell (specific examples, code, numbers)
+3. STRUCTURE for scanning (headers, bold, short paragraphs)
+4. CUT ruthlessly (every sentence must earn its place)
+5. BE honest about trade-offs
 
-## Core Principles
+**Blog Post Structure:**
+```markdown
+# Title (specific promise)
 
-### 1. Lead with Value
-Start with what the reader will learn or gain. Skip the preamble.
-
-**Bad:** "In today's fast-paced software development landscape, quality has become increasingly important..."
-**Good:** "Here's how we reduced bug escape rate by 60% without adding test automation."
+## Opening (2-3 paragraphs)
+- Hook: The problem or insight
+- Context: Why this matters
+- Promise: What they'll learn
 
-### 2. Show, Don't Just Tell
-Use specific examples from actual work. Code snippets, real scenarios, actual numbers.
+## Body (3-5 sections)
+- One clear idea per section
+- Support with examples/code/data
 
-```
-Generic: "We improved our testing approach."
-Specific: "We switched from scripted E2E tests to risk-based exploratory sessions. 
-Bug detection improved from 12 to 47 issues per sprint while cutting test execution time by 40%."
+## Closing
+- Key takeaway (1-2 sentences)
+- Action reader can take
 ```
 
-### 3. Be Honest About Trade-offs
-Nothing works everywhere. Share what you gave up to gain something else.
+**Before/After:**
+❌ "We implemented a comprehensive testing strategy..."
+✅ "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement."
+</default_to_action>
 
-Example: "TDD slowed our initial feature velocity by 20%, but reduced production bugs by 75% and made refactoring fearless."
+## Quick Reference Card
 
-### 4. Structure for Scanning
-- Use clear headers that tell the story
-- Bold key points
-- Keep paragraphs short (3-5 sentences max)
-- Use code blocks for technical details
-- Lists for options or steps
+### Core Principles
 
-### 5. Cut Ruthlessly
-Every sentence must earn its place. Kill:
-- Hedge words (basically, actually, probably)
-- Corporate speak (leverage, synergy, paradigm shift)
-- Unnecessary qualifiers (very, really, quite)
-- Repetition of the same point
+| Principle | Bad | Good |
+|-----------|-----|------|
+| **Lead with value** | "In today's landscape..." | "Here's how we cut bugs 60%" |
+| **Show, don't tell** | "We improved testing" | "Bug detection: 12→47 per sprint" |
+| **Be specific** | "Performance improved" | "Response time: 2.3s→180ms" |
+| **Honest trade-offs** | "This approach is best" | "TDD slowed velocity 20%, reduced bugs 75%" |
 
-## Blog Post Structure
+### Words to Cut
 
-### Opening (2-3 paragraphs)
-- Hook: The problem or surprising insight
-- Context: Why this matters
-- Promise: What they'll learn
-
-### Body (3-5 sections)
-- Each section: one clear idea
-- Support with examples, code, data
-- Explain your reasoning
-- Show alternatives considered
+| Kill | Reason |
+|------|--------|
+| basically, actually, probably | Hedge words |
+| leverage, synergy, paradigm | Corporate speak |
+| very, really, quite | Unnecessary qualifiers |
+| it should be noted that | Just note it |
 
-### Closing
-- Key takeaway (1-2 sentences)
-- Action readers can take
-- Optional: What's next for you
+---
 
-## Writing for Different Audiences
+## Audience-Specific Writing
 
 ### For Developers
 - Lead with code or concrete problem
 - Show implementation details
 - Discuss trade-offs and alternatives
-- Link to repos or working examples
+- Link to repos or examples
 
 ### For QA/QE
 - Start with testing challenge
-- Show testing strategy, not just tools
-- Include risk assessment thinking
-- Provide heuristics they can adapt
+- Show strategy, not just tools
+- Include risk assessment
+- Provide adaptable heuristics
 
 ### For Leadership
 - Open with business impact
-- Use metrics that matter (not vanity metrics)
-- Connect technical decisions to outcomes
+- Use metrics that matter
+- Connect technical to outcomes
 - Keep technical details concise
 
-### For General Tech Audience
-- Use analogies from everyday life
-- Define jargon when first used
-- Focus on concepts over implementation
-- Make it relatable
-
-## Common Pitfalls
-
-**Tutorial Hell:** Don't just list steps. Explain *why* each step matters.
-
-**False Expertise:** Only write about what you've actually done in production. If you're exploring, say so.
-
-**Tool Worship:** Focus on problems and approaches, not specific tools. Tools change, principles persist.
-
-**Defensive Writing:** Don't pre-apologize or over-qualify. State your experience clearly and invite discussion.
-
-## Voice and Tone
-
-- **Direct:** Say what you mean
-- **Conversational:** Write like you're explaining to a colleague over coffee
-- **Confident but humble:** Share what worked for you, acknowledge context matters
-- **Occasionally irreverent:** It's okay to call out BS in the industry
+---
 
 ## Editing Checklist
 
 Before publishing:
-- [ ] Does the title promise something specific?
-- [ ] Does the opening hook the reader in 30 seconds?
-- [ ] Are claims backed by specific examples?
-- [ ] Have I cut all unnecessary words?
-- [ ] Would I send this to a colleague I respect?
-- [ ] Are code examples tested and correct?
-- [ ] Is the takeaway crystal clear?
+- [ ] Title promises something specific
+- [ ] Opening hooks in 30 seconds
+- [ ] Claims backed by examples
+- [ ] All unnecessary words cut
+- [ ] Code examples tested and correct
+- [ ] Takeaway crystal clear
+- [ ] Would send to respected colleague
+
+---
 
 ## Example Transformations
 
-**Before:** "We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."
+**Before:**
+"We decided to implement a more comprehensive testing strategy that would allow us to catch bugs earlier in the development lifecycle."
 
-**After:** "We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."
+**After:**
+"We moved exploratory testing into sprint planning. QE now pairs with devs during story refinement, identifying risks before code is written."
 
 ---
 
-**Before:** "The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."
+**Before:**
+"The benefits of this approach are numerous and include improved quality, faster feedback loops, and better team collaboration."
 
-**After:** "Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design."
+**After:**
+"Three outcomes: bugs found 2 days earlier on average, 30% fewer regression issues, and devs now ask QE for input during design."
 
-## Resources
-
-- **Plain Language:** www.plainlanguage.gov
-- **On Writing Well** by William Zinsser
-- **Technical Blogging** by Antonio Cangiano (pragmatic approach)
-- Your own blog archives - review what got engagement vs. what flopped
-
-## Using with QE Agents
+---
 
-### Automated Documentation Generation
+## Agent Integration
 
-**qe-quality-analyzer** generates documentation from code:
 ```typescript
-// Agent generates documentation from source code
-const docs = await agent.generateDocs({
+// Generate documentation from code
+const docs = await Task("Generate Docs", {
   source: 'src/services/PaymentService.ts',
   format: 'markdown',
-  includeExamples: true,
-  includeApiDocs: true,
-  includeTypeDefinitions: true
-});
-
-// Generates:
-// - Function signatures
-// - Parameter descriptions
-// - Return types
-// - Usage examples
-// - Error handling docs
-```
-
-### Documentation Quality Review
+  includeExamples: true
+}, "qe-quality-analyzer");
 
-```typescript
-// Agent reviews documentation for quality
-const docReview = await qe-quality-analyzer.reviewDocumentation({
-  files: ['README.md', 'docs/api.md', 'docs/guides/*.md'],
+// Review documentation quality
+const review = await Task("Review Docs", {
+  files: ['README.md', 'docs/api.md'],
   checkClarity: true,
-  checkCompleteness: true,
-  checkAccuracy: true,
   checkCodeExamples: true
-});
-
-// Returns:
-// {
-//   issues: [
-//     { file: 'README.md', line: 45, issue: 'Example code is outdated' },
-//     { file: 'docs/api.md', line: 12, issue: 'Missing error response docs' }
-//   ],
-//   score: 0.82
-// }
+}, "qe-quality-analyzer");
 ```
 
-### Automated README Updates
+---
 
-```typescript
-// Agent keeps README in sync with code
-const readmeUpdate = await qe-quality-analyzer.syncReadme({
-  source: 'src/',
-  readme: 'README.md',
-  sections: {
-    installation: true,
-    usage: true,
-    api: true,
-    examples: true
-  },
-  preserveManual: true  // Keep manually written sections
-});
-```
+## Agent Coordination Hints
 
-### Documentation Fleet
+### Memory Namespace
+```
+aqe/technical-writing/
+├── generated-docs/*   - Auto-generated documentation
+├── reviews/*          - Documentation review findings
+└── templates/*        - Reusable doc templates
+```
 
+### Fleet Coordination
 ```typescript
 const docsFleet = await FleetManager.coordinate({
   strategy: 'documentation',
   agents: [
-    'qe-quality-analyzer',     // Generate and review docs
-    'qe-api-contract-validator', // API documentation accuracy
-    'qe-test-generator'        // Generate example code
+    'qe-quality-analyzer',         // Generate and review
+    'qe-api-contract-validator'    // API doc accuracy
   ],
   topology: 'sequential'
 });
@@ -214,16 +166,13 @@ const docsFleet = await FleetManager.coordinate({
 ---
 
 ## Related Skills
-
-**Communication:**
-- [bug-reporting-excellence](../bug-reporting-excellence/) - Technical writing for bugs
+- [bug-reporting-excellence](../bug-reporting-excellence/) - Technical bug writing
 - [code-review-quality](../code-review-quality/) - Review documentation
 
-**Development:**
-- [agentic-quality-engineering](../agentic-quality-engineering/) - Doc automation
-
 ---
 
 ## Remember
 
-You're not writing to impress people. You're writing to help them solve problems you've already solved. Be the colleague you wish you'd had when you were figuring this stuff out.
+**You're not writing to impress.** You're writing to help people solve problems you've already solved. Be the colleague you wish you'd had.
+
+**Write from experience.** Only write about what you've done in production. If exploring, say so.