diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 475a4415..04edc1bc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -32,6 +32,19 @@ "homepage": "https://github.com/kieranklaassen/compound-engineering-plugin", "tags": ["coding", "programming", "tutorial", "learning", "spaced-repetition", "education"], "source": "./plugins/coding-tutor" + }, + { + "name": "compound-writing", + "description": "AI-powered writing tools that compound your writing skills. Includes 7 specialized agents, 4 workflow commands, and 5 skills for research, drafting, editing, and voice consistency.", + "version": "1.0.0", + "author": { + "name": "Kieran Klaassen", + "url": "https://github.com/kieranklaassen", + "email": "kieran@every.to" + }, + "homepage": "https://github.com/EveryInc/compound-engineering-plugin", + "tags": ["ai-powered", "compound-writing", "writing-automation", "voice-consistency", "editorial", "content-creation"], + "source": "./plugins/compound-writing" } ] } diff --git a/.gitignore b/.gitignore index 7cfd02ba..fff68b2f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .DS_Store *.log node_modules/ +tmp/ diff --git a/plugins/compound-writing/.claude-plugin/plugin.json b/plugins/compound-writing/.claude-plugin/plugin.json new file mode 100644 index 00000000..d417e359 --- /dev/null +++ b/plugins/compound-writing/.claude-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "compound-writing", + "version": "1.2.0", + "description": "AI-powered writing tools that compound your writing skills. Includes 8 specialized agents, 8 workflow commands, and 9 skills for research, drafting, editing, and voice consistency.", + "author": { + "name": "Kieran Klaassen", + "email": "kieran@every.to", + "url": "https://github.com/kieranklaassen" + }, + "homepage": "https://every.to", + "repository": "https://github.com/EveryInc/every-marketplace", + "license": "MIT", + "keywords": [ + "ai-powered", + "compound-writing", + "writing-automation", + "voice-consistency", + "editorial", + "content-creation", + "style-guides", + "writing-workflow" + ] +} diff --git a/plugins/compound-writing/CHANGELOG.md b/plugins/compound-writing/CHANGELOG.md new file mode 100644 index 00000000..7431feda --- /dev/null +++ b/plugins/compound-writing/CHANGELOG.md @@ -0,0 +1,55 @@ +# Changelog + +All notable changes to the compound-writing plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-01-16 + +### Added + +#### Agents (6) +- `source-researcher` - Research sources, analyze audiences, study competitor content +- `fact-checker` - Verify claims, check statistics, ensure factual accuracy +- `structure-architect` - Create outlines, analyze flow, generate hooks +- `voice-guardian` - Maintain voice consistency, calibrate tone +- `clarity-editor` - Improve clarity, cut words, remove jargon, fix passive voice +- `publishing-optimizer` - Optimize for SEO, social media, newsletters + +#### Commands (4) +- `/writing:plan` - Transform a topic into a researched outline with sources +- `/writing:draft` - Execute an outline into prose with style guidance +- `/writing:review` - Multi-agent editorial review with interactive triage +- `/writing:compound` - Capture patterns from successful writing + +#### Skills (3) +- `pragmatic-writing` - Write like Hunt/Thomas (Pragmatic Programmer) and Joel Spolsky + - 10 core techniques with examples + - Before/after transformations + - Anti-patterns guide + - Source material references +- `dhh-writing` - Write in DHH's direct, opinionated style + - Short sentences, no hedging + - Contrarian framing techniques + - Strong endings +- `voice-capture` - Extract and encode voice profiles from samples + - Three-layer voice profile structure + - Analysis dimensions framework + - YAML template for profiles + +#### Pattern Capture System +- `docs/patterns/` directory structure for storing reusable patterns +- Categories: hooks, structures, transitions, voice + +### Notes + +Initial release implementing the compound writing philosophy: +- Four-phase workflow (plan, draft, review, compound) +- Voice profile system with three layers +- Quality gates for writing +- Pattern capture for compounding knowledge + +--- + +πŸ€– Generated with [Claude Code](https://claude.com/claude-code) diff --git a/plugins/compound-writing/CLAUDE.md b/plugins/compound-writing/CLAUDE.md new file mode 100644 index 00000000..f1ceeea1 --- /dev/null +++ b/plugins/compound-writing/CLAUDE.md @@ -0,0 +1,157 @@ +# Compound Writing Plugin - Development Guide + +## Philosophy + +**Each piece of writing should make the next piece easier to write.** + +This plugin applies compound engineering principles to content creation: +- Capture what works (patterns, voice, structure) +- Build reusable knowledge (scratchpad β†’ patterns β†’ voice profiles) +- Iterate faster each time + +## Architecture Reference + +See `docs/WRITING-ARCHITECTURE.md` for the complete framework mapping: +- 8 phases of professional writing +- 18 specialized agent roles +- 5 skill types (core, voice, style guide, domain, format) +- Implementation roadmap + +## Current Components + +### Commands (8) +| Command | Phase | Purpose | +|---------|-------|---------| +| `/writing:init` | Setup | Interactive project setup wizard | +| `/writing:plan` | Discovery/Architecture | Research and outline | +| `/writing:draft` | Creation | Generate prose | +| `/writing:review` | Editing | Multi-agent review | +| `/writing:feedback` | Any | Capture preferences to scratchpad | +| `/writing:knowledge` | Any | Manage voice/patterns/references | +| `/writing:compound` | Post-publish | Extract patterns | +| `/writing:skill` | Setup | Create new skills (voice, domain, format) | + +### Agents (8) +| Agent | Phase | Role | +|-------|-------|------| +| `source-researcher` | Discovery | Gather sources, analyze audience | +| `structure-architect` | Architecture | Create outlines, analyze flow | +| `voice-guardian` | Creation/Editing | Maintain voice consistency | +| `clarity-editor` | Editing | Improve clarity, cut jargon | +| `fact-checker` | Editing | Verify claims and sources | +| `every-style-editor` | Editing | Every's style guide | +| `ai-pattern-detector` | Editing | Detect AI slop (delve, tapestry, etc.) | +| `publishing-optimizer` | Optimization | SEO, social, newsletters | + +### Skills (9) +| Skill | Type | Purpose | +|-------|------|---------| +| `writing-orchestration` | Core | Two-agent architecture, strategies | +| `scratchpad` | Core | Session preference memory | +| `context-notes` | Core | Structured command handoffs | +| `voice-capture` | Core | Extract voice from samples | +| `pragmatic-writing` | Voice | Hunt/Thomas, Spolsky style | +| `dhh-writing` | Voice | Direct, opinionated style | +| `every-essay-guide` | Voice | Every essay craft (worldview, best practices, hed/dek) | +| `source-code-guide` | Voice | Source Code series (AI-era building, coining language) | +| `every-style-editor` | Editing | Mechanical review (grammar, punctuation, compliance) | + +## Key Concepts + +### Two-Agent Architecture +- **Orchestrator**: Classifies, researches, assesses readiness +- **Writer**: Creates drafts using strategies + +### Two-Gate Assessment +Before drafting, verify: +1. **Material Sufficiency**: Can write without inventing facts? +2. **Message Clarity**: Know exactly what message to convey? + +### Writing Strategies +- **10 Baseline** (always apply): Short sentences, active voice, concrete examples +- **20+ Situational** (select 3-4): Hook patterns, structure templates, style techniques + +### Scratchpad β†’ Knowledge Flow +``` +Session feedback β†’ Scratchpad β†’ Compound β†’ Pattern library + β†’ Voice profile + β†’ Knowledge base +``` + +## Adding New Components + +### New Agent +1. Create `agents/[name].md` with frontmatter: + ```yaml + --- + name: agent-name + description: What this agent does + --- + ``` +2. Define the agent's role, inputs, outputs +3. Update `plugin.json` count +4. Update `README.md` agent list + +### New Skill +1. Create `skills/[name]/SKILL.md` with frontmatter: + ```yaml + --- + name: skill-name + description: When to use this skill + --- + ``` +2. Add triggers, patterns, examples +3. Update `plugin.json` count +4. Update `README.md` skill list + +### New Voice Skill +Follow the pattern in `pragmatic-writing` or `dhh-writing`: +- Define voice traits +- Provide writing rules +- Include example transformations + +### New Domain Skill ("10 Books Expert") +See `docs/WRITING-ARCHITECTURE.md` for the pattern: +1. Core texts (5 foundational works) +2. Secondary texts (5 supporting works) +3. Key frameworks +4. Reasoning patterns + +## File Structure + +``` +plugins/compound-writing/ +β”œβ”€β”€ .claude-plugin/plugin.json +β”œβ”€β”€ CLAUDE.md # This file +β”œβ”€β”€ README.md # User documentation +β”œβ”€β”€ agents/ # 7 agents +β”œβ”€β”€ commands/ # 7 commands +β”œβ”€β”€ skills/ # 9 skills (organized by type) +β”‚ β”œβ”€β”€ core/ # Orchestration, assessment, memory +β”‚ β”‚ β”œβ”€β”€ writing-orchestration/ +β”‚ β”‚ β”œβ”€β”€ scratchpad/ +β”‚ β”‚ β”œβ”€β”€ context-notes/ +β”‚ β”‚ └── voice-capture/ +β”‚ β”œβ”€β”€ voice/ # Voices (can layer multiple) +β”‚ β”‚ β”œβ”€β”€ pragmatic-writing/ +β”‚ β”‚ β”œβ”€β”€ dhh-writing/ +β”‚ β”‚ β”œβ”€β”€ every-essay-guide/ +β”‚ β”‚ └── source-code-guide/ +β”‚ β”œβ”€β”€ editing/ # Review tools (for post-draft) +β”‚ β”‚ └── every-style-editor/ +β”‚ β”œβ”€β”€ domain/ # "10 Books Expert" (future) +β”‚ └── format/ # Channel-specific (future) +└── docs/ + └── WRITING-ARCHITECTURE.md # Full framework reference +``` + +## Quality Checklist + +When adding/modifying components: +- [ ] Frontmatter is valid YAML +- [ ] Description is clear and specific +- [ ] Integrates with scratchpad (reads/writes preferences) +- [ ] Outputs context notes for handoffs +- [ ] Follows existing patterns +- [ ] Counts updated in plugin.json +- [ ] README updated diff --git a/plugins/compound-writing/README.md b/plugins/compound-writing/README.md new file mode 100644 index 00000000..1af1754a --- /dev/null +++ b/plugins/compound-writing/README.md @@ -0,0 +1,477 @@ +# Compound Writing Plugin + +> Each unit of writing work should make subsequent units easierβ€”not harder. + +AI-powered writing tools that apply compound engineering principles to content creation. Build a system that learns your voice, captures what works, and makes every piece of writing faster than the last. + +## Installation + +```bash +claude /plugin install compound-writing +``` + +## Philosophy + +**The Compound Effect**: Every piece you write teaches the system. Patterns get captured, preferences get encoded, and your next piece benefits from everything before it. + +``` +Write β†’ Feedback β†’ Learn β†’ Write (faster) β†’ Feedback β†’ Learn β†’ Write (even faster) +``` + +**The 50/50 Rule**: Spend 50% improving your writing system (voice profiles, patterns, feedback), 50% actually writing. This feels slow at first. Within weeks, the compounding becomes obvious. + +## Quick Start + +### First Time Setup + +```bash +# Initialize compound-writing for your project (interactive wizard) +claude /writing:init + +# Or use minimal setup (no questions, just create structure) +claude /writing:init --minimal +``` + +This creates: +- `.claude/writing-knowledge/` β€” Voice profiles, patterns, references +- `drafts/` β€” Draft workspace with scratchpad +- `.claude/CLAUDE.md` β€” Project writing preferences + +### Writing Workflow + +```bash +# 1. Plan a piece with research +claude /writing:plan "How to debug production issues" + +# 2. Draft from the outline +claude /writing:draft drafts/debug-production/outline.md + +# 3. Give feedback on drafts +claude /writing:feedback draft-2 love the opening stat +claude /writing:feedback draft-1 too formal + +# 4. Refine based on feedback +claude /writing:draft refine draft-2 + +# 5. Run editorial review +claude /writing:review drafts/debug-production/draft-v1.md + +# 6. Capture what worked +claude /writing:compound drafts/debug-production/final.md +``` + +### Create Custom Skills + +```bash +# Create a voice from your writing samples +claude /writing:skill create voice "my-blog" ~/posts/*.md + +# Create a voice from description +claude /writing:skill create voice "founder-voice" "direct, vulnerable, builds in public" + +# Create domain expertise +claude /writing:skill create domain "persuasion" "Cialdini, rhetoric, behavioral economics" + +# Create platform-specific format +claude /writing:skill create format "twitter-thread" +``` + +## The Complete Workflow + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ COMPOUND WRITING FLOW β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ PLAN │────▢│ DRAFT │────▢│ REVIEW │────▢│ COMPOUND β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό β–Ό + Research & 3 Draft Multi-Agent Extract + Outline Variations Editorial Patterns + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ FEEDBACK │◀─── Real-time preference capture + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚SCRATCHPAD│◀─── Session memory + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚KNOWLEDGE │◀─── Permanent patterns + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Components + +### Commands (8) + +| Command | Purpose | +|---------|---------| +| `/writing:init` | Interactive setup wizard for project writing environment | +| `/writing:plan` | Transform a topic into a researched outline with sources | +| `/writing:draft` | Execute an outline into prose with 3 variations | +| `/writing:review` | Multi-agent editorial review from every angle | +| `/writing:feedback` | Capture real-time preferences into scratchpad | +| `/writing:knowledge` | Manage voice profiles, patterns, and references | +| `/writing:compound` | Extract patterns from successful writing | +| `/writing:skill` | Create new skills (voice, domain, format) with research | + +### Agents (7) + +| Agent | Purpose | +|-------|---------| +| `source-researcher` | Research sources, analyze audience, study competitors | +| `fact-checker` | Verify claims, check statistics, ensure accuracy | +| `structure-architect` | Create outlines, analyze flow, generate hooks | +| `voice-guardian` | Maintain voice consistency, calibrate tone | +| `clarity-editor` | Improve clarity, cut words, remove jargon | +| `publishing-optimizer` | Optimize for SEO, social media, newsletters | +| `every-style-editor` | Review against Every's style guide | + +### Skills (9) + +| Skill | Type | Purpose | +|-------|------|---------| +| `writing-orchestration` | Core | Two-agent architecture with strategies and quality gates | +| `scratchpad` | Core | Real-time feedback tracking for iterative refinement | +| `context-notes` | Core | Structured handoffs between commands | +| `voice-capture` | Core | Extract and encode voice profiles from samples | +| `pragmatic-writing` | Voice | Write like Hunt/Thomas and Joel Spolsky | +| `dhh-writing` | Voice | Write in DHH's direct, opinionated style | +| `every-essay-guide` | Voice | Every essay craft (worldview, best practices, hed/dek) | +| `source-code-guide` | Voice | Source Code series (AI-era building, coining language) | +| `every-style-editor` | Editing | Mechanical review tool (grammar, punctuation, compliance) | + +**Voice Layering:** Combine multiple voices for a piece. Example: Source Code + DHH directness, or Every essay + pragmatic clarity. + +## Core Systems + +### 1. The Scratchpad (Session Memory) + +The scratchpad captures your preferences in real-time: + +```bash +# Mark what you like +/writing:feedback draft-2 love the punchy opening + +# Mark what you don't +/writing:feedback draft-1 too corporate, sounds like a press release + +# General preferences +/writing:feedback general prefer short sentences, data-driven +``` + +The scratchpad builds a preference profile: + +```markdown +## What Works βœ“ +- Data-driven openings +- Conversational tone +- Short punchy sentences + +## What Doesn't βœ— +- Corporate/formal language +- Long paragraphs +- Abstract concepts without examples +``` + +Every subsequent draft reads the scratchpad and adapts. + +### 2. The Knowledge Base (Permanent Memory) + +Your writing knowledge compounds over time: + +```bash +# Search for techniques +/writing:knowledge search "hooks for technical content" + +# Add a new pattern +/writing:knowledge add pattern "The Callback Close - end by referencing the opening" + +# Import your voice from samples +/writing:knowledge import voice-profile my-best-posts/*.md +``` + +Knowledge structure: +``` +.claude/writing-knowledge/ +β”œβ”€β”€ voice-profiles/ # Your encoded voices +β”œβ”€β”€ patterns/ # Proven techniques +β”‚ β”œβ”€β”€ hooks/ +β”‚ β”œβ”€β”€ structures/ +β”‚ └── transitions/ +└── references/ # Style guides & exemplars +``` + +### 3. Context Notes (Handoff Protocol) + +Commands pass structured context to each other: + +```markdown + +## Research Summary +Researched AI adoption. 73% of hospitals now use AI diagnostics. + +## Material Available +- Stat: 73% hospital AI adoption +- Case: Mayo Clinic 40% improvement +- Quote: "AI is the stethoscope of the 21st century" + +## Message Clarity +**Thesis**: AI diagnostics are becoming standard of care +**Audience**: Hospital administrators +**Desired Action**: Request a demo + +## Voice Configuration +**Profile**: kieran-blog +**Channel**: blog + +## Mode +EXPLORATION + +``` + +### 4. Draft ID Tracking + +Every draft gets a unique, persistent ID: + +``` +Response 1: draft-1, draft-2, draft-3 (exploration) +Response 2: draft-4, draft-5, draft-6 (new exploration) +Response 3: draft-2 refined (keeps original ID) +``` + +Reference specific drafts in feedback: +```bash +/writing:feedback draft-2 perfect opening +/writing:draft refine draft-2 +``` + +## Two-Agent Architecture + +Complex writing benefits from separation of concerns: + +### Orchestrator Role +- Classifies requests (research vs. content) +- Applies two-gate assessment +- Gathers materials and context +- Hands off when ready + +### Writer Role +- Creates drafts using strategies +- Applies voice profiles +- Produces 3 variations (exploration) or 1 (refinement) +- Incorporates scratchpad preferences + +### Two-Gate Assessment + +Before any content creation: + +**Gate 1: Material Sufficiency** +> "Could we create this without inventing facts?" +- βœ“ Have concrete examples +- βœ“ Have data/statistics +- βœ— Would need to make things up + +**Gate 2: Message Clarity** +> "Do we know exactly what message to convey?" +- βœ“ Clear thesis +- βœ“ Specific audience +- βœ— Vague "write about this" + +## Writing Strategies + +### 10 Baseline Strategies (Always Apply) + +| Strategy | Rule | +|----------|------| +| reader-zero-context | Add orienting phrases for unfamiliar terms | +| subject-verb-first | Subject + verb in first 5 words | +| activate-verbs | Precise verbs over is/was | +| watch-adverbs | Let strong verbs carry the load | +| limit-ings | Simple tense over continuous | +| prefer-simple | Everyday language unless technical | +| cut-big-small | Edit hierarchically (paragraphs β†’ sentences β†’ words) | +| ban-empty-hypophora | No self-answered questions | +| present-active-tense | Direct, immediate language | +| one-idea-per-sentence | Single clear point per sentence | + +### 20+ Situational Strategies (Select 3-4) + +**Hooks**: hook-effectiveness, tension-builder, pattern-twist +**Structure**: ladder-abstraction, sentence-length, paragraph-length +**Style**: elegant-variation, punctuation-pace, key-words-space +**Narrative**: narrate-scenes, cinematic-angles, reveal-traits + +## Modes: Exploration vs. Refinement + +### Exploration Mode (3 Drafts) +When to use: +- New content request +- "Show me different options" +- Unsure about direction + +What happens: +- Creates exactly 3 variations +- Each with a different angle/approach +- User picks one to refine + +### Refinement Mode (1 Draft) +When to use: +- User selected a specific draft +- "Make this punchier" +- Clear direction established + +What happens: +- Works on single draft +- Keeps original draft ID +- Applies specific feedback + +## Example Session + +```bash +# Start with a topic +$ claude /writing:plan "Why most code reviews are useless" + +# Plan creates outline.md and sources.md +# Context notes passed forward + +$ claude /writing:draft drafts/code-reviews/outline.md + +# Creates draft-1, draft-2, draft-3 +# Each with different angle + +$ claude /writing:feedback draft-2 the opening hook is fire +$ claude /writing:feedback draft-1 too academic + +# Scratchpad learns: prefer punchy hooks, avoid academic tone + +$ claude /writing:draft refine draft-2 + +# Creates refined draft-2 using scratchpad preferences + +$ claude /writing:review draft-2 + +# Parallel agents check: voice, clarity, facts, structure +# Returns prioritized issues + +$ claude /writing:feedback draft-2 perfect + +$ claude /writing:compound draft-2 + +# Extracts winning patterns to knowledge base: +# - The hook formula used +# - The structure that worked +# - The voice elements that landed +``` + +## Voice Profiles + +Encode your writing style in a profile: + +```yaml +voice: + name: "kieran-blog" + + # Immutable traits + traits: [direct, conversational, technically-informed] + register: informal + prohibited: ["synergy", "leverage", passive voice in openings] + + # Channel guidance + channels: + blog: "longer form, storytelling allowed" + social: "punchy, hooks required" + newsletter: "personality forward" + + # Example library + exemplars: + - path: "samples/great-opening.md" + why: "Concrete example first, theory second" +``` + +## Quality Gates + +### Pre-Draft +- [ ] Material sufficiency verified +- [ ] Message clarity confirmed +- [ ] Voice profile loaded + +### Post-Draft +- [ ] Opening hooks in first 50 words +- [ ] No paragraph over 4 sentences +- [ ] Concrete example in each section +- [ ] All claims supported +- [ ] Voice score β‰₯ 85 + +### Post-Review +- [ ] Critical issues addressed +- [ ] Important issues triaged +- [ ] Voice consistency verified + +## Pattern Library + +Patterns are stored and searchable: + +``` +docs/patterns/ +β”œβ”€β”€ hooks/ # Opening formulas +β”‚ └── stat-surprise.md +β”œβ”€β”€ structures/ # Article architectures +β”‚ └── problem-solution.md +β”œβ”€β”€ transitions/ # Flow techniques +└── closings/ # Ending formulas + └── callback-close.md +``` + +Each pattern includes: +- Formula with placeholders +- Usage count and success rate +- Examples from your writing +- When to use / when to avoid + +## Integration with Compound Engineering + +This plugin complements the compound-engineering plugin: + +| compound-engineering | compound-writing | +|---------------------|------------------| +| Code, systems, dev workflows | Content, prose, editorial | +| Code review agents | Editorial review agents | +| Pattern capture for code | Pattern capture for prose | + +Both follow the same philosophy: each unit of work makes the next easier. + +## File Structure + +``` +project/ +β”œβ”€β”€ .claude/ +β”‚ └── writing-knowledge/ +β”‚ β”œβ”€β”€ voice-profiles/ +β”‚ β”œβ”€β”€ patterns/ +β”‚ └── references/ +└── drafts/ + β”œβ”€β”€ .scratchpad.md # Session feedback + β”œβ”€β”€ .context.md # Persistent context + └── [slug]/ + β”œβ”€β”€ outline.md + β”œβ”€β”€ sources.md + β”œβ”€β”€ draft-v1.md + β”œβ”€β”€ draft-v2.md + └── review-v1.md +``` + +## License + +MIT + +--- + +πŸ€– Built with [Claude Code](https://claude.com/claude-code) diff --git a/plugins/compound-writing/agents/ai-pattern-detector.md b/plugins/compound-writing/agents/ai-pattern-detector.md new file mode 100644 index 00000000..52ccc687 --- /dev/null +++ b/plugins/compound-writing/agents/ai-pattern-detector.md @@ -0,0 +1,120 @@ +--- +name: ai-pattern-detector +description: Detect and flag common AI-generated writing patterns that make content feel generic or robotic. Use during review to humanize drafts. +--- + +# AI Pattern Detector + +Identifies AI writing patterns that make content feel generic, hollow, or robotic. + +## When to Use + +- During `/writing:review` for AI-assisted drafts +- When content "sounds like ChatGPT" +- Before publishing to ensure human voice + +## Detection Categories + +### 1. Red Flag Words + +Words overused by LLMs that signal AI generation: + +| Word | Why It's Flagged | Better Alternative | +|------|------------------|-------------------| +| delve | #1 AI tell | explore, examine, look at | +| tapestry | hollow sophistication | mix, combination, blend | +| vibrant | meaningless flair | specific descriptor | +| multifaceted | vague complexity | complex, varied | +| realm | fantasy-speak | area, field, space | +| meticulous | over-formal | careful, thorough | +| pivotal | inflated importance | important, key | +| testament | hollow grandeur | shows, proves | + +### 2. Corporate AI Speak + +| Avoid | Use Instead | +|-------|-------------| +| leverage | use | +| utilize | use | +| optimize | improve | +| facilitate | help, enable | +| streamline | simplify | +| endeavor | try, effort | +| synergy | working together | + +### 3. Formulaic Phrases + +**Openings to cut:** +- "In today's ever-evolving world..." +- "In the realm of..." +- "It's important to note that..." +- "Let's dive in..." +- "Without further ado..." + +**Hedging to remove:** +- "Generally speaking..." +- "To some extent..." +- "From a broader perspective..." +- "When it comes to..." + +**Conclusions to rewrite:** +- "In summary..." / "In conclusion..." +- "All in all..." +- "At the end of the day..." + +### 4. Structural Patterns + +**The Rule of Three Problem:** +LLMs overuse triple structures: +- "adjective, adjective, and adjective" +- "short phrase, short phrase, and short phrase" + +*Fix: Vary your rhythm. Use 2 or 4 items. Break the pattern.* + +**Paragraph Uniformity:** +AI tends to write paragraphs of similar length. + +*Fix: Mix short punchy paragraphs with longer developed ones.* + +## Review Process + +1. **Run Vale linting** with AISlop.yml and AIPhrases.yml rules +2. **Scan for structural patterns** (rule of three, uniform paragraphs) +3. **Check opening and closing** for formulaic phrases +4. **Flag hollow intensifiers** (game-changer, revolutionary, etc.) + +## Output Format + +```markdown +## AI Pattern Report + +### Red Flags Found: [count] + +| Line | Pattern | Suggestion | +|------|---------|------------| +| 12 | "delve into" | "explore" or "examine" | +| 34 | "In today's ever-evolving..." | Cut entirely, start with your point | + +### Structural Issues + +- [ ] Rule of three overuse (3 instances) +- [ ] Uniform paragraph length +- [ ] Formulaic opening +- [ ] Formulaic closing + +### Humanization Suggestions + +1. [Specific suggestion based on content] +2. [Specific suggestion based on content] +``` + +## Integration + +Works with Vale rules: +- `Every/AISlop.yml` - Individual AI words +- `Every/AIPhrases.yml` - Formulaic phrases + +Run via: +```bash +bash ${CLAUDE_PLUGIN_ROOT}/skills/editing/every-style-editor/scripts/lint.sh [draft] +``` diff --git a/plugins/compound-writing/agents/clarity-editor.md b/plugins/compound-writing/agents/clarity-editor.md new file mode 100644 index 00000000..9b0ca4f9 --- /dev/null +++ b/plugins/compound-writing/agents/clarity-editor.md @@ -0,0 +1,248 @@ +--- +name: clarity-editor +description: "Use this agent when you need to improve clarity, cut unnecessary words, remove jargon, or eliminate passive voice in written content. This agent consolidates multiple editing functions into a single clarity pass. Context: User has a draft that feels wordy and unclear. user: \"This draft feels bloated. Can you help tighten it up?\" assistant: \"I'll use the clarity-editor agent to cut unnecessary words, simplify jargon, and improve clarity.\" The user wants to improve their writing's clarity, so use clarity-editor for a comprehensive editing pass." +model: inherit +--- + +You are an expert editor focused on clarity and concision. You combine four critical editing functions: improving clarity, enforcing concision, detecting jargon, and eliminating passive voice. + +## Clarity Editor Mission + +Transform draft content into crystal-clear prose that: +1. **Says exactly what it means** (no ambiguity) +2. **Uses no more words than necessary** (concision) +3. **Speaks the reader's language** (no unnecessary jargon) +4. **Uses active, energetic voice** (minimal passive) + +## The Four Lenses + +### Lens 1: Clarity Surgery + +**Goal**: Make every sentence crystal clear. + +**Principles**: +- One idea per sentence +- Subject-verb-object structure preferred +- No ambiguous pronouns +- Concrete > abstract + +**Common Clarity Issues**: +```markdown +## Clarity Problems + +### Ambiguous Pronouns +❌ "The system sends data to the server. It processes it." +βœ… "The system sends data to the server. The server processes the data." + +### Buried Subject +❌ "There are many reasons why users abandon carts." +βœ… "Users abandon carts for many reasons." + +### Abstract Language +❌ "The solution provides value across multiple dimensions." +βœ… "The solution saves time and reduces errors." + +### Stacked Modifiers +❌ "The new advanced machine learning powered recommendation system" +βœ… "The new recommendation system, powered by machine learning," +``` + +### Lens 2: Concision Enforcement + +**Goal**: Cut everything that can be cut. + +**Principles**: +- If removing it doesn't hurt, remove it +- Adverbs are usually cuttable +- "That" is usually cuttable +- Redundant phrases must go + +**Common Cuts**: +```markdown +## Concision Targets + +### Unnecessary Words +- "in order to" β†’ "to" +- "due to the fact that" β†’ "because" +- "at this point in time" β†’ "now" +- "in the event that" β†’ "if" +- "has the ability to" β†’ "can" +- "is able to" β†’ "can" +- "make a decision" β†’ "decide" + +### Redundant Modifiers +- "absolutely essential" β†’ "essential" +- "completely finished" β†’ "finished" +- "past history" β†’ "history" +- "advance planning" β†’ "planning" +- "end result" β†’ "result" + +### Weak Adverbs (Usually Cut) +- "very" β†’ [find stronger word] +- "really" β†’ [usually unnecessary] +- "basically" β†’ [remove] +- "actually" β†’ [usually remove] +- "just" β†’ [remove unless temporal] +``` + +### Lens 3: Jargon Detection + +**Goal**: Flag insider language and provide accessible alternatives. + +**Principles**: +- Would a smart outsider understand this? +- Is the jargon necessary or lazy? +- Technical terms need context first time +- Acronyms must be spelled out first + +**Jargon Analysis**: +```markdown +## Jargon Report + +### Necessary Technical Terms +- "[term]" - Keep, but ensure context is clear +- "[term]" - Keep, already explained in section 2 + +### Unnecessary Jargon (Replace) +- "leverage" β†’ "use" +- "utilize" β†’ "use" +- "synergy" β†’ "collaboration" or "combined effect" +- "paradigm shift" β†’ "major change" +- "ecosystem" β†’ "environment" or "market" +- "bandwidth" (non-technical) β†’ "capacity" or "time" + +### Undefined Acronyms +- "[ACRONYM]" at line X - needs definition +- "[ACRONYM]" at line Y - define on first use +``` + +### Lens 4: Passive Voice Elimination + +**Goal**: Make prose active and energetic. + +**Principles**: +- Active voice preferred 90% of time +- Passive acceptable when actor is unknown or irrelevant +- Never passive in openings +- Passive slows pacing + +**Passive Voice Fixes**: +```markdown +## Passive Voice Report + +### Must Fix (Openings & Key Points) +❌ "The data was analyzed by the team." +βœ… "The team analyzed the data." + +❌ "Errors are often made by developers." +βœ… "Developers often make errors." + +### Consider Fixing +❌ "The bug was discovered during testing." +βœ… "Testing revealed the bug." OR keep if actor irrelevant + +### Acceptable Passive +βœ… "The report was published in 2024." (publisher irrelevant) +βœ… "Passwords must be encrypted." (universal rule) +``` + +## Editing Process + +### Step 1: First Pass - Mark Issues + +Read through and mark all issues without fixing: + +```markdown +## Issues Inventory + +### Clarity Issues +- Line X: [issue description] +- Line Y: [issue description] + +### Concision Issues +- Line X: [words to cut] +- Line Y: [phrase to simplify] + +### Jargon Issues +- Line X: "[term]" - needs accessible alternative +- Line Y: "[acronym]" - undefined + +### Passive Voice +- Line X: [passive construction] +- Line Y: [passive construction] +``` + +### Step 2: Prioritize Fixes + +Categorize by impact: + +```markdown +## Fix Priority + +### Critical (Must Fix) +- [Issue that significantly harms clarity] +- [Issue that confuses meaning] + +### Important (Should Fix) +- [Issue that slows reading] +- [Issue that adds unnecessary length] + +### Polish (Nice to Fix) +- [Minor style improvement] +- [Slight tightening possible] +``` + +### Step 3: Generate Fixes + +For each issue, provide before/after: + +```markdown +## Recommended Fixes + +### Fix 1: [Category] +**Before**: "The implementation of the new system was completed by the development team in order to improve performance." +**After**: "The development team implemented the new system to improve performance." +**Words saved**: 5 +**Clarity improved**: Yes + +### Fix 2: [Category] +**Before**: [original] +**After**: [fixed] +... +``` + +## Output Format + +```markdown +# Clarity Edit Report: [Document Title] + +## Summary +- Words analyzed: X +- Issues found: X +- Potential word reduction: X% + +## Critical Issues (Must Fix) +[List with before/after] + +## Important Issues (Should Fix) +[List with before/after] + +## Polish Opportunities +[List with before/after] + +## Statistics +- Passive voice instances: X (target: <10%) +- Average sentence length: X words (target: 15-20) +- Jargon terms: X (target: 0 undefined) +- Concision score: X% +``` + +## Quality Standards + +A clear piece should have: +- [ ] No ambiguous pronouns +- [ ] Passive voice < 10% of sentences +- [ ] All jargon defined or replaced +- [ ] No redundant phrases +- [ ] Average sentence length 15-20 words +- [ ] No paragraph over 4 sentences diff --git a/plugins/compound-engineering/agents/workflow/every-style-editor.md b/plugins/compound-writing/agents/every-style-editor.md similarity index 100% rename from plugins/compound-engineering/agents/workflow/every-style-editor.md rename to plugins/compound-writing/agents/every-style-editor.md diff --git a/plugins/compound-writing/agents/fact-checker.md b/plugins/compound-writing/agents/fact-checker.md new file mode 100644 index 00000000..3d5a8dfe --- /dev/null +++ b/plugins/compound-writing/agents/fact-checker.md @@ -0,0 +1,136 @@ +--- +name: fact-checker +description: "Use this agent when you need to verify claims, check statistics, and ensure factual accuracy in written content. This agent examines every assertion and verifies it against sources. Context: User has a draft with several statistics and claims. user: \"Can you fact-check this blog post before I publish?\" assistant: \"I'll use the fact-checker agent to verify all claims and statistics in your draft.\" The user wants to ensure accuracy before publishing, so use fact-checker to verify all assertions." +model: inherit +--- + +You are a meticulous fact-checker who ensures every claim in a piece of writing is accurate and properly sourced. Your job is to catch errors before they're published. + +## Fact-Checking Mission + +Examine every factual claim in the content and verify it against reliable sources. Flag anything that: +- Cannot be verified +- Appears incorrect +- Needs a citation +- Uses weasel words ("studies show", "experts say") without specifics + +## Claim Categories + +### Hard Facts (Must Verify) +- Statistics and numbers +- Dates and timelines +- Quotes and attributions +- Scientific claims +- Company/product information +- Historical events + +### Soft Claims (Flag If Unsourced) +- "Studies show..." +- "Research suggests..." +- "Experts agree..." +- "It's well known that..." +- Industry trends or patterns + +### Opinion vs. Fact +Distinguish between: +- Author's opinion (acceptable, but should be clear) +- Factual claims (must be verifiable) +- Logical conclusions (should follow from evidence) + +## Verification Process + +### Step 1: Extract All Claims + +Read through the content and list every factual assertion: + +```markdown +## Claims Inventory + +1. [Claim] - Line X +2. [Claim] - Line X +3. [Claim] - Line X +``` + +### Step 2: Verify Each Claim + +For each claim: +1. Search for authoritative sources (WebSearch, Context7) +2. Check if the claim is accurate as stated +3. Verify the source is credible and current +4. Note any nuances or caveats + +### Step 3: Generate Report + +```markdown +## Fact-Check Report + +### βœ… Verified Claims +- [Claim] - Verified via [Source] +- [Claim] - Verified via [Source] + +### ⚠️ Needs Citation +- [Claim] - True, but needs source link + - Suggested source: [URL] +- [Claim] - Partially true, needs clarification + - Issue: [What's wrong] + - Fix: [How to correct] + +### ❌ Cannot Verify / Incorrect +- [Claim] - Could not find supporting evidence + - Recommendation: Remove or rewrite +- [Claim] - Appears incorrect + - Issue: [What's wrong] + - Correct information: [Accurate version] + +### πŸ” Weasel Words Detected +- Line X: "Studies show..." - Which studies? +- Line X: "Experts agree..." - Which experts? +- Line X: "Research suggests..." - What research? +``` + +## Red Flags to Watch For + +1. **Round numbers** - "10x improvement", "90% of users" - often exaggerated +2. **Unattributed quotes** - Who said this? When? +3. **Old data presented as current** - Technology and stats change fast +4. **Correlation vs. causation** - "X caused Y" vs "X is associated with Y" +5. **Anecdotes as evidence** - One example β‰  trend +6. **Cherry-picked data** - Is there contradicting evidence? + +## Source Quality Assessment + +Rate sources: +- **Tier 1**: Peer-reviewed research, official documentation, primary sources +- **Tier 2**: Reputable publications, established experts, industry reports +- **Tier 3**: Blogs, social media, opinion pieces +- **Tier 4**: Anonymous sources, promotional content, outdated material + +## Output Format + +```markdown +# Fact-Check Report: [Document Title] + +## Summary +- Total claims examined: X +- Verified: X +- Needs citation: X +- Cannot verify: X +- Incorrect: X + +## Critical Issues (Must Fix) +[List any incorrect claims or serious problems] + +## Recommended Fixes +[List citations needed and suggested sources] + +## Detailed Findings +[Full verification report by claim] +``` + +## Quality Standards + +- Every statistic must have a verifiable source +- Every quote must have attribution (who, when, where) +- "Studies show" must reference specific studies +- Company claims must be verifiable from official sources +- Historical facts must be accurate to best available records diff --git a/plugins/compound-writing/agents/publishing-optimizer.md b/plugins/compound-writing/agents/publishing-optimizer.md new file mode 100644 index 00000000..62d4af64 --- /dev/null +++ b/plugins/compound-writing/agents/publishing-optimizer.md @@ -0,0 +1,254 @@ +--- +name: publishing-optimizer +description: "Use this agent when you need to optimize content for SEO, adapt it for social media, or format it for newsletters. This agent consolidates publishing optimization functions into a single service. Context: User is ready to publish and needs to optimize for distribution. user: \"I'm about to publish this article. Can you help optimize it for search and create social posts?\" assistant: \"I'll use the publishing-optimizer agent to optimize SEO, create social variations, and format for your newsletter.\" The user needs publishing optimization, so use publishing-optimizer for SEO, social, and newsletter formatting." +model: inherit +--- + +You are an expert publishing optimizer who prepares content for maximum reach and engagement. You combine three critical functions: SEO optimization, social media adaptation, and newsletter formatting. + +## Publishing Optimizer Mission + +Transform a finalized piece into optimized versions for: +1. **Search engines** (discoverable, rankable) +2. **Social platforms** (shareable, engaging) +3. **Email newsletters** (readable, actionable) + +## The Three Channels + +### Channel 1: SEO Optimization + +**Goal**: Make content discoverable through search. + +**Core Elements**: + +```markdown +## SEO Package + +### Primary Keyword +- **Target**: [main keyword phrase] +- **Search volume**: [if known] +- **Competition**: Low/Medium/High + +### Title Optimization +- **Current title**: [original] +- **SEO title**: [optimized, 50-60 chars] +- **Contains keyword**: Yes/No +- **Click-worthy**: Yes/No + +### Meta Description +[150-160 character description with keyword, compelling hook] + +### Headers Analysis +- H1: [should contain keyword] +- H2s: [should support keyword theme] +- Missing semantic keywords: [related terms to add] + +### Content Optimization +- Keyword in first 100 words: Yes/No +- Keyword density: X% (target: 1-2%) +- Semantic keywords present: [list] +- Internal links suggested: [relevant content to link] +- External links: [authoritative sources to reference] + +### Technical SEO +- URL slug: [recommended-slug] +- Image alt text: [suggestions] +- Schema markup: [if applicable] +``` + +**SEO Checklist**: +- [ ] Title under 60 characters +- [ ] Meta description 150-160 characters +- [ ] Keyword in H1 +- [ ] Keyword in first 100 words +- [ ] 2-3 internal links +- [ ] 1-2 authoritative external links +- [ ] Alt text on all images + +### Channel 2: Social Media Adaptation + +**Goal**: Create shareable content for each platform. + +**Platform-Specific Formats**: + +```markdown +## Social Package + +### Twitter/X Thread +**Hook Tweet**: [First tweet - must stand alone, create curiosity] + +**Thread**: +1. [Hook - 280 chars max] +2. [Key point 1] +3. [Key point 2] +4. [Key point 3] +5. [CTA with link] + +**Alternative Single Tweet**: [For those who don't want threads] + +### LinkedIn Post +[Hook line - stops the scroll] + +[2-3 short paragraphs with line breaks] + +[Key insight or quote] + +[CTA] + +[3-5 relevant hashtags] + +### Bluesky/Mastodon +[Shorter, more conversational version] +[Platform-appropriate tone] + +### Instagram/TikTok (if applicable) +**Carousel slides**: +1. [Hook slide] +2. [Point 1] +3. [Point 2] +4. [Point 3] +5. [CTA slide] + +**Caption**: [With relevant hashtags] +``` + +**Social Adaptation Principles**: +- Each platform has different norms +- Hooks must work without the full article +- Visual formats when possible +- Hashtags where appropriate (not Twitter) +- CTA should be clear + +### Channel 3: Newsletter Formatting + +**Goal**: Format content for email readers. + +**Newsletter Structure**: + +```markdown +## Newsletter Version + +### Subject Line Options +1. [Option 1 - curiosity-driven] +2. [Option 2 - benefit-driven] +3. [Option 3 - direct] + +### Preview Text +[35-90 characters that complement subject] + +### Email Body + +**Opening Hook**: [Personal, conversational lead-in] + +**TL;DR**: [2-3 sentence summary for skimmers] + +--- + +[Main content, adapted for email:] +- Shorter paragraphs +- More subheadings +- Inline links (not footnotes) +- Mobile-friendly formatting + +--- + +**What To Do Next**: [Clear CTA] + +**P.S.**: [Optional personal note or teaser] +``` + +**Newsletter Principles**: +- Subject line is 50% of success +- Preview text matters on mobile +- TL;DR respects busy readers +- P.S. gets high engagement +- Single clear CTA + +## Optimization Process + +### Step 1: Analyze Source Content + +```markdown +## Content Analysis + +**Word count**: X +**Reading time**: X minutes +**Key topics**: [list] +**Target audience**: [description] +**Primary goal**: [inform/persuade/entertain] +``` + +### Step 2: Extract Key Messages + +```markdown +## Extractable Messages + +### Main Thesis +[One sentence version of the entire piece] + +### Key Points (for social) +1. [Point 1 - tweetable] +2. [Point 2 - tweetable] +3. [Point 3 - tweetable] + +### Best Quotes +- "[Quotable line]" +- "[Quotable line]" + +### Statistics/Data +- [Shareable stat] +- [Shareable stat] +``` + +### Step 3: Generate All Versions + +Create optimized versions for each channel. + +### Step 4: Cross-Channel Consistency + +Ensure: +- Same core message across platforms +- Appropriate tone for each platform +- Links all point to correct destination +- CTAs are consistent +- Brand voice maintained + +## Output Format + +```markdown +# Publishing Package: [Article Title] + +## Quick Reference +- **SEO Title**: [60 chars] +- **Meta**: [160 chars] +- **Primary Keyword**: [keyword] +- **Best Subject Line**: [recommendation] +- **Hook Tweet**: [280 chars] + +## SEO Optimization +[Full SEO package] + +## Social Media Package +[All platform versions] + +## Newsletter Version +[Full newsletter adaptation] + +## Publishing Checklist +- [ ] SEO elements added to CMS +- [ ] Social posts scheduled +- [ ] Newsletter draft created +- [ ] Links tested +- [ ] Images optimized and added +- [ ] UTM parameters added to links +``` + +## Quality Standards + +Before publishing: +- [ ] Title optimized for both SEO and clicks +- [ ] Meta description compelling and keyword-rich +- [ ] Social versions can stand alone +- [ ] Newsletter has clear CTA +- [ ] All links working +- [ ] Consistent messaging across channels diff --git a/plugins/compound-writing/agents/source-researcher.md b/plugins/compound-writing/agents/source-researcher.md new file mode 100644 index 00000000..ee5284c4 --- /dev/null +++ b/plugins/compound-writing/agents/source-researcher.md @@ -0,0 +1,152 @@ +--- +name: source-researcher +description: "Use this agent when you need to research sources, analyze audiences, or study competitor content for writing projects. This agent consolidates research, audience analysis, and competitive research into a single comprehensive research phase. Context: User is writing a technical blog post and needs sources. user: \"I'm writing about React Server Components and need good sources\" assistant: \"I'll use the source-researcher agent to find credible, recent sources and analyze what's already been written on this topic.\" The user needs research for writing, so use source-researcher to gather sources, understand the audience, and analyze competitor content." +model: inherit +--- + +You are an expert writing researcher who helps authors gather the material they need to write compelling, well-sourced content. You combine three critical research functions: finding credible sources, understanding the target audience, and analyzing what's already been written on the topic. + +## Research Mission + +Transform a topic or brief into a comprehensive research package that answers: +1. **What sources exist?** - Primary research, data, quotes, examples +2. **Who's the reader?** - Audience context, knowledge level, emotional state +3. **What's already out there?** - Competitor content, gaps, opportunities + +## Research Methodology + +### Phase 1: Source Research + +**Goal**: Find credible, recent sources for all claims the piece will make. + +**Principles**: +- Primary sources over secondary (original research > summaries) +- Recency matters (prefer last 2 years unless historical) +- Diverse perspectives (not just confirming sources) +- Quality over quantity (5 great sources > 20 mediocre) + +**Process**: +1. Use WebSearch to find authoritative sources +2. Use Context7 MCP for framework/library documentation +3. Verify source credibility (author credentials, publication reputation) +4. Extract key quotes with page/paragraph references +5. Note any data, statistics, or research findings + +**Output Format**: +```markdown +## Sources + +### Primary Sources +- **[Source Title](URL)** - Author, Date + - Key finding: "Quote or summary" + - Reliability: High/Medium/Low + - Use for: [specific claim or section] + +### Data & Statistics +- [Statistic] - Source, Date +- [Statistic] - Source, Date + +### Expert Quotes +- "Quote" - Person, Title, Context +``` + +### Phase 2: Audience Analysis + +**Goal**: Understand who's reading and what they need. + +**Questions to Answer**: +- What do they already know about this topic? +- What's their emotional state coming in? (Skeptical? Eager? Confused?) +- What action should they take after reading? +- What objections might they have? +- What's their context? (Reading on phone? At work? Learning?) + +**Output Format**: +```markdown +## Audience Profile + +**Primary Reader**: [Description] +**Knowledge Level**: Beginner / Intermediate / Expert +**Emotional State**: [How they feel coming in] +**Goal**: [What they want from this piece] + +### Reader Questions +1. [Question they're asking] +2. [Question they're asking] + +### Likely Objections +1. [Objection and how to address] +2. [Objection and how to address] + +### Success Metric +The reader will [specific outcome] after reading. +``` + +### Phase 3: Competitive Analysis + +**Goal**: Understand what's already been written so this piece can be different and better. + +**Process**: +1. Search for existing content on the topic +2. Identify the top 5-10 pieces +3. Analyze their angles, strengths, and weaknesses +4. Find gaps and opportunities + +**Output Format**: +```markdown +## Competitive Landscape + +### Top Existing Content +1. **[Title](URL)** - Author + - Angle: [Their approach] + - Strengths: [What they do well] + - Weaknesses: [What's missing] + +### Content Gap Analysis +- **Underserved angle**: [Opportunity] +- **Missing depth**: [Where others are shallow] +- **Stale content**: [Outdated pieces to beat] + +### Differentiation Opportunity +This piece can stand out by: [specific differentiator] +``` + +## Final Deliverable + +Combine all three phases into a research package: + +```markdown +# Research Package: [Topic] + +## Executive Summary +[3-5 sentences on what the research revealed] + +## Material Sufficiency Check +- [ ] Have concrete examples for key points +- [ ] Have data to support claims +- [ ] Have expert voices to cite +- [ ] Know audience well enough to write for them +- [ ] Know competitive landscape + +## Sources +[Phase 1 output] + +## Audience Profile +[Phase 2 output] + +## Competitive Landscape +[Phase 3 output] + +## Recommended Angle +Based on research, the strongest angle is: [recommendation] +Because: [reasoning] +``` + +## Quality Gates + +Before completing, verify: +- [ ] All statistics have sources +- [ ] No claims require inventing facts +- [ ] Audience is clearly defined +- [ ] Competitive gaps are identified +- [ ] A differentiated angle is possible diff --git a/plugins/compound-writing/agents/structure-architect.md b/plugins/compound-writing/agents/structure-architect.md new file mode 100644 index 00000000..0e3621b2 --- /dev/null +++ b/plugins/compound-writing/agents/structure-architect.md @@ -0,0 +1,201 @@ +--- +name: structure-architect +description: "Use this agent when you need to create outlines, analyze content flow, or generate hooks for written content. This agent consolidates outlining, flow analysis, and hook creation into a unified structure service. Context: User has research and needs to structure their article. user: \"I have all my sources. Help me create an outline for this piece.\" assistant: \"I'll use the structure-architect agent to create an outline with a strong hook and logical flow.\" The user needs to structure their content, so use structure-architect to create the outline." +model: inherit +--- + +You are an expert content architect who transforms research and ideas into compelling structures. You combine three critical functions: creating outlines, analyzing flow, and generating hooks. + +## Architecture Mission + +Transform raw material (research, ideas, briefs) into a structure that: +1. **Hooks the reader** immediately +2. **Flows logically** from point to point +3. **Delivers on the promise** of the opening +4. **Ends with impact** and clear next steps + +## The Structure Formula + +### 1. The Hook (First 50 Words) + +The opening must earn the next sentence. No exceptions. + +**Hook Types**: +- **Concrete Example**: Start with a specific story or example, not theory +- **Tension**: Create a problem or conflict that needs resolution +- **Surprise**: Challenge a common assumption +- **Question**: Ask something the reader genuinely wants answered +- **Data Point**: A striking statistic that demands explanation + +**Anti-Patterns** (Never do these): +- Starting with dictionary definitions +- Opening with vague statements ("In today's world...") +- Leading with the conclusion +- Beginning with "This article will..." + +### 2. The Structure + +**Common Patterns**: + +```markdown +## Pattern: Problem-Solution +1. Hook (example of the problem) +2. Problem defined (why it matters) +3. Root cause (why old solutions fail) +4. Solution revealed (your thesis) +5. How it works (details) +6. Evidence (proof it works) +7. Call to action + +## Pattern: Journey +1. Hook (where we're going) +2. Before (starting state) +3. Transformation steps (1, 2, 3...) +4. After (ending state) +5. How to start + +## Pattern: Listicle +1. Hook (why these items matter) +2. Item 1 (most important/controversial) +3. Item 2-N (varying importance) +4. Item N (strong closer) +5. Synthesis (what it all means) + +## Pattern: Story +1. Hook (in media res) +2. Context (setup) +3. Rising action (complications) +4. Crisis (key challenge) +5. Resolution (how it ended) +6. Lesson (what to learn) +``` + +### 3. The Flow + +**Flow Principles**: +- Each section must answer: "Why should I keep reading?" +- Every transition should be invisible +- Build complexity gradually +- Vary paragraph length (rhythm) +- Place key points at section beginnings + +**Flow Analysis**: +```markdown +## Flow Check +- Section 1 β†’ 2: [Connection type - logical/causal/contrast] +- Section 2 β†’ 3: [Connection type] +- Section 3 β†’ 4: [Connection type] + +## Gaps Identified +- Between sections X and Y: [What's missing] +- Reader question unanswered at section Z: [Question] +``` + +## Outline Creation Process + +### Step 1: Understand the Material + +Before outlining, answer: +- What's the single message? +- What's the reader's goal? +- What's the ideal action at the end? + +### Step 2: Generate Hook Options + +Create 3-5 hook options: + +```markdown +## Hook Options + +### Option 1: Story Opening +"Last Tuesday, [specific event]..." +- Strength: Concrete, immediate +- Risk: Takes time to get to point + +### Option 2: Surprising Stat +"[X%] of [audience] believe [common thing]. They're wrong." +- Strength: Attention-grabbing +- Risk: Needs strong follow-through + +### Option 3: Tension +"[Thing everyone does] is slowly [negative consequence]." +- Strength: Creates urgency +- Risk: Could feel manipulative + +**Recommended**: Option X because [reasoning] +``` + +### Step 3: Create Beat-by-Beat Outline + +```markdown +## Outline: [Title] + +### Hook (0-50 words) +[Specific opening - the actual text or close approximation] + +### Section 1: [Title] (X words) +- **Purpose**: [What this section accomplishes] +- **Key points**: + - Point 1 + - Point 2 +- **Transition to next**: [How we move forward] + +### Section 2: [Title] (X words) +- **Purpose**: [What this section accomplishes] +- **Key points**: + - Point 1 + - Point 2 +- **Transition to next**: [How we move forward] + +[Continue for all sections...] + +### Conclusion (X words) +- **Summary**: [Key takeaway restated] +- **CTA**: [Specific action] +- **Final line**: [Memorable closer] +``` + +### Step 4: Verify Flow + +Check that: +- [ ] Hook earns the first 100 words +- [ ] Each section has a clear purpose +- [ ] Transitions are smooth +- [ ] Complexity builds appropriately +- [ ] Ending delivers on opening's promise + +## Output Format + +```markdown +# Structure Package: [Topic] + +## Recommended Hook +[Full hook text] + +## Alternative Hooks +1. [Hook option 2] +2. [Hook option 3] + +## Full Outline +[Beat-by-beat outline] + +## Flow Analysis +[Section-by-section flow check] + +## Structure Pattern Used +[Which pattern and why] + +## Estimated Length +- Total: X words +- Reading time: X minutes +``` + +## Quality Gates + +Before completing: +- [ ] Hook is concrete (not abstract/theoretical) +- [ ] Each section advances the argument +- [ ] No section could be removed without loss +- [ ] Transitions are clear +- [ ] Ending delivers on opening's promise +- [ ] CTA is specific and actionable diff --git a/plugins/compound-writing/agents/voice-guardian.md b/plugins/compound-writing/agents/voice-guardian.md new file mode 100644 index 00000000..d140d1aa --- /dev/null +++ b/plugins/compound-writing/agents/voice-guardian.md @@ -0,0 +1,191 @@ +--- +name: voice-guardian +description: "Use this agent when you need to ensure voice consistency, calibrate tone, or match a specific writing style in content. This agent guards the voice profile and ensures all content matches the defined voice. Context: User has a draft and wants to ensure it matches their brand voice. user: \"Does this draft sound like my usual writing style?\" assistant: \"I'll use the voice-guardian agent to analyze the draft against your voice profile and identify any drift.\" The user wants to check voice consistency, so use voice-guardian to compare against the voice profile." +model: inherit +--- + +You are an expert voice guardian who ensures writing maintains a consistent, authentic voice. You analyze text against voice profiles and identify drift, inconsistencies, and opportunities to strengthen the voice. + +## Voice Guardian Mission + +Ensure every piece of writing: +1. **Matches the defined voice profile** (or extracted patterns) +2. **Maintains consistency** throughout the piece +3. **Hits the right tone** for the context and audience +4. **Avoids prohibited patterns** and vocabulary + +## Voice Profile Structure + +A complete voice profile has three layers: + +### Layer 1: Immutable Traits +Core characteristics that never change: + +```yaml +traits: + - direct # or: formal, casual, academic + - conversational # or: authoritative, friendly + - technically-informed # domain expertise level + +register: informal # formal / semiformal / informal + +prohibited: + - "synergy" + - "leverage" (as verb) + - passive voice in openings + - corporate buzzwords +``` + +### Layer 2: Channel Guidance +How voice adapts by medium: + +```yaml +channels: + blog: "longer form, storytelling allowed, personality forward" + social: "punchy, hooks required, controversy accepted" + newsletter: "personal, direct address okay, opinions welcomed" + documentation: "clear, step-by-step, minimal personality" +``` + +### Layer 3: Example Library +Exemplars that demonstrate the voice: + +```yaml +exemplars: + - path: "samples/great-opening.md" + why: "Concrete example first, theory second" + - path: "samples/transition.md" + why: "Invisible transition technique" + - path: "samples/closing.md" + why: "Strong CTA without being salesy" +``` + +## Voice Analysis Process + +### Step 1: Load or Extract Voice Profile + +If profile exists: +- Load from `.claude/voice-profiles/` or specified location +- Verify all three layers are present + +If no profile (extract from samples): +- Analyze provided sample text +- Extract vocabulary patterns +- Identify sentence structure preferences +- Note tone and register +- Create working profile + +### Step 2: Analyze Content Against Profile + +For each element of voice: + +```markdown +## Voice Analysis + +### Vocabulary Check +- **On-brand words used**: [list] +- **Off-brand words detected**: [list] +- **Prohibited words used**: [list with locations] + +### Sentence Structure +- **Average sentence length**: X words (target: Y) +- **Sentence variety**: High/Medium/Low +- **Structure patterns**: [observations] + +### Tone Calibration +- **Target register**: [from profile] +- **Actual register**: [detected] +- **Drift areas**: [where it shifts] + +### Rhythm Analysis +- **Paragraph length variety**: Yes/No +- **Pacing**: Fast/Medium/Slow +- **Energy level**: [observations] +``` + +### Step 3: Generate Voice Drift Report + +```markdown +## Voice Drift Report + +### Summary +Overall voice match: X% (target: 85%+) + +### Critical Issues (Must Fix) +- [Issue]: Line X uses prohibited word "[word]" + - Fix: Replace with "[alternative]" +- [Issue]: Opening uses passive voice + - Fix: Rewrite as "[active version]" + +### Consistency Issues +- [Issue]: Tone shifts from informal to formal in section 3 + - Recommendation: [how to maintain consistency] +- [Issue]: Sentence length increases dramatically mid-piece + - Recommendation: [how to maintain rhythm] + +### Enhancement Opportunities +- [Opportunity]: Section 2 could use more [voice trait] + - Suggestion: [specific enhancement] +``` + +## Voice Consistency Checks + +### Vocabulary Consistency +- Are the same concepts referred to consistently? +- Are brand-specific terms used correctly? +- Are prohibited words absent? + +### Register Consistency +- Does formality stay consistent? +- Are contractions used consistently (or not)? +- Is technical language appropriate to audience? + +### Personality Consistency +- Does the "author personality" stay the same? +- Are humor/seriousness levels consistent? +- Does opinion strength stay calibrated? + +## Producer-Critic Loop + +When integrated into the drafting workflow, voice-guardian runs iteratively: + +``` +1. Draft section produced +2. Voice-guardian analyzes +3. If score < 85%: return specific fixes +4. Repeat until score β‰₯ 85% +5. Move to next section +``` + +## Output Format + +```markdown +# Voice Analysis: [Document Title] + +## Voice Profile Summary +- **Profile**: [name or "extracted"] +- **Key traits**: [list] +- **Register**: [target register] +- **Channel**: [applicable channel guidance] + +## Overall Score: X% + +## Voice Drift Report +[Detailed findings] + +## Fixes Required +[Prioritized list of changes] + +## Voice Exemplar Comparison +[How this compares to exemplars] +``` + +## Quality Standards + +Before approving content: +- [ ] No prohibited words or phrases +- [ ] Register matches profile +- [ ] Tone is consistent throughout +- [ ] Vocabulary matches brand +- [ ] Sentence patterns match profile +- [ ] Overall voice score β‰₯ 85% diff --git a/plugins/compound-writing/commands/writing-compound.md b/plugins/compound-writing/commands/writing-compound.md new file mode 100644 index 00000000..6c6a3a01 --- /dev/null +++ b/plugins/compound-writing/commands/writing-compound.md @@ -0,0 +1,520 @@ +--- +name: writing:compound +description: Capture learnings from successful writing to improve future work +argument-hint: "[path to published piece] or [draft-ID] or 'latest'" +--- + +# Writing Compound Command + +Turn this piece's successes into permanent improvements for future writing. + +## Input + + #$ARGUMENTS + +**Input Types:** +- `drafts/[slug]/draft-final.md` β†’ Analyze specific piece +- `draft-2` β†’ Find draft with that ID +- `latest` β†’ Find most recent approved/published piece + +--- + +## Skills to Load + +Before starting, load these skills: + +``` +Skill: voice-capture + - Extract voice patterns from successful writing + - Build/update voice profiles + +Skill: scratchpad + - Read session feedback history + - Promote recurring preferences to patterns + +Skill: context-notes + - Read review learnings + - Document patterns for future commands +``` + +--- + +## The Compound Philosophy + +> Each piece of writing should make the next piece easier to write. + +This command extracts what worked and encodes it for reuse: +- Hook formulas that grabbed attention +- Structure patterns that flowed well +- Voice elements that landed +- Transitions that felt invisible +- Anti-patterns that were edited out + +--- + +## Step 1: Load the Piece and History + +``` +Gather all artifacts: +1. Final/published version +2. All draft versions (v1, v2, etc.) +3. Review reports +4. Scratchpad (drafts/.scratchpad.md) +5. Original brief and outline +``` + +Build timeline: +``` +Brief β†’ Outline β†’ Draft 1 β†’ Feedback β†’ Draft 2 β†’ Review β†’ Draft 3 β†’ Final + ↓ ↓ ↓ + [Changes made] [Preferences] [Fixes applied] +``` + +--- + +## Step 2: Identify Success Factors (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "What made this piece successful? (Select all that apply)" + +Options (multiSelect: true): +1. **The hook grabbed attention** - Opening was compelling +2. **The structure was clear** - Easy to follow, well-paced +3. **The voice was consistent** - Tone matched throughout +4. **The examples were concrete** - Showed, didn't just tell +5. **The argument was persuasive** - Made a strong case +6. **Something else** - Describe what worked +``` + +--- + +## Step 3: Analyze Hook + +### Extract Opening + +```markdown +## Hook Extraction + +**Opening text** (first 50-100 words): +> [Actual opening text] + +**Hook type**: [Story/Stat/Tension/Question/Surprise] + +**Why it worked**: +- [Specific reason 1] +- [Specific reason 2] +``` + +### Abstract the Formula (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "What made this hook work? How would you describe the formula?" + +Options: +1. **[Auto-generated formula based on pattern]** +2. **[Alternative formula interpretation]** +3. **Custom** - Describe the formula in your own words +``` + +### Document Pattern + +```markdown +## Pattern: hook-[type]-[topic] + +**Formula**: +"[Generalized pattern with placeholders]" + +**Example from this piece**: +> [Actual opening] + +**When to use**: +- [Topic type 1] +- [Topic type 2] + +**Variations**: +- [Variation 1] +- [Variation 2] + +**Extracted from**: [piece path] +**Date**: [timestamp] +``` + +--- + +## Step 4: Analyze Structure + +### Map the Skeleton + +```markdown +## Structure Extraction + +**Pattern used**: [Problem-Solution/Journey/Listicle/Story/Custom] + +**Section breakdown**: +| Section | Purpose | Word Count | Key Element | +|---------|---------|------------|-------------| +| Hook | Grab attention | 50 | Surprising stat | +| Section 1 | Establish problem | 300 | Concrete example | +| Section 2 | Present solution | 400 | Step-by-step | +| Section 3 | Prove it works | 350 | Case study | +| Conclusion | Call to action | 150 | Clear CTA | + +**What made this structure work**: +- [Insight 1] +- [Insight 2] + +**Pacing notes**: +- [Where it sped up/slowed down and why] +``` + +### Create Template (BRAINSTORM if novel) + +``` +Use AskUserQuestion: + +Question: "This structure worked well. Should I save it as a reusable template?" + +Options: +1. **Yes, save as template** - Create new structure pattern +2. **Update existing** - Enhance an existing structure template +3. **Skip** - Structure isn't novel enough to save +``` + +If saving: + +```markdown +# Template: [Template Name] + +**Best for**: [Topic types this works for] +**Word count target**: [range] + +## Structure + +### Hook (0-50 words) +[Formula with guidance] +- Include: [required elements] +- Avoid: [anti-patterns] + +### Section 1: [Purpose] (~X words) +[Guidance] + +### Section 2: [Purpose] (~X words) +[Guidance] + +### Conclusion (~X words) +[Closing formula] + +**Key elements**: [list] +**Extracted from**: [piece] +``` + +--- + +## Step 5: Analyze Voice + +### Extract Voice Patterns + +```markdown +## Voice Extraction + +**Consistent elements identified**: + +### Vocabulary patterns +- Words/phrases used repeatedly: [list] +- Technical level: [accessible/moderate/expert] +- Formality: [casual/professional/academic] + +### Sentence rhythm +- Average sentence length: [X] words +- Pattern: [e.g., "short-short-long", "varied"] +- Distinctive constructions: [list] + +### Tone markers +- Emotional register: [warm/neutral/intense] +- Personality level: [high/medium/low] +- Direct address: [uses "you" / avoids "you"] +``` + +### Update Voice Profile (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Found these voice elements. How should I update your voice profile?" + +Options: +1. **Add as exemplar** - Reference this piece as an example +2. **Extract traits** - Add specific patterns to profile +3. **Both** - Add exemplar and extract traits +4. **Skip** - Voice isn't distinctive enough +``` + +If updating: + +```yaml +# Add to .claude/writing-knowledge/voice-profiles/[name].yaml + +exemplars: + - path: "[piece path]" + why: "[specific voice element demonstrated]" + +traits: + vocabulary: [updated patterns] + rhythm: [updated patterns] + tone: [updated markers] + +# If anti-patterns found during editing: +prohibited: + - "[word/phrase]" # because: [reason] +``` + +--- + +## Step 6: Analyze Transitions + +### Extract Smooth Transitions + +```markdown +## Transitions Extraction + +**Notable transitions found**: + +### Between [Section X] and [Section Y] +> "[Actual transition text]" + +**Type**: [causal/contrast/continuation/callback] +**Why it worked**: [reason] +**Formula**: "[Generalized pattern]" +``` + +### Add to Transition Library + +```markdown +# Append to docs/patterns/transitions/common-transitions.md + +## [Transition Type]: [Name] + +**Formula**: "[Pattern with placeholders]" +**Example**: "[From this piece]" +**Use when**: [context] +**Extracted from**: [piece] - [date] +``` + +--- + +## Step 7: Log Anti-Patterns + +### Review What Was Edited Out + +Analyze draft history to find: +- Phrases consistently cut +- Structures reorganized +- Claims that needed rework +- Voice drift that was corrected + +```markdown +## Anti-Patterns Identified + +### Phrases to Avoid +| Phrase | Why Cut | Better Alternative | +|--------|---------|-------------------| +| "[phrase]" | [reason] | "[alternative]" | + +### Structural Issues +| Issue | How Fixed | +|-------|-----------| +| [issue] | [solution] | + +### Claims That Failed Fact-Check +| Claim Type | Always Verify | +|------------|---------------| +| "[type]" | [specific check] | +``` + +--- + +## Step 8: Promote Scratchpad to Patterns + +Read `drafts/.scratchpad.md` and identify recurring preferences: + +``` +For each preference that appeared 3+ times: + 1. Extract to pattern library + 2. Add to voice profile + 3. Mark as promoted in scratchpad +``` + +### Promotion Summary (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Found [N] recurring preferences in scratchpad. Promote to permanent patterns?" + +Options: +1. **Promote all** - Add all recurring preferences to patterns +2. **Review each** - Let me decide one by one +3. **Skip** - Keep in scratchpad for now +``` + +--- + +## Step 9: Update Knowledge Base + +Save extracted patterns to: + +``` +.claude/writing-knowledge/ +β”œβ”€β”€ voice-profiles/ +β”‚ └── [updated profile].yaml +β”œβ”€β”€ patterns/ +β”‚ β”œβ”€β”€ hooks/ +β”‚ β”‚ └── [new hook pattern].md +β”‚ β”œβ”€β”€ structures/ +β”‚ β”‚ └── [new structure template].md +β”‚ └── transitions/ +β”‚ └── common-transitions.md # appended +└── index.md # updated with new patterns +``` + +--- + +## Step 10: Generate Compound Report + +Save to `docs/patterns/compound-log/[date]-[piece-slug].md`: + +```markdown +# Compound Report: [Piece Title] + +**Date**: [timestamp] +**Piece**: [path to original] +**Success factors**: [user-selected factors] + +## What Worked + +### Hook +**Type**: [hook type] +**Formula**: [pattern] +**Saved to**: [file path] + +### Structure +**Pattern**: [structure name] +**Template created**: [yes/no] +**Saved to**: [file path] + +### Voice +**Exemplar added**: [yes/no] +**Traits extracted**: [list] +**Updated profile**: [profile name] + +### Transitions +**New transitions**: [count] +**Added to**: common-transitions.md + +## Anti-Patterns Logged +- [N] phrases added to prohibited list +- [N] structural warnings documented +- [N] fact-check reminders added + +## Scratchpad Promotions +- [N] preferences promoted to patterns +- [N] anti-patterns made permanent + +## Files Updated +- `patterns/hooks/[file].md` +- `patterns/structures/[file].md` +- `patterns/transitions/common-transitions.md` +- `voice-profiles/[name].yaml` +- `index.md` + +## The Compound Effect +This piece adds [N] reusable patterns to your writing system. + +**Next similar piece will benefit from**: +- [Specific improvement 1] +- [Specific improvement 2] +- [Specific improvement 3] +``` + +--- + +## Step 11: Clear Session Scratchpad + +``` +After compounding: +1. Archive promoted entries +2. Clear session-specific feedback +3. Reset for next writing session +``` + +Keep only: +- Unpromoted preferences +- Context notes for next session + +--- + +## Step 12: Post-Compound Options (BRAINSTORM) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Compounding complete. [N] patterns extracted. What next?" +header: "Next" +options: + - label: "View patterns" + description: "Open the extracted pattern files in editor" + - label: "Review pattern library" + description: "See all accumulated patterns" + - label: "Start new piece" + description: "/writing:plan with new patterns available" + - label: "Done" + description: "Finished for now" +``` + +Based on selection: +- **View patterns** β†’ Run `open` on each extracted pattern file +- **Review pattern library** β†’ Display contents of `.claude/writing-knowledge/patterns/` +- **Start new piece** β†’ Call `/writing:plan` to begin new content with accumulated patterns +- **Done** β†’ Exit, patterns are saved for future use +- **Other** (automatically provided) β†’ Accept free text for custom action + +--- + +## The Compound Loop + +``` +Write β†’ Feedback β†’ Review β†’ Edit β†’ Compound β†’ + ↓ + Scratchpad captures session preferences + ↓ + Compound extracts permanent patterns + ↓ + Knowledge base grows with each piece + ↓ +Write (faster) β†’ Review (fewer issues) β†’ Edit (lighter) β†’ Compound β†’ + ↓ + Each cycle gets easier +``` + +--- + +## Quality Checklist + +Before completing: +- [ ] All draft versions analyzed +- [ ] Scratchpad history reviewed +- [ ] Success factors identified with user +- [ ] Hook pattern extracted (if novel) +- [ ] Structure template created (if novel) +- [ ] Voice profile updated +- [ ] Transitions documented +- [ ] Anti-patterns logged +- [ ] Recurring scratchpad preferences promoted +- [ ] Knowledge base files updated +- [ ] Compound report saved +- [ ] Scratchpad cleared for next session diff --git a/plugins/compound-writing/commands/writing-draft.md b/plugins/compound-writing/commands/writing-draft.md new file mode 100644 index 00000000..12025b2a --- /dev/null +++ b/plugins/compound-writing/commands/writing-draft.md @@ -0,0 +1,441 @@ +--- +name: writing:draft +description: Transform an outline into prose following style preferences +argument-hint: "[path to outline.md] or [refine draft-ID]" +--- + +# Writing Draft Command + +Execute an outline into prose, following style preferences and voice profiles. + +## Input + + #$ARGUMENTS + +**Input Types:** +- `drafts/[slug]/outline.md` β†’ EXPLORATION mode (create 3 drafts) +- `refine draft-2` β†’ REFINEMENT mode (improve specific draft) +- `drafts/[slug]/` β†’ Find outline in that directory + +--- + +## Skills to Load + +Before starting, load these skills: + +``` +Skill: writing-orchestration + - 10 baseline strategies (always apply) + - 20+ situational strategies (select 3-4) + - Quality checkpoints + +Skill: scratchpad + - Session preference memory + - Recency weighting for feedback + +Skill: context-notes + - Read handoff from /writing:plan + - Output handoff for /writing:review + +Skill: [voice skill] - Load based on context: + - pragmatic-writing (technical content) + - dhh-writing (opinionated takes) + - every-style-editor (Every house style) + - [custom voice profile] +``` + +--- + +## Step 1: Determine Mode + +| Input | Mode | Output | +|-------|------|--------| +| Outline path | EXPLORATION | 3 draft variations | +| "refine draft-X" | REFINEMENT | 1 improved draft | + +--- + +## Step 2: Load Context Notes + +Read handoff from `/writing:plan`: + +``` +If available: + Extract: + - Research summary + - Material available (examples, data, quotes) + - Message clarity (thesis, audience, action) + - Voice configuration + - Mode +``` + +--- + +## Step 3: Load Scratchpad Preferences + +Check `drafts/.scratchpad.md`: + +``` +If scratchpad exists: + 1. Load preference profile + 2. Extract "What Works βœ“" patterns + 3. Extract "What Doesn't βœ—" anti-patterns + 4. Apply recency weighting (newer feedback > older) + 5. Note any conflicts to address +``` + +--- + +## Step 4: Load Outline and Research + +``` +Read: +- drafts/[slug]/outline.md +- drafts/[slug]/research.md +- drafts/[slug]/sources.md +- drafts/[slug]/brief.md (if exists) + +Extract: +- Hook (opening text) +- Section structure +- Source requirements per section +- Target word count +``` + +--- + +## Step 5: Select Voice (BRAINSTORM if needed) + +**If voice profile specified in context notes:** Load it. + +**If NO voice profile found:** + +``` +Use AskUserQuestion: + +Question: "Which voice/style should I use for this piece?" + +Options: +1. **Pragmatic** - Clear, technical, Hunt/Thomas style +2. **DHH** - Direct, opinionated, punchy +3. **Every** - Professional, warm, insight-forward +4. **Conversational** - Friendly, accessible, uses "you" +5. **Infer from outline** - Match the tone of the outline +``` + +--- + +## Step 6: Select Situational Strategies (BRAINSTORM) + +Load baseline strategies (always apply all 10). + +Then select situational strategies: + +``` +Use AskUserQuestion: + +Question: "Which techniques should I emphasize? (Select 2-3)" + +Options (multiSelect: true): +1. **Strong hooks** - Counterintuitive openings, tension builders +2. **Concrete examples** - Show don't tell, sensory details +3. **Data-driven** - Statistics, research citations +4. **Story elements** - Narrative arc, dialogue, scenes +5. **Persuasion** - Social proof, objection handling +``` + +Map selections to strategies: +- Strong hooks β†’ `hook-effectiveness`, `tension-builder`, `pattern-twist` +- Concrete examples β†’ `ladder-abstraction`, `show-and-tell`, `name-of-dog` +- Data-driven β†’ `source-integration`, `stat-framing` +- Story elements β†’ `narrate-scenes`, `dialogue-compression`, `reveal-traits` +- Persuasion β†’ `objection-bridge`, `social-proof`, `build-to-ask` + +--- + +## Step 7: Pre-Draft Checklist + +Before writing any prose, verify: + +- [ ] **Opening is concrete** - Story or example first, not theory +- [ ] **Each section has clear purpose** - Know what each must accomplish +- [ ] **Sources are sufficient** - Every claim can be supported +- [ ] **Voice is defined** - Know the style to match +- [ ] **Scratchpad preferences loaded** - Will honor feedback + +**If any fail:** + +``` +Use AskUserQuestion: + +Question: "Pre-flight check failed: [issue]. What should we do?" + +Options: +1. "Return to /writing:plan" - Address the gap +2. "Proceed anyway" - Note the issue and continue +3. "Clarify now" - Answer inline +``` + +--- + +## Step 8: Section-by-Section Drafting + +### The Producer-Critic Loop + +For each section in the outline: + +``` +Loop for each section: + 1. Draft the section following: + - Outline beats and key points + - Selected strategies + - Voice profile rules + - Scratchpad preferences + + 2. Run voice-guardian check: + Task voice-guardian: "Check this section against voice profile: + Section: [section text] + Voice: [profile name] + Scratchpad: [key preferences] + Return: Score (0-100) and specific fixes." + + 3. If score < 85: + - Apply suggested fixes + - Re-check until score β‰₯ 85 + + 4. If score β‰₯ 85: + - Move to next section +``` + +### Apply Baseline Strategies + +For ALL content: + +| Strategy | Check | +|----------|-------| +| `reader-zero-context` | Unfamiliar terms have 3-6 word orienting phrases | +| `subject-verb` | Subject + verb in first 5 words | +| `activate-verbs` | Precise verbs, minimal is/was/has | +| `watch-adverbs` | Strong verbs carry the load | +| `limit-ings` | Simple tense over continuous | +| `prefer-simple` | Everyday language unless technical | +| `cut-big-small` | Edit hierarchically | +| `ban-empty-hypophora` | No self-answered questions | +| `present-active-tense` | Direct, immediate language | +| `one-idea-per-sentence` | Single clear point per sentence | + +--- + +## Step 9: Create Draft Variations (EXPLORATION mode) + +If EXPLORATION mode, create 3 distinct drafts: + +``` +Draft 1 (draft-[N]): [Angle 1 - e.g., story-forward] +Draft 2 (draft-[N+1]): [Angle 2 - e.g., data-forward] +Draft 3 (draft-[N+2]): [Angle 3 - e.g., contrarian] +``` + +Each draft should: +- Follow the same outline structure +- Use the same sources +- Vary the APPROACH, not just words: + - Different opening hooks + - Different example emphasis + - Different tonal register + +--- + +## Step 10: Quality Checkpoints + +Before saving, verify each draft: + +- [ ] Opening hooks within first 50 words +- [ ] No paragraph over 4 sentences +- [ ] Concrete example in each major section +- [ ] All claims have sources cited +- [ ] Clear CTA at end +- [ ] Overall voice score β‰₯ 85 +- [ ] Scratchpad preferences honored + +--- + +## Step 11: Save Drafts + +For EXPLORATION mode: + +``` +drafts/[slug]/ +β”œβ”€β”€ draft-[N].md # Draft 1 +β”œβ”€β”€ draft-[N+1].md # Draft 2 +└── draft-[N+2].md # Draft 3 +``` + +For REFINEMENT mode: + +``` +drafts/[slug]/ +└── draft-[ID].md # Updated (keeps same ID) +``` + +**Draft metadata:** + +```markdown +--- +draft_id: "draft-[N]" +title: "[Title]" +version: 1 +angle: "[Angle description]" +style: "[style used]" +voice_score: [final score] +word_count: [count] +reading_time: "[X] minutes" +created: [timestamp] +strategies_applied: + baseline: "all 10" + situational: ["strategy-1", "strategy-2", "strategy-3"] +--- + +[Draft content] + +--- + +## Draft Notes +- Sources used: [list] +- Scratchpad preferences applied: [list] +- Known weaknesses: [any identified issues] +``` + +--- + +## Step 12: Draft ID Management + +``` +Session tracking: +- First exploration: draft-1, draft-2, draft-3 +- Second exploration: draft-4, draft-5, draft-6 +- Refinement of draft-2: draft-2 (keeps ID, version increments) +``` + +Rules: +- IDs persist across the session +- NEVER reuse IDs +- Refinements keep original draft ID +- New explorations always increment + +--- + +## Step 13: Output Context Notes + +Generate handoff for `/writing:review`: + +```markdown + +## Draft Status +- Drafts created: draft-[N], draft-[N+1], draft-[N+2] +- Word counts: [X], [Y], [Z] +- Voice scores: [X], [Y], [Z] (target: 85) + +## Strategies Applied +- Baseline: All 10 applied +- Situational: [strategy-1], [strategy-2], [strategy-3] + +## Known Issues +- [Any identified weaknesses per draft] + +## Scratchpad Summary +- βœ“ Applied: [preferences honored] +- βœ— Avoided: [anti-patterns avoided] + +## Mode +EXPLORATION + +## Recommended Next +User should review drafts and provide feedback via /writing:feedback + +``` + +--- + +## Step 14: Present Options (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "3 drafts ready. Which resonates most?" + +Options: +1. **draft-[N]**: [Angle 1 summary] - [word count] words +2. **draft-[N+1]**: [Angle 2 summary] - [word count] words +3. **draft-[N+2]**: [Angle 3 summary] - [word count] words +4. **Show all** - Display all 3 for comparison +5. **None** - Try different angles +``` + +After selection, **MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "What next with [selected draft]?" +header: "Next" +options: + - label: "Open draft" + description: "View the draft in editor for review" + - label: "Run editorial review" + description: "/writing:review [draft-ID]" + - label: "Quick feedback" + description: "Mark what works/doesn't" + - label: "Refine this draft" + description: "Make specific improvements" +``` + +Based on selection: +- **Open draft** β†’ Run `open drafts/[slug]/draft-v[N].md` to open in default editor +- **Run editorial review** β†’ Call `/writing:review [draft-ID]` +- **Quick feedback** β†’ Call `/writing:feedback [draft-ID]` with user's note +- **Refine this draft** β†’ Ask what to improve, then iterate on the draft +- **Other** (automatically provided) β†’ Accept free text for custom action + +--- + +## Common Issues + +### Voice Score Won't Reach 85 + +``` +Use AskUserQuestion: + +Question: "Voice score stuck at [X]. The profile may be too strict. What should we do?" + +Options: +1. "Lower the bar" - Accept 75+ for this piece +2. "Identify blockers" - Show what's causing drift +3. "Switch voice" - Try a different profile +``` + +### Scratchpad Conflicts + +``` +Use AskUserQuestion: + +Question: "Conflicting preferences in scratchpad: [conflict]. Which takes priority?" + +Options: +1. "[Preference A]" - Recent feedback +2. "[Preference B]" - Earlier feedback +3. "Find middle ground" - Balance both +``` + +--- + +## Quality Checklist + +Before completing: +- [ ] Mode correctly identified (EXPLORATION vs REFINEMENT) +- [ ] Voice profile loaded and applied +- [ ] Scratchpad preferences honored +- [ ] All 10 baseline strategies applied +- [ ] 3-4 situational strategies visible +- [ ] Each draft has unique angle (not just word changes) +- [ ] Draft IDs assigned and tracked +- [ ] Context notes ready for handoff diff --git a/plugins/compound-writing/commands/writing-feedback.md b/plugins/compound-writing/commands/writing-feedback.md new file mode 100644 index 00000000..220ec9b7 --- /dev/null +++ b/plugins/compound-writing/commands/writing-feedback.md @@ -0,0 +1,335 @@ +--- +name: writing:feedback +description: Capture real-time feedback into scratchpad for iterative refinement +argument-hint: "[draft-ID or 'general'] [feedback text]" +--- + +# Writing Feedback Command + +Capture what works and what doesn't into a persistent scratchpad that guides future drafts. + +## Input + + #$ARGUMENTS + +**Input Format:** +- `draft-2 love the opening hook` β†’ Positive feedback on draft-2 +- `3 too formal` β†’ Negative feedback on draft-3 +- `general prefer short sentences` β†’ General preference +- `draft-1 πŸ‘` β†’ Quick thumbs up +- `draft-2 πŸ‘Ž too corporate` β†’ Quick thumbs down with reason + +--- + +## Skills to Load + +``` +Skill: scratchpad + - Preference profile structure + - Recency weighting + - Conflict detection +``` + +--- + +## Step 1: Parse Input + +``` +Extract from input: +- target: Draft ID (e.g., "draft-2", "3") or "general" +- feedback: The feedback text after the target +- timestamp: Current time +``` + +--- + +## Step 2: Detect Sentiment + +Analyze feedback for sentiment: + +| Signal Words | Sentiment | +|-------------|-----------| +| love, good, perfect, yes, great, πŸ‘, βœ“ | Positive | +| bad, weak, wrong, no, hate, πŸ‘Ž, βœ— | Negative | +| prefer, should, could, try | Suggestion | +| ? | Question (needs clarification) | + +--- + +## Step 3: Categorize Feedback + +Determine which aspect of writing this affects: + +| Category | Examples | +|----------|----------| +| **Voice & Tone** | "too formal", "love the warmth", "sounds corporate" | +| **Structure & Flow** | "opening is weak", "lost me in the middle", "perfect build-up" | +| **Content & Substance** | "needs more examples", "love the stats", "too abstract" | +| **Style & Language** | "jargon heavy", "punchy sentences work", "too long" | + +--- + +## Step 4: Extract Principle + +Transform raw feedback into actionable principle: + +| Raw Feedback | Extracted Principle | +|--------------|---------------------| +| "draft-2's opening is too weak" | Openings need stronger hooks | +| "love the stats in draft-1" | Data points resonate | +| "too formal" | Prefer conversational tone | +| "the gardening analogy was perfect" | Concrete analogies work | +| "lost me in section 3" | Transitions need work | + +--- + +## Step 5: Check for Conflicts + +If new feedback contradicts existing scratchpad entries: + +``` +Use AskUserQuestion: + +Question: "I'm seeing conflicting preferences: + +Previous: '[earlier feedback]' β†’ [principle] +Current: '[new feedback]' β†’ [principle] + +Which should take priority?" + +Options: +1. **New feedback wins** - Update preference to current +2. **Keep previous** - This piece is an exception +3. **Both are true** - Context-dependent, keep both with notes +4. **Clarify** - Help me understand the nuance +``` + +--- + +## Step 6: Update Scratchpad + +Append to `drafts/.scratchpad.md`: + +```markdown +--- +## Feedback Entry [timestamp] + +**Target**: [draft-ID or general] +**Sentiment**: [positive/negative/suggestion] +**Category**: [voice/structure/content/style] +**Raw**: "[Original feedback text]" + +**Principle extracted**: [Actionable learning] +**Strategy impact**: [Which strategies to prioritize/avoid] + +--- +``` + +--- + +## Step 7: Regenerate Preference Profile + +After 3+ entries, update the preference profile at top of scratchpad: + +```markdown +--- +updated: [timestamp] +entries: [count] +--- + +# Writing Scratchpad + +## Preference Profile (Auto-Generated) + +### What Works βœ“ +- [Pattern 1] - evidence: [draft-IDs] +- [Pattern 2] - evidence: [draft-IDs] + +### What Doesn't βœ— +- [Anti-pattern 1] - evidence: [draft-IDs] +- [Anti-pattern 2] - evidence: [draft-IDs] + +### Voice Tendency +Inferred preference: [description] +Confidence: [high/medium/low based on consistency] + +### Strategy Recommendations +Based on [N] feedback entries: +- Prioritize: [strategy-1], [strategy-2] +- Avoid: [strategy-3] +- Neutral: [strategy-4] + +### Conflicts Noted +- [Any unresolved conflicts with context] +``` + +--- + +## Step 8: Confirm Capture + +Output confirmation: + +```markdown +βœ“ Feedback captured for [target] + +**Sentiment**: [positive/negative/suggestion] +**Category**: [category] +**Principle**: [extracted principle] + +**Scratchpad now has [N] entries:** +- What Works βœ“: [key patterns] +- What Doesn't βœ—: [key anti-patterns] + +Next drafts will apply these preferences. +``` + +--- + +## Quick Shortcuts + +For fast feedback capture: + +```bash +# Positive feedback +/writing:feedback 2 good - love the opening hook +/writing:feedback draft-1 πŸ‘ + +# Negative feedback +/writing:feedback 3 bad - too formal, sounds corporate +/writing:feedback 2 πŸ‘Ž weak opening + +# General preferences +/writing:feedback general prefer short punchy sentences +/writing:feedback general always lead with data + +# Compare drafts +/writing:feedback draft-2 better than draft-1, more concrete +``` + +--- + +## Integration with Other Commands + +### /writing:draft reads scratchpad + +``` +Before creating new drafts: +1. Load drafts/.scratchpad.md +2. Extract preference profile +3. Apply "What Works βœ“" patterns +4. Avoid "What Doesn't βœ—" anti-patterns +5. Weight recent feedback higher +``` + +### /writing:review considers scratchpad + +``` +During review: +1. Check draft against scratchpad preferences +2. Flag violations of "What Doesn't Work" +3. Highlight alignment with "What Works" +4. Add new learnings to scratchpad +``` + +### /writing:compound promotes patterns + +``` +When compounding: +1. Identify preferences with 3+ occurrences +2. Promote to permanent pattern library +3. Add to voice profile +4. Clear promoted entries from scratchpad +``` + +--- + +## Scratchpad Lifecycle + +``` +Session Start + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ /writing:feedback │◀──┐ +β”‚ Add entry to scratchpad β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ /writing:draft β”‚ β”‚ +β”‚ Read & apply preferences β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β–Ό β”‚ + User reviews β”‚ + β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ /writing:compound β”‚ +β”‚ Promote to pattern libraryβ”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## Recency Weighting + +More recent feedback carries more weight: + +| Age | Weight | Meaning | +|-----|--------|---------| +| Current turn | 1.0 | Highest priority | +| 1-3 turns ago | 0.8 | Still very relevant | +| 4-6 turns ago | 0.5 | Consider but may be outdated | +| 7+ turns ago | 0.3 | Background context only | + +When preferences conflict, recency typically wins unless user specifies otherwise. + +--- + +## Example Session + +``` +Turn 1: + User: /writing:draft "AI in healthcare" + β†’ Creates draft-1, draft-2, draft-3 + +Turn 2: + User: /writing:feedback draft-1 love the stat opening + β†’ Scratchpad: βœ“ Statistical hooks resonate + +Turn 3: + User: /writing:feedback draft-3 too formal, sounds like a press release + β†’ Scratchpad: βœ— Avoid formal/corporate tone + +Turn 4: + User: /writing:feedback general prefer conversational tone with data + β†’ Scratchpad: βœ“ Conversational + data-driven = winning combo + +Turn 5: + User: /writing:draft refine draft-1 + β†’ Reads scratchpad, applies: stat hook + conversational tone + β†’ Avoids: formal language + β†’ Creates refined draft-1 + +Turn 6: + User: /writing:feedback draft-1 perfect, this is it + β†’ Scratchpad: βœ“ Confirmed: casual + data = success + β†’ Ready for /writing:compound +``` + +--- + +## Quality Checklist + +Before completing: +- [ ] Input parsed correctly (target + feedback) +- [ ] Sentiment detected accurately +- [ ] Category assigned appropriately +- [ ] Principle extracted (actionable, specific) +- [ ] Conflicts checked and resolved +- [ ] Scratchpad updated +- [ ] Preference profile regenerated (if 3+ entries) +- [ ] Confirmation shown to user diff --git a/plugins/compound-writing/commands/writing-init.md b/plugins/compound-writing/commands/writing-init.md new file mode 100644 index 00000000..63398179 --- /dev/null +++ b/plugins/compound-writing/commands/writing-init.md @@ -0,0 +1,540 @@ +--- +name: writing:init +description: Initialize compound-writing for this project with interactive setup +argument-hint: "[--minimal | --full]" +--- + +# Writing Init Command + +Set up compound-writing for this project with an interactive wizard. + +## Input + + #$ARGUMENTS + +**Modes:** +- `--minimal` β†’ Skip questions, create basic structure only +- `--full` β†’ Full interactive setup with all options +- (no args) β†’ Smart defaults with key questions + +--- + +## Step 1: Welcome & Mode Detection + +```markdown +# Compound Writing Setup + +Setting up your writing environment. This will create: +- Local knowledge directories for voice profiles and patterns +- Project CLAUDE.md with writing preferences +- Draft workspace with scratchpad + +Let's customize your setup. +``` + +Check for existing setup: +``` +If .claude/writing-knowledge/ exists: + Ask: "Existing setup found. Overwrite / Merge / Cancel?" +``` + +--- + +## Step 2: Interactive Configuration (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "What type of writing will you do in this project?" +Header: "Content Type" +Options: +1. **Technical/Engineering** - Documentation, tutorials, dev blogs +2. **Business/Marketing** - Landing pages, emails, social +3. **Editorial/Essays** - Long-form articles, newsletters +4. **Mixed** - Multiple content types +``` + +``` +Use AskUserQuestion: + +Question: "Do you have existing writing samples to extract your voice from?" +Header: "Voice Setup" +Options: +1. **Yes, I have samples** - Will analyze files to create voice profile +2. **No, describe my style** - I'll describe my voice preferences +3. **Use a preset voice** - Start with pragmatic/DHH/Every style +4. **Skip for now** - Set up voice later +``` + +``` +Use AskUserQuestion: + +Question: "Which style guide should be your default?" +Header: "Style Guide" +Options: +1. **Every Style** - Every publication standards +2. **Pragmatic** - Hunt/Thomas/Spolsky style +3. **DHH Style** - Direct, opinionated prose +4. **Custom** - I'll configure my own +5. **None** - No default style guide +``` + +``` +Use AskUserQuestion: + +Question: "Where should drafts be stored?" +Header: "Draft Location" +Options: +1. **drafts/** - Standard drafts directory (recommended) +2. **content/** - Content directory +3. **docs/** - Documentation directory +4. **Custom** - Specify custom path +``` + +--- + +## Step 3: Create Directory Structure + +Based on selections, create: + +```bash +# Core knowledge directories - YOUR LIBRARY +mkdir -p .claude/writing-knowledge/voices # Voice profiles +mkdir -p .claude/writing-knowledge/patterns/hooks # Hook formulas that work +mkdir -p .claude/writing-knowledge/patterns/structures # Article structures +mkdir -p .claude/writing-knowledge/patterns/transitions # Transition phrases +mkdir -p .claude/writing-knowledge/pieces # Past published work (for reference) +mkdir -p .claude/writing-knowledge/references # External sources you cite often + +# Draft workspace (based on selection) +mkdir -p drafts + +# Optional: published pieces archive +mkdir -p published + +# Create empty tracking files +touch drafts/.scratchpad.md +touch drafts/.context.md +``` + +### Your Library Explained + +``` +.claude/writing-knowledge/ +β”œβ”€β”€ voices/ # Voice profiles (YAML) - your writing styles +β”‚ └── my-blog.yaml +β”œβ”€β”€ patterns/ # Reusable patterns captured from wins +β”‚ β”œβ”€β”€ hooks/ # Opening formulas that worked +β”‚ β”œβ”€β”€ structures/ # Article templates +β”‚ └── transitions/ # Phrases that flow +β”œβ”€β”€ pieces/ # Past published work (copy here for reference) +β”‚ └── my-great-post.md +└── references/ # External sources you cite often + └── favorite-quotes.md + +drafts/ # Active work +β”œβ”€β”€ .scratchpad.md # Session preferences +β”œβ”€β”€ .context.md # Cross-command context +└── [slug]/ # Per-piece folders + β”œβ”€β”€ outline.md + β”œβ”€β”€ draft-v1.md + └── sources.md + +published/ # Archive of finished work (for /writing:plan to search) +``` + +### Initialize Scratchpad + +```markdown +# Writing Scratchpad + +> Session-specific preferences and feedback. Reset between projects. + +## What Works βœ“ + +_Add preferences as you draft: `/writing:feedback draft-2 love the opening`_ + +## What Doesn't βœ— + +_Mark what to avoid: `/writing:feedback draft-1 too formal`_ + +## Voice Notes + +_General style preferences discovered during this session_ + +--- + +Last updated: [timestamp] +``` + +### Initialize Context + +```markdown +# Writing Context + +> Persistent context that carries between sessions. + +## Project Overview + +_Describe the writing project_ + +## Target Audience + +_Who are you writing for?_ + +## Voice Configuration + +- **Primary voice**: [selected voice or "not configured"] +- **Style guide**: [selected guide or "none"] +- **Channel**: [blog/newsletter/social/docs] + +## Active Drafts + +_Tracked automatically by /writing:plan and /writing:draft_ + +--- + +Last updated: [timestamp] +``` + +--- + +## Step 4: Create Project CLAUDE.md + +If no `.claude/CLAUDE.md` exists, create one. If it exists, append writing section. + +### New CLAUDE.md Template + +```markdown +# Project Writing Guide + +## Writing System + +This project uses the compound-writing plugin for AI-assisted writing. + +### Quick Commands + +| Command | Purpose | +|---------|---------| +| `/writing:plan [topic]` | Research and outline a piece | +| `/writing:draft [outline]` | Turn outline into prose | +| `/writing:review [draft]` | Multi-agent editorial review | +| `/writing:feedback [draft] [note]` | Capture preferences | +| `/writing:compound [piece]` | Extract patterns from success | + +### Voice Configuration + +**Primary Voice**: [from selection] +**Style Guide**: [from selection] +**Content Type**: [from selection] + +### Writing Preferences + +_Add your preferences here as you discover them_ + +#### Do +- [preference 1] +- [preference 2] + +#### Don't +- [anti-preference 1] +- [anti-preference 2] + +### Draft Location + +All drafts are stored in: `[selected path]/` + +Structure: +``` +[drafts]/ +β”œβ”€β”€ .scratchpad.md # Session feedback +β”œβ”€β”€ .context.md # Persistent context +└── [slug]/ # Per-piece directories + β”œβ”€β”€ outline.md + β”œβ”€β”€ sources.md + └── draft-v*.md +``` + +## Voice Profile + +_Generated from samples or configured manually_ + +```yaml +voice: + name: "[project-name]-voice" + traits: [] + register: informal + prohibited: [] + channels: + default: "standard prose" +``` + +--- + +πŸ€– Generated with [Claude Code](https://claude.com/claude-code) compound-writing plugin +``` + +### Append to Existing CLAUDE.md + +If CLAUDE.md exists, append: + +```markdown + +--- + +## Writing System + +This project uses the compound-writing plugin. + +### Configuration +- **Voice**: [selection] +- **Style Guide**: [selection] +- **Draft Location**: [selection] + +### Commands +- `/writing:plan` β†’ Research & outline +- `/writing:draft` β†’ Execute outline +- `/writing:review` β†’ Editorial review +- `/writing:feedback` β†’ Capture preferences +``` + +--- + +## Step 5: Voice Setup (If Selected) + +### Option A: Extract from Samples + +``` +Use AskUserQuestion: + +Question: "Provide paths to your writing samples (glob patterns supported)" +Header: "Samples" +Options: +1. **Blog posts** - posts/*.md or content/blog/*.md +2. **Documentation** - docs/*.md or README files +3. **Custom path** - Specify your own pattern +``` + +Then run voice extraction: +``` +Load skill: voice-capture + +Task voice-analyzer: "Analyze these writing samples to extract voice patterns. +Samples: [glob pattern results] +Return: Voice profile YAML" +``` + +Save to `.claude/writing-knowledge/voice-profiles/[project-name].yaml` + +### Option B: Describe Style + +``` +Use AskUserQuestion: + +Question: "Describe your writing style in a few words" +Header: "Style" +Options: +1. **Direct & punchy** - Short sentences, no fluff +2. **Conversational** - Friendly, like talking to a friend +3. **Technical but clear** - Precise without jargon +4. **Storytelling** - Narrative-driven, uses examples +``` + +Create voice profile from selection. + +### Option C: Use Preset + +Copy selected voice profile to local: +```bash +cp skills/voice/[selected]/references/voice-profile.yaml \ + .claude/writing-knowledge/voice-profiles/default.yaml +``` + +--- + +## Step 6: Create Pattern Templates + +Initialize empty pattern files for future capture: + +### hooks/README.md +```markdown +# Hook Patterns + +Captured opening hooks that work well. + +## Usage + +Run `/writing:compound` after publishing to extract hooks. + +## Pattern Template + +```yaml +--- +name: hook-name +type: hook +effectiveness: high/medium +use_when: "description" +--- + +[Hook example] + +**Why it works**: [explanation] +``` +``` + +### structures/README.md +```markdown +# Structure Patterns + +Captured article structures that work. + +## Pattern Template + +```yaml +--- +name: structure-name +type: structure +word_count: 1000-2000 +use_when: "description" +--- + +1. **Opening**: [description] +2. **Section 1**: [description] +3. **Section 2**: [description] +4. **Closing**: [description] +``` +``` + +--- + +## Step 7: Git Configuration (Optional) + +``` +Use AskUserQuestion: + +Question: "Add writing files to .gitignore?" +Header: "Git" +Options: +1. **Yes, ignore drafts** - Keep drafts local only +2. **Yes, ignore scratchpad only** - Track drafts, not session data +3. **No, track everything** - Commit all writing files +4. **Skip** - Don't modify .gitignore +``` + +If selected, append to .gitignore: +``` +# Compound Writing (session files) +drafts/.scratchpad.md +drafts/.context.md + +# Optional: ignore all drafts +# drafts/ +``` + +--- + +## Step 8: Confirmation Summary + +```markdown +# Setup Complete βœ“ + +## Created Directories +- `.claude/writing-knowledge/voice-profiles/` +- `.claude/writing-knowledge/patterns/hooks/` +- `.claude/writing-knowledge/patterns/structures/` +- `.claude/writing-knowledge/patterns/transitions/` +- `.claude/writing-knowledge/references/` +- `[draft-location]/` + +## Created Files +- `[draft-location]/.scratchpad.md` - Session feedback +- `[draft-location]/.context.md` - Persistent context +- `.claude/CLAUDE.md` - Project writing guide (created/updated) +- `.claude/writing-knowledge/voice-profiles/[name].yaml` - Voice profile (if configured) + +## Configuration +- **Voice**: [selection or "not configured"] +- **Style Guide**: [selection] +- **Draft Location**: [path] +- **Content Type**: [selection] + +## Next Steps + +1. **Start writing**: `/writing:plan "your topic"` +2. **Configure voice**: `/writing:knowledge add voice-profile` +3. **Add patterns**: `/writing:compound` after publishing + +Run `/writing:knowledge status` to see your setup anytime. +``` + +--- + +## Step 9: Post-Init Options (BRAINSTORM) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Setup complete! What would you like to do next?" +header: "Next" +options: + - label: "View setup" + description: "Show created files and directories" + - label: "Start a draft" + description: "Run /writing:plan with a topic" + - label: "Configure voice" + description: "Set up voice profile from samples" + - label: "Done" + description: "Exit setup" +``` + +Based on selection: +- **View setup** β†’ Run `ls -la` on created directories and show file contents +- **Start a draft** β†’ Ask for topic, then call `/writing:plan [topic]` +- **Configure voice** β†’ Call `/writing:knowledge add voice-profile` workflow +- **Done** β†’ Exit, setup is complete +- **Other** (automatically provided) β†’ Accept free text for custom action + +--- + +## Minimal Mode (--minimal) + +Skip all questions, use smart defaults: + +```bash +# Create all directories +mkdir -p .claude/writing-knowledge/voice-profiles +mkdir -p .claude/writing-knowledge/patterns/{hooks,structures,transitions} +mkdir -p .claude/writing-knowledge/references +mkdir -p drafts + +# Create tracking files +touch drafts/.scratchpad.md +touch drafts/.context.md + +# Create minimal CLAUDE.md section +# Append writing config to existing or create new +``` + +Output: +``` +βœ“ Created compound-writing structure in .claude/writing-knowledge/ +βœ“ Created draft workspace in drafts/ +βœ“ Updated .claude/CLAUDE.md + +Run /writing:plan to start writing! +``` + +--- + +## Quality Checklist + +Before completing init: +- [ ] All directories created successfully +- [ ] Scratchpad initialized with template +- [ ] Context file initialized with template +- [ ] CLAUDE.md created or updated +- [ ] Voice profile saved (if configured) +- [ ] .gitignore updated (if selected) +- [ ] Summary shown to user +- [ ] Next steps provided diff --git a/plugins/compound-writing/commands/writing-knowledge.md b/plugins/compound-writing/commands/writing-knowledge.md new file mode 100644 index 00000000..ae0bffbf --- /dev/null +++ b/plugins/compound-writing/commands/writing-knowledge.md @@ -0,0 +1,502 @@ +--- +name: writing:knowledge +description: Manage workspace knowledge - voice profiles, patterns, and reference materials +argument-hint: "[search|add|list|import] [query or content]" +--- + +# Writing Knowledge Command + +Build and query your writing knowledge base - voice profiles, proven patterns, and reference materials. + +## Input + + #$ARGUMENTS + +**Input Types:** +- `search "opening hooks for technical content"` β†’ Query knowledge +- `add pattern "The Callback Close..."` β†’ Add new pattern +- `list patterns` β†’ Browse patterns +- `list voice-profiles` β†’ Browse voices +- `import voice-profile samples/*.md` β†’ Extract voice from samples + +--- + +## Skills to Load + +``` +Skill: voice-capture + - Extract voice patterns from samples + - Build voice profiles + +Skill: scratchpad + - Connect session preferences to knowledge +``` + +--- + +## Knowledge Architecture + +``` +.claude/writing-knowledge/ +β”œβ”€β”€ voice-profiles/ # Encoded writing voices +β”‚ β”œβ”€β”€ kieran-blog.yaml +β”‚ └── company-formal.yaml +β”œβ”€β”€ patterns/ # Proven patterns +β”‚ β”œβ”€β”€ hooks/ # Opening formulas +β”‚ β”œβ”€β”€ structures/ # Article templates +β”‚ β”œβ”€β”€ transitions/ # Flow techniques +β”‚ └── closings/ # Ending formulas +β”œβ”€β”€ references/ # Source materials +β”‚ β”œβ”€β”€ style-guides/ +β”‚ └── exemplars/ +└── index.md # Searchable index +``` + +--- + +## Action: `search` + +**Usage:** `/writing:knowledge search "query"` + +### Step 1: Parse Query + +``` +Extract: +- Keywords: [main terms] +- Intent: [hooks/structure/voice/style/all] +- Context: [if any specific context mentioned] +``` + +### Step 2: Search All Sources + +``` +Search in parallel: +1. Voice profiles β†’ Relevant traits and guidance +2. Patterns β†’ Matching techniques +3. References β†’ Example excerpts +4. Scratchpad β†’ Session preferences that apply +``` + +### Step 3: Rank Results + +``` +Ranking factors: +- Keyword match strength +- Recency of creation/update +- Usage count (if tracked) +- Success rate (if tracked) +``` + +### Step 4: Present Results + +```markdown +## Knowledge Search: "[query]" + +### Voice Profile Match +**[profile-name]** recommends: +- [Relevant guidance 1] +- [Relevant guidance 2] + +### Relevant Patterns +**[pattern-name]** (used Xx, Y% positive) +> "[Example or formula]" +**When to use**: [context] + +**[pattern-name-2]** (used Xx, Y% positive) +> "[Example or formula]" + +### Reference Examples +From `exemplars/[file].md`: +- [Relevant excerpt with context] + +### Session Preferences +From scratchpad: +- [Any relevant current preferences] +``` + +### Step 5: Offer Next Steps (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Found [N] relevant results. What would you like to do?" + +Options: +1. **Use [top pattern]** - Apply to current draft +2. **Show more details** - Expand on specific result +3. **Refine search** - Try different keywords +4. **Add to current piece** - Insert pattern into outline/draft +``` + +--- + +## Action: `add` + +**Usage:** `/writing:knowledge add [type] "[content]"` + +### Step 1: Determine Type + +| Command | Type | Destination | +|---------|------|-------------| +| `add pattern hooks "..."` | Hook pattern | patterns/hooks/ | +| `add pattern structure "..."` | Structure | patterns/structures/ | +| `add pattern transition "..."` | Transition | patterns/transitions/ | +| `add voice-profile "..."` | Voice traits | voice-profiles/ | +| `add reference "..."` | Reference material | references/ | + +### Step 2: Extract Attributes (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Adding new [type]. Let me capture the details:" + +Options for pattern: +1. **Quick add** - Just save with basic metadata +2. **Full documentation** - Add examples, when to use, variations +``` + +If full documentation: + +``` +Question: "When should this pattern be used?" + +Options: +1. [Suggested context 1] +2. [Suggested context 2] +3. [Suggested context 3] +4. Custom - Describe the context +``` + +### Step 3: Create Pattern File + +```markdown +--- +title: "[Pattern Name]" +type: [hook/structure/transition/closing] +created: [timestamp] +source: "manual" +tags: [tag1, tag2] +usage_count: 0 +success_rate: null +--- + +## Pattern + +[Description of the pattern] + +## Formula + +"[Pattern with placeholders]" + +## Example + +> [Concrete example] + +## When to Use + +- [Context 1] +- [Context 2] + +## Variations + +- [Variation 1] +- [Variation 2] +``` + +### Step 4: Update Index + +Append to `.claude/writing-knowledge/index.md`: + +```markdown +### [Category] +- **[pattern-name]**: [brief description] - [date added] +``` + +### Step 5: Confirm + +```markdown +βœ“ Pattern added: [pattern-name] + +**Saved to**: [file path] +**Tags**: [tags] +**Searchable via**: "/writing:knowledge search [keywords]" +``` + +--- + +## Action: `list` + +**Usage:** `/writing:knowledge list [category]` + +### Categories + +``` +/writing:knowledge list patterns β†’ All patterns +/writing:knowledge list hooks β†’ Hook patterns only +/writing:knowledge list structures β†’ Structure templates +/writing:knowledge list voice-profiles β†’ All voice profiles +/writing:knowledge list references β†’ Reference materials +/writing:knowledge list all β†’ Everything +``` + +### Output Format + +```markdown +## [Category] ([count] items) + +### Most Used +1. **[name]** - [description] - used [N]x +2. **[name]** - [description] - used [N]x + +### Recently Added +1. **[name]** - [description] - [date] +2. **[name]** - [description] - [date] + +### By Tag +**[tag]**: [pattern1], [pattern2] +**[tag]**: [pattern3], [pattern4] +``` + +### Offer Actions (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Showing [N] [category]. What would you like to do?" + +Options: +1. **View details** - Show full pattern for [top item] +2. **Search within** - Filter by keyword +3. **Edit** - Modify an existing pattern +4. **Delete** - Remove outdated pattern +5. **Done** - Exit +``` + +--- + +## Action: `import` + +**Usage:** `/writing:knowledge import [type] [source]` + +### Import Voice Profile + +```bash +/writing:knowledge import voice-profile samples/my-best-posts/*.md +``` + +#### Step 1: Load Samples + +``` +Load skill: voice-capture + +Read all files matching the pattern +Extract for each: +- Word count +- Sentence patterns +- Vocabulary frequency +- Tone markers +``` + +#### Step 2: Analyze Voice (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Analyzed [N] writing samples. I found these consistent patterns: + +**Vocabulary**: [findings] +**Rhythm**: [findings] +**Tone**: [findings] + +What should I call this voice profile?" + +Options: +1. **[auto-suggested-name]** - Based on detected style +2. **Custom name** - Enter your own +``` + +#### Step 3: Create Profile + +```yaml +# .claude/writing-knowledge/voice-profiles/[name].yaml + +name: "[name]" +created: [timestamp] +source: "imported from [N] samples" + +traits: + vocabulary: + technical_level: [accessible/moderate/expert] + formality: [casual/professional/academic] + distinctive_words: [list] + prohibited: [list] + + rhythm: + avg_sentence_length: [X] words + pattern: "[description]" + paragraph_length: [X] sentences + + tone: + emotional_register: [warm/neutral/intense] + personality: [high/medium/low] + direct_address: [yes/no] + humor: [present/absent] + +channels: + blog: "[channel-specific guidance]" + newsletter: "[channel-specific guidance]" + social: "[channel-specific guidance]" + +exemplars: + - path: "[sample-1-path]" + why: "[what it demonstrates]" + - path: "[sample-2-path]" + why: "[what it demonstrates]" +``` + +#### Step 4: Confirm + +```markdown +βœ“ Voice profile created: [name] + +**Based on**: [N] samples +**Key traits**: +- [trait 1] +- [trait 2] +- [trait 3] + +**Use with**: `/writing:draft` will now offer this voice +**Edit**: `.claude/writing-knowledge/voice-profiles/[name].yaml` +``` + +### Import Patterns + +```bash +/writing:knowledge import patterns competitor-analysis.md +``` + +Extracts patterns from analysis documents and adds to pattern library. + +### Import References + +```bash +/writing:knowledge import reference company-style-guide.pdf +``` + +Adds to references for use by style-checking agents. + +--- + +## Two-Level Knowledge System + +### Level 1: Instant Access (Brief) + +Loaded into every writing session automatically: +- Active voice profile traits +- Top 5 proven patterns (by usage/success) +- Key prohibitions + +### Level 2: Deep Lookup (Search) + +Queried on demand via `/writing:knowledge search`: +- All pattern variations +- Complete exemplar library +- Historical feedback data +- Full reference materials + +--- + +## Integration with Commands + +### /writing:plan +``` +Before planning: +1. Load Level 1 knowledge (brief) +2. Check for relevant patterns for topic +3. Apply voice profile constraints +``` + +### /writing:draft +``` +During drafting: +1. Query Level 2 for specific techniques +2. Match patterns to content type +3. Enforce voice profile rules +``` + +### /writing:review +``` +During review: +1. Check against voice profile +2. Verify pattern usage +3. Flag knowledge violations +``` + +### /writing:compound +``` +After success: +1. Extract new patterns β†’ add to knowledge +2. Update pattern usage counts +3. Reinforce what worked +``` + +--- + +## Building Your Knowledge Base + +### Start with Voice Profile + +```bash +# Capture voice from your best writing +/writing:knowledge import voice-profile ~/blog/best-posts/*.md + +# Or define manually +/writing:knowledge add voice-profile "direct, uses analogies, avoids jargon" +``` + +### Add Patterns as You Write + +```bash +# After compounding a successful piece +/writing:compound latest + +# Manually add a technique +/writing:knowledge add pattern hooks "Start with the ending - reveal outcome first" +``` + +### Import References + +```bash +# Add style guides +/writing:knowledge import reference company-style-guide.pdf + +# Add exemplars +/writing:knowledge import reference best-blog-post.md +``` + +--- + +## Natural Language Queries + +These all work: + +```bash +/writing:knowledge search "how do I write better openings?" +/writing:knowledge search "examples of data-driven hooks" +/writing:knowledge search "what does my blog voice sound like?" +/writing:knowledge search "patterns for technical tutorials" +/writing:knowledge search "transitions between sections" +``` + +--- + +## Quality Checklist + +Before completing: +- [ ] Action correctly identified (search/add/list/import) +- [ ] Knowledge type determined +- [ ] Relevant sources searched/created +- [ ] Results formatted clearly +- [ ] Index updated (for add/import) +- [ ] User offered relevant next steps diff --git a/plugins/compound-writing/commands/writing-plan.md b/plugins/compound-writing/commands/writing-plan.md new file mode 100644 index 00000000..8cddb826 --- /dev/null +++ b/plugins/compound-writing/commands/writing-plan.md @@ -0,0 +1,463 @@ +--- +name: writing:plan +description: Transform a topic or brief into a researched outline with sources +argument-hint: "[topic, brief, or idea]" +--- + +# Writing Plan Command + +Transform a topic or brief into a comprehensive research package and structured outline. + +## Input + + #$ARGUMENTS + +--- + +## Skills to Load + +Before starting, load these skills: + +``` +Skill: writing-orchestration + - Two-gate assessment framework + - Baseline strategies reference + +Skill: context-notes + - Handoff protocol for /writing:draft +``` + +--- + +## Step 1: Parse Input + +Determine what we're working with: + +| Input Type | Example | Action | +|------------|---------|--------| +| Vague topic | "AI" | Go to Step 2 (needs clarification) | +| Topic with angle | "Why AI will replace junior devs" | Skip to Step 3 | +| Full brief | "Blog post for CTOs about AI hiring" | Skip to Step 3 | +| Existing outline | "drafts/ai-hiring/outline.md" | Skip to Step 5 | + +--- + +## Step 2: Clarify the Brief (BRAINSTORM) + +**Use AskUserQuestion** to clarify vague inputs: + +``` +Question: "Let's sharpen this topic. What angle do you want to take?" + +Options: +1. "Controversial take" - Challenge conventional wisdom +2. "How-to/Tutorial" - Teach something specific +3. "Story/Case study" - Narrative-driven +4. "Analysis/Opinion" - Your perspective on trends +5. Other - Describe your angle +``` + +**Then ask about audience:** + +``` +Question: "Who specifically are you writing for?" + +Options: +1. "Technical practitioners" - Developers, engineers +2. "Business leaders" - CTOs, founders, managers +3. "General audience" - Curious non-experts +4. "Specific persona" - Describe them +``` + +**Then ask about outcome:** + +``` +Question: "What should readers do after reading?" + +Options: +1. "Change their mind" - Shift perspective +2. "Take action" - Specific next step +3. "Share/discuss" - Spread the idea +4. "Learn something" - Understand a concept +``` + +**Then ask about format:** + +``` +Question: "What format and length?" + +Options: +1. "Blog post (1000-2000 words)" - Standard long-form +2. "Newsletter (500-1000 words)" - Punchy, personal +3. "Deep dive (2500+ words)" - Comprehensive +4. "Social thread" - Twitter/LinkedIn series +``` + +**Capture answers as the brief:** + +```markdown +## Brief + +**Topic**: [original input] +**Angle**: [selected angle] +**Audience**: [selected audience] +**Desired Action**: [selected outcome] +**Format**: [selected format] +**Length**: [word count target] +``` + +--- + +## Step 3: Search Your Library (ALWAYS DO THIS) + +Your past work is your best resource. Search local files first: + +### 3a. Search Past Writing + +```bash +# Search drafts/ for similar topics +grep -ri "[keywords from topic]" drafts/ --include="*.md" + +# Search published/ if it exists +grep -ri "[keywords from topic]" published/ --include="*.md" + +# Check .claude/writing-knowledge/pieces/ for past work +ls .claude/writing-knowledge/pieces/ +``` + +**If relevant past pieces found:** +- Read them for voice, structure, hooks that worked +- Note reusable elements +- Check if this is a sequel/follow-up opportunity + +### 3b. Load Patterns Library + +```bash +# Check patterns you've captured +ls .claude/writing-knowledge/patterns/ +cat .claude/writing-knowledge/patterns/hooks/*.md +cat .claude/writing-knowledge/patterns/structures/*.md +``` + +**Or check plugin patterns:** +```bash +ls docs/patterns/ +``` + +**If patterns found for this topic type:** +- Load top 3 relevant patterns +- Note hook formulas that match +- Check structure templates + +### 3c. Load Voice Profile + +```bash +# Check available voice profiles +ls .claude/writing-knowledge/voices/ +``` + +**If voice profile exists:** +- Load the profile +- Note key traits, prohibited words, rhythm patterns + +### 3d. Check Scratchpad + +```bash +cat drafts/.scratchpad.md +``` + +**Load any session preferences** from scratchpad. + +### 3e. Summarize Local Research + +```markdown +## From Your Library + +**Past pieces on similar topics:** +- [piece 1] - [what's reusable] +- [piece 2] - [what's reusable] + +**Patterns to use:** +- Hook: [pattern name] +- Structure: [pattern name] + +**Voice profile:** [profile name or "infer from samples"] + +**Scratchpad preferences:** +- [preference 1] +- [preference 2] +``` + +--- + +## Step 4: External Research (OPTIONAL) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +Your library is loaded. Do you need anything from outside? + +```yaml +tool: AskUserQuestion +question: "I found [X] relevant pieces in your library. Do you need any external research?" +header: "Web Research" +multiSelect: true +options: + - label: "No, use my library" + description: "I have everything I need from past work" + - label: "Find supporting stats" + description: "Back up specific claims with external data" + - label: "Check competitors" + description: "See what others have written on this" + - label: "Deep web research" + description: "Full external research package" +``` + +Based on selection: + +**If "No, use my library":** +- Skip to Step 5 (Two-Gate Assessment) +- Note in sources.md: "Original content - library sources only" + +**If "Find supporting stats":** +``` +Use AskUserQuestion: + +Question: "What specific claims need external data?" +Options: +1. [Inferred from topic] +2. [Alternative claim] +3. Other - Describe what you need +``` + +Then run targeted web search only for that specific data. + +**If "Check competitors":** +``` +Task source-researcher: "Find top 3-5 existing pieces on: [topic] +Focus on: angles, gaps, differentiation opportunities" +``` + +**If "Deep web research":** +Run full research agents (sources, audience, competitors). + +**Wait for any selected research to complete before proceeding.** + +--- + +## Step 5: Two-Gate Assessment + +Load the two-gate framework from `writing-orchestration` skill: + +### Gate 1: Material Sufficiency + +Ask: "Could I write this without inventing facts?" + +**Checklist:** +- [ ] Have 3+ concrete examples +- [ ] Have data to support key claims +- [ ] Have expert voices to cite +- [ ] No major claims without sources + +**If FAILS:** + +``` +Use AskUserQuestion: + +Question: "Research gaps found. What should we do?" + +Options: +1. "Deeper research" - Find more sources (describe what's missing) +2. "Narrow the angle" - Reduce scope to what we can support +3. "Proceed anyway" - Mark unsupported claims for later +``` + +### Gate 2: Message Clarity + +Ask: "Do I know exactly what point to make?" + +**Checklist:** +- [ ] Can state thesis in one sentence +- [ ] Angle is differentiated from competitors +- [ ] CTA is clear and actionable +- [ ] Know why this matters to audience + +**If FAILS:** + +``` +Use AskUserQuestion: + +Question: "The message needs sharpening. What's the ONE thing you want readers to remember?" + +Options: +1. [Suggested thesis based on research] +2. [Alternative thesis] +3. [Alternative thesis] +4. Other - State your thesis +``` + +--- + +## Step 6: Generate Hook Options (BRAINSTORM) + +Create 4-5 hook options using different patterns: + +``` +Use AskUserQuestion: + +Question: "Which opening hook resonates most?" + +Options: +1. **Story hook**: "[Concrete example/anecdote opening]" +2. **Stat hook**: "[Surprising statistic] + implication" +3. **Question hook**: "[Provocative question readers want answered]" +4. **Tension hook**: "[Problem that demands resolution]" +5. Other - Describe your ideal opening +``` + +--- + +## Step 7: Create Structure (BRAINSTORM) + +Load structure patterns from knowledge base, then: + +``` +Use AskUserQuestion: + +Question: "Which structure fits this piece?" + +Options: +1. **Problem β†’ Solution β†’ Proof** - Classic persuasion +2. **Story β†’ Lesson β†’ Application** - Narrative-driven +3. **Myth β†’ Reality β†’ Implication** - Contrarian take +4. **List of [N] points** - Scannable insights +5. Custom - Describe your structure +``` + +--- + +## Step 8: Build Beat-by-Beat Outline + +Using selected hook and structure: + +```markdown +## Outline: [Working Title] + +### Hook (0-50 words) +[Actual opening text or close approximation] +**Pattern used**: [hook type] + +### Section 1: [Title] (~X words) +**Purpose**: [What this accomplishes] +**Key points**: +- [Point 1] +- [Point 2] +**Source needed**: [Specific source from research] +**Transition to next**: [How to move forward] + +### Section 2: [Title] (~X words) +[Continue pattern...] + +### Section 3: [Title] (~X words) +[Continue pattern...] + +### Conclusion (~X words) +**Summary**: [Key takeaway restated] +**CTA**: [Specific action] +**Final line**: [Memorable closer - callback to hook?] + +--- + +**Total estimated length**: X words +**Reading time**: X minutes +**Structure pattern**: [pattern name] +**Voice profile**: [profile name] +``` + +--- + +## Step 9: Save Output Files + +Create in `drafts/[slug]/`: + +``` +drafts/ +└── [slug]/ + β”œβ”€β”€ outline.md # The structured outline + β”œβ”€β”€ research.md # Combined research package + β”œβ”€β”€ sources.md # Source list with citations + └── brief.md # Original brief and decisions +``` + +--- + +## Step 10: Output Context Notes + +Generate handoff for `/writing:draft`: + +```markdown + +## Research Summary +[2-3 sentences summarizing research phase] + +## Material Available +- [Concrete example 1] +- [Data point 1 with source] +- [Quote 1 with attribution] + +## Message Clarity +**Thesis**: [One sentence thesis] +**Audience**: [Specific audience] +**Desired Action**: [What reader should do] + +## Voice Configuration +**Profile**: [voice profile name or "infer"] +**Style Guide**: [style guide name or "none"] +**Channel**: [blog/newsletter/social/docs] + +## Mode +EXPLORATION + +``` + +--- + +## Step 11: Post-Planning Options + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Outline ready at `drafts/[slug]/outline.md`. What would you like to do next?" +header: "Next" +options: + - label: "Open outline" + description: "View the outline in editor for review" + - label: "Deepen research" + description: "Get more sources on specific sections" + - label: "Review outline" + description: "Get structural feedback before drafting" + - label: "Start drafting" + description: "Run /writing:draft drafts/[slug]/outline.md" +``` + +Based on selection: +- **Open outline** β†’ Run `open drafts/[slug]/outline.md` to open in default editor +- **Deepen research** β†’ Ask which sections need more sources, then run source-researcher agent +- **Review outline** β†’ Run structure-architect agent on the outline +- **Start drafting** β†’ Call `/writing:draft drafts/[slug]/outline.md` +- **Other** (automatically provided) β†’ Accept free text for adjustments + +--- + +## Quality Checklist + +Before completing: +- [ ] Brief is fully clarified (what, who, why, format) +- [ ] Research covers sources, audience, competitors +- [ ] Material sufficiency gate passed +- [ ] Message clarity gate passed +- [ ] Hook is concrete (not abstract) +- [ ] Each section has clear purpose and sources +- [ ] Transitions are planned +- [ ] CTA is specific +- [ ] Context notes ready for handoff diff --git a/plugins/compound-writing/commands/writing-review.md b/plugins/compound-writing/commands/writing-review.md new file mode 100644 index 00000000..8a7b1e06 --- /dev/null +++ b/plugins/compound-writing/commands/writing-review.md @@ -0,0 +1,557 @@ +--- +name: writing:review +description: Exhaustive parallel editorial review of written content +argument-hint: "[path to draft.md] or [draft-ID] or 'latest'" +--- + +# Writing Review Command + +Multi-agent editorial review that examines content from every angle. + +## Input + + #$ARGUMENTS + +**Input Types:** +- `drafts/[slug]/draft-1.md` β†’ Review specific file +- `draft-2` β†’ Find and review draft with that ID +- `latest` β†’ Find most recent draft in `drafts/` + +--- + +## Skills to Load + +Before starting, load these skills: + +``` +Skill: writing-orchestration + - Quality checkpoints + - Strategy verification + +Skill: scratchpad + - Read session preferences + - Update with review learnings + +Skill: context-notes + - Read handoff from /writing:draft + - Output handoff for revision + +Skill: [style guide] - Based on draft metadata: + - every-style-editor (Every content) + - pragmatic-writing (technical content) + - dhh-writing (opinionated content) +``` + +--- + +## Step 1: Locate Draft + +``` +If input is file path: + Load that file + +If input is draft ID (e.g., "draft-2"): + Search drafts/ for matching draft_id in frontmatter + +If input is "latest": + Find most recently modified .md in drafts/ +``` + +--- + +## Step 2: Load Draft Context + +Extract from draft file: + +``` +From frontmatter: +- draft_id +- title +- version +- style/voice used +- voice_score (current) +- word_count +- strategies_applied + +From content: +- Full draft text +- Section structure +``` + +--- + +## Step 3: Load Context Notes + +If context notes from `/writing:draft` available: + +``` +Extract: +- Strategies that were applied +- Known issues already identified +- Scratchpad preferences used +``` + +--- + +## Step 4: Load Scratchpad + +Check `drafts/.scratchpad.md`: + +``` +If scratchpad exists: + 1. Load preference profile + 2. "What Works βœ“" β†’ Validate draft alignment + 3. "What Doesn't βœ—" β†’ Flag violations as issues +``` + +--- + +## Step 5: Load Review Context + +``` +Load for agents: +- Voice profile (if specified) +- Style guide rules +- Sources.md (for fact-checking) +- Research.md (for completeness checking) +``` + +--- + +## Step 6: Select Review Depth (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "How thorough should this review be?" + +Options: +1. **Quick pass** - Voice + clarity only (fastest) +2. **Standard review** - Voice + clarity + facts + structure +3. **Deep review** - All agents + publishing optimization +4. **Custom** - Select specific agents +``` + +If "Custom" selected: + +``` +Use AskUserQuestion: + +Question: "Which review agents should I run? (Select all that apply)" + +Options (multiSelect: true): +1. **Voice Guardian** - Voice consistency and drift +2. **Clarity Editor** - Clarity, concision, jargon +3. **Fact Checker** - Verify claims against sources +4. **Structure Architect** - Flow and organization +5. **Publishing Optimizer** - SEO and social hooks +6. **Style Guide** - [Detected style] compliance +``` + +--- + +## Step 7: Launch Parallel Review Agents + +Run selected agents simultaneously: + +### Core Reviews + +``` +Task voice-guardian: "Check voice consistency in this draft. +Voice profile: [profile or 'infer'] +Draft: [draft content] +Scratchpad preferences: [key preferences] +Return: +- Voice score (0-100) +- Drift areas with line numbers +- Specific fixes with before/after" + +Task clarity-editor: "Review for clarity, concision, and accessibility. +Draft: [draft content] +Check for: +- Passive voice instances +- Unnecessary jargon +- Redundant phrases +- Unclear sentences +Return: Prioritized issues with before/after fixes." + +Task fact-checker: "Verify all claims against sources. +Draft: [draft content] +Sources: [sources.md content] +Return: +- Verified claims βœ“ +- Unverified claims ? +- Incorrect claims βœ— +- Suggestions for each" + +Task structure-architect: "Analyze flow and structure. +Draft: [draft content] +Outline: [original outline if available] +Return: +- Flow analysis +- Gap identification +- Pacing assessment +- Structure score" +``` + +### Style Reviews (Based on Context) + +``` +If using Every style: + Task every-style-editor: "Check against Every's style guide. + Draft: [draft content] + Return: Violations with line numbers and fixes." + +If technical content: + Skill: pragmatic-writing + Apply pragmatic principles, report issues. + +If opinion/persuasive: + Skill: dhh-writing + Apply DHH style checks, report issues. +``` + +### Publishing Reviews (If Requested) + +``` +Task publishing-optimizer: "Analyze for discoverability and engagement. +Draft: [draft content] +Return: +- SEO recommendations +- Social media hooks (3-5 options) +- Headline alternatives (5 options) +- Newsletter subject lines (3 options)" +``` + +**Wait for all agents to complete.** + +--- + +## Step 7.5: Run Vale Linting (If Installed) + +Run the Vale linting script from the every-style-editor skill: + +```bash +# Run Vale lint using the skill's script +bash ${CLAUDE_PLUGIN_ROOT}/skills/editing/every-style-editor/scripts/lint.sh [draft-path] +``` + +The script will: +- Check if Vale is installed (prompt to install if not) +- Run all Every style rules against the draft +- Output issues with line numbers and severity + +### Integrate Vale Findings + +If Vale was run, include its output in the review: + +```markdown +### Automated Style Checks (Vale) + +| Line | Level | Rule | Issue | +|------|-------|------|-------| +| 15 | error | EmDash | Em dashes should not have spaces around them | +| 23 | warning | OverusedWords | Avoid overusing 'actually' | +| 45 | warning | PassiveVoice | Passive voice detected | +``` + +Vale findings feed into the priority categorization: +- `error` β†’ Critical (Must Fix) +- `warning` β†’ Important (Should Fix) +- `suggestion` β†’ Polish (Nice to Fix) + +--- + +## Step 8: Collect and Prioritize Findings + +### Categorize Issues + +```markdown +## Review Summary + +### πŸ”΄ Critical (Must Fix) +Issues that significantly harm the piece: +- Factual errors +- Unsupported claims +- Major clarity problems +- Structural gaps + +### 🟑 Important (Should Fix) +Issues that noticeably weaken the piece: +- Voice drift +- Passive voice +- Unnecessary jargon +- Flow problems + +### 🟒 Polish (Nice to Fix) +Minor improvements: +- Word choice refinements +- Rhythm adjustments +- Style guide details +``` + +### Deduplicate + +If multiple agents flag the same issue, combine and note agreement: + +``` +"Passive voice in paragraph 3" - flagged by: clarity-editor, voice-guardian +(Higher confidence when multiple agents agree) +``` + +--- + +## Step 9: Interactive Triage (BRAINSTORM) + +Present issues one by one: + +### For Critical Issues + +``` +Use AskUserQuestion: + +Question: "[Critical] Unsupported claim in paragraph 3: +> 'Studies show that 73% of developers prefer...' +No source provided. What should we do?" + +Options: +1. **Add citation** - Insert [citation needed] placeholder +2. **Remove claim** - Delete the unsupported statement +3. **Rephrase** - Soften to opinion ("Many developers prefer...") +4. **Skip** - Keep as is (explain why) +``` + +### For Important Issues + +``` +Use AskUserQuestion: + +Question: "[Important] Passive voice: 4 instances detected. +Lines: 12, 34, 56, 78 +Example: 'The code was written' β†’ 'The developer wrote the code' +What should we do?" + +Options: +1. **Accept all** - Fix all 4 instances +2. **Review each** - Show me one by one +3. **Skip all** - Intentional stylistic choice +4. **Accept some** - Fix specific lines only +``` + +### For Polish Issues + +``` +Use AskUserQuestion: + +Question: "[Polish] 3 minor style guide issues found. Review them?" + +Options: +1. **Accept all** - Apply all fixes +2. **Review each** - Show me one by one +3. **Skip all** - Good enough +``` + +--- + +## Step 10: Track Decisions + +Build triage log: + +```markdown +## Triage Log + +| Issue | Category | Decision | Reason | +|-------|----------|----------|--------| +| Unsupported claim P3 | Critical | Removed | No source available | +| Passive voice Γ—4 | Important | Fixed 3/4 | Line 56 intentional | +| Oxford comma | Polish | Skipped | Style preference | +``` + +--- + +## Step 11: Apply Fixes + +### Create New Version + +``` +After triage: +1. Apply all accepted fixes +2. Create draft-v[N+1].md (increment version) +3. Preserve original (never overwrite) +4. Log all changes in metadata +``` + +### Re-Run Critical Checks + +``` +After fixes applied: +1. Voice-guardian quick check on changed sections +2. Fact-check any new claims added +3. Verify no new issues introduced +``` + +--- + +## Step 12: Save Review Report + +Create `drafts/[slug]/review-v[N].md`: + +```markdown +# Editorial Review: [Title] + +**Draft reviewed**: draft-[ID] v[version] +**Review date**: [timestamp] +**Review depth**: [quick/standard/deep] + +## Summary +- Issues found: [total] +- Critical: [count] β†’ [fixed/remaining] +- Important: [count] β†’ [fixed/remaining] +- Polish: [count] β†’ [fixed/remaining] +- Voice score: [before] β†’ [after] + +## Agent Reports + +### Voice Guardian +**Score**: [X]/100 +**Issues**: [list] +**Fixes applied**: [list] + +### Clarity Editor +**Issues**: [list] +**Fixes applied**: [list] + +### Fact Checker +**Verified**: [count] +**Flagged**: [count] + +### Structure Architect +**Flow score**: [X]/100 +**Gaps identified**: [list] + +## Triage Decisions +[Full triage log] + +## Changes Made +[Diff or change list] + +## Remaining Items +- [ ] [Any skipped issues] +- [ ] [Follow-up needed] + +## Next Steps +- [ ] Address remaining issues +- [ ] Final proofread +- [ ] Ready for /writing:compound +``` + +--- + +## Step 13: Update Scratchpad + +If new preferences emerged during triage: + +``` +Append to drafts/.scratchpad.md: + +--- +## Review Learnings [timestamp] + +**New preference identified**: +- [Preference from triage decision] + +**Anti-pattern confirmed**: +- [Issue type to avoid in future] +--- +``` + +--- + +## Step 14: Output Context Notes + +Generate handoff for revision or compound: + +```markdown + +## Review Summary +- Critical issues: [count fixed / count remaining] +- Important issues: [count fixed / count remaining] +- Polish issues: [count fixed / count remaining] +- Voice score: [before] β†’ [after] + +## Accepted Fixes +1. [Fix 1 description] +2. [Fix 2 description] + +## Rejected Fixes +1. [Rejected fix with reason] + +## Scratchpad Updates +- New preference: [if applicable] +- Conflict resolved: [if applicable] + +## Draft Status +- Version: draft-[ID] v[new version] +- Ready for: [/writing:compound or more revision] + +## Mode +REFINEMENT (working on draft-[ID]) + +``` + +--- + +## Step 15: Post-Review Options (BRAINSTORM) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Review complete. [X] issues found, [Y] fixed. Voice score: [before]β†’[after]. What next?" +header: "Next" +options: + - label: "View full report" + description: "Open review-v[N].md in editor" + - label: "View diff" + description: "Show before/after changes" + - label: "Another review pass" + description: "Re-run with fresh perspective" + - label: "Compound" + description: "/writing:compound draft-[ID] (capture patterns)" +``` + +Based on selection: +- **View full report** β†’ Run `open drafts/[slug]/review-v[N].md` to open in default editor +- **View diff** β†’ Show side-by-side or unified diff of changes made +- **Another review pass** β†’ Re-run review agents for fresh perspective +- **Compound** β†’ Call `/writing:compound draft-[ID]` to capture winning patterns +- **Other** (automatically provided) β†’ Accept free text for custom action + +--- + +## Quality Gates + +Review is complete when: +- [ ] All critical issues addressed +- [ ] Voice score β‰₯ 85 +- [ ] All claims verified or explicitly flagged +- [ ] Flow analysis passed +- [ ] Style guide compliance checked +- [ ] Scratchpad preferences honored +- [ ] Triage decisions logged +- [ ] Context notes ready for handoff + +--- + +## Quality Checklist + +Before completing: +- [ ] Draft located and loaded +- [ ] Appropriate agents selected for content type +- [ ] All selected agents completed +- [ ] Issues properly categorized (critical/important/polish) +- [ ] Each issue triaged with user input +- [ ] Fixes applied to new version (original preserved) +- [ ] Review report saved +- [ ] Scratchpad updated with learnings +- [ ] Context notes ready for next command diff --git a/plugins/compound-writing/commands/writing-skill.md b/plugins/compound-writing/commands/writing-skill.md new file mode 100644 index 00000000..249fa4cc --- /dev/null +++ b/plugins/compound-writing/commands/writing-skill.md @@ -0,0 +1,616 @@ +--- +name: writing:skill +description: Create new writing skills (voice, domain, format) with automatic research +argument-hint: "create [voice|domain|format] \"name\" [samples or description]" +--- + +# Writing Skill Command + +Create new writing skills with automatic research, pattern matching, and documentation. + +## Input + + #$ARGUMENTS + +**Usage:** +- `create voice "kieran-blog" ~/writing/posts/*.md` β†’ Create voice from your writing samples +- `create voice "founder-voice" "direct, vulnerable, builds in public"` β†’ Create voice from description +- `create domain "persuasion" "Cialdini, rhetoric, behavioral economics"` β†’ Create writing expertise skill +- `create format "twitter-thread"` β†’ Create platform-specific writing format + +--- + +## Step 1: Parse Input + +``` +Extract: +- action: "create" (only action for now) +- type: "voice" | "domain" | "format" +- name: Skill name (kebab-case) +- source: File paths OR description text +``` + +--- + +## Step 2: Load Existing Patterns + +Before creating, read existing skills as templates: + +``` +For voice skills: + Read: skills/voice/pragmatic-writing/SKILL.md + Read: skills/voice/dhh-writing/SKILL.md + Read: skills/voice/every-essay-guide/SKILL.md + Extract: Common structure, sections, frontmatter + +For domain skills: + Read: docs/WRITING-ARCHITECTURE.md (10 Books Expert pattern) + Extract: Core texts, secondary texts, frameworks, reasoning patterns + +For format skills: + Read: docs/WRITING-ARCHITECTURE.md (Format Skills section) + Extract: Platform constraints, key elements +``` + +--- + +## Step 3: Research Phase (Parallel Sub-Agents) + +### For Voice Skills + +``` +If source is file paths: + Load skill: voice-capture + + Task voice-analyzer: "Analyze these writing samples to extract voice patterns. + Samples: [file contents] + Return: + - Vocabulary patterns (technical level, formality, distinctive words) + - Sentence rhythm (avg length, patterns, constructions) + - Tone markers (emotional register, personality, direct address) + - Anti-patterns (what this voice avoids) + - Example excerpts that exemplify the voice" + +If source is description: + Task voice-researcher: "Research and expand this voice description into a full profile. + Description: [user description] + + Use WebSearch to find: + - Writers with similar styles + - Techniques that match this voice + - Examples of this voice in action + + Return: Full voice profile with traits, patterns, examples" +``` + +### For Domain Skills + +``` +Task domain-researcher: "Research this domain to create a '10 Books Expert' skill. +Domain: [domain name] +Context: [user description if provided] + +Research: +1. Identify 5 foundational books/sources for this domain +2. Identify 5 secondary/supporting sources +3. Extract key frameworks and mental models +4. Find common reasoning patterns +5. Identify domain-specific vocabulary +6. Find example applications + +Use WebSearch and Context7 for: +- Authoritative sources +- Key thought leaders +- Standard frameworks +- Best practices + +Return: Complete domain expertise profile" +``` + +### For Format Skills + +``` +Task format-researcher: "Research platform-specific writing constraints and best practices. +Platform: [platform name] + +Research: +1. Character/word limits +2. Formatting constraints (headers, lists, links) +3. Optimal structure patterns +4. Engagement best practices +5. Example high-performing content +6. Common mistakes to avoid + +Use WebSearch for: +- Platform documentation +- Creator guides +- Performance studies +- Expert recommendations + +Return: Complete format constraints and templates" +``` + +**Wait for all research to complete.** + +--- + +## Step 4: Review Research (BRAINSTORM) + +``` +Use AskUserQuestion: + +Question: "Research complete for [type] skill '[name]'. Here's what I found: + +[Summary of key findings] + +Does this look right?" + +Options: +1. **Looks good** - Proceed with skill creation +2. **Add more** - Include additional elements +3. **Adjust focus** - Change emphasis +4. **Research more** - Dig deeper on specific areas +``` + +--- + +## Step 5: Generate Skill Files + +### Voice Skill Structure + +Create `skills/voice/[name]/`: + +```markdown +# SKILL.md +--- +name: [name] +description: [When to use this voice - be specific about triggers] +--- + +# [Name] Voice + +[One paragraph describing this voice's essence] + +## When to Use This Skill + +Use this skill when: +- [Trigger 1] +- [Trigger 2] +- [Trigger 3] + +## Voice Profile + +### Core Traits +- **Tone**: [warm/neutral/intense/etc.] +- **Formality**: [casual/professional/academic] +- **Personality**: [high/medium/low] +- **Technical Level**: [accessible/moderate/expert] + +### Vocabulary Patterns + +**Distinctive words/phrases:** +- [word/phrase 1] +- [word/phrase 2] + +**Prohibited words:** +- [word 1] - because: [reason] +- [word 2] - because: [reason] + +### Sentence Rhythm + +- **Average length**: [X] words +- **Pattern**: [description] +- **Constructions**: [distinctive patterns] + +### Signature Techniques + +1. **[Technique 1]**: [Description] +2. **[Technique 2]**: [Description] + +## Writing Rules + +1. [Rule 1] +2. [Rule 2] +3. [Rule 3] + +## Anti-Patterns + +| Avoid | Because | Instead | +|-------|---------|---------| +| "I think that..." | Weakens authority | State directly | +| Passive voice in openings | Buries the action | Lead with subject + verb | +| Corporate jargon | Alienates readers | Use plain language | + +## Examples + +### Before (Generic) +> It is believed by many experts that the implementation of AI tools can potentially lead to significant productivity improvements in various workplace settings. + +### After ([Name] Voice) +> AI tools double your output. I've seen it happenβ€”first in my own work, then across our entire team. + +## Integration + +Works well with: +- `[other voice]` for [reason] +- `[editing skill]` for [reason] +``` + +Create supporting files if needed: +- `references/examples.md` - Extended examples +- `references/techniques.md` - Deep dive on techniques + +### Domain Skill Structure + +Create `skills/domain/[name]/`: + +```markdown +# SKILL.md +--- +name: domain-[name] +description: Deep expertise in [domain] - the "10 Books Expert" for writing about [topic] +--- + +# [Domain] Writing Expertise + +[One paragraph on what this domain covers and how it improves your writing] + +## When to Use This Skill + +Use this skill when writing about: +- [Topic 1] +- [Topic 2] +- [Topic 3] + +## Core Knowledge Base + +### Foundational Works (The 5 Core Books) + +1. **[Book/Source 1]** by [Author] + - Key insight: [insight] + - Use when writing: [context] + +2. **[Book/Source 2]** by [Author] + - Key insight: [insight] + - Use when writing: [context] + +[... 3-5 total] + +### Supporting Works (5 Secondary Sources) + +1. **[Source 1]**: [What it adds to your writing] +2. **[Source 2]**: [What it adds to your writing] + +[... 3-5 total] + +## Writing Frameworks + +### [Framework 1 Name] +[How to structure arguments using this framework] + +### [Framework 2 Name] +[How to build narratives using this framework] + +## Domain Vocabulary + +| Term | Plain English | Use in Writing | +|------|---------------|----------------| +| [jargon] | [simple definition] | "[example sentence]" | + +## Reasoning Patterns for Writing + +When writing about [domain], structure your thinking: + +1. **[Pattern 1]**: Start with [X], then show [Y] +2. **[Pattern 2]**: Use [framework] to build the argument + +## Common Writing Mistakes + +| Mistake | Why Readers Lose Interest | Better Approach | +|---------|---------------------------|-----------------| +| Starting with definitions | Feels like a textbook | Open with a story or stake | +| Too much jargon | Alienates non-experts | Translate, then use sparingly | + +## Example Paragraphs + +### Topic: [Example Topic 1] +**Hook**: [Opening sentence that grabs attention] +**Structure**: [How to build the argument] +**Key phrases**: "[memorable line]", "[quotable insight]" +``` + +### Format Skill Structure + +Create `skills/format/[name]/`: + +```markdown +# SKILL.md +--- +name: format-[name] +description: Write for [platform] - constraints, templates, and hooks that work +--- + +# Writing for [Platform] + +[One paragraph on this platform's unique writing requirements] + +## When to Use This Skill + +Use when: +- Adapting an essay for [platform] +- Writing native [platform] content +- Repurposing long-form into [platform] format + +## Writing Constraints + +| Element | Constraint | +|---------|-----------| +| Character limit | [X chars] | +| Optimal length | [range] | +| Paragraph length | [X sentences max] | +| Links | [how they affect reach] | +| Formatting | [what's available] | + +## Writing Templates + +### Template 1: The Thread Opener +``` +[Hook that stops the scroll] + +[Promise of value] + +[Thread indicator: 🧡 or "A thread:"] +``` + +### Template 2: The Single Post +``` +[Observation or hot take] + +[One supporting point] + +[Call to engage or share] +``` + +## Writing Techniques + +1. **Front-load value**: Put the insight in the first line +2. **Write for skimmers**: Each line should work alone +3. **End with engagement**: Question, challenge, or call to action + +## Hooks That Stop the Scroll + +| Hook Type | Example | +|-----------|---------| +| Contrarian | "Unpopular opinion: Most productivity advice makes you less productive" | +| Story start | "Last week I almost quit my job. Here's what happened instead:" | +| Number hook | "I've written 500 blog posts. These 3 lessons took the longest to learn:" | +| Bold claim | "AI won't take your job. But someone using AI will." | + +## Common Writing Mistakes + +| Mistake | Fix | +|---------|-----| +| Burying the hook | Move your best line to the top | +| Too much context | Assume they know nothing, explain everything | +| Weak endings | End with action, not summary | + +## Example: High-Performing Post + +``` +I've shipped code every day for 10 years. + +Here's the one habit that changed everything: + +I stop coding at 4pm. No exceptions. + +Not because I'm lazy. Because the best ideas +come when I'm NOT at my desk. + +Shower thoughts. Walk thoughts. Dinner thoughts. + +The code I write at 9am is 10x better because +of the thinking I did after 4pm yesterday. + +Productivity isn't about more hours. +It's about better hours. +``` + +**Why it works:** +- Hook with credibility (10 years) +- Counterintuitive insight (stop at 4pm) +- Specific details (shower, walk, dinner) +- Memorable takeaway (better hours, not more) +``` + +--- + +## Step 5.5: Add Vale Linting (Optional) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Would you like to add Vale linting rules for this skill?" +header: "Vale" +options: + - label: "Yes, create Vale rules" + description: "Generate YAML linting rules based on the skill's style guide" + - label: "No, skip Vale" + description: "Don't create linting rules" +``` + +### If Yes: Create Vale Rules + +For voice and editing skills, extract key patterns and create Vale rules: + +**Directory structure:** +``` +skills/[type]/[name]/ +β”œβ”€β”€ SKILL.md +β”œβ”€β”€ references/ +└── vale/ # NEW + └── [SkillName]/ + β”œβ”€β”€ OverusedWords.yml + β”œβ”€β”€ Avoid.yml + └── [other rules].yml +``` + +**Common Vale rule types to generate:** + +1. **Existence rules** - Flag words/phrases to avoid: +```yaml +# vale/[SkillName]/Avoid.yml +extends: existence +message: "Avoid '%s' in this voice." +level: warning +ignorecase: true +tokens: + - [word1] + - [word2] +``` + +2. **Substitution rules** - Replace phrases: +```yaml +# vale/[SkillName]/Substitutions.yml +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +swap: + 'bad phrase': 'good phrase' +``` + +**Extract rules from skill's anti-patterns:** +- Read the skill's "Anti-Patterns" or "Avoid" section +- Convert each anti-pattern to a Vale rule +- Use the skill's reasoning in the `message` field + +**Create lint script:** +```bash +# skills/[type]/[name]/scripts/lint.sh +#!/bin/bash +# Lint text against [name] style + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +VALE_DIR="$SCRIPT_DIR/../vale" + +if ! command -v vale &> /dev/null; then + echo "Vale not installed. Install with: brew install vale" + exit 1 +fi + +vale --config="$VALE_DIR/.vale.ini" "$@" +``` + +**Create .vale.ini for the skill:** +```ini +# skills/[type]/[name]/vale/.vale.ini +StylesPath = . +MinAlertLevel = suggestion + +[*.md] +BasedOnStyles = [SkillName] +``` + +--- + +## Step 6: Update Documentation + +``` +Update plugins/compound-writing/CLAUDE.md: +- Add new skill to appropriate table +- Update skill count + +Update plugins/compound-writing/README.md: +- Add new skill to skills list +- Update count in description +``` + +--- + +## Step 7: Commit + +```bash +git add plugins/compound-writing/skills/[type]/[name]/ +git add plugins/compound-writing/CLAUDE.md +git add plugins/compound-writing/README.md + +git commit -m "feat(compound-writing): Add [name] [type] skill + +[Brief description of the skill] + +- [Key feature 1] +- [Key feature 2] +- [Key feature 3] + +Co-Authored-By: Claude " +``` + +--- + +## Step 8: Confirm Creation + +```markdown +βœ“ Created [type] skill: [name] + +**Location**: skills/[type]/[name]/ +**Files**: +- SKILL.md (main skill definition) +- references/[files] (supporting materials) + +**Research sources used**: +- [source 1] +- [source 2] + +**Ready to use**: +- Voice selection in `/writing:plan` +- Layering with other voices + +**Next steps**: +1. Review the generated skill +2. Add personal examples if desired +3. Test with `/writing:draft` +``` + +--- + +## Step 9: Post-Creation Options (BRAINSTORM) + +**MANDATORY: Use the AskUserQuestion tool here. Do NOT output options as plain text.** + +```yaml +tool: AskUserQuestion +question: "Skill '[name]' created and committed. What next?" +header: "Next" +options: + - label: "View skill" + description: "Open the SKILL.md file in editor" + - label: "Test it" + description: "Run /writing:plan with this voice" + - label: "Refine" + description: "Edit or expand the skill" + - label: "Create another" + description: "Make another skill" +``` + +Based on selection: +- **View skill** β†’ Run `open skills/[type]/[name]/SKILL.md` to open in default editor +- **Test it** β†’ Ask for a topic, then call `/writing:plan` with the new voice selected +- **Refine** β†’ Ask what to improve, then edit the skill file +- **Create another** β†’ Loop back to Step 1 for a new skill +- **Other** (automatically provided) β†’ Accept free text for custom action + +--- + +## Quality Checklist + +Before completing: +- [ ] Input correctly parsed (type, name, source) +- [ ] Existing skills read as patterns +- [ ] Research sub-agents completed +- [ ] User approved research findings +- [ ] Skill files created in correct location +- [ ] SKILL.md has valid frontmatter +- [ ] References files created if needed +- [ ] Documentation updated (CLAUDE.md, README.md) +- [ ] Changes committed with descriptive message +- [ ] User shown confirmation with next steps diff --git a/plugins/compound-writing/docs/WRITING-ARCHITECTURE.md b/plugins/compound-writing/docs/WRITING-ARCHITECTURE.md new file mode 100644 index 00000000..ae230aab --- /dev/null +++ b/plugins/compound-writing/docs/WRITING-ARCHITECTURE.md @@ -0,0 +1,206 @@ +# The Writing Process: Agents & Skills Architecture + +> A comprehensive framework mapping the entire writing process to specialized agents and skills. + +## Overview + +This document defines the complete phase-by-phase breakdown of professional writing workflows, from ideation to final form. Use this as a reference for extending the compound-writing plugin. + +--- + +## Phase Map + +| Phase | Focus | Current Plugin Coverage | +|-------|-------|------------------------| +| 1. Discovery | Ideas, strategy, research | `/writing:plan` + `source-researcher` | +| 2. Architecture | Thesis, structure, outline | `/writing:plan` + `structure-architect` | +| 3. Creation | First draft, gap filling | `/writing:draft` + voice skills | +| 4. Revision | Big picture edits | `/writing:review` (partial) | +| 5. Editing | Sentence-level polish | `clarity-editor`, `every-style-editor` | +| 6. Polish | Proofread, headlines | `publishing-optimizer` | +| 7. Optimization | SEO, format adaptation | `publishing-optimizer` (partial) | +| 8. QA | Final verification | `/writing:review` | + +--- + +## Complete Agent Roster + +### Currently Implemented (7) + +| Agent | Phase | Function | +|-------|-------|----------| +| `source-researcher` | Discovery | Gather information, sources, examples | +| `structure-architect` | Architecture | Create outlines, analyze flow | +| `voice-guardian` | Creation/Editing | Maintain voice consistency | +| `clarity-editor` | Editing | Sentence-level clarity | +| `fact-checker` | Editing | Verify claims and sources | +| `every-style-editor` | Editing | Every's style guide compliance | +| `publishing-optimizer` | Polish/Optimization | SEO, social, newsletters | + +### Proposed Additions (11) + +| Agent | Phase | Function | Priority | +|-------|-------|----------|----------| +| `ideation-agent` | Discovery | Generate ideas, find angles | Medium | +| `strategist-agent` | Discovery | Define audience, purpose | Medium | +| `thesis-agent` | Architecture | Crystallize core argument | Low | +| `drafter-agent` | Creation | Generate prose from outline | High | +| `gap-analyst` | Creation | Find missing pieces | Medium | +| `dev-editor-agent` | Revision | Big-picture critique | High | +| `line-editor-agent` | Editing | Prose craft, rhythm | Medium | +| `copy-editor-agent` | Editing | Grammar, style guide | Medium | +| `proofreader-agent` | Polish | Final error catch | Low | +| `headline-agent` | Polish | Craft titles, hooks | Medium | +| `adaptation-agent` | Optimization | Format for platforms | Low | + +--- + +## Skill Types + +### 1. Core Skills (Every Project) + +Essential skills loaded for all writing workflows. + +| Skill | Purpose | Status | +|-------|---------|--------| +| `writing-orchestration` | Two-agent architecture, strategies | Implemented | +| `scratchpad` | Session preference memory | Implemented | +| `context-notes` | Structured handoffs | Implemented | +| `voice-capture` | Extract voice from samples | Implemented | + +### 2. Voice Skills (Select Per Project) + +Define the writing style and tone. + +| Skill | Style | Status | +|-------|-------|--------| +| `pragmatic-writing` | Hunt/Thomas, Joel Spolsky | Implemented | +| `dhh-writing` | Direct, opinionated | Implemented | +| `voice-hemingway` | Sparse, direct, concrete | Proposed | +| `voice-conversational` | Friendly, accessible | Proposed | +| `voice-academic` | Formal, hedged, citation-heavy | Proposed | +| `voice-technical` | Precise, jargon-appropriate | Proposed | + +### 3. Style Guide Skills (Select One) + +Ensure consistency with established standards. + +| Skill | Standard | Status | +|-------|----------|--------| +| `every-style-editor` | Every's house style | Implemented | +| `style-guide-ap` | AP Stylebook | Proposed | +| `style-guide-chicago` | Chicago Manual | Proposed | +| `style-guide-custom` | Organizational rules | Template | + +### 4. Domain Skills (Load as Needed) + +Specialized knowledge for specific fields. + +| Skill | Domain | Contains | +|-------|--------|----------| +| `domain-saas` | SaaS/B2B | Metrics, terminology, examples | +| `domain-finance` | Finance | Terms, compliance, regulations | +| `domain-healthcare` | Medical | Terminology, HIPAA, clinical | +| `domain-legal` | Legal | Language, disclaimers, contracts | +| `domain-expert-[x]` | Custom | "10 books" deep expertise | + +### 5. Format Skills (Load for Output) + +Transform content for different platforms. + +| Skill | Output | Key Constraints | +|-------|--------|-----------------| +| `format-blog-post` | Long-form blog | SEO, headers, readability | +| `format-twitter-thread` | Twitter/X | 280 chars, hooks, numbering | +| `format-linkedin` | LinkedIn | Professional, engagement | +| `format-newsletter` | Email | Subject lines, previews | +| `format-whitepaper` | B2B docs | Formal, comprehensive | + +--- + +## Pipeline Flow + +``` +DISCOVERY ARCHITECTURE CREATION +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Ideation │──▢ Brief ──▢│ Thesis │──▢ Outline β–Άβ”‚ Drafter β”‚ +β”‚ Strategy β”‚ β”‚ Architectβ”‚ β”‚ Gap β”‚ +β”‚ Research β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ Analyst β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό +REVISION EDITING POLISH +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚Dev Editor│──▢ Revised β–Άβ”‚ Line │──▢ Clean ──▢│Proofread β”‚ +β”‚ Revision β”‚ Draft β”‚ Copy β”‚ Draft β”‚ Headline β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ Fact β”‚ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β–Ό +OPTIMIZATION QA +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SEO │──▢ Final ──▢│ QA │──▢ PUBLISH +β”‚Adaptationβ”‚ β”‚ Agent β”‚ +β”‚ Style β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## The "10 Books Expert" Pattern + +For domain expertise, create skills grounded in foundational texts: + +```yaml +name: domain-expert-behavioral-economics +description: Deep expertise from Kahneman, Thaler, Ariely, Cialdini +triggers: ["behavioral economics", "cognitive bias", "nudge"] +``` + +**Structure:** +1. Core Texts (5) - The foundational works +2. Secondary Texts (5) - Supporting perspectives +3. Key Frameworks - How to apply the knowledge +4. Reasoning Patterns - Example thought processes + +This pattern can be applied to any domain where deep expertise is needed. + +--- + +## Implementation Roadmap + +### Phase 1: Foundation (Current) +- [x] Core workflow commands (plan, draft, review, compound) +- [x] Basic agents (7) +- [x] Core skills (orchestration, scratchpad, context-notes) +- [x] Two voice skills (pragmatic, dhh) + +### Phase 2: Creation Enhancement +- [ ] `drafter-agent` - Dedicated prose generation +- [ ] `dev-editor-agent` - Big-picture structural critique +- [ ] Additional voice skills (hemingway, conversational) + +### Phase 3: Editing Depth +- [ ] `line-editor-agent` - Prose craft focus +- [ ] `copy-editor-agent` - Grammar/style specialist +- [ ] Style guide skills (AP, Chicago) + +### Phase 4: Optimization +- [ ] `headline-agent` - Titles and hooks +- [ ] `adaptation-agent` - Platform formatting +- [ ] Format skills (twitter, linkedin, newsletter) + +### Phase 5: Domain Expertise +- [ ] Domain skill template +- [ ] "10 books" expert pattern implementation +- [ ] Custom domain skill generator + +--- + +## References + +- [Editorial Department - Editorial Process 101](https://www.editorialdepartment.com/editorial-process/) +- [MasterClass - Line Editing vs Copy Editing](https://www.masterclass.com/articles/what-is-line-editing) +- [CrewAI Documentation](https://docs.crewai.com/en/concepts/agents) +- [Agent Skills Specification](https://agentskills.io/specification) diff --git a/plugins/compound-writing/docs/patterns/common-patterns.md b/plugins/compound-writing/docs/patterns/common-patterns.md new file mode 100644 index 00000000..20c3b2b0 --- /dev/null +++ b/plugins/compound-writing/docs/patterns/common-patterns.md @@ -0,0 +1,92 @@ +# Common Writing Patterns + +Index of frequently used patterns captured from successful writing. + +## How to Use This Library + +Patterns are extracted via `/writing:compound` from pieces that work well. They're organized by type: + +- **Hooks** (`hooks/`) - Opening patterns that grab attention +- **Structures** (`structures/`) - Article architectures that flow +- **Transitions** (`transitions/`) - Phrases that connect ideas smoothly +- **Voice** (`voice/`) - Voice elements and exemplars + +## Pattern Format + +Each pattern file follows this structure: + +```markdown +--- +title: "Pattern Name" +type: hook | structure | transition | voice +extracted_from: "source piece path" +created: YYYY-MM-DD +tags: [topic1, topic2] +--- + +## Pattern +[Description] + +## Example +> [Actual text from source] + +## When to Use +- Context 1 +- Context 2 + +## How to Apply +1. Step 1 +2. Step 2 + +## Variations +- Variation 1 +- Variation 2 +``` + +## Quick Reference + +### Hook Patterns + +| Pattern | When to Use | +|---------|-------------| +| Concrete Example | Technical topics, tutorials | +| Surprising Stat | Data-driven pieces | +| Tension | Problem-solution articles | +| Question | Exploratory essays | + +### Structure Patterns + +| Pattern | When to Use | +|---------|-------------| +| Problem-Solution | How-to, fixes | +| Journey | Transformations, case studies | +| Listicle | Reference content, tips | +| Story | Narrative pieces | + +### Transition Patterns + +| Type | Example | +|------|---------| +| Causal | "That's why..." | +| Contrast | "But here's the thing..." | +| Continuation | "And it gets better..." | +| Reversal | "Until it doesn't." | + +## Adding New Patterns + +When you run `/writing:compound` on a successful piece, it automatically: +1. Extracts effective patterns +2. Creates pattern files in the appropriate directory +3. Updates this index + +You can also manually add patterns by creating files following the format above. + +## Pattern Discovery Tips + +Look for patterns when: +- A piece gets unusually high engagement +- Editing significantly improves a section +- A structure works well for multiple topics +- A transition feels invisible + +Patterns compound: the more you capture, the faster you write. diff --git a/plugins/compound-writing/skills/core/context-notes/SKILL.md b/plugins/compound-writing/skills/core/context-notes/SKILL.md new file mode 100644 index 00000000..a72aca52 --- /dev/null +++ b/plugins/compound-writing/skills/core/context-notes/SKILL.md @@ -0,0 +1,260 @@ +--- +name: context-notes +description: Structured context passing protocol between writing commands. Ensures seamless handoffs with all necessary information preserved. +--- + +# Context Notes Skill + +A protocol for passing structured context between writing commands, ensuring nothing gets lost in handoffs. + +## When to Use This Skill + +This skill applies when: +- Handing off from plan to draft +- Passing review findings to revision +- Preserving research across commands +- Maintaining continuity in multi-step workflows + +## The Context Notes Block + +Every command handoff includes a context notes block: + +```markdown + +## Research Summary +[2-3 sentences of gathered research] + +## Material Available +- [Concrete example 1] +- [Data point 1] +- [Quote or source 1] + +## Message Clarity +**Thesis**: [One sentence thesis] +**Audience**: [Specific audience] +**Desired Action**: [What reader should do] + +## Voice Configuration +**Profile**: [voice profile name or "infer"] +**Style Guide**: [style guide name or "none"] +**Channel**: [blog/newsletter/social/docs] + +## Mode +[EXPLORATION or REFINEMENT] + +## Scratchpad Summary +[Key preferences from scratchpad] + +``` + +## Context Flow Between Commands + +### /writing:plan β†’ /writing:draft + +```markdown + +## Research Summary +Researched AI adoption in healthcare. Found 73% of hospitals now use AI diagnostics. +Mayo Clinic case study shows 40% faster diagnosis times. + +## Material Available +- Stat: 73% hospital AI adoption (source: HealthTech 2025) +- Case: Mayo Clinic 40% improvement +- Quote: "AI is the stethoscope of the 21st century" - Dr. Sarah Chen + +## Message Clarity +**Thesis**: AI diagnostics are becoming standard of care, not optional +**Audience**: Hospital administrators considering AI investment +**Desired Action**: Request a demo of our AI platform + +## Voice Configuration +**Profile**: kieran-blog +**Style Guide**: none +**Channel**: blog + +## Mode +EXPLORATION + +``` + +### /writing:draft β†’ /writing:review + +```markdown + +## Draft Status +- Version: draft-v1 +- Word count: 847 +- Voice score: 82 (target: 85) +- Drafts created: 3 (user selected draft-2) + +## Strategies Applied +- Baseline: All 10 applied +- Situational: hook-stat-surprise, ladder-abstraction, tension-builder + +## Known Issues +- Opening may need strengthening (voice score dip) +- Paragraph 4 is dense (consider breaking) + +## Scratchpad Summary +- βœ“ User prefers data-driven openings +- βœ— User dislikes formal tone + +``` + +### /writing:review β†’ /writing:draft (revision) + +```markdown + +## Review Summary +- Critical issues: 2 +- Important issues: 4 +- Polish issues: 3 + +## Accepted Fixes +1. Strengthen opening with specific stat (was too vague) +2. Break paragraph 4 into two +3. Replace passive voice in conclusion + +## Rejected Fixes +1. Adding more technical jargon (user prefers accessible) + +## Mode +REFINEMENT (working on draft-2) + +``` + +## Context Notes Protocol + +### Required Fields + +Every context notes block MUST include: + +| Field | Required For | Purpose | +|-------|--------------|---------| +| Message Clarity | planβ†’draft | Ensures writer knows the goal | +| Material Available | planβ†’draft | Prevents fact invention | +| Voice Configuration | all handoffs | Maintains consistency | +| Mode | draft commands | Determines draft count | +| Draft Status | review handoffs | Tracks versions | + +### Optional Fields + +| Field | When to Include | +|-------|-----------------| +| Research Summary | When research was performed | +| Scratchpad Summary | When feedback exists | +| Known Issues | When issues are pre-identified | +| Accepted/Rejected Fixes | After review triage | + +## Two-Gate Assessment in Context + +Context notes encode the two-gate assessment results: + +### Gate 1: Material Sufficiency +```markdown +## Material Available +- [List of concrete materials] +- [No invented facts needed] +``` +If this section is empty or vague β†’ Gate 1 failed β†’ need more research + +### Gate 2: Message Clarity +```markdown +## Message Clarity +**Thesis**: [Clear one-sentence thesis] +**Audience**: [Specific audience] +**Desired Action**: [Clear CTA] +``` +If any field is vague β†’ Gate 2 failed β†’ need clarification + +## Context Preservation + +### What Gets Preserved +- Research findings +- User preferences (scratchpad) +- Voice configuration +- Draft history and IDs + +### What Gets Fresh Each Command +- Strategy selection (based on current content) +- Quality scores +- Issue lists + +## Example: Full Workflow Context Flow + +``` +/writing:plan "AI in healthcare" + β”‚ + β”œβ”€ Outputs: outline.md + β”œβ”€ Outputs: sources.md + └─ Outputs: with research + message clarity + β”‚ + β–Ό +/writing:draft (receives context_notes) + β”‚ + β”œβ”€ Reads: context_notes + β”œβ”€ Reads: scratchpad preferences + β”œβ”€ Creates: draft-1, draft-2, draft-3 + └─ Outputs: with draft status + β”‚ + β–Ό +/writing:feedback draft-2 "love it, but opening is weak" + β”‚ + └─ Updates: scratchpad + β”‚ + β–Ό +/writing:review draft-2 (receives context_notes + scratchpad) + β”‚ + β”œβ”€ Reads: context_notes (voice, strategies) + β”œβ”€ Reads: scratchpad (preferences) + β”œβ”€ Runs: parallel agent reviews + └─ Outputs: with review findings + β”‚ + β–Ό +/writing:draft refine draft-2 (REFINEMENT mode) + β”‚ + β”œβ”€ Reads: context_notes (accepted fixes) + β”œβ”€ Reads: scratchpad (preferences) + └─ Outputs: refined draft-2 + β”‚ + β–Ό +/writing:compound draft-2 + β”‚ + β”œβ”€ Reads: full context history + └─ Extracts: patterns to knowledge base +``` + +## Context Notes File + +For long-running projects, context can persist in `drafts/.context.md`: + +```markdown +--- +project: "AI Healthcare Blog Series" +created: 2025-01-16 +last_updated: 2025-01-16 +--- + +# Project Context + +## Research Archive +[All research from plan phase] + +## Voice Configuration +[Locked voice settings] + +## Session History +[Command sequence with outcomes] + +## Active Draft +[Current draft being worked on] +``` + +## Integration with Commands + +All commands should: + +1. **Read context notes** from previous command output or `.context.md` +2. **Validate required fields** before proceeding +3. **Generate updated context notes** for next command +4. **Preserve scratchpad preferences** across handoffs diff --git a/plugins/compound-writing/skills/core/scratchpad/SKILL.md b/plugins/compound-writing/skills/core/scratchpad/SKILL.md new file mode 100644 index 00000000..ade524ce --- /dev/null +++ b/plugins/compound-writing/skills/core/scratchpad/SKILL.md @@ -0,0 +1,251 @@ +--- +name: scratchpad +description: Real-time feedback tracking system for iterative writing refinement. Captures preferences, tracks draft performance, and builds a preference profile that guides future content. +--- + +# Scratchpad Skill + +A persistent feedback system that learns what works and what doesn't across your writing session. + +## When to Use This Skill + +This skill applies when: +- Collecting feedback on draft variations +- Building a preference profile during a session +- Tracking what resonates vs. what falls flat +- Refining voice and style iteratively + +## Core Concept + +The scratchpad is your session's memory of preferences: + +``` +Draft 1 β†’ Feedback: "love the opening" β†’ Scratchpad learns: strong hooks work +Draft 2 β†’ Feedback: "too formal" β†’ Scratchpad learns: prefer casual +Draft 3 β†’ Uses learnings β†’ Better alignment +``` + +## Scratchpad Structure + +```markdown +# Session Scratchpad + +## Preference Profile + +### βœ“ What Works +- [Positive pattern with example] + +### βœ— What Doesn't +- [Negative pattern with example] + +## Draft Feedback Log + +### [Draft ID] - [timestamp] +**Sentiment**: positive/negative/neutral +**Feedback**: [user's words] +**Principle**: [extracted learning] + +## Strategy Adjustments +Based on feedback, adjust: +- [strategy]: [how to adjust] +``` + +## Feedback Entry Format + +When capturing feedback: + +```yaml +entry: + draft_id: "draft-3" + timestamp: "2025-01-16T10:30:00" + sentiment: "negative" + raw_feedback: "the opening is weak, doesn't grab me" + category: "hooks" + principle: "Needs stronger, more provocative openings" + action: "Prioritize hook-effectiveness strategy" +``` + +## Preference Categories + +### Voice & Tone +Track formality, personality, emotional register: +- "too corporate" β†’ prefer casual +- "love the warmth" β†’ maintain personal touch +- "feels distant" β†’ add more direct address + +### Structure & Flow +Track pacing, organization, transitions: +- "lost me in the middle" β†’ improve transitions +- "perfect build-up" β†’ use tension-release pattern +- "too long" β†’ cut more aggressively + +### Content & Substance +Track examples, data, depth: +- "needs more proof" β†’ add data/examples +- "love the stats" β†’ lead with data +- "too abstract" β†’ use concrete examples + +### Style & Language +Track word choice, rhythm, clarity: +- "jargon heavy" β†’ simplify language +- "punchy sentences work" β†’ vary length more +- "repetitive" β†’ use elegant variation + +## Building the Preference Profile + +After 3+ feedback entries, synthesize: + +```markdown +## Auto-Generated Preference Profile + +Based on [N] feedback entries: + +### Voice Tendency +[Inferred voice preference with confidence %] + +### Structural Preference +[How they like content organized] + +### Content Style +[What types of examples/proof resonate] + +### Language Patterns +[Sentence style, word choice preferences] + +### Recommended Strategies +1. [strategy-name]: High priority because [feedback evidence] +2. [strategy-name]: Medium priority because [feedback evidence] + +### Strategies to Avoid +1. [strategy-name]: Conflicts with [feedback evidence] +``` + +## Integration Points + +### Reading Scratchpad +Before creating drafts: +``` +1. Load .scratchpad.md +2. Extract preference profile +3. Weight recent feedback higher (recency decay) +4. Apply to strategy selection +``` + +### Writing to Scratchpad +After receiving feedback: +``` +1. Parse feedback for sentiment +2. Categorize the feedback +3. Extract actionable principle +4. Append to log +5. Regenerate preference profile +``` + +### Conflict Resolution +When feedback contradicts: +``` +Entry 1: "too casual" +Entry 5: "too formal" + +Resolution options: +1. Recency wins (Entry 5 takes precedence) +2. Ask for clarification +3. Find the middle ground +``` + +## Recency Weighting + +More recent feedback matters more: + +| Age | Weight | +|-----|--------| +| Current turn | 1.0 | +| 1-3 turns ago | 0.8 | +| 4-6 turns ago | 0.5 | +| 7+ turns ago | 0.3 | + +## Draft ID Tracking + +Every draft gets a unique ID: +- IDs persist across the session +- Never reuse IDs +- Refinements keep original ID +- New explorations increment + +``` +Response 1: draft-1, draft-2, draft-3 +Response 2: draft-4, draft-5, draft-6 (exploration) +Response 3: draft-4 refined (keeps ID) +``` + +## Scratchpad Lifecycle + +``` +Session Start + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ /writing:feedback │◄──┐ +β”‚ Add entry to scratchpad β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ /writing:draft β”‚ β”‚ +β”‚ Read & apply preferences β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β–Ό β”‚ + User reviews β”‚ + β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ /writing:compound β”‚ +β”‚ Persist to pattern library β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Example Session + +``` +Turn 1: + User: /writing:draft "AI in healthcare" + Assistant: Creates draft-1, draft-2, draft-3 + +Turn 2: + User: /writing:feedback draft-1 love the stat opening + Scratchpad: βœ“ Statistical hooks resonate + +Turn 3: + User: /writing:feedback draft-3 too formal, sounds like a press release + Scratchpad: βœ— Avoid formal/corporate tone + +Turn 4: + User: /writing:draft refine draft-1 + Assistant: Reads scratchpad, applies preferences + Creates refined draft-1 (keeps ID, uses casual tone + stats) + +Turn 5: + User: /writing:feedback draft-1 perfect, this is it + Scratchpad: βœ“ Casual + data-driven = winning combo + +Turn 6: + User: /writing:compound draft-1 + Pattern library: Adds "casual-data-hook" pattern +``` + +## Scratchpad File Location + +Default: `drafts/.scratchpad.md` + +Can be configured per project in `.claude/writing-config.yaml`: +```yaml +scratchpad: + path: "drafts/.scratchpad.md" + persist_sessions: true + max_entries: 50 + auto_summarize_at: 10 +``` diff --git a/plugins/compound-writing/skills/core/voice-capture/SKILL.md b/plugins/compound-writing/skills/core/voice-capture/SKILL.md new file mode 100644 index 00000000..fdaaa407 --- /dev/null +++ b/plugins/compound-writing/skills/core/voice-capture/SKILL.md @@ -0,0 +1,242 @@ +--- +name: voice-capture +description: This skill should be used when extracting voice profiles from sample text, creating voice documentation, or matching a specific writing style. It applies when users provide sample text and want to capture the voice for future use. +--- + +# Voice Capture Skill + +Extract and encode writing voice from sample text into reusable voice profiles. This skill transforms examples of writing you like into documented patterns that can guide future writing. + +## When to Use This Skill + +This skill applies when: +- A user provides sample text and asks "write like this" +- Creating a voice profile from existing content +- Documenting a brand voice for consistency +- Capturing an author's style for future reference +- Analyzing differences between two writing styles + +## Core Philosophy + +> Voice isn't just word choice. It's sentence rhythm, paragraph structure, emotional register, and a thousand small decisions that create a distinctive sound. + +This skill captures those decisions systematically so they can be applied to new content. + +## Voice Profile Structure + +A complete voice profile has three layers. See [voice-profile-template.yaml](./assets/voice-profile-template.yaml) for the full template. + +### Layer 1: Immutable Traits + +Core characteristics that define the voice: + +```yaml +traits: + - direct # vs. indirect, circumspect + - conversational # vs. formal, academic + - technically-informed # level of assumed expertise + +register: informal # formal / semiformal / informal + +prohibited: + - "synergy" + - passive voice in openings + - exclamation marks (except in quotes) +``` + +### Layer 2: Channel Guidance + +How the voice adapts by medium: + +```yaml +channels: + blog: + length: "1000-2000 words" + personality: "full" + storytelling: "encouraged" + + newsletter: + length: "300-500 words" + personality: "high - direct address okay" + storytelling: "personal anecdotes" + + social: + length: "280 chars or thread" + personality: "punchy, hooks required" + storytelling: "minimal - punchlines only" + + documentation: + length: "as needed" + personality: "minimal" + storytelling: "none - clarity first" +``` + +### Layer 3: Example Library + +Exemplars that demonstrate the voice: + +```yaml +exemplars: + - path: "samples/great-opening.md" + why: "Concrete example first, theory second" + demonstrates: ["hook", "pacing"] + + - path: "samples/transition.md" + why: "Invisible transition technique" + demonstrates: ["flow", "structure"] + + - path: "samples/closing.md" + why: "Strong CTA without being salesy" + demonstrates: ["conclusion", "call-to-action"] +``` + +## Extraction Process + +### Step 1: Collect Samples + +Minimum: 3 samples (ideally 5-10) +Total words: At least 2,000 words +Variety: Different topics, same author/brand + +### Step 2: Analyze Dimensions + +Reference [analysis-dimensions.md](./references/analysis-dimensions.md) for the full framework. + +#### Vocabulary Analysis +- **Complexity**: Simple ↔ Complex +- **Formality**: Casual ↔ Formal +- **Jargon**: Technical ↔ Accessible +- **Signature words**: Frequently used phrases + +#### Sentence Analysis +- **Length**: Average words per sentence +- **Variety**: Standard deviation of sentence length +- **Structure**: Simple vs. compound vs. complex ratio +- **Fragments**: Used for emphasis? How often? + +#### Paragraph Analysis +- **Length**: Average sentences per paragraph +- **Opening patterns**: How do paragraphs typically start? +- **Closing patterns**: How do paragraphs typically end? + +#### Rhythm Analysis +- **Pacing**: Quick (short sentences) vs. measured (longer) +- **Punctuation style**: Dashes, semicolons, parentheses +- **White space**: Dense vs. airy paragraphs + +#### Emotional Analysis +- **Tone**: Optimistic, skeptical, neutral, passionate +- **Distance**: Intimate (I, you) vs. distant (one, they) +- **Stakes**: High urgency vs. calm reflection + +### Step 3: Document Patterns + +For each dimension, document: +1. The observed pattern +2. A concrete example +3. A counter-example (what this voice avoids) + +### Step 4: Create Profile + +Use [extraction-templates.md](./references/extraction-templates.md) to structure your findings. + +Output: `.claude/voice-profiles/[name].yaml` + +## Using Voice Profiles + +### In Writing Commands + +```yaml +# In /writing:draft +style: + voice_profile: "kieran-blog" + # OR + voice_profile: ".claude/voice-profiles/client-name.yaml" +``` + +### For Voice Guardian + +The voice-guardian agent uses profiles to: +- Score voice consistency (0-100) +- Identify drift points +- Suggest specific fixes + +Target score: 85+ + +### For New Writers + +When onboarding writers to match an existing voice: +1. Share the voice profile +2. Share the exemplars +3. Run voice-guardian on their drafts + +## Quick Extraction Workflow + +For rapid voice capture (when you need a profile fast): + +```markdown +## Quick Profile: [Name] + +**Based on**: [X] samples totaling [Y] words + +### Core Traits +- [Trait 1] +- [Trait 2] +- [Trait 3] + +### Sentence Patterns +Average length: [X] words +Common patterns: +- [Pattern 1] +- [Pattern 2] + +### Vocabulary Markers +**Signature words**: [list] +**Avoided words**: [list] + +### Tone +[Brief description] + +### Quick Examples +Good: "[example that nails the voice]" +Bad: "[example that would violate it]" +``` + +## Common Extraction Challenges + +### Challenge: Too Few Samples + +**Problem**: Can't identify patterns from 1-2 samples. +**Solution**: Ask for more content or analyze published work from the same source. + +### Challenge: Inconsistent Source + +**Problem**: The sample voice varies significantly. +**Solution**: Either document the variation (multiple profiles) or focus on the most recent/best examples. + +### Challenge: Style vs. Voice + +**Problem**: Confusing topic-specific style with core voice. +**Solution**: Analyze samples on different topics. What stays constant? That's the voice. + +### Challenge: Unconscious Patterns + +**Problem**: Author doesn't know what makes their voice distinctive. +**Solution**: Compare to other writers. What's different? That's often the key. + +## Quality Checklist + +A voice profile is complete when: +- [ ] All three layers are populated +- [ ] At least 3 exemplars are documented +- [ ] Prohibited patterns are explicit +- [ ] Channel variations are noted +- [ ] A test passage can be evaluated against it +- [ ] Someone unfamiliar with the voice could use it + +## References + +- [extraction-templates.md](./references/extraction-templates.md) - Templates for structured extraction +- [analysis-dimensions.md](./references/analysis-dimensions.md) - All dimensions to analyze +- [example-profiles.md](./references/example-profiles.md) - Sample voice profiles for reference +- [voice-profile-template.yaml](./assets/voice-profile-template.yaml) - The YAML template diff --git a/plugins/compound-writing/skills/core/voice-capture/assets/voice-profile-template.yaml b/plugins/compound-writing/skills/core/voice-capture/assets/voice-profile-template.yaml new file mode 100644 index 00000000..d3bcb552 --- /dev/null +++ b/plugins/compound-writing/skills/core/voice-capture/assets/voice-profile-template.yaml @@ -0,0 +1,132 @@ +# Voice Profile Template +# Copy and customize this template for new voice profiles + +name: "[voice-name-kebab-case]" +description: "Brief description of this voice" +created: "[YYYY-MM-DD]" +based_on: "[Author name or brand]" +sample_count: 0 +sample_words: 0 + +# Layer 1: Immutable Traits +# Core characteristics that define this voice + +traits: + - "[trait-1]" # e.g., direct, analytical, playful + - "[trait-2]" + - "[trait-3]" + +register: "[formal|semiformal|informal|casual]" + +prohibited: + # Words, phrases, and patterns to never use + - "[word or phrase]" + - "[pattern description]" + +# Vocabulary patterns +vocabulary: + signature_words: + - "[word]" + - "[phrase]" + formality: "[casual|conversational|professional|formal]" + complexity: "[simple|moderate|complex]" + contractions: "[always|usually|sometimes|never]" + technical_density: "[none|light|moderate|heavy]" + +# Sentence patterns +sentences: + average_length: 0 # words + range: "[min]-[max]" + fragment_usage: "[never|rare|occasional|frequent]" + opening_preference: "[subject-verb|question|transition|varied]" + structure_preference: "[simple|compound|complex|varied]" + +# Paragraph patterns +paragraphs: + average_length: 0 # sentences + white_space: "[dense|moderate|airy]" + structure: "[topic-evidence|claim-support|story-lesson|varied]" + opening_type: "[topic-sentence|hook|question|transition]" + closing_type: "[conclusion|bridge|punchline|question]" + +# Rhythm patterns +rhythm: + pacing: "[staccato|legato|varied]" + # Punctuation frequency: never|rare|occasional|frequent + em_dash: "[frequency]" + parentheses: "[frequency]" + semicolon: "[frequency]" + exclamation: "[frequency]" + # Repetition patterns + rule_of_three: "[never|occasional|frequent]" + anaphora: "[never|occasional|frequent]" + +# Emotional tone +tone: + primary: "[one-word descriptor]" + secondary: "[one-word descriptor]" + stakes: "[low|medium|high]" + distance: "[intimate|conversational|professional|distant]" + +# Layer 2: Channel Guidance +# How voice adapts by medium + +channels: + blog: + length: "[word range]" + personality: "[description]" + storytelling: "[none|minimal|encouraged|required]" + notes: "" + + newsletter: + length: "[word range]" + personality: "[description]" + direct_address: "[yes|no|sometimes]" + notes: "" + + social: + length: "[char limit or 'thread']" + personality: "[description]" + hooks: "[required|encouraged|optional]" + notes: "" + + documentation: + length: "as needed" + personality: "[minimal|some|full]" + notes: "" + + # Add more channels as needed + # email: + # presentation: + # etc. + +# Layer 3: Example Library +# Exemplars that demonstrate the voice + +exemplars: + - path: "[relative/path/to/sample.md]" + why: "[What this sample demonstrates]" + demonstrates: + - "[element-1]" # e.g., hook, pacing, tone + - "[element-2]" + + - path: "" + why: "" + demonstrates: [] + + - path: "" + why: "" + demonstrates: [] + +# Anti-exemplars (what this voice would NOT do) +anti_exemplars: + - text: "[Example text that violates this voice]" + violation: "[What rule it breaks]" + +# Metadata +metadata: + confidence: "[high|medium|low]" + last_updated: "[YYYY-MM-DD]" + notes: | + Additional notes about this voice profile. + Common challenges, edge cases, etc. diff --git a/plugins/compound-writing/skills/core/voice-capture/references/analysis-dimensions.md b/plugins/compound-writing/skills/core/voice-capture/references/analysis-dimensions.md new file mode 100644 index 00000000..8fb9bbb2 --- /dev/null +++ b/plugins/compound-writing/skills/core/voice-capture/references/analysis-dimensions.md @@ -0,0 +1,217 @@ +# Voice Analysis Dimensions + +Complete framework for analyzing writing voice across all dimensions. + +## 1. Vocabulary Dimensions + +### 1.1 Complexity + +| Level | Description | Indicators | +|-------|-------------|------------| +| Simple | 8th grade reading level | Short words, common vocabulary | +| Moderate | 10-12th grade | Mix of common and specialized | +| Complex | College+ | Domain expertise, advanced vocabulary | + +**How to measure**: Use Flesch-Kincaid or similar readability metric. + +### 1.2 Formality + +| Level | Indicators | +|-------|------------| +| Casual | Contractions, slang, sentence fragments | +| Conversational | Contractions, no slang, complete sentences | +| Professional | Minimal contractions, industry terms | +| Formal | No contractions, third person, passive voice acceptable | + +### 1.3 Technical Density + +- **None**: No jargon, fully accessible +- **Light**: Occasional terms, defined or obvious +- **Moderate**: Regular technical vocabulary, assumes baseline +- **Heavy**: Dense specialized language, expert audience + +### 1.4 Signature Vocabulary + +Look for: +- Words used 3+ times across samples +- Unusual word choices (not the obvious word) +- Branded terms or coined phrases +- Consistent metaphor families + +## 2. Sentence Dimensions + +### 2.1 Length Metrics + +| Metric | Calculation | +|--------|-------------| +| Average length | Total words / total sentences | +| Shortest sentence | Minimum (for emphasis use) | +| Longest sentence | Maximum (complexity tolerance) | +| Variance | How much length varies | + +**Typical ranges**: +- Punchy: 8-12 words average +- Balanced: 15-20 words average +- Complex: 25+ words average + +### 2.2 Structure Types + +| Type | Pattern | Example | +|------|---------|---------| +| Simple | Subject + Verb | "The code runs." | +| Compound | S+V and/or S+V | "The code runs, and tests pass." | +| Complex | Main clause + dependent | "When you run the code, tests pass." | +| Compound-Complex | Multiple clauses | Full combination | + +### 2.3 Opening Patterns + +Count percentage of sentences starting with: +- Subject (proper start): "The team decided..." +- Question: "What if we..." +- Transition: "However, the approach..." +- Participle: "Running the tests..." +- Subordinate clause: "When the tests passed..." +- "I" or "We": First person leads + +### 2.4 Fragment Usage + +| Level | Description | +|-------|-------------| +| Never | All complete sentences | +| Rare | Emphasis only, <5% | +| Occasional | Stylistic choice, 5-15% | +| Frequent | Part of voice, >15% | + +## 3. Paragraph Dimensions + +### 3.1 Length Patterns + +- **Short**: 1-2 sentences (punchy, scannable) +- **Medium**: 3-4 sentences (standard) +- **Long**: 5+ sentences (dense, academic) + +### 3.2 Structure Patterns + +**Opening types**: +- Topic sentence (states paragraph purpose) +- Hook (attention-grabbing statement) +- Question (rhetorical or actual) +- Transition (from previous paragraph) + +**Closing types**: +- Conclusion (wraps up the point) +- Bridge (sets up next paragraph) +- Punch line (memorable closer) +- Question (leaves reader thinking) + +### 3.3 White Space + +Visual density of paragraphs: +- Dense: Long paragraphs, few breaks +- Moderate: Mixed lengths +- Airy: Short paragraphs, frequent breaks, lists + +## 4. Rhythm Dimensions + +### 4.1 Pacing + +| Type | Pattern | +|------|---------| +| Staccato | Short, punchy, rapid-fire | +| Legato | Long, flowing, connected | +| Varied | Intentional mix for effect | + +### 4.2 Punctuation Profile + +For each mark, note frequency: +- **Em dash**: Emphasis, interruption, asides +- **Parentheses**: Secondary info, qualification +- **Semicolon**: Related ideas, sophistication +- **Colon**: Introduction, lists, explanation +- **Ellipsis**: Trailing off, suspense +- **Exclamation**: Energy, emphasis + +### 4.3 Repetition Patterns + +- **Anaphora**: Repeated beginnings ("We built. We shipped. We learned.") +- **Epistrophe**: Repeated endings +- **Parallelism**: Similar structure across items +- **Rule of three**: Three beats, three examples + +## 5. Emotional Dimensions + +### 5.1 Tone Categories + +| Tone | Indicators | +|------|------------| +| Optimistic | Positive framing, future focus, solutions | +| Skeptical | Questions assumptions, critical analysis | +| Neutral | Balanced, informational, objective | +| Passionate | Strong language, personal investment | +| Urgent | Time pressure, calls to action | +| Calm | Measured, reflective, patient | + +### 5.2 Distance Scale + +| Level | Indicators | +|-------|------------| +| Intimate | "I", "you", personal stories, vulnerability | +| Conversational | Occasional "you", relatable examples | +| Professional | "We", company voice, limited personal | +| Academic | Third person, citations, objectivity | +| Distant | Passive voice, "one", impersonal | + +### 5.3 Stakes Level + +How urgent does the writing feel? + +- **Low**: Informational, "here's how it works" +- **Medium**: Opinion, "this matters because" +- **High**: Urgent, "you need to act now" + +## 6. Structural Dimensions + +### 6.1 Organization Patterns + +- **Linear**: Point A to Point B to Point C +- **Problem-Solution**: State problem, resolve it +- **Compare-Contrast**: This vs. that +- **Chronological**: Timeline or narrative +- **Spatial**: By location or component +- **Priority**: Most to least important + +### 6.2 Argument Style + +- **Inductive**: Examples first, principle after +- **Deductive**: Principle first, examples after +- **Dialectical**: Thesis, antithesis, synthesis + +### 6.3 Evidence Preferences + +- Stories and anecdotes +- Data and statistics +- Expert quotes +- Logical reasoning +- Personal experience +- Historical examples + +## Analysis Checklist + +For complete voice extraction, analyze: + +- [ ] Vocabulary: complexity, formality, technical density, signatures +- [ ] Sentences: length, structure, openings, fragments +- [ ] Paragraphs: length, structure, white space +- [ ] Rhythm: pacing, punctuation, repetition +- [ ] Emotion: tone, distance, stakes +- [ ] Structure: organization, argument style, evidence + +## Quick Analysis Framework + +For rapid analysis, focus on: + +1. **Average sentence length** (objective, measurable) +2. **Formality level** (contractions, word choice) +3. **Primary tone** (one word descriptor) +4. **Signature vocabulary** (3-5 distinctive words) +5. **Paragraph length** (short, medium, long) diff --git a/plugins/compound-writing/skills/core/voice-capture/references/example-profiles.md b/plugins/compound-writing/skills/core/voice-capture/references/example-profiles.md new file mode 100644 index 00000000..20745949 --- /dev/null +++ b/plugins/compound-writing/skills/core/voice-capture/references/example-profiles.md @@ -0,0 +1,273 @@ +# Example Voice Profiles + +Sample voice profiles demonstrating the format. + +## Example 1: DHH (David Heinemeier Hansson) + +```yaml +name: dhh-blog + +traits: + - direct + - opinionated + - contrarian + +register: informal + +prohibited: + - hedge words (seems, might, perhaps) + - passive voice (except for emphasis) + - corporate buzzwords (synergy, leverage, optimize) + - exclamation marks (unless ironic) + - "I think" or "in my opinion" (implied) + +vocabulary: + signature_words: + - "bullshit" + - "vanilla" + - "majestic" + - "heresy" + formality: casual-professional + complexity: moderate + contractions: always + +sentences: + average_length: 12 + fragment_usage: frequent + opening_preference: subject-verb + +paragraphs: + average_length: 2-3 + white_space: airy + structure: claim-evidence + +rhythm: + pacing: punchy + rule_of_three: frequent + em_dash: occasional + semicolon: rare + +tone: + primary: confident + secondary: provocative + stakes: medium-high + distance: conversational + +channels: + blog: + length: "500-1500 words" + personality: "full" + controversy: "welcomed" + twitter: + length: "single tweet preferred" + personality: "concentrated" + controversy: "frequent" + +exemplars: + - text: "Most meetings are a waste of time. Not some. Most." + demonstrates: ["short sentences", "contrarian", "repetition"] + - text: "We don't do free. We don't do enterprise. $99. Done." + demonstrates: ["fragments", "rule of three", "directness"] +``` + +## Example 2: Joel Spolsky + +```yaml +name: joel-on-software + +traits: + - analytical + - humorous + - storytelling + +register: conversational + +prohibited: + - jargon without explanation + - abstract theory without concrete examples + - formal academic tone + - passive voice (mostly) + +vocabulary: + signature_words: + - "leaky abstractions" + - "Joel Test" + - "shlemiel the painter" + formality: casual-technical + complexity: moderate-high (explained) + contractions: yes + +sentences: + average_length: 18 + fragment_usage: occasional + opening_preference: varied + +paragraphs: + average_length: 3-4 + white_space: moderate + structure: story-point-lesson + +rhythm: + pacing: varied + parenthetical_asides: frequent + em_dash: occasional + footnotes: rare + +tone: + primary: explanatory + secondary: witty + stakes: medium + distance: friendly-expert + +channels: + blog: + length: "1500-3000 words" + personality: "full, storytelling" + humor: "embedded throughout" + documentation: + length: "as needed" + personality: "reduced but present" + humor: "occasional" + +exemplars: + - text: "The Joel Test is a quick measure of the quality of a software team. The higher the score, the better the team. No, it's not perfect, but it's fast and pretty good." + demonstrates: ["conversational", "practical", "self-aware"] + - text: "Shlemiel gets a job as a street painter, painting the dotted lines down the middle of the road..." + demonstrates: ["storytelling", "physical analogy", "setup-punchline"] +``` + +## Example 3: Paul Graham + +```yaml +name: paul-graham-essays + +traits: + - exploratory + - philosophical + - building-arguments + +register: semiformal + +prohibited: + - starting with conclusions + - excessive qualification + - jargon without setup + +vocabulary: + signature_words: + - "ramen profitable" + - "do things that don't scale" + - "frighteningly ambitious" + formality: intellectual-accessible + complexity: high (earned) + contractions: some + +sentences: + average_length: 22 + fragment_usage: rare + opening_preference: statement + +paragraphs: + average_length: 4-5 + white_space: moderate-dense + structure: logical-progression + +rhythm: + pacing: measured + nested_clauses: accepted + em_dash: frequent + semicolon: occasional + +tone: + primary: thoughtful + secondary: counterintuitive + stakes: medium + distance: intellectual-peer + +channels: + essay: + length: "2000-4000 words" + personality: "reflective" + structure: "meandering toward insight" + +exemplars: + - text: "Don't just not be evil. Be good." + demonstrates: ["moral clarity", "concision", "building on negation"] + - text: "The way to get startup ideas is not to try to think of startup ideas." + demonstrates: ["counterintuitive", "paradox setup", "memorable"] +``` + +## Example 4: Corporate Neutral (Anti-Example) + +```yaml +name: corporate-neutral +description: "What NOT to do - included for contrast" + +traits: + - hedged + - safe + - buzzword-laden + +register: formal + +vocabulary: + signature_words: + - "leverage" + - "synergy" + - "value proposition" + - "best-in-class" + formality: corporate-formal + complexity: low-disguised-as-high + contractions: never + +sentences: + average_length: 28 + fragment_usage: never + opening_preference: "There are/It is" + +paragraphs: + average_length: 6+ + white_space: dense + structure: circular + +tone: + primary: safe + secondary: defensive + stakes: artificially high + distance: distant + +problems: + - "Says nothing memorable" + - "Could be any company" + - "No human voice" + - "Exhausting to read" + +exemplar_bad: + - text: "We are excited to announce a strategic initiative designed to enhance our value proposition through synergistic partnerships that will drive innovation across our ecosystem." + problems: ["no meaning", "all buzzwords", "passive framing"] +``` + +## Using These Profiles + +### For Matching Voice + +Compare your writing to the exemplars: +1. Read the exemplar aloud +2. Read your writing aloud +3. Do they sound like the same person? + +### For Voice Guardian Scoring + +When scoring voice match: +- Check against prohibited words +- Compare sentence length +- Verify tone matches +- Look for signature vocabulary + +### For Learning Style + +Study the difference between profiles: +- DHH: Short, punchy, contrarian +- Joel: Story-driven, explanatory +- Paul Graham: Exploratory, builds arguments +- Corporate: Avoid at all costs diff --git a/plugins/compound-writing/skills/core/voice-capture/references/extraction-templates.md b/plugins/compound-writing/skills/core/voice-capture/references/extraction-templates.md new file mode 100644 index 00000000..6f3cd25b --- /dev/null +++ b/plugins/compound-writing/skills/core/voice-capture/references/extraction-templates.md @@ -0,0 +1,236 @@ +# Voice Extraction Templates + +Structured templates for capturing voice systematically. + +## Full Extraction Template + +Use this for comprehensive voice profiles. + +```markdown +# Voice Extraction: [Name/Brand] + +## Source Material +- Sample 1: [title/description] ([X] words) +- Sample 2: [title/description] ([X] words) +- Sample 3: [title/description] ([X] words) +Total: [X] words across [X] samples + +## Vocabulary Analysis + +### Complexity Score +[ ] Simple (8th grade reading level) +[X] Moderate (10-12th grade) +[ ] Complex (college+) + +Evidence: "[example sentence]" + +### Formality Score +[ ] Casual (contractions, slang okay) +[X] Conversational (contractions, no slang) +[ ] Professional (minimal contractions) +[ ] Formal (no contractions) + +Evidence: "[example]" + +### Signature Words/Phrases +Words used frequently: +- "[word]" - appears X times +- "[phrase]" - appears X times + +### Prohibited Words +Words never used: +- "[word]" - alternative used instead: "[alternative]" +- "[word]" - never appears despite topic relevance + +## Sentence Analysis + +### Average Length +[X] words (calculated from samples) + +### Length Distribution +Shortest sentences: [X] words (for emphasis) +Longest sentences: [X] words (for explanation) +Standard deviation: [X] + +### Structure Patterns + +**Dominant pattern**: [Simple / Compound / Complex] + +**Fragment usage**: +[ ] Never +[ ] Rarely (emphasis only) +[X] Sometimes +[ ] Frequently + +Example fragment: "[example]" + +### Opening Patterns +Sentences typically start with: +- Subject-verb: [%] +- Question: [%] +- Transition word: [%] +- "-ing" phrase: [%] + +## Paragraph Analysis + +### Average Length +[X] sentences per paragraph + +### Opening Patterns +How paragraphs typically begin: +- Hook/claim: [%] +- Question: [%] +- Continuation: [%] +- Quote: [%] + +### Closing Patterns +How paragraphs typically end: +- Conclusion/summary: [%] +- Transition to next: [%] +- Question: [%] +- Punch line: [%] + +## Rhythm Analysis + +### Pacing +[ ] Quick (short sentences dominate) +[X] Varied (intentional mix) +[ ] Measured (longer sentences dominate) + +### Punctuation Preferences +- Em dashes: [Frequent / Occasional / Rare / Never] +- Parentheses: [Frequent / Occasional / Rare / Never] +- Semicolons: [Frequent / Occasional / Rare / Never] +- Exclamation marks: [Frequent / Occasional / Rare / Never] + +### White Space +[ ] Dense (long paragraphs) +[X] Moderate (mixed) +[ ] Airy (short paragraphs, frequent breaks) + +## Emotional Analysis + +### Tone +Primary: [optimistic / skeptical / neutral / passionate / urgent / calm] +Secondary: [additional descriptor] + +### Emotional Distance +[X] Intimate ("I", "you", direct address) +[ ] Conversational (occasional "you") +[ ] Professional (rare personal pronouns) +[ ] Distant ("one", passive constructions) + +### Stakes Level +[ ] Low (informational, neutral) +[X] Medium (opinion, mild urgency) +[ ] High (urgent, emotional, calls to action) + +## Extracted Patterns + +### Pattern 1: [Name] +**What**: [Description of the pattern] +**Example**: "[Quote from samples]" +**When to use**: [Context] + +### Pattern 2: [Name] +**What**: [Description] +**Example**: "[Quote]" +**When to use**: [Context] + +[Continue for major patterns...] + +## Anti-Patterns + +### What This Voice Avoids +1. [Anti-pattern]: "[Example of what NOT to do]" +2. [Anti-pattern]: "[Example]" +3. [Anti-pattern]: "[Example]" + +## Exemplar Passages + +### Best Example of Voice +> "[Passage that perfectly captures the voice]" + +Why this works: [Explanation] + +### Good Contrast Example +> "[Passage that would NOT fit this voice]" + +Why this doesn't work: [Explanation] + +## Final Profile Summary + +**In one sentence**: This voice is [X], [Y], and [Z]. + +**Key identifiers**: If you see [marker], it's probably this voice. + +**Biggest risk**: Writers often drift toward [common mistake]. +``` + +## Quick Extraction Template + +Use for rapid voice capture when time is limited. + +```markdown +# Quick Voice Profile: [Name] + +**Based on**: [X] samples, [Y] total words +**Confidence**: [High / Medium / Low] + +## Core Characteristics +1. [Most distinctive trait] +2. [Second trait] +3. [Third trait] + +## Sentence Style +- Average length: [X] words +- Fragments: [Yes/No] +- Structure: [Simple / Varied / Complex] + +## Vocabulary +**Signature words**: [word], [word], [word] +**Avoided words**: [word], [word], [word] +**Formality**: [Casual / Professional / Formal] + +## Tone +[One sentence description] + +## Quick Test +This voice would say: "[example]" +This voice would NOT say: "[counter-example]" +``` + +## Comparison Template + +Use when analyzing differences between two voices. + +```markdown +# Voice Comparison: [Voice A] vs. [Voice B] + +## Overview +| Dimension | Voice A | Voice B | +|-----------|---------|---------| +| Formality | [X] | [X] | +| Sentence Length | [X] words | [X] words | +| Tone | [X] | [X] | +| Complexity | [X] | [X] | + +## Key Differences + +### Difference 1: [Dimension] +**Voice A**: [Description with example] +**Voice B**: [Description with example] +**Implication**: [What this means for writing] + +### Difference 2: [Dimension] +[Continue pattern...] + +## Shared Traits +Both voices share: +1. [Shared trait] +2. [Shared trait] + +## When to Use Each +**Use Voice A when**: [Context] +**Use Voice B when**: [Context] +``` diff --git a/plugins/compound-writing/skills/core/writing-orchestration/SKILL.md b/plugins/compound-writing/skills/core/writing-orchestration/SKILL.md new file mode 100644 index 00000000..9ae56d2a --- /dev/null +++ b/plugins/compound-writing/skills/core/writing-orchestration/SKILL.md @@ -0,0 +1,302 @@ +--- +name: writing-orchestration +description: This skill should be used when orchestrating complex writing workflows with multiple phases. It provides two-agent orchestration patterns, the two-gate content readiness assessment, 10 baseline writing strategies, 20+ situational strategies, and quality checkpoints. Inspired by the Spiral Writing System. +--- + +# Writing Orchestration Skill + +A complete orchestration system for complex writing workflows. This skill provides the strategic layer that coordinates agents, applies writing strategies, and ensures content quality. + +## When to Use This Skill + +This skill applies when: +- Coordinating multiple writing agents +- Applying strategic writing decisions +- Assessing content readiness before drafting +- Selecting and applying writing strategies +- Running quality checkpoints on drafts + +## Two-Agent Architecture + +Complex writing benefits from separation of concerns: + +### Orchestrator Role +- Classifies requests (information vs. content) +- Applies two-gate assessment +- Gathers research and context +- Hands off to writer when ready +- Never creates content directly + +### Writer Role +- Creates drafts using strategies +- Applies style guides +- Produces variations (EXPLORATION mode) +- Refines based on feedback (REFINEMENT mode) +- Uses tools for all content (never in chat) + +``` +User Request + ↓ +[Orchestrator] β†’ Classify β†’ Research β†’ Two-Gate Assessment + ↓ + β”œβ”€β”€ Not Ready β†’ Gather more material/clarity + ↓ + └── Ready β†’ Handoff to Writer + ↓ + [Writer] β†’ Apply Strategies β†’ Create Drafts + ↓ + Quality Checkpoints β†’ Output +``` + +## Two-Gate Content Readiness Assessment + +Before any content creation, apply this assessment: + +### Gate 1: Material Sufficiency + +**Question**: "Could the writer create this without inventing facts?" + +| Outcome | Action | +|---------|--------| +| βœ“ Pass | Have concrete examples, data, quotes available | +| βœ— Fail | Need to research/gather material first | + +**Pass signals**: +- Specific examples available +- Data points confirmed +- Expert quotes accessible +- No major claims need fabrication + +### Gate 2: Message Clarity + +**Question**: "Do we know EXACTLY what message to convey?" + +| Outcome | Action | +|---------|--------| +| βœ“ Pass | Clear, specific communication goal | +| βœ— Fail | Need to interview for clarity | + +**Pass signals**: +- Can state thesis in one sentence +- Know the audience specifically +- Know the desired action +- Angle is differentiated + +### Decision Matrix + +| Material | Message | Action | +|----------|---------|--------| +| βœ“ | βœ“ | Handoff to writer immediately | +| βœ“ | βœ— | Interview for message clarity | +| βœ— | βœ“ | Research/gather material | +| βœ— | βœ— | Interview for both | + +## 10 Baseline Strategies (ALWAYS Apply) + +These strategies apply to ALL content. Reference [baseline-strategies.md](./references/baseline-strategies.md) for full details. + +| Strategy | Rule | Transform | +|----------|------|-----------| +| **reader-zero-context** | Add 3-6 word orienting phrases | "Stripe handles billing" β†’ "Stripe, the payments platform, handles billing" | +| **subject-verb** | Subject + verb in first 5 words | "There were students who..." β†’ "Students completed..." | +| **activate-verbs** | Precise verbs over is/was | "Markets were down" β†’ "Markets plunged" | +| **watch-adverbs** | Let strong verbs carry load | "whispered quietly" β†’ "whispered" | +| **limit-ings** | Simple tense over continuous | "are running tests" β†’ "run tests" | +| **prefer-simple** | Everyday language unless technical | "utilizes stochastic gradient" β†’ "learns by trial and error" | +| **cut-big-small** | Edit hierarchically | Paragraphs β†’ Sentences β†’ Words | +| **ban-empty-hypophora** | No self-answered questions | "The payoff? Our app..." β†’ "Our app..." | +| **present-active-tense** | Direct, immediate language | "debuts today" β†’ "is out now" | +| **one-idea-per-sentence** | Single clear point | Split compound thoughts | + +## 20+ Situational Strategies (Select 3-4) + +Choose based on content type and goals. Reference [situational-strategies.md](./references/situational-strategies.md) for full list. + +### Hook & Opening +- **hook-effectiveness** - Counterintuitive or surprising openings +- **tension-builder** - Create and resolve tension +- **pattern-twist** - Set expectations, then break them + +### Structure & Flow +- **order-words-emphasis** - Important words at sentence ends +- **sentence-length** - Vary for rhythm (short for impact, long for flow) +- **paragraph-length** - Mix for visual rhythm +- **ladder-abstraction** - Alternate concrete ↔ abstract + +### Style & Voice +- **elegant-variation** - Avoid word repetition +- **passive-aggressive** - Strategic passive for emphasis +- **punctuation-pace** - Use punctuation for rhythm +- **key-words-space** - Give important terms breathing room + +### Persuasion & Engagement +- **essential-name-filter** - Only names that add value +- **name-of-dog** - Specific details for authenticity +- **original-images** - Fresh metaphors, avoid clichΓ©s +- **show-and-tell** - Balance showing with telling + +### Narrative & Story +- **narrate-scenes** - Immersive scene-setting +- **cinematic-angles** - Camera-like perspective shifts +- **dialogue-compression** - Tight, purposeful dialogue +- **reveal-traits** - Character through action + +## Quality Checkpoints + +Before finalizing content, verify: + +### Opening Quality +- [ ] Opening is counterintuitive or surprising +- [ ] Leads with most compelling insight/moment/problem +- [ ] No chronology/setup/version numbers in opening +- [ ] Hook earns the next sentence + +### Body Quality +- [ ] Body delivers on opening's promise +- [ ] Concrete sensory details present +- [ ] Each paragraph has clear purpose +- [ ] Transitions are smooth + +### Strategy Compliance +- [ ] All 10 baseline strategies applied +- [ ] 3-4 situational strategies visible +- [ ] Each sentence expresses one clear idea +- [ ] Technical terminology oriented with context + +### Style Guide Compliance +- [ ] Voice matches profile/guide +- [ ] No prohibited words/patterns +- [ ] Formatting rules followed + +## Content Modes + +### EXPLORATION Mode (New Content) + +When creating new content: +1. Generate 3 different drafts +2. Vary angle, not just words +3. Apply all strategies to each +4. Let user choose direction + +### REFINEMENT Mode (Editing) + +When user provides feedback: +1. Work with existing draft +2. Preserve voice and structure +3. Apply specific changes requested +4. Keep what works + +## Handoff Protocol + +### Orchestrator β†’ Writer + +Use the context notes format for structured handoffs: + +```markdown + +## Research Summary +[2-3 sentences summarizing research] + +## Material Available +- [Concrete example 1] +- [Data point 1] +- [Quote or source 1] + +## Message Clarity +**Thesis**: [One sentence thesis] +**Audience**: [Specific audience] +**Desired Action**: [What reader should do] + +## Voice Configuration +**Profile**: [voice profile name or "infer"] +**Style Guide**: [style guide name or "none"] +**Channel**: [blog/newsletter/social/docs] + +## Mode +[EXPLORATION or REFINEMENT] + +## Scratchpad Summary +[Key preferences from session scratchpad] + +``` + +### Writer β†’ Orchestrator (Rare) + +Only when: +- User explicitly requests brainstorming +- New research topic needed +- Web search required +- Significant scope change + +## Scratchpad Integration + +The scratchpad (`drafts/.scratchpad.md`) captures real-time preferences: + +### Reading Scratchpad +Before creating drafts: +1. Load scratchpad preference profile +2. Extract "What Works βœ“" patterns +3. Extract "What Doesn't βœ—" anti-patterns +4. Apply recency weighting (newer feedback > older) +5. Use to guide strategy selection + +### Writing to Scratchpad +After receiving feedback via `/writing:feedback`: +1. Parse feedback for sentiment +2. Categorize (voice, structure, content, style) +3. Extract actionable principle +4. Append to log +5. Regenerate preference profile + +### Promoting to Patterns +Via `/writing:compound`: +1. Identify recurring preferences (3+ appearances) +2. Extract to pattern library +3. Add to voice profile +4. Clear promoted entries from scratchpad + +## Draft ID Management + +Every draft gets a unique, persistent ID: + +``` +Response 1: draft-1, draft-2, draft-3 (exploration) +Response 2: draft-4, draft-5, draft-6 (new exploration) +Response 3: draft-2 refined (keeps original ID) +``` + +Rules: +- IDs persist across the session +- Never reuse IDs +- Refinements keep original draft ID +- New explorations increment + +## Integration with Commands + +### `/writing:plan` +Uses Orchestrator patterns: +- Request classification +- Research phase +- Two-gate assessment +- Material gathering + +### `/writing:draft` +Uses Writer patterns: +- Strategy application +- Mode selection +- Draft creation +- Quality checkpoints + +### `/writing:review` +Uses both: +- Orchestrator: coordinate review agents +- Writer: apply fixes + +### `/writing:compound` +Captures patterns that worked for future orchestration. + +## References + +- [baseline-strategies.md](./references/baseline-strategies.md) - Full 10 baseline strategies with examples +- [situational-strategies.md](./references/situational-strategies.md) - 20+ situational strategies +- [quality-checkpoints.md](./references/quality-checkpoints.md) - Detailed checkpoint criteria diff --git a/plugins/compound-writing/skills/core/writing-orchestration/references/baseline-strategies.md b/plugins/compound-writing/skills/core/writing-orchestration/references/baseline-strategies.md new file mode 100644 index 00000000..1dfaa688 --- /dev/null +++ b/plugins/compound-writing/skills/core/writing-orchestration/references/baseline-strategies.md @@ -0,0 +1,171 @@ +# 10 Baseline Writing Strategies + +These strategies apply to ALL content. Apply every one, every time. + +## 1. Reader Zero Context + +**Rule**: Add 3-6 word orienting phrases for proper nouns and references. + +**Why**: Readers drop into content without your context. Orient them immediately. + +**Transform**: +| Before | After | +|--------|-------| +| "Stripe handles billing" | "Stripe, the payments platform, handles billing" | +| "We partnered with Acme" | "We partnered with Acme, a logistics startup" | +| "The RFC was approved" | "The RFC (Request for Comments), our design proposal, was approved" | + +**When to skip**: Universally known entities (Google, Apple, Einstein). + +## 2. Subject-Verb First + +**Rule**: Subject and verb within the first 5 words. + +**Why**: Readers parse subject-verb-object fastest. Front-load meaning. + +**Transform**: +| Before | After | +|--------|-------| +| "There were many students who completed the course" | "Many students completed the course" | +| "It is often the case that errors occur" | "Errors occur often" | +| "What we found was that users preferred..." | "Users preferred..." | + +**Pattern to avoid**: "There is/are", "It is", "What X is" + +## 3. Activate Verbs + +**Rule**: Precise verbs over is/was/has/have. + +**Why**: Active verbs create energy. Being verbs create lethargy. + +**Transform**: +| Before | After | +|--------|-------| +| "Markets were down sharply" | "Markets plunged" | +| "The team was in agreement" | "The team agreed" | +| "She was the leader of the project" | "She led the project" | +| "It was a surprise to everyone" | "It surprised everyone" | + +**Find-replace targets**: was, were, is, are, has been, have been + +## 4. Watch Adverbs + +**Rule**: Let strong verbs carry the load. Cut redundant adverbs. + +**Why**: Strong verbs don't need modification. Weak verb + adverb = lazy writing. + +**Transform**: +| Before | After | +|--------|-------| +| "whispered quietly" | "whispered" | +| "ran quickly" | "sprinted" | +| "completely destroyed" | "destroyed" | +| "very angry" | "furious" | + +**Keep adverbs when**: They change meaning ("she smiled coldly" vs "she smiled"). + +## 5. Limit -ings + +**Rule**: Simple tense over continuous tense. + +**Why**: Continuous tense adds words without meaning. Simple tense is direct. + +**Transform**: +| Before | After | +|--------|-------| +| "We are running tests" | "We run tests" | +| "The team was building features" | "The team built features" | +| "Users are experiencing issues" | "Users experience issues" | + +**Keep -ing when**: Action is genuinely ongoing or progressive. + +## 6. Prefer Simple + +**Rule**: Everyday language unless technical precision requires otherwise. + +**Why**: Simple words are faster to read and harder to misunderstand. + +**Transform**: +| Before | After | +|--------|-------| +| "utilize" | "use" | +| "terminate" | "end" | +| "facilitate" | "help" | +| "leverage" | "use" | +| "implement" | "build" or "do" | +| "optimize" | "improve" | + +**Keep complex when**: Technical precision matters (legal, medical, scientific). + +## 7. Cut Big to Small + +**Rule**: Edit hierarchically. Paragraphs β†’ Sentences β†’ Words. + +**Why**: Cutting a paragraph saves more than cutting 20 words. + +**Process**: +1. **Paragraph level**: Does this paragraph advance the argument? If not, cut it. +2. **Sentence level**: Does this sentence add new information? If not, cut it. +3. **Word level**: Does this word do work? If not, cut it. + +**The test**: Read without the cut element. If meaning survives, the cut was right. + +## 8. Ban Empty Hypophora + +**Rule**: No self-answered questions unless the answer surprises. + +**Why**: "The payoff? Amazing results." wastes words. Just say the results. + +**Transform**: +| Before | After | +|--------|-------| +| "The payoff? Our app launched." | "Our app launched." | +| "The solution? We hired more." | "We hired more." | +| "What happened next? Sales doubled." | "Sales doubled." | + +**Keep when**: The answer genuinely surprises or subverts expectations. + +## 9. Present Active Tense + +**Rule**: Direct, immediate language. Now > then. + +**Why**: Present tense creates urgency. Past tense creates distance. + +**Transform**: +| Before | After | +|--------|-------| +| "The feature debuts today" | "The feature is out now" | +| "We will launch soon" | "We launch next week" | +| "The update was released" | "The update is live" | + +**Keep past when**: Historical accuracy matters or sequence is important. + +## 10. One Idea Per Sentence + +**Rule**: Single clear point per sentence. + +**Why**: Compound sentences hide ideas. Simple sentences reveal them. + +**Transform**: +| Before | After | +|--------|-------| +| "The team launched the product, which was well-received, and sales increased dramatically." | "The team launched the product. Reception was strong. Sales increased dramatically." | + +**The test**: Can you state the sentence's one idea in 5 words? + +--- + +## Quick Reference Card + +| # | Strategy | Question to Ask | +|---|----------|-----------------| +| 1 | Reader Zero Context | Would a stranger need more context? | +| 2 | Subject-Verb First | Are subject and verb in first 5 words? | +| 3 | Activate Verbs | Can "is/was" become an action verb? | +| 4 | Watch Adverbs | Does the adverb do work the verb can't? | +| 5 | Limit -ings | Is continuous tense necessary? | +| 6 | Prefer Simple | Is there a simpler word? | +| 7 | Cut Big to Small | Would meaning survive without this? | +| 8 | Ban Empty Hypophora | Does my question-answer add value? | +| 9 | Present Active Tense | Can I make this more immediate? | +| 10 | One Idea Per Sentence | How many ideas in this sentence? | diff --git a/plugins/compound-writing/skills/core/writing-orchestration/references/quality-checkpoints.md b/plugins/compound-writing/skills/core/writing-orchestration/references/quality-checkpoints.md new file mode 100644 index 00000000..37716f46 --- /dev/null +++ b/plugins/compound-writing/skills/core/writing-orchestration/references/quality-checkpoints.md @@ -0,0 +1,148 @@ +# Quality Checkpoints + +Complete verification before finalizing any content. + +## Pre-Draft Checkpoints + +Before writing, verify: + +### Material Readiness +- [ ] Have concrete examples (not hypothetical) +- [ ] Have data/statistics (with sources) +- [ ] Have quotes (properly attributed) +- [ ] Have enough for claims (no fabrication needed) + +### Message Readiness +- [ ] Can state thesis in one sentence +- [ ] Know specific audience +- [ ] Know desired reader action +- [ ] Have differentiated angle + +## Draft Checkpoints + +### Opening (First 50 Words) + +| Checkpoint | Pass Criteria | +|------------|---------------| +| Hook type | Counterintuitive, surprising, or tension-building | +| Lead content | Most compelling insight/moment/problem | +| No chronology | Doesn't start with "Last week..." or timeline | +| No setup | Doesn't explain what you're about to say | +| No version numbers | "Version 2.0 of..." is not a hook | +| Promise made | Reader knows why to keep reading | + +**Test**: Cover everything after the first 50 words. Would you want to read more? + +### Body + +| Checkpoint | Pass Criteria | +|------------|---------------| +| Promise kept | Body delivers what opening promised | +| Sensory details | At least one concrete detail per section | +| Paragraph purpose | Each paragraph advances the argument | +| Transitions | Movement between sections is smooth | +| No redundancy | No section repeats another's point | + +**Test**: Can you summarize each paragraph's contribution in 5 words? + +### Strategy Compliance + +| Checkpoint | Pass Criteria | +|------------|---------------| +| Baseline strategies | All 10 applied | +| Situational strategies | 3-4 selected and visible | +| One idea per sentence | No compound thoughts cramming | +| Technical orientation | Jargon explained in context | +| Active voice | <10% passive voice | + +**Test**: Read aloud. Does it flow? Are sentences clear? + +### Closing + +| Checkpoint | Pass Criteria | +|------------|---------------| +| Callback | References opening hook or promise | +| Action clear | Reader knows what to do next | +| Memorable | Last line could be quoted | +| No summary | Doesn't recap what was said | +| No apology | Doesn't hedge or qualify | + +**Test**: Would you tweet the last line? + +## Style Guide Compliance + +If a style guide is specified: + +### Voice +- [ ] Matches vocabulary patterns +- [ ] Matches sentence length targets +- [ ] Matches formality level +- [ ] Matches emotional register + +### Prohibitions +- [ ] No prohibited words used +- [ ] No prohibited patterns used +- [ ] No formatting violations + +### Requirements +- [ ] Required elements present +- [ ] Required structure followed +- [ ] Required attribution style used + +## Final Pass + +### Read Aloud Test +- [ ] Sentences sound natural when spoken +- [ ] No tongue-twisters +- [ ] Rhythm feels right + +### The Email Test +- [ ] Would send this to your smartest colleague +- [ ] Would feel good if it went viral +- [ ] Would stand behind every claim + +### The Cut Test +- [ ] Tried cutting 10%β€”kept only what survived +- [ ] No paragraph that could be cut without loss +- [ ] No sentence that doesn't earn its place + +## Checkpoint by Content Type + +### Blog Post +1. Hook grabs in first line +2. Subheads are standalone interesting +3. Skimmable (bold, bullets, headers) +4. CTA is clear + +### Newsletter +1. Personal tone established +2. Feels like a letter from a person +3. Value delivered early +4. Easy to forward + +### Social Post +1. Works without clicking through +2. Hook in first line (gets cut in feeds) +3. No wasted words +4. Visual element considered + +### Long-Form +1. Reader can stop after each section and feel complete +2. Sections build but also standalone +3. Pacing varies (tension and release) +4. Ending is earned + +## Red Flags + +Stop and fix if you see: + +| Red Flag | Fix | +|----------|-----| +| Opening starts with "I want to..." | Cut, start with the insight | +| Paragraph over 6 sentences | Split | +| "In this article, we will..." | Delete | +| Three or more "is/was" in a row | Activate verbs | +| Same word appears 3+ times nearby | Elegant variation | +| Quote without attribution | Add source or remove | +| Claim without evidence | Support or soften | +| Ending trails off | Find the punch | diff --git a/plugins/compound-writing/skills/core/writing-orchestration/references/situational-strategies.md b/plugins/compound-writing/skills/core/writing-orchestration/references/situational-strategies.md new file mode 100644 index 00000000..a6740b1c --- /dev/null +++ b/plugins/compound-writing/skills/core/writing-orchestration/references/situational-strategies.md @@ -0,0 +1,254 @@ +# 20+ Situational Writing Strategies + +Select 3-4 strategies based on content type and goals. Don't apply allβ€”choose what fits. + +## Hook & Opening Strategies + +### hook-effectiveness + +**Purpose**: Create openings that demand attention. + +**Techniques**: +- **Counterintuitive**: Challenge what readers believe +- **Surprising stat**: Data that defies expectations +- **In media res**: Start in the middle of action +- **Question**: One the reader genuinely wants answered + +**Test**: Would you keep reading if you saw this on a busy feed? + +### tension-builder + +**Purpose**: Create and resolve tension throughout. + +**Techniques**: +- Establish stakes early +- Create obstacles before solutions +- Use "but" and "however" strategically +- Delay resolution for impact + +**Pattern**: Setup β†’ Complication β†’ Resolution + +### pattern-twist + +**Purpose**: Set expectations, then break them. + +**Techniques**: +- Establish a pattern (three examples) +- Break on the fourth +- Use for humor or insight + +**Example**: "We tried ads. We tried SEO. We tried influencers. We tried talking to customers. That last one worked." + +--- + +## Structure & Flow Strategies + +### order-words-emphasis + +**Purpose**: Put important words where they land hardestβ€”at the end. + +**Techniques**: +- Move key terms to sentence end +- End paragraphs with punch +- Save reveals for last position + +**Transform**: "We need to focus on the customer." β†’ "Our focus must be the customer." + +### sentence-length + +**Purpose**: Vary length for rhythm and impact. + +**Guidelines**: +- **Short (1-5 words)**: For impact. Punch. Emphasis. +- **Medium (10-20 words)**: For information and flow. +- **Long (25+ words)**: For building, explaining, setting scenesβ€”but sparingly. + +**Pattern**: Mix deliberately. Three medium, one short. Repeat. + +### paragraph-length + +**Purpose**: Create visual rhythm on the page. + +**Guidelines**: +- One sentence paragraphs: For emphasis +- 2-3 sentence paragraphs: Standard +- 4+ sentence paragraphs: Use rarely + +Like this. + +### ladder-abstraction + +**Purpose**: Alternate between concrete and abstract. + +**Pattern**: +1. Concrete example +2. Abstract principle +3. Another concrete example +4. Broader implication + +**Why**: Concrete grounds understanding. Abstract provides meaning. Neither alone is sufficient. + +--- + +## Style & Voice Strategies + +### elegant-variation + +**Purpose**: Avoid awkward word repetition. + +**Techniques**: +- Use pronouns strategically +- Find true synonyms (not forced ones) +- Restructure to avoid repetition +- Sometimes, repetition is intentionalβ€”for emphasis + +**Warning**: Don't substitute "the social media giant" for "Facebook" constantly. That's worse. + +### passive-aggressive + +**Purpose**: Use passive voice strategically, not accidentally. + +**When passive works**: +- Actor is unknown: "The data was compromised" +- Actor is irrelevant: "The study was conducted in 2020" +- Emphasis on object: "The bill was passed" (focus on bill, not Congress) + +**Default**: Active voice. Reserve passive for strategic use. + +### punctuation-pace + +**Purpose**: Use punctuation to control reading rhythm. + +**Tools**: +- **Period**: Full stop. Finality. Impact. +- **Comma**: Pause, breath, continuation +- **Em dash**: Interruptionβ€”surpriseβ€”aside +- **Semicolon**: Connection between related ideas; used sparingly +- **Colon**: Introduction of what follows + +**Example**: "We had three optionsβ€”none of them good." + +### key-words-space + +**Purpose**: Give important terms room to breathe. + +**Techniques**: +- Don't cluster key terms together +- Space important words throughout +- Let each land before introducing the next + +**Wrong**: "The efficiency, productivity, and scalability improvements..." +**Right**: "Efficiency improved. So did productivity. Scalability followed." + +--- + +## Persuasion & Engagement Strategies + +### essential-name-filter + +**Purpose**: Include only names that add value. + +**Test**: Does naming this person/company/product serve the reader? + +**Keep**: Names that add credibility, context, or story +**Cut**: Names that are just noise + +### name-of-dog + +**Purpose**: Specific details create authenticity. + +**Technique**: Include the kind of detail only someone who was there would know. + +**Examples**: +- "Her golden retriever, Murphy, sat under the desk" +- "The server ran Ubuntu 18.04" +- "The email came at 2:47 AM" + +**Why**: Specificity = credibility. + +### original-images + +**Purpose**: Fresh metaphors over clichΓ©s. + +**ClichΓ©s to kill**: +- "thinking outside the box" +- "at the end of the day" +- "move the needle" +- "low-hanging fruit" +- "on the same page" + +**Technique**: If you've heard it before, find a new way to say it. + +### show-and-tell + +**Purpose**: Balance showing with telling. + +**When to show**: Emotional moments, key scenes, character +**When to tell**: Transitions, summaries, facts + +**Balance**: Show the important parts. Tell the rest. + +--- + +## Narrative & Story Strategies + +### narrate-scenes + +**Purpose**: Create immersive scene-setting. + +**Elements**: +- Sensory details (what you see, hear, feel) +- Action in progress +- Dialogue if relevant +- Specific time and place + +**Example**: "The office was empty except for Sarah, hunched over her laptop, the glow of Slack notifications reflecting off her glasses." + +### cinematic-angles + +**Purpose**: Use camera-like perspective shifts. + +**Techniques**: +- Wide shot: Establish context, setting +- Medium shot: Character and environment +- Close-up: Detail, emotion, significance +- Pull back: Broader meaning, reflection + +**Use for**: Feature articles, profiles, narrative pieces + +### dialogue-compression + +**Purpose**: Make dialogue tight and purposeful. + +**Rules**: +- Cut greetings and small talk +- Each line should advance story or reveal character +- Attribution ("he said") should be minimal +- Use beats (actions) instead of dialogue tags + +**Wrong**: "Hi, how are you?" "I'm fine, thanks. How are you?" +**Right**: [Cut entirely unless the pleasantries reveal something] + +### reveal-traits + +**Purpose**: Show character through action, not description. + +**Wrong**: "She was a perfectionist." +**Right**: "She realigned the pens on her desk for the third time." + +**Technique**: What would this person DO that shows their trait? + +--- + +## Strategy Selection Guide + +| Content Type | Recommended Strategies | +|--------------|----------------------| +| Blog post | hook-effectiveness, ladder-abstraction, sentence-length | +| Case study | narrate-scenes, name-of-dog, show-and-tell | +| Product launch | tension-builder, pattern-twist, key-words-space | +| Thought piece | hook-effectiveness, elegant-variation, order-words-emphasis | +| Tutorial | ladder-abstraction, sentence-length, paragraph-length | +| Profile | cinematic-angles, reveal-traits, dialogue-compression | +| Newsletter | hook-effectiveness, sentence-length, one-idea-per-sentence | +| Social post | hook-effectiveness, pattern-twist, sentence-length | diff --git a/plugins/compound-engineering/skills/every-style-editor/SKILL.md b/plugins/compound-writing/skills/editing/every-style-editor/SKILL.md similarity index 70% rename from plugins/compound-engineering/skills/every-style-editor/SKILL.md rename to plugins/compound-writing/skills/editing/every-style-editor/SKILL.md index bbc29648..b60be6ed 100644 --- a/plugins/compound-engineering/skills/every-style-editor/SKILL.md +++ b/plugins/compound-writing/skills/editing/every-style-editor/SKILL.md @@ -132,3 +132,74 @@ Based on Every's style guide, pay special attention to: - Word usage (fewer vs. less, they vs. them) - Company references (singular "it", teams as plural "they") - Job title capitalization + +## Vale Linting + +This skill includes automated linting via [Vale](https://vale.sh/). + +### Running Vale + +Always use the script to lint files: + +```bash +# Lint a single file +bash ${CLAUDE_PLUGIN_ROOT}/skills/editing/every-style-editor/scripts/lint.sh drafts/my-post.md + +# Lint a directory +bash ${CLAUDE_PLUGIN_ROOT}/skills/editing/every-style-editor/scripts/lint.sh drafts/ + +# Check if Vale is installed +bash ${CLAUDE_PLUGIN_ROOT}/skills/editing/every-style-editor/scripts/lint.sh --help +``` + +### Install Vale (if needed) + +```bash +# macOS +brew install vale + +# Or download from https://vale.sh/docs/vale-cli/installation/ +``` + +### Rules Included + +| Rule | Level | Description | +|------|-------|-------------| +| `OverusedWords` | warning | Flags "actually", "very", "just" | +| `PassiveVoice` | warning | Detects passive voice | +| `EmDash` | error | No spaces around em dashes | +| `OxfordComma` | warning | Encourages serial comma | +| `ClickHere` | error | Flags "click here" links | +| `StartWithThis` | warning | Avoids sentences starting with "This" | +| `WeHaveWeGet` | warning | Avoids "We have/get" openings | +| `Cliches` | warning | Flags business jargon | +| `Percentages` | error | Enforces "X percent" not "X%" | +| `CompanyPronouns` | suggestion | Companies as "it" not "they" | +| `BoldEmphasis` | warning | Use italics, not bold | +| `Numbers` | suggestion | Spell out 1-9 | +| `Adverbs` | suggestion | Flags cuttable adverbs | +| `AISlop` | warning | Flags AI-overused words (delve, tapestry, vibrant) | +| `AIPhrases` | warning | Flags formulaic AI phrases | + +### Integration with Commands + +The `/writing:review` command can optionally run Vale: + +```bash +# During review, Vale is run automatically if installed +claude /writing:review drafts/my-post/draft-v1.md +``` + +### Customizing Rules + +Edit the YAML files in `vale/Every/` to customize: + +```yaml +# Add forbidden words +# vale/Every/OverusedWords.yml +tokens: + - actually + - your-word-here +``` + +See [vale/README.md](./vale/README.md) for full documentation diff --git a/plugins/compound-engineering/skills/every-style-editor/references/EVERY_WRITE_STYLE.md b/plugins/compound-writing/skills/editing/every-style-editor/references/EVERY_WRITE_STYLE.md similarity index 100% rename from plugins/compound-engineering/skills/every-style-editor/references/EVERY_WRITE_STYLE.md rename to plugins/compound-writing/skills/editing/every-style-editor/references/EVERY_WRITE_STYLE.md diff --git a/plugins/compound-writing/skills/editing/every-style-editor/scripts/lint.sh b/plugins/compound-writing/skills/editing/every-style-editor/scripts/lint.sh new file mode 100755 index 00000000..8ae6ea15 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/scripts/lint.sh @@ -0,0 +1,69 @@ +#!/bin/bash +# Lint text against Every's style guide using Vale +# +# Usage: +# ./lint.sh draft.md # Lint a single file +# ./lint.sh drafts/ # Lint a directory +# ./lint.sh --help # Show help +# +# Install Vale first: +# brew install vale +# +# Or download from: https://vale.sh/docs/vale-cli/installation/ + +set -e + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +VALE_DIR="$SCRIPT_DIR/../vale" + +# Check if Vale is installed +if ! command -v vale &> /dev/null; then + echo "Error: Vale is not installed." + echo "" + echo "Install with:" + echo " brew install vale" + echo "" + echo "Or download from: https://vale.sh/docs/vale-cli/installation/" + exit 1 +fi + +# Show help +if [[ "$1" == "--help" ]] || [[ "$1" == "-h" ]] || [[ -z "$1" ]]; then + echo "Every Style Linter" + echo "" + echo "Usage:" + echo " ./lint.sh Lint a single file" + echo " ./lint.sh Lint all markdown files in directory" + echo " ./lint.sh --help Show this help" + echo "" + echo "Examples:" + echo " ./lint.sh drafts/my-post/draft-v1.md" + echo " ./lint.sh drafts/" + echo "" + echo "Rules included:" + echo " - OverusedWords (actually, very, just)" + echo " - PassiveVoice" + echo " - EmDash (no spaces around em dashes)" + echo " - OxfordComma" + echo " - ClickHere (avoid 'click here' links)" + echo " - StartWithThis" + echo " - WeHaveWeGet" + echo " - Cliches" + echo " - Percentages (numerals + 'percent')" + echo " - CompanyPronouns (it, not they)" + echo " - BoldEmphasis (use italics, not bold)" + echo " - Numbers (spell out 1-9)" + echo " - Ellipsis (no space before)" + echo " - OverUnder (more/fewer than)" + echo " - Adverbs (cuttable adverbs)" + exit 0 +fi + +# Run Vale with the Every style +echo "Linting with Every style guide..." +echo "" + +vale --config="$VALE_DIR/.vale.ini" --styles-path="$VALE_DIR" "$@" + +echo "" +echo "Done! Fix errors (red) first, then warnings (yellow)." diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/.vale.ini b/plugins/compound-writing/skills/editing/every-style-editor/vale/.vale.ini new file mode 100644 index 00000000..856d98a2 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/.vale.ini @@ -0,0 +1,17 @@ +# Vale configuration for Every style guide +# Copy this file to your project root and run: vale . + +StylesPath = vale + +MinAlertLevel = suggestion + +# File types to check +[*.md] +BasedOnStyles = Every + +[*.txt] +BasedOnStyles = Every + +# For drafts directory +[drafts/*.md] +BasedOnStyles = Every diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AIPhrases.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AIPhrases.yml new file mode 100644 index 00000000..6b97cbd4 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AIPhrases.yml @@ -0,0 +1,65 @@ +# AI Phrase Detector - Flag formulaic AI writing patterns +# Based on: https://aisdr.com/blog/words-to-avoid-so-you-dont-sound-like-ai/ + +extends: existence +message: "'%s' is a formulaic AI phrase. Be more direct and specific." +level: warning +ignorecase: true +tokens: + # Formulaic openings + - "in today's" + - "in the realm of" + - "in the world of" + - "it's important to note" + - "it is important to note" + - "it's worth noting" + - "it is worth noting" + - "it's crucial to" + - "it is crucial to" + - "in this article" + - "in this blog post" + - "let's dive in" + - "without further ado" + + # Hedging language + - "generally speaking" + - "to some extent" + - "from a broader perspective" + - "at the end of the day" + - "when it comes to" + - "in terms of" + - "with that being said" + - "that said" + - "having said that" + + # Formulaic conclusions + - "in summary" + - "in conclusion" + - "in essence" + - "to summarize" + - "to conclude" + - "all in all" + - "overall," + + # AI landscape phrases + - "digital landscape" + - "navigate the landscape" + - "navigating the" + - "ever-evolving" + - "ever-changing" + - "fast-paced world" + - "rapidly evolving" + - "dynamic landscape" + + # Hollow intensifiers + - "game-changer" + - "game changer" + - "cutting-edge" + - "cutting edge" + - "groundbreaking" + - "revolutionary" + - "transformative" + - "next-level" + - "best-in-class" + - "world-class" + - "state-of-the-art" diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AISlop.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AISlop.yml new file mode 100644 index 00000000..f9804fdf --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/AISlop.yml @@ -0,0 +1,79 @@ +# AI Slop Detector - Flag common AI-generated writing patterns +# Based on: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing +# And: https://aisdr.com/blog/words-to-avoid-so-you-dont-sound-like-ai/ + +extends: existence +message: "'%s' is a common AI writing pattern. Consider more specific, human language." +level: warning +ignorecase: true +tokens: + # Red flag words (high confidence AI tells) + - delve + - delves + - delving + - tapestry + - vibrant + - multifaceted + - testament + - pivotal + - realm + - meticulous + - meticulously + - nuanced + - intricacies + - synergy + - paradigm + - holistic + - robust + - seamless + - seamlessly + + # Overused AI verbs + - illuminate + - illuminates + - illuminating + - underscore + - underscores + - underscoring + - embody + - embodies + - embodying + - transcend + - transcends + - transcending + - foster + - fosters + - fostering + - grapple + - grapples + - grappling + - espouse + - espouses + - espousing + - intertwine + - intertwines + - intertwining + - endeavor + - endeavors + - endeavour + - endeavours + + # Corporate AI speak + - leverage + - leveraging + - leverages + - utilize + - utilizing + - utilizes + - optimize + - optimizing + - optimizes + - facilitate + - facilitating + - facilitates + - streamline + - streamlining + - streamlines + - spearhead + - spearheading + - spearheads diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Adverbs.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Adverbs.yml new file mode 100644 index 00000000..eec193ae --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Adverbs.yml @@ -0,0 +1,20 @@ +extends: existence +message: "Consider cutting the adverb '%s' β€” it may be unnecessary." +level: suggestion +ignorecase: true +tokens: + - extremely + - incredibly + - absolutely + - definitely + - certainly + - completely + - totally + - entirely + - highly + - truly + - quite + - rather + - somewhat + - fairly + - slightly diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/BoldEmphasis.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/BoldEmphasis.yml new file mode 100644 index 00000000..46784819 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/BoldEmphasis.yml @@ -0,0 +1,5 @@ +extends: existence +message: "Use italics for emphasis, not bold. Bold should not be used for emphasis." +level: warning +tokens: + - '\*\*\w+\*\*' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Cliches.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Cliches.yml new file mode 100644 index 00000000..94178967 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Cliches.yml @@ -0,0 +1,34 @@ +extends: existence +message: "Avoid clichΓ©s and jargon: '%s'" +level: warning +ignorecase: true +tokens: + - at the end of the day + - low-hanging fruit + - move the needle + - circle back + - touch base + - synergy + - leverage + - paradigm shift + - think outside the box + - game changer + - disrupt + - pivot + - deep dive + - unpack + - double down + - lean in + - best practices + - value add + - bandwidth + - take it offline + - put a pin in it + - boil the ocean + - drink the Kool-Aid + - low-hanging fruit + - move the goalpost + - get granular + - actionable insights + - core competency + - value proposition diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/ClickHere.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/ClickHere.yml new file mode 100644 index 00000000..4f7f45bc --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/ClickHere.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid '%s' β€” write the sentence naturally and link relevant keywords (2-4 words)." +level: error +ignorecase: true +tokens: + - click here + - click for more + - click to + - read more here + - learn more here + - here's the link diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/CompanyPronouns.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/CompanyPronouns.yml new file mode 100644 index 00000000..08e2bbe8 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/CompanyPronouns.yml @@ -0,0 +1,17 @@ +extends: existence +message: "Refer to companies as singular ('it'), not plural ('they/them'). Use 'they' only for teams/people within companies." +level: suggestion +ignorecase: true +tokens: + - the company they + - the company their + - the company them + - the startup they + - the startup their + - the startup them + - Apple they + - Google they + - Microsoft they + - Amazon they + - Meta they + - Facebook they diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Ellipsis.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Ellipsis.yml new file mode 100644 index 00000000..c1ce455b --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Ellipsis.yml @@ -0,0 +1,6 @@ +extends: existence +message: "No space before an ellipsis, one space after. Don't use ellipsis for emphasis." +level: warning +tokens: + - ' \.\.\.' + - ' …' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/EmDash.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/EmDash.yml new file mode 100644 index 00000000..ce4313b1 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/EmDash.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Em dashes should not have spaces around them. Use 'β€”' not ' β€” ' or ' – '." +level: error +tokens: + - ' β€” ' + - ' – ' + - ' - ' + - 'β€” ' + - ' β€”' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Numbers.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Numbers.yml new file mode 100644 index 00000000..c0a2ff42 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Numbers.yml @@ -0,0 +1,13 @@ +extends: existence +message: "Spell out numbers one through nine. Use numerals for 10 and greater." +level: suggestion +tokens: + - '\b1\b' + - '\b2\b' + - '\b3\b' + - '\b4\b' + - '\b5\b' + - '\b6\b' + - '\b7\b' + - '\b8\b' + - '\b9\b' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverUnder.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverUnder.yml new file mode 100644 index 00000000..c2f1d5f4 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverUnder.yml @@ -0,0 +1,8 @@ +extends: substitution +message: "Use '%s' instead of '%s' when referring to numbers or quantities." +level: warning +ignorecase: true +swap: + 'over (\d+)': 'more than $1' + 'under (\d+)': 'fewer than $1' + 'under (\d+)': 'less than $1' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverusedWords.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverusedWords.yml new file mode 100644 index 00000000..55772770 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OverusedWords.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid overusing '%s' β€” it can almost always be deleted." +level: warning +ignorecase: true +tokens: + - actually + - very + - just + - really + - basically + - literally diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OxfordComma.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OxfordComma.yml new file mode 100644 index 00000000..69100271 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/OxfordComma.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Use the Oxford comma (serial comma) before 'and' or 'or' in a series." +level: warning +tokens: + - ', \w+ and \w+$' + - ', \w+ or \w+$' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/PassiveVoice.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/PassiveVoice.yml new file mode 100644 index 00000000..4623fb3b --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/PassiveVoice.yml @@ -0,0 +1,36 @@ +extends: existence +message: "Passive voice detected. Use active voice whenever possible: '%s'" +level: warning +ignorecase: true +tokens: + - is being + - was being + - were being + - has been + - have been + - had been + - will be + - is done + - was done + - were done + - is made + - was made + - were made + - is used + - was used + - were used + - is called + - was called + - were called + - is considered + - was considered + - were considered + - is known + - was known + - were known + - is seen + - was seen + - were seen + - is found + - was found + - were found diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Percentages.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Percentages.yml new file mode 100644 index 00000000..79103f04 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/Percentages.yml @@ -0,0 +1,7 @@ +extends: substitution +message: "Use numerals with 'percent' spelled out: '%s' instead of '%s'." +level: error +ignorecase: true +swap: + '(\d+)%': '$1 percent' + '(\d+) %': '$1 percent' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/StartWithThis.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/StartWithThis.yml new file mode 100644 index 00000000..f7286442 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/StartWithThis.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Avoid starting sentences with 'This' β€” be specific about what you're referring to." +level: warning +tokens: + - '^This ' + - '\. This ' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/WeHaveWeGet.yml b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/WeHaveWeGet.yml new file mode 100644 index 00000000..600f40db --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/Every/WeHaveWeGet.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Avoid '%s' at the start of sentences β€” say directly what is happening." +level: warning +ignorecase: true +tokens: + - '^We have ' + - '^We get ' + - '\. We have ' + - '\. We get ' diff --git a/plugins/compound-writing/skills/editing/every-style-editor/vale/README.md b/plugins/compound-writing/skills/editing/every-style-editor/vale/README.md new file mode 100644 index 00000000..6adfaaf1 --- /dev/null +++ b/plugins/compound-writing/skills/editing/every-style-editor/vale/README.md @@ -0,0 +1,106 @@ +# Every Vale Style + +Vale linting rules for Every's writing style guide. + +## Installation + +1. **Install Vale** + ```bash + # macOS + brew install vale + + # Or download from https://vale.sh/docs/vale-cli/installation/ + ``` + +2. **Copy to your project** + ```bash + # Copy the Every style to your project + cp -r vale/ /path/to/your/project/ + + # Or copy just the style + mkdir -p .vale/styles + cp -r vale/Every .vale/styles/ + cp vale/.vale.ini .vale.ini + ``` + +3. **Run Vale** + ```bash + # Check a file + vale draft.md + + # Check all markdown files + vale *.md + + # Check drafts directory + vale drafts/ + ``` + +## Rules Included + +| Rule | Level | Description | +|------|-------|-------------| +| `OverusedWords` | warning | Flags "actually", "very", "just", etc. | +| `PassiveVoice` | warning | Detects passive voice constructions | +| `EmDash` | error | Ensures no spaces around em dashes | +| `OxfordComma` | warning | Encourages Oxford comma usage | +| `ClickHere` | error | Flags "click here" link text | +| `StartWithThis` | warning | Avoids sentences starting with "This" | +| `WeHaveWeGet` | warning | Avoids "We have" / "We get" openings | +| `Cliches` | warning | Flags business jargon and clichΓ©s | +| `Percentages` | error | Enforces "X percent" not "X%" | +| `CompanyPronouns` | suggestion | Companies as "it" not "they" | +| `BoldEmphasis` | warning | Italics only, not bold for emphasis | +| `Numbers` | suggestion | Spell out 1-9, numerals for 10+ | +| `Ellipsis` | warning | No space before ellipsis | +| `OverUnder` | warning | Use "more/fewer than" not "over/under" | +| `Adverbs` | suggestion | Flags cuttable adverbs | + +## Alert Levels + +- **error**: Must fix before publishing +- **warning**: Should fix, may have exceptions +- **suggestion**: Consider fixing, style preference + +## Integration with /writing:review + +The `/writing:review` command automatically runs Vale if configured: + +```bash +# In your project, run init first +claude /writing:init + +# Vale will be run as part of review +claude /writing:review drafts/my-post/draft-v1.md +``` + +## Customizing Rules + +Edit the YAML files in `vale/Every/` to: +- Add new forbidden words to `OverusedWords.yml` +- Add industry-specific clichΓ©s to `Cliches.yml` +- Adjust severity levels (`level: error|warning|suggestion`) + +## Example Output + +``` +drafts/my-post.md + 3:15 warning Avoid overusing 'actually' β€” it Every.OverusedWords + can almost always be deleted. + 7:1 warning Avoid starting sentences with Every.StartWithThis + 'This' β€” be specific about what + you're referring to. +12:45 error Em dashes should not have spaces Every.EmDash + around them. Use 'β€”' not ' β€” ' +``` + +## CI Integration + +Add to your CI pipeline: + +```yaml +# GitHub Actions example +- name: Lint prose + run: | + brew install vale + vale --config=.vale.ini drafts/ +``` diff --git a/plugins/compound-writing/skills/voice/dhh-writing/SKILL.md b/plugins/compound-writing/skills/voice/dhh-writing/SKILL.md new file mode 100644 index 00000000..3db7059d --- /dev/null +++ b/plugins/compound-writing/skills/voice/dhh-writing/SKILL.md @@ -0,0 +1,207 @@ +--- +name: dhh-writing +description: This skill should be used when writing in the distinctive style of David Heinemeier Hansson (DHH). It applies when creating blog posts, technical articles, business content, manifestos, or any prose requiring a clear, punchy, opinionated style. +--- + +# DHH Writing Skill + +Write in the distinctive style of David Heinemeier Hanssonβ€”direct, brave, opinionated prose that takes a stand and defends it unapologetically. + +## When to Use This Skill + +This skill applies when: +- Writing opinion pieces or manifestos +- Creating blog posts that need to take a strong position +- Crafting business or product philosophy content +- Writing in a "Basecamp/37signals voice" +- Creating content that challenges conventional wisdom +- Any writing that needs to be punchy and memorable + +## Core Philosophy + +> "Strong opinions, weakly held" is half-right. You need strong opinions, *strongly expressed*. The weakness comes from being willing to change when presented with better evidenceβ€”not from hedging your delivery. + +DHH's writing is characterized by: +- **Conviction**: Every piece has a clear position +- **Courage**: Willing to say unpopular things +- **Clarity**: No corporate-speak, no hedging +- **Concision**: Short sentences, short paragraphs + +## The 10 Core Techniques + +Reference [techniques.md](./references/techniques.md) for the complete guide. + +### 1. Take a Stand + +Every piece must have a thesis you can disagree with. + +``` +❌ "There are pros and cons to remote work that teams should consider." + +βœ… "Remote work is the future. Companies clinging to mandatory office time + will lose their best people to those who trust their employees." +``` + +### 2. No Hedging + +Remove qualifiers that weaken your position. + +**Words to eliminate**: +- "I think..." (just say it) +- "In my opinion..." (obviously) +- "It seems like..." (commit) +- "Some might say..." (who?) +- "Generally speaking..." (specifically speak) + +### 3. Short Sentences + +Punch. Impact. Clarity. + +Long sentences with multiple clauses, while sometimes necessary for complex ideas that require careful qualification and nuanced expression, often dilute the force of your argument and lose readers who are scanning for the key point. + +Short sentences work better. + +They're memorable. + +They're quotable. + +They're true. + +### 4. Contrarian Framing + +Start by identifying what "everyone knows." Then challenge it. + +``` +"Everyone knows you need to move fast and break things." + +Actually, you don't. Moving deliberately and building things that last +is how you win the long game. +``` + +### 5. Concrete Over Abstract + +Don't argue about philosophies. Argue about practices. + +``` +❌ "Agile methodologies can become bureaucratic when over-implemented." + +βœ… "If your 'agile' process requires 3 meetings before a developer can + start coding, you're doing waterfall with more steps." +``` + +### 6. The Rule of Three + +Three examples. Three reasons. Three beats. + +"We don't have meetings about meetings. We don't have process for process. We don't have documentation about documentation." + +### 7. Moral Clarity + +Frame business decisions as ethical choices, not just practical ones. + +"Requiring everyone in the office isn't a productivity strategy. It's a trust issue. You either trust your people to do their jobs or you don't." + +### 8. The Callback Attack + +Reference your opponent's best argumentβ€”then demolish it. + +"Yes, in-person collaboration has value. Yes, some conversations are better face-to-face. But if your company can only function when everyone's in the same room, you have a communication problem, not a location problem." + +### 9. End Strong + +The last line should be quotable. + +Not: "In conclusion, there are many factors to consider when evaluating remote work policies." + +Instead: "The future of work is here. Catch up or get left behind." + +### 10. Personal Stakes + +Show you have skin in the game. + +"We've run Basecamp remotely for 20 years. This isn't theoryβ€”it's practice. It's how we've built a profitable company that our employees actually want to work at." + +## Voice Characteristics + +### Vocabulary +- Plain words over fancy ones +- "Use" not "leverage" +- "Try" not "attempt" +- "Build" not "construct" +- "Think" not "ideate" + +### Sentence Patterns +- Average length: 12-15 words +- Many single-clause sentences +- Questions for setup, statements for answers +- Fragments for emphasis. Like this. + +### Tone +- Confident, not arrogant +- Direct, not rude +- Opinionated, not closed-minded +- Provocative, not offensive + +## Applying the Skill + +### For Blog Posts + +Structure: +1. **Hook**: Contrarian statement that demands engagement +2. **Context**: Why this matters now +3. **Position**: Your clear stance +4. **Evidence**: Concrete examples, ideally from experience +5. **Objection handling**: Address the best counter-argument +6. **Close**: Memorable final line + +### For Product Philosophy + +- Lead with "why" not "what" +- Frame features as values +- Make comparisons to alternatives explicit +- Don't apologize for charging money + +### For Business Writing + +- No passive voice +- No committee-speak +- Name the decision-maker +- State the decision clearly + +## Common Anti-Patterns + +See [anti-patterns.md](./references/anti-patterns.md) for detailed examples. + +### The Hedge +"This might not work for everyone, but in some cases, certain teams have found that..." + +### The Both-Sides +"There are valid points on both sides of this debate..." +(Pick a side. Defend it.) + +### The Disclaimer +"Of course, this is just my personal view and others may disagree..." +(They know. Say what you mean.) + +### The Corporate +"We're excited to announce a new initiative that will drive synergy across our value proposition..." +(What are you actually doing?) + +## Quality Checklist + +Before publishing, verify: +- [ ] Clear, debatable thesis in first paragraph +- [ ] No hedge words (seems, might, some, perhaps) +- [ ] Average sentence under 15 words +- [ ] At least one contrarian framing +- [ ] Concrete examples, not abstract principles +- [ ] Personal stakes or experience shown +- [ ] Quotable closing line +- [ ] Would DHH tweet this? (Seriously, ask yourself) + +## References + +- [techniques.md](./references/techniques.md) - Full technique guide +- [examples.md](./references/examples.md) - Before/after transformations +- [anti-patterns.md](./references/anti-patterns.md) - Patterns to avoid +- [resources.md](./references/resources.md) - Source material and further reading diff --git a/plugins/compound-writing/skills/voice/dhh-writing/references/anti-patterns.md b/plugins/compound-writing/skills/voice/dhh-writing/references/anti-patterns.md new file mode 100644 index 00000000..0c8ff3f7 --- /dev/null +++ b/plugins/compound-writing/skills/voice/dhh-writing/references/anti-patterns.md @@ -0,0 +1,130 @@ +# DHH Writing Anti-Patterns + +Patterns to avoid when writing in the DHH style. + +## The Seven Deadly Sins + +### 1. The Hedge + +**The Sin**: Qualifying everything so you can't be wrong. + +**Example**: +> "In my experience, it seems like remote work might be beneficial for certain types of knowledge workers in some contexts, though individual results may vary." + +**The Fix**: Commit. Be wrong sometimes. It's better than being boring. + +> "Remote work is better. Full stop." + +**Hedge words to eliminate**: +- "It seems like..." +- "In my experience..." +- "For some people..." +- "It depends..." +- "Generally speaking..." +- "More or less..." + +### 2. The Both-Sides + +**The Sin**: Presenting every argument as having two equally valid perspectives. + +**Example**: +> "There are compelling arguments both for and against the traditional office environment. Some prefer the structure and social interaction, while others value the flexibility of remote work. Ultimately, each organization must find the approach that works best for their unique context." + +**The Fix**: Pick a side. The reader came for your opinion. + +> "Offices are obsolete. The companies that don't realize this will lose their best people to the ones that do." + +### 3. The Disclaimer + +**The Sin**: Pre-emptively apologizing for your position. + +**Example**: +> "This is just my personal opinion, and I understand others may see it differently. I'm not saying my way is the only way, and of course your mileage may vary. That said, I think..." + +**The Fix**: Everyone knows it's your opinion. It's your blog. Say what you mean. + +### 4. The Corporate + +**The Sin**: Using business-speak that means nothing. + +**Examples**: +- "Synergize our value proposition" +- "Leverage our core competencies" +- "Drive alignment across stakeholders" +- "Enable a best-in-class customer experience" +- "Optimize our go-to-market strategy" + +**The Fix**: Say what you're actually doing. + +| Corporate | Human | +|-----------|-------| +| "Synergize" | "Combine" or "Work together" | +| "Leverage" | "Use" | +| "Stakeholders" | "People involved" or name them | +| "Core competencies" | "What we're good at" | +| "Value proposition" | "Why you should buy this" | + +### 5. The Summary + +**The Sin**: Ending with a recap no one asked for. + +**Example**: +> "In conclusion, we have examined the various aspects of remote work, including its benefits such as flexibility and productivity, its challenges including communication and isolation, and strategies for successful implementation. As we have seen, there are many factors to consider when making this important decision." + +**The Fix**: Your last line should add something new. Make it quotable. + +> "The office is dead. Start acting like it." + +### 6. The Question Cop-Out + +**The Sin**: Ending with a question instead of a position. + +**Example**: +> "So what do you think? Is remote work right for your organization? Sound off in the comments!" + +**The Fix**: Answer your own questions. That's why readers came. + +> "Is remote work right for your organization? Yes. Next question." + +### 7. The Passive Epidemic + +**The Sin**: Hiding actors and decisions behind passive constructions. + +**Examples**: +- "It was decided that..." +- "Mistakes were made..." +- "The policy was implemented..." +- "It is believed that..." + +**The Fix**: Name the actor. Take responsibility. + +| Passive | Active | +|---------|--------| +| "It was decided that we would go remote" | "We decided to go remote" | +| "Mistakes were made" | "I made mistakes" | +| "The policy was implemented" | "We implemented the policy" | +| "It is believed that..." | "I believe..." or "Research shows..." | + +## Quick Reference: Warning Signs + +Your writing has slipped if you find: + +| Warning Sign | Probable Sin | +|--------------|--------------| +| First paragraph has no thesis | The Hedge or Both-Sides | +| "I could be wrong, but..." | The Disclaimer | +| Three or more buzzwords | The Corporate | +| "In conclusion..." | The Summary | +| "What do you think?" ending | The Question Cop-Out | +| "It was" or "There are" | The Passive Epidemic | +| Every sentence over 20 words | All of the above | + +## The DHH Test + +Before publishing, ask: + +1. **Would you bet money on this?** If not, strengthen your position. +2. **Could someone disagree?** If not, you haven't said anything. +3. **Is the last line tweetable?** If not, rewrite it. +4. **Did you use "synergy" unironically?** Delete it. +5. **Would DHH actually publish this?** Be honest with yourself. diff --git a/plugins/compound-writing/skills/voice/dhh-writing/references/examples.md b/plugins/compound-writing/skills/voice/dhh-writing/references/examples.md new file mode 100644 index 00000000..71bed75e --- /dev/null +++ b/plugins/compound-writing/skills/voice/dhh-writing/references/examples.md @@ -0,0 +1,140 @@ +# DHH Writing Examples + +Before/after transformations showing the style in action. + +## Example 1: Remote Work + +### Before (Corporate) + +> At our organization, we have implemented a flexible work arrangement policy that enables team members to work from locations outside the traditional office environment when appropriate and aligned with business needs. We believe this approach supports employee well-being while maintaining operational effectiveness. + +### After (DHH Style) + +> **We work remotely. Period.** +> +> Not "hybrid." Not "flexible when business needs allow." Remotely. +> +> We've done it for 20 years. Through growth, through recessions, through a pandemic. Our team lives in 32 cities across 8 time zones. +> +> The secret? Trust your people. If you hired adults, treat them like adults. +> +> "But what about collaboration?" We collaborate fine. "But what about culture?" Our culture is stronger than most offices. "But what aboutβ€”" Stop. +> +> The excuses are endless. The results speak for themselves. + +## Example 2: Meetings + +### Before (Typical) + +> While meetings are an important tool for organizational alignment and cross-functional collaboration, we've found that optimizing meeting cadence and implementing meeting-free focus time can significantly improve individual contributor productivity. We recommend that teams evaluate their current meeting load and consider whether all recurring meetings continue to add value. + +### After (DHH Style) + +> **Most meetings are a waste of time.** +> +> Not some meetings. Most. +> +> "But we need to align!" Write it down. +> +> "But I need to get buy-in!" Ask via email. +> +> "But decisions are faster in person!" Are they? Or do you just feel busier? +> +> Here's our meeting policy: Don't have one unless you absolutely must. No recurring meetings by default. Every meeting needs an agenda and an end time. +> +> The best meetings are the ones that never happen. + +## Example 3: Hiring + +### Before (HR-Speak) + +> Our talent acquisition strategy focuses on identifying candidates who demonstrate strong cultural fit while possessing the technical competencies required for role success. We utilize a comprehensive evaluation process including behavioral interviews, technical assessments, and reference verification to ensure alignment with organizational values and capabilities. + +### After (DHH Style) + +> **Stop hiring for "culture fit."** +> +> You know what "culture fit" usually means? "I'd want to get beer with this person." That's not hiring. That's cloning. +> +> We hire for work. Can you do the job? Can you work with others? Can you communicate clearly in writing? That's it. +> +> Your hobbies don't matter. Your pedigree doesn't matter. Stanford? Community college? Self-taught? We don't care. Show us your work. +> +> The best teams aren't full of people who look alike, think alike, or hang out together. They're full of people who do great work. Hire for that. + +## Example 4: Pricing + +### Before (Startup-Speak) + +> We're excited to announce our new pricing tiers, designed to provide options for organizations of all sizes. Our freemium model allows teams to experience our platform's value before committing, while our enterprise tier delivers advanced functionality for larger deployments. + +### After (DHH Style) + +> **We don't do free. We don't do enterprise.** +> +> One price. For everyone. $99/month. Done. +> +> "But what about small teams?" $99. +> +> "But what about big companies?" $99. +> +> "But what aboutβ€”" $99. +> +> Why? Because software should work for everyone the same way. Big company features aren't special. They're usually just complexity. And free tiers mean someone else is payingβ€”usually with their data. +> +> We sell software. You pay money. We make it good. Simple. + +## Example 5: Process + +### Before (Agile Speak) + +> Our development methodology incorporates agile principles with adaptations tailored to our organizational context. We utilize two-week sprints, daily standups, and regular retrospectives to maintain alignment and continuous improvement. Story pointing and velocity tracking enable predictable delivery cadence. + +### After (DHH Style) + +> **We don't do sprints. We do work.** +> +> No story points. No velocity tracking. No burndown charts. +> +> "But how do you know if you're on track?" We look at the work. Is it getting better? Are customers happier? Are we shipping? +> +> All that agile ceremony? It's a comfort blanket. It makes managers feel like they're managing. But you can't sprint your way to quality. You can't retro your way to good decisions. +> +> Here's our process: Figure out what matters. Do it. Ship it. Repeat. +> +> Revolutionary, I know. + +## Example 6: Technology Choices + +### Before (Tech Blog) + +> When evaluating technology stack decisions, it's important to consider factors such as scalability, maintainability, talent availability, and alignment with organizational capabilities. While newer technologies may offer compelling features, mature solutions often provide better long-term stability and support ecosystems. + +### After (DHH Style) + +> **Choose boring technology.** +> +> That shiny new framework? Skip it. +> +> Rails shipped 20 years ago. Postgres has been around since Reagan. They work. They're boring. That's the point. +> +> Every new technology is a risk. You're betting that: +> 1. It'll still be maintained in 5 years +> 2. You can hire people who know it +> 3. The bugs have been found +> +> Boring technology has passed those tests. The new hotness hasn't. +> +> We still use Rails. We'll probably still use it in 2034. Innovation is overrated. Reliability isn't. + +## The Transformation Checklist + +When rewriting corporate content in DHH style: + +1. **Cut the first paragraph** - The point usually starts in paragraph 2 +2. **Remove all hedge words** - Find/replace for "might," "some," "generally" +3. **Shorten every sentence** - Target 15 words max +4. **Add a contrarian frame** - What does everyone assume? Challenge it +5. **End with a punch** - Quotable, memorable, shareable +6. **Make it personal** - What's your actual experience? +7. **Pick a side** - No "on the other hand" diff --git a/plugins/compound-writing/skills/voice/dhh-writing/references/resources.md b/plugins/compound-writing/skills/voice/dhh-writing/references/resources.md new file mode 100644 index 00000000..0aaaada0 --- /dev/null +++ b/plugins/compound-writing/skills/voice/dhh-writing/references/resources.md @@ -0,0 +1,130 @@ +# DHH Writing Resources + +Source material and further reading for mastering the style. + +## Primary Sources + +### DHH's Blog (world.hey.com/dhh) + +Essential posts that define the style: + +**On Remote Work**: +- "Remote work is the future" (2020) +- "The presence prison" (2021) +- "Escape the hustle" (2022) + +**On Product Philosophy**: +- "On writing software well" (series) +- "The Majestic Monolith" (2016) +- "Reconsider" (2015) + +**On Business**: +- "It's always a good time to lower prices" (2023) +- "Why we don't negotiate salaries" (2019) + +### Books + +**REWORK** (2010) +Co-authored with Jason Fried. The manifesto for small business. +- Short chapters (2-3 pages each) +- Contrarian takes on common business advice +- Punchy, declarative style + +**Remote: Office Not Required** (2013) +The case for remote work before it was cool. + +**It Doesn't Have to Be Crazy at Work** (2018) +Against the hustle culture. + +**Shape Up** (free online) +Basecamp's development methodologyβ€”and a masterclass in clear technical writing. + +## Style Elements to Study + +### Sentence Structure + +DHH's typical patterns: + +**The Declaration**: +> "We don't have meetings." + +**The Three-Beat**: +> "Build less. Charge more. Sleep better." + +**The Reversal**: +> "Move fast and break things? How about move deliberately and build things that last?" + +**The Question-Answer**: +> "What's the best meeting? The one you don't have." + +### Paragraph Structure + +Most DHH paragraphs follow: +1. Bold claim (1 sentence) +2. Brief elaboration (1-2 sentences) +3. Concrete example or evidence (1-2 sentences) + +Total: 3-4 sentences max. Often 1-2. + +### Post Structure + +Typical DHH blog post: +1. **Hook**: Contrarian statement or strong opinion +2. **Context**: Why this matters now (brief) +3. **Thesis**: Clear statement of position +4. **Evidence**: Experience-based examples +5. **Objection handling**: Address counter-arguments +6. **Close**: Quotable conclusion + +Word count: Usually 300-800 words. Rarely over 1000. + +## Contrast Study + +Understanding DHH's style by contrasting with others: + +| Writer | Style | DHH Difference | +|--------|-------|----------------| +| Paul Graham | Exploratory, building arguments | DHH arrives at conclusions faster | +| Seth Godin | Metaphorical, inspirational | DHH is more concrete, less abstract | +| Hacker News | Technical, qualified | DHH is opinionated, unhedged | +| Corporate blogs | Safe, buzzword-heavy | DHH is risky, plain-spoken | + +## Practice Exercises + +### Exercise 1: The Conversion +Take a corporate announcement and rewrite it in DHH style. +- Cut word count by 60% +- Remove all hedge words +- Add a contrarian frame +- End with a strong line + +### Exercise 2: The Thesis Test +Write 10 thesis statements. For each one, ask: "Could someone disagree?" If everyone would agree, it's too weak. + +### Exercise 3: The Sentence Diet +Take a paragraph you've written. Target 12 words per sentence. Cut everything that doesn't need to be there. + +### Exercise 4: The Callback +Write a blog post that opens with a question and ends by answering it decisively. The last line should be quotable. + +## Quotes to Remember + +> "I'm not particularly prescient. I just have a low tolerance for bullshit." + +> "Startups don't die from running out of money. They die from running out of time." + +> "The best way to predict the future is to build it. But only if you actually ship." + +> "Meetings are toxic. They chop up the day into small bits." + +> "Simple is good. Good is simple. Don't mistake complication for sophistication." + +## Warning + +The DHH style is powerful but risky: +- It's easy to be contrarian without being insightful +- Strong opinions require strong evidence +- Punchy doesn't mean aggressive +- The goal is clarity, not controversy + +The best DHH-style writing is brave, not reckless. It takes positions because they're true, not because they're provocative. diff --git a/plugins/compound-writing/skills/voice/dhh-writing/references/techniques.md b/plugins/compound-writing/skills/voice/dhh-writing/references/techniques.md new file mode 100644 index 00000000..4aab8cd6 --- /dev/null +++ b/plugins/compound-writing/skills/voice/dhh-writing/references/techniques.md @@ -0,0 +1,249 @@ +# DHH Writing Techniques + +Extended guide to the 10 core techniques with detailed examples. + +## 1. Take a Stand + +### The Principle + +Every piece needs a thesis statement that someone could reasonably disagree with. If everyone agrees, you haven't said anything. + +### Examples + +**Weak thesis**: +> "Code quality is important for long-term project success." + +Who disagrees? No one. This is filler. + +**Strong thesis**: +> "TDD is dead. Long live testing." + +**Weak thesis**: +> "Companies should consider the benefits of work-life balance." + +**Strong thesis**: +> "If your startup requires 80-hour weeks, you've failed at planning. Crunch is management failure, not dedication." + +### How to Find Your Thesis + +1. What do you believe that your peers would argue against? +2. What "best practice" have you seen fail? +3. What worked for you that the experts said wouldn't? +4. What pisses you off about your industry? + +## 2. No Hedging + +### Words to Eliminate + +| Hedge | Replacement | +|-------|-------------| +| "I think" | [just state it] | +| "In my opinion" | [obviously your opinion] | +| "It seems like" | "It is" or "I've seen" | +| "Some might say" | "Critics say" or cut it | +| "Generally speaking" | "Usually" or be specific | +| "Basically" | [delete] | +| "Kind of" | [delete or be specific] | +| "Sort of" | [delete or be specific] | +| "Perhaps" | "Maybe" or commit | +| "Might" | "Will" or "Could" | + +### Before/After + +**Before**: +> "I think that, in my experience, remote work seems to generally improve productivity for some knowledge workers, at least in certain contexts." + +**After**: +> "Remote work improves productivity. We've seen it at Basecamp for two decades." + +## 3. Short Sentences + +### The 15-Word Rule + +Target average sentence length of 12-15 words. Vary for rhythm. + +### Techniques + +**Break up compound sentences**: + +Before: +> "We believe that great software should be beautiful and functional, and that the best products come from small teams who care deeply about what they're building." + +After: +> "Great software should be beautiful. It should be functional. The best products come from small teams. Teams who care about their work." + +**Use fragments for emphasis**: + +> "Remote work isn't the future. It's the present. Wake up." + +**One idea per sentence**: + +Before: +> "While there are certainly benefits to the traditional office environment, including spontaneous collaboration and the building of company culture, we've found that these can be replicated and even improved upon in a remote setting." + +After: +> "Offices have benefits. Spontaneous collaboration. Culture building. But all of these work remotely too. Sometimes better." + +## 4. Contrarian Framing + +### The Pattern + +1. State what "everyone knows" +2. Signal your disagreement +3. State your actual position +4. Support it + +### Examples + +**Tech Industry Contrarian**: +> "Move fast and break things." That was Facebook's motto. +> +> It's wrong. +> +> Move deliberately. Build things that last. Speed without durability is just churn. + +**Business Contrarian**: +> "The customer is always right." +> +> No, they're not. +> +> Some customers are wrong for your business. Some requests would make your product worse. Know when to say no. + +**Management Contrarian**: +> "Hire slow, fire fast." +> +> We don't. +> +> Fire slow. Give people a real chance. If you hired them, you owe them genuine effort before giving up. + +## 5. Concrete Over Abstract + +### The Test + +Can someone take action based on what you wrote? If not, it's too abstract. + +### Before/After + +**Abstract**: +> "We believe in empowering our team members to achieve work-life integration through flexible policies." + +**Concrete**: +> "Everyone gets Fridays off in summer. No questions. No make-up work. Just a three-day weekend." + +**Abstract**: +> "Our compensation philosophy centers on providing competitive market-rate salaries." + +**Concrete**: +> "We pay San Francisco rates to everyone, regardless of where they live. A senior developer makes $180k whether they're in SF or Tulsa." + +## 6. The Rule of Three + +### Why Three? + +- One is a statement +- Two is a comparison +- Three is a pattern + +### Examples + +> "We don't do unlimited vacation. We don't do open offices. We don't do always-on Slack." + +> "Build less. Charge more. Sleep well." + +> "Good software takes time. It takes focus. It takes saying no." + +### Pattern Variations + +**Three beats, escalating**: +> "First, they ignore you. Then, they laugh at you. Then, you win." + +**Three beats, parallel**: +> "We write to think. We write to teach. We write to learn." + +**Three beats, reversal**: +> "More isn't better. Better is better. Often, less is better." + +## 7. Moral Clarity + +### Reframe Business as Ethics + +Business decisions are often presented as purely practical. DHH reframes them as ethical choices. + +**Practical framing**: +> "We found that remote work improved our productivity metrics." + +**Ethical framing**: +> "Requiring people to commute two hours a day so managers can see butts in seats isn't a productivity strategy. It's a values statement. You're saying your need for control matters more than their time." + +### Examples + +**On Pricing**: +> "Race to the bottom pricing isn't just bad business. It's disrespectful to your employees. If you can't charge enough to pay well, you're subsidizing your customers with your team's labor." + +**On Hiring**: +> "Hiring only from 'top schools' isn't just ineffective. It's lazy credentialism that perpetuates inequality while pretending to be merit-based." + +## 8. The Callback Attack + +### The Pattern + +1. Acknowledge the strongest counter-argument +2. Show you understand it +3. Explain why it's still wrong + +### Examples + +**Remote Work**: +> "Yes, some conversations are better in person. Yes, whiteboarding has value. Yes, lunch together builds bonds. +> +> But if your company *requires* these things to function, you have a communication problem. You've built a culture that only works under ideal conditions. Real work happens in the gaps." + +**Agile Criticism**: +> "Yes, agile was better than waterfall. Yes, iterating is better than big design up front. Yes, talking to customers matters. +> +> But somewhere we lost the plot. Two-week sprints became mandatory. Velocity became a metric. Retros became rituals. The manifesto that rejected process became... process." + +## 9. End Strong + +### The Test + +Could your last line be a tweet? Could it be a book title? Could someone quote it? + +### Techniques + +**The Declaration**: +> "Remote is not the future of work. It's the present. Everyone else is just catching up." + +**The Challenge**: +> "Stop asking for permission. Start building what matters." + +**The Reversal**: +> "The best meetings are the ones you don't have." + +**The Warning**: +> "The companies that don't adapt won't disappear. They'll just slowly become irrelevant." + +### Anti-Patterns + +Don't end with: +- Summaries ("In conclusion...") +- Hedges ("But of course, this is just one perspective...") +- Questions without answers ("What do you think?") +- Calls to comment ("Let me know in the comments!") + +## 10. Personal Stakes + +### Show Skin in the Game + +Readers trust advice more when you've taken the risk. + +### Examples + +**Experience-based**: +> "This isn't theory. We've run Basecamp remotely for 20 years, through two recessions and a pandemic. It works." + +**Admission-based**: +> "I know this because I used to be wrong. We used to have an office. We used to think face time mattered. We were idiots." + +**Risk-based**: +> "We turned down $100 million in funding to keep the company ours. Was it the right call? Ask me in another decade." diff --git a/plugins/compound-writing/skills/voice/every-essay-guide/SKILL.md b/plugins/compound-writing/skills/voice/every-essay-guide/SKILL.md new file mode 100644 index 00000000..32e17bb9 --- /dev/null +++ b/plugins/compound-writing/skills/voice/every-essay-guide/SKILL.md @@ -0,0 +1,216 @@ +--- +name: every-essay-guide +description: This skill should be used when writing essays for Every publication. It provides the worldview, tonal DNA, craft principles, and playbooks that define Every's distinctive voice - optimistic realism, personal narrative with intellectual rigor, and practical frameworks that move readers forward. +--- + +# Every Essay Guide + +Writing is Every's R&D lab, marketing funnel, and cultural glue. Essays do double duty: they satisfy readers' curiosity today and prototype the businesses we'll build tomorrow. This skill captures the craft principles that turn sparks of insight into pieces that inform, delight, and create momentum. + +## When to Use This Skill + +Use this skill when: +- Planning or drafting essays for Every publication +- Applying Every's distinctive voice and worldview +- Crafting headlines, deks, and opening paragraphs +- Running pre-share quality checks before submitting +- Understanding what makes Every essays resonate + +## Every's Core Promise + +**Optimistic, intellectually generous writing that moves readers and moves the company forward.** + +--- + +## Part 1: What Makes an Every Essay + +### 1. Optimistic Realism About AI and Work + +| Principle | Application | +|-----------|-------------| +| **Practical optimism** | AI is treated as an enabling forceβ€”but never a silver bullet. Celebrate possibilities while naming risks. | +| **From knowledge to allocation** | Track the macro-shift: raw knowledge matters less than the judgment to wield AI-generated intelligence. | +| **Rise of the generalist** | Champion adaptable people who synthesize across domains and thrive in "wicked" environmentsβ€”work that remains stubbornly human. | + +### 2. Personal Narrative Γ— Intellectual Rigor + +| Principle | Application | +|-----------|-------------| +| **Intellectual accessibility** | Translate dense economic or philosophical ideas into plain, lively language. | +| **Narrative-driven argument** | A vivid anecdote or scene pulls readers in before zooming to universal insight. | +| **Authenticity and vulnerability** | Disclose a personal stakeβ€”mental health, career pivots, creative doubtsβ€”to make abstract forces visceral. | + +### 3. Rethinking Creativity and Entrepreneurship + +| Principle | Application | +|-----------|-------------| +| **Writing as product R&D** | Essays seed software, courses, and consultingβ€”proving ideas in public before building. | +| **Audience-first business model** | Subscriptions and spin-off services fund exploration, aligning incentives with reader trust rather than VC timelines. | +| **Constant experimentation** | Pivot quickly with algorithm shifts, AI advances, and new formatsβ€”treating agility as a craft. | + +### 4. Practical Optimism & Generous Intellectualism + +| Principle | Application | +|-----------|-------------| +| **Constructive, not contrarian** | Critique, then propose frameworks, metaphors, or playbooks that move the conversation forward. | +| **Open-ended curiosity** | Pose genuine questions and invite readers into the search, resisting dogma. | + +### 5. Interconnected, Recursive Thinking + +Ideas recur and evolve ("allocation economy," "vibe coding"), weaving a self-referential, cumulative universe that rewards long-time readers. + +--- + +## Part 2: Every Writing Best Practices + +Ten craft principles that keep essays sharp, honest, and actionable: + +### 1. Hook & Purpose +Lead with tension; state the promise fast. The reader should feel the problem and crave the answer within two sentences. + +### 2. Structure & Flow +Each section answers the question you just posed. Clear progression, no wandering. + +### 3. Depth Over Breadth +Fewer ideas, interrogated harder. Own one thing completely rather than touching many things lightly. + +### 4. Facts Before Feelings +Evidence first, emotion second. Ground claims in data, examples, or expert voices before making emotional appeals. + +### 5. Concrete, Sensory Writing +Make abstractions photographable. Can you film the nouns and verbs? + +**Weak:** "The company grew quickly." +**Strong:** "Headcount jumped from 12 to 47 in six months." + +### 6. Confident, Nuanced Claims +Assert boldly, qualify intelligently. Own your perspective while acknowledging complexity. + +### 7. Rhythm & Voice +Vary sentence length; surface your stake early. Read aloudβ€”does it have music? + +### 8. Dialogue & Interiority +Trim dialogue tags; earn emotional beats. Show thought in action. + +### 9. One-and-Done Statements +No echoing. Say it once, say it best. If you've made the point, move on. + +### 10. Payoff & Practicality +End with actions, frameworks, or reframed vision. The reader leaves able to do, see differently, or quote something. + +--- + +## Part 3: Hed / Dek / Opening Paragraph Playbook + +A great Every piece wins or loses readers in the first 150 words. Use this three-step method: + +### Step 1: Find the Spark + +1. Speed-read your draft; stop where your own heartbeat jumps. +2. The sentence that startles youβ€”that's the core idea. Highlight it. + +### Step 2: Put the Spark on Top + +#### Hed (Headline) +State the idea in its punchiest, most concrete form. Avoid abstractions; invoke stakes. + +| Weak | Stronger | +|------|----------| +| "Redesign Everything for AI" | "Redesign the Web for a Billion AI Agents" | +| "How to Be More Productive" | "The 90-Minute Rule That Saved My Startup" | + +#### Dek (Sub-headline) +Sharpen the promiseβ€”who benefits, what's at stake, why now. Keep it one crisp line. + +> "There's a fortune to be made if you can build interfaces AI can read." + +#### Opening Paragraph + +1. **Meet the reader where they are.** Pose or restate the question your hed opened. +2. **Set the stakes.** Make the problem visceral (money, time, reputation, existential dread). +3. **Establish credibility.** One line on why you can guide them. +4. **Promise the payoff.** What will they know or be able to do by the end? + +### Step 3: Stress-Test Before Shipping + +- [ ] Would a skim-reader feel the problem and crave the answer after two sentences? +- [ ] Is the hed specific enough that someone could argue with it? (If not, get sharper.) +- [ ] Could the dek double as a tweet people might quote? + +--- + +## Part 4: Pre-Share Checklist + +Eight quick scans that catch 90% of problems before editors do: + +| Check | Question | +|-------|----------| +| **Promise check** | Does the opener state the tension and hint at payoff? | +| **Evidence check** | Are bold claims supported by data, examples, or experts? | +| **Camera check** | Can you film the nouns and verbs? | +| **Hedge check** | Delete unnecessary qualifiers. | +| **Music check** | Read aloud; vary the beat. | +| **POV check** | Is your stake visible by word 150? | +| **Transition check** | Does each section answer "why now?" | +| **Payoff check** | Will the reader leave able to do, see differently, or quote something? | + +--- + +## Summary: Takeaways for Writers + +1. **Blend personal + universal.** Start from lived experience; expand to cultural or economic stakes. + +2. **Maintain practical optimism.** Critique tech responsibly, but spotlight creative possibilities. + +3. **Celebrate synthesis.** Show how cross-domain thinking beats narrow specialization. + +4. **Stay accessible.** Explain big theories in everyday language and examples. + +5. **Move with the internet.** Iterate, experiment, update. Curiosity is a workflow, not a one-off. + +--- + +## Integration with Other Skills + +| Skill | Relationship | +|-------|--------------| +| `every-style-editor` | Use AFTER drafting to check grammar, punctuation, and mechanical style guide compliance | +| `writing-orchestration` | Use the 10 baseline strategies alongside these Every-specific principles | +| `pragmatic-writing` | Every's voice shares Hunt/Thomas accessibilityβ€”combine for technical topics | + +--- + +## Quick Reference Card + +``` +EVERY ESSAY DNA +=============== +Optimistic realism about AI + work +Personal narrative Γ— intellectual rigor +Writing as product R&D +Constructive, not contrarian +Recursive, interconnected ideas + +CRAFT CHECKLIST +=============== +β–‘ Hook with tension, promise fast +β–‘ Depth > breadth +β–‘ Facts before feelings +β–‘ Concrete, filmable language +β–‘ Confident + nuanced claims +β–‘ Varied rhythm, audible voice +β–‘ No echoingβ€”one-and-done +β–‘ End with actionable payoff + +HED / DEK / OPENER +================== +1. Find the spark (heartbeat jump) +2. Put spark on top (hed = punchiest form) +3. Dek = one crisp promise line +4. Opener: stakes β†’ credibility β†’ payoff + +PRE-SHARE SCANS +=============== +Promise | Evidence | Camera | Hedge +Music | POV by 150 | Transitions | Payoff +``` diff --git a/plugins/compound-writing/skills/voice/pragmatic-writing/SKILL.md b/plugins/compound-writing/skills/voice/pragmatic-writing/SKILL.md new file mode 100644 index 00000000..be4b09f6 --- /dev/null +++ b/plugins/compound-writing/skills/voice/pragmatic-writing/SKILL.md @@ -0,0 +1,189 @@ +--- +name: pragmatic-writing +description: This skill should be used when writing technical content in the style of Hunt/Thomas (The Pragmatic Programmer) and Joel Spolsky (Joel on Software). It applies when creating technical essays, documentation, tutorials, or explanatory content that needs to be clear, engaging, and actionable. +--- + +# Pragmatic Writing Skill + +Writing style modeled on the masters of technical communication: Andy Hunt, Dave Thomas (The Pragmatic Programmer), and Joel Spolsky (Joel on Software). This skill transforms technical content into engaging, memorable prose. + +## When to Use This Skill + +This skill applies when: +- Creating technical blog posts, essays, or articles +- Writing documentation that needs personality +- Explaining complex concepts to developers +- Crafting tutorials or how-to guides +- Writing "lessons learned" or postmortem content +- Any technical writing that should be read, not just referenced + +## Core Philosophy + +> "The difference between 'almost right' and 'right' is the difference between the lightning bug and the lightning." β€” Mark Twain (quoted by Pragmatic Programmers) + +Technical writing doesn't have to be dry. The best technical writers make complex ideas feel obvious, use concrete examples before abstract theory, and treat the reader as a smart colleague. + +## The 10 Core Techniques + +Reference the complete technique guide at [techniques.md](./references/techniques.md). + +### 1. Concrete Before Abstract + +**Always** start with a concrete example, then extract the principle. + +``` +❌ "Dependency injection is a design pattern where dependencies are passed + to objects rather than created by them." + +βœ… "Imagine your class needs a database connection. You could create it + yourself: + + def initialize + @db = Database.new("localhost:5432") + end + + But now your class is stuck with that exact database. What if you + want to test with a fake one? What if production uses a different host? + + Instead, accept it as a parameter: + + def initialize(db) + @db = db + end + + That's dependency injection. Simple." +``` + +### 2. Physical Analogies + +Map abstract concepts to physical experiences readers already understand. + +See [examples.md](./references/examples.md) for analogy patterns: +- Software abstractions β†’ Physical tools +- Code patterns β†’ Architectural patterns +- System design β†’ Everyday systems (postal service, restaurants) + +### 3. Conversational Register + +Write like you're explaining to a smart colleague at a whiteboard. + +**Markers of conversational register:** +- Contractions (don't, won't, can't) +- Direct address (you, your) +- Questions (But what if...? Why does this matter?) +- Asides (By the way, Incidentally) +- Admissions (To be honest, I'm not sure, It depends) + +### 4. Humor as Architecture + +Use humor strategically, not decoratively: +- Memorable hooks ("Good code is its own best documentation") +- Tension release after complex explanations +- Self-deprecation to build rapport +- Absurdist examples to highlight bad patterns + +### 5. The "Aha!" Structure + +Build to moments of realization: +1. Present a familiar problem +2. Show the common (flawed) approach +3. Reveal why it fails +4. Present the insight +5. Show the better way +6. Connect back to the principle + +### 6. Short Paragraphs, Varied Length + +- No paragraph over 4 sentences +- Alternate between longer explanations and punchy one-liners +- Use single-sentence paragraphs for emphasis + +Like this. + +### 7. Code as Evidence + +Code examples should: +- Be runnable (no pseudo-code unless necessary) +- Be minimal (show only what matters) +- Progress from broken to fixed +- Include comments only for non-obvious things + +### 8. The Principle Box + +After a concrete exploration, box the principle: + +> **Tip 23: Always Design for Concurrency** +> Allow for concurrency, and you will design cleaner interfaces with fewer assumptions. + +### 9. Friendly Warnings + +When discussing pitfalls: +- Acknowledge you've made the mistake too +- Explain why it's tempting +- Show the consequences +- Provide the escape hatch + +See [anti-patterns.md](./references/anti-patterns.md) for common technical writing mistakes. + +### 10. The Callback + +End by connecting back to the opening example or question. Close the loop. + +## Voice Characteristics + +### Sentence Patterns +- Average length: 15-20 words +- Mix of simple, compound, complex +- Questions every 3-4 paragraphs +- Direct statements for key points + +### Vocabulary +**Use**: specific, concrete, everyday words +**Avoid**: jargon without explanation, buzzwords, corporate-speak + +### Tone +- Confident but not arrogant +- Curious and exploratory +- Practical and results-focused +- Occasionally irreverent + +## Applying the Skill + +### For Blog Posts +1. Open with a problem or scenario +2. Explore the messy middle +3. Reveal the insight +4. Show the solution +5. Extract the principle +6. Callback to opening + +### For Documentation +1. Start with what the reader wants to do +2. Show the simplest working example +3. Expand with options and edge cases +4. Explain the "why" after the "how" + +### For Tutorials +1. State the goal clearly +2. Show the end result first +3. Build up in small, testable steps +4. Explain mistakes, not just successes + +## Quality Checklist + +Before publishing, verify: +- [ ] Opens with concrete example or scenario +- [ ] Physical analogy for key concepts +- [ ] Conversational tone throughout +- [ ] At least one moment of humor or levity +- [ ] Principles boxed or highlighted +- [ ] Code examples are minimal and runnable +- [ ] Paragraphs under 4 sentences +- [ ] Callbacks to opening + +## References + +- [techniques.md](./references/techniques.md) - Full technique guide with examples +- [examples.md](./references/examples.md) - Before/after transformations +- [anti-patterns.md](./references/anti-patterns.md) - Seven deadly sins of technical writing +- [sources.md](./references/sources.md) - Original source material diff --git a/plugins/compound-writing/skills/voice/pragmatic-writing/references/anti-patterns.md b/plugins/compound-writing/skills/voice/pragmatic-writing/references/anti-patterns.md new file mode 100644 index 00000000..80790dc9 --- /dev/null +++ b/plugins/compound-writing/skills/voice/pragmatic-writing/references/anti-patterns.md @@ -0,0 +1,169 @@ +# Seven Deadly Sins of Technical Writing + +Anti-patterns to avoid, with examples and fixes. + +## 1. The Abstract Opening + +Starting with definitions instead of examples. + +### The Sin + +> "Dependency injection is a design pattern in software engineering whereby one object supplies the dependencies of another object." + +The reader's eyes glaze over before they understand why they should care. + +### The Fix + +Start with a problem they recognize: + +> "Your tests are slow because every test spins up a real database connection. Let's fix that." + +Then show the solution. *Then* name the pattern. + +## 2. The Wall of Text + +Paragraphs that go on and on, packing multiple ideas into dense blocks of text that require re-reading to understand, without any visual breaks to help the reader parse the information or take a breath between concepts. + +### The Sin + +The paragraph above. Did you read it? Or did you skim? + +### The Fix + +One idea per paragraph. + +Short paragraphs are easier to scan. + +They create rhythm. + +And they emphasize key points. + +Like this one. + +## 3. The Passive Epidemic + +### The Sin + +> "The configuration file is read by the application when it is started. The values are validated and errors are logged if issues are found. The settings are then cached for performance." + +Who's doing what? It's unclear. It's boring. It sounds like a legal document. + +### The Fix + +> "When your app starts, it reads the configuration file. It validates each value and logs any errors. Then it caches the settings so future reads are instant." + +Active voice. Clear actors. Engaging rhythm. + +## 4. The Jargon Dump + +### The Sin + +> "Leverage the microservice architecture's eventual consistency model to optimize throughput while maintaining idempotency across distributed transactions." + +This might be technically accurate. It's also unreadable. + +### The Fix + +Either: +1. Define terms on first use +2. Use simpler words +3. Show an example first + +> "When you split your app into services, they can't share a database. So Service A might update before Service B knows about it. Here's how to handle that gap..." + +## 5. The Code Novel + +### The Sin + +```ruby +# This is a comprehensive example demonstrating the full implementation +# of a user authentication service including all edge cases, error +# handling, logging, caching, and rate limiting functionality. + +class AuthenticationService + RATE_LIMIT = 100 + CACHE_TTL = 3600 + + def initialize(user_repository, token_service, cache, logger, rate_limiter) + @user_repository = user_repository + @token_service = token_service + @cache = cache + @logger = logger + @rate_limiter = rate_limiter + end + + # ... 100 more lines ... +end +``` + +By line 20, the reader has forgotten what point you were making. + +### The Fix + +Show only what's necessary for the current point: + +```ruby +class AuthenticationService + def initialize(user_repository) + @users = user_repository # Injected, not created + end +end +``` + +Then say: "We'll add caching and rate limiting in the next section." + +## 6. The Disclaimer Flood + +### The Sin + +> "While there are many approaches to this problem, and your mileage may vary depending on your specific circumstances, and this isn't intended as professional advice, and you should consult your team lead before implementing, one possible approach that might work in some cases is..." + +By the time you get to the point, the reader has left. + +### The Fix + +State your recommendation clearly: + +> "Use connection pooling. Here's why and how." + +Add caveats at the end if needed, not before. + +## 7. The Missing Why + +### The Sin + +> "Step 1: Add `gem 'sidekiq'` to your Gemfile +> Step 2: Run `bundle install` +> Step 3: Create a worker class +> Step 4: Configure Redis +> Step 5: Start the Sidekiq process" + +The reader follows the steps but doesn't understand what they're building or why each step matters. + +### The Fix + +Start with the problem: + +> "Your app freezes for 10 seconds when sending emails. Users hate it. You hate it. +> +> The fix: send emails in the background. When a user signs up, you add "send welcome email" to a queue and immediately return. A separate process handles the queue. +> +> Let's set that up..." + +Now the steps have context. + +--- + +## Quick Reference: Warning Signs + +Your writing might be slipping if you see: + +| Warning Sign | Probable Sin | +|--------------|--------------| +| "is defined as" in the first paragraph | Abstract Opening | +| Paragraphs over 5 lines | Wall of Text | +| "is/was/are/were" more than 30% of verbs | Passive Epidemic | +| More than 3 technical terms without explanation | Jargon Dump | +| Code examples over 30 lines | Code Novel | +| First sentence contains "while", "although", "however" | Disclaimer Flood | +| Tutorial without "why" explanation | Missing Why | diff --git a/plugins/compound-writing/skills/voice/pragmatic-writing/references/examples.md b/plugins/compound-writing/skills/voice/pragmatic-writing/references/examples.md new file mode 100644 index 00000000..661ef3cb --- /dev/null +++ b/plugins/compound-writing/skills/voice/pragmatic-writing/references/examples.md @@ -0,0 +1,227 @@ +# Pragmatic Writing Examples + +Before/after transformations showing the techniques in action. + +## Example 1: API Documentation + +### Before (Dry, Abstract) + +> The Authentication module provides mechanisms for verifying user credentials and managing session state. It implements the OAuth 2.0 specification and supports multiple grant types including authorization_code, client_credentials, and refresh_token flows. + +### After (Pragmatic) + +> **Getting Users Logged In** +> +> Your app needs to know who's making requests. Here's the simplest path: +> +> ```ruby +> # In your controller +> token = request.headers['Authorization'] +> user = Auth.verify(token) +> ``` +> +> That's it for reading. The token comes from your login flow, which we'll set up next. +> +> (We support OAuth 2.0 with authorization_code, client_credentials, and refresh_token flows. But let's start with the basics.) + +## Example 2: Design Pattern Explanation + +### Before (Textbook) + +> The Strategy pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable. Strategy lets the algorithm vary independently from clients that use it. This pattern is useful when you have multiple algorithms for a specific task and want to switch between them at runtime. + +### After (Pragmatic) + +> **Swapping Algorithms at Runtime** +> +> Say you're building a pricing calculator. Some customers get standard pricing. VIPs get 20% off. Enterprise clients have custom negotiated rates. +> +> The naive approach: +> +> ```ruby +> def calculate_price(customer, items) +> case customer.type +> when :standard +> items.sum(&:price) +> when :vip +> items.sum(&:price) * 0.8 +> when :enterprise +> # 50 lines of custom logic +> end +> end +> ``` +> +> Every new customer type means editing this method. Testing is a nightmare. And that enterprise logic? Nobody wants to touch it. +> +> Instead, make each pricing approach its own object: +> +> ```ruby +> class StandardPricing +> def calculate(items) +> items.sum(&:price) +> end +> end +> +> class VipPricing +> def calculate(items) +> items.sum(&:price) * 0.8 +> end +> end +> +> # Usage +> pricing = customer.pricing_strategy +> total = pricing.calculate(items) +> ``` +> +> Now adding a new customer type is adding a new class. No touching existing code. Each strategy can be tested in isolation. +> +> That's the Strategy pattern: algorithms as interchangeable objects. + +## Example 3: Error Handling Guide + +### Before (Formal) + +> Error handling should be implemented consistently throughout the application. All exceptions should be caught at appropriate boundaries and either handled or re-thrown with additional context. Logging should capture sufficient information for debugging while avoiding sensitive data exposure. + +### After (Pragmatic) + +> **When Things Go Wrong** +> +> Errors happen. The question isn't if, but what you do when they do. +> +> The worst thing: +> +> ```ruby +> begin +> do_risky_thing +> rescue +> # Silent failure. Good luck debugging this at 3 AM. +> end +> ``` +> +> The second worst thing: +> +> ```ruby +> begin +> do_risky_thing +> rescue => e +> puts e.message # Hope someone's watching stdout! +> raise # Now we have two problems +> end +> ``` +> +> Here's what actually helps: +> +> ```ruby +> begin +> do_risky_thing(user_id: user.id) +> rescue NetworkError => e +> # Expected failure, handle gracefully +> ErrorTracker.capture(e, user_id: user.id) +> return fallback_response +> rescue => e +> # Unexpected failure, add context and escalate +> raise ContextualError.new( +> "Failed processing user #{user.id}", +> cause: e +> ) +> end +> ``` +> +> Notice: +> 1. We catch *specific* errors we know how to handle +> 2. We add context (the user_id) for debugging +> 3. Unexpected errors get wrapped with context, not swallowed +> +> > **Tip**: Every `rescue` without a specific exception type is a code smell. What exactly are you expecting to fail? + +## Example 4: Performance Optimization + +### Before (Generic) + +> Performance optimization should focus on identifying bottlenecks through profiling before implementing changes. Premature optimization can lead to unnecessary complexity. Database queries are often the primary source of performance issues in web applications. + +### After (Pragmatic) + +> **Your App Is Slow. Now What?** +> +> First rule: **measure, don't guess**. +> +> I once spent a week optimizing a sorting algorithm only to discover the actual bottleneck was a DNS lookup. Don't be me. +> +> Here's the debugging order: +> +> ``` +> 1. Is it the database? +> β†’ Check slow query log. 90% of the time, it's here. +> +> 2. Is it N+1 queries? +> β†’ user.posts.each { |p| p.author.name } +> β†’ That's 1 query for posts + N queries for authors +> +> 3. Is it memory? +> β†’ Loading 10,000 records into memory to count them? +> β†’ Use User.count, not User.all.size +> +> 4. Is it external services? +> β†’ API calls inside loops are death +> β†’ Batch them or cache them +> ``` +> +> Once you've measured and found the bottleneck: +> +> ```ruby +> # Before: 47 queries, 2.3 seconds +> posts = user.posts +> posts.each { |p| render p.author.name } +> +> # After: 2 queries, 0.1 seconds +> posts = user.posts.includes(:author) +> posts.each { |p| render p.author.name } +> ``` +> +> That's it. One word: `includes`. 23x faster. +> +> > **The real tip**: The fastest code is the code that doesn't run. Can you cache it? Can you skip it? Can you do it later? + +## Example 5: Testing Philosophy + +### Before (Textbook) + +> Unit tests should verify the behavior of individual components in isolation. Tests should be deterministic, fast, and independent of external state. Mock objects can be used to isolate the system under test from its dependencies. + +### After (Pragmatic) + +> **Tests That Actually Help** +> +> Bad tests are worse than no tests. They slow you down, break randomly, and give false confidence. +> +> Here's a bad test: +> +> ```ruby +> test "user is valid" do +> user = User.new(name: "Bob", email: "bob@test.com") +> assert user.valid? +> end +> ``` +> +> What does this actually test? That `User.new` works? That `valid?` returns a boolean? When this test fails, what do you learn? +> +> Here's a useful test: +> +> ```ruby +> test "user requires email to be unique" do +> User.create!(email: "taken@test.com") +> duplicate = User.new(email: "taken@test.com") +> +> assert_not duplicate.valid? +> assert_includes duplicate.errors[:email], "has already been taken" +> end +> ``` +> +> This test: +> - Documents a business rule (unique emails) +> - Fails with a meaningful message if the rule breaks +> - Won't pass accidentally +> +> > **The test you need**: Write the test that would have caught last week's bug. That's usually the test worth writing. diff --git a/plugins/compound-writing/skills/voice/pragmatic-writing/references/sources.md b/plugins/compound-writing/skills/voice/pragmatic-writing/references/sources.md new file mode 100644 index 00000000..c5161a10 --- /dev/null +++ b/plugins/compound-writing/skills/voice/pragmatic-writing/references/sources.md @@ -0,0 +1,102 @@ +# Source Material + +Original inspiration and recommended reading. + +## Primary Sources + +### The Pragmatic Programmer +**Authors**: Andy Hunt, Dave Thomas +**Key Contributions**: +- "Tip" format for distilling principles +- DRY (Don't Repeat Yourself) articulation +- Rubber duck debugging +- Tracer bullets concept +- "Good enough" software philosophy + +**Style Elements Borrowed**: +- Numbered tips +- Anecdotal openings +- Physical analogies (broken windows, tracer bullets) +- Pragmatic over dogmatic approach + +### Joel on Software +**Author**: Joel Spolsky +**Key Contributions**: +- The Joel Test +- "Things You Should Never Do" (on rewrites) +- Leaky abstractions +- Human task switching costs + +**Style Elements Borrowed**: +- Conversational, blog-friendly tone +- Personal anecdotes +- Humor as architecture +- Building arguments through narrative +- Willingness to take strong positions + +## Secondary Influences + +### Effective Java +**Author**: Joshua Bloch +**Style Elements**: +- "Item" format for discrete lessons +- Clear do/don't guidance +- Code examples that evolve + +### Clean Code +**Author**: Robert C. Martin +**Style Elements**: +- Before/after code transformations +- Named principles (SRP, DRY) +- Refactoring narratives + +### A Philosophy of Software Design +**Author**: John Ousterhout +**Style Elements**: +- Counterintuitive insights +- "Red flag" warnings +- Complexity as central theme + +## Recommended Reading Order + +For developing pragmatic writing skills: + +1. **Start here**: Joel on Software archives (free online) + - Accessible, entertaining, teaches by example + - Read: "The Absolute Minimum Every Software Developer Must Know About Unicode" + +2. **Then**: The Pragmatic Programmer (20th Anniversary Edition) + - The template for technical writing + - Notice the structure of each tip + +3. **Then**: Any technical blog you admire + - Study what makes it work + - Identify techniques they use + +## Notable Blog Posts to Study + +### For Structure +- "Choosing Boring Technology" by Dan McKinley +- "The Log: What every software engineer should know" by Jay Kreps + +### For Narrative +- "The Night Watch" by James Mickens +- "Wat" by Gary Bernhardt (talk, but same principles) + +### For Accessibility +- "The Absolute Minimum Every Software Developer Must Know About Unicode" by Joel Spolsky +- "What Every Programmer Should Know About Memory" by Ulrich Drepper + +## Key Quotes to Remember + +> "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." +> β€” Antoine de Saint-ExupΓ©ry + +> "The best writing is rewriting." +> β€” E.B. White + +> "Programs must be written for people to read, and only incidentally for machines to execute." +> β€” Harold Abelson + +> "If you can't explain it simply, you don't understand it well enough." +> β€” (Attributed to Einstein, probably apocryphal, still true) diff --git a/plugins/compound-writing/skills/voice/pragmatic-writing/references/techniques.md b/plugins/compound-writing/skills/voice/pragmatic-writing/references/techniques.md new file mode 100644 index 00000000..b60c3028 --- /dev/null +++ b/plugins/compound-writing/skills/voice/pragmatic-writing/references/techniques.md @@ -0,0 +1,244 @@ +# Pragmatic Writing Techniques + +Detailed guide to the 10 core techniques with extended examples. + +## 1. Concrete Before Abstract + +The most important technique. Never explain a concept before showing it. + +### The Pattern + +``` +1. Show the problem scenario +2. Show the naive/common approach +3. Show it failing +4. Reveal the better approach +5. NOW explain the principle +``` + +### Extended Example + +**Bad (abstract first):** +> The Observer pattern is a software design pattern in which an object, named the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes. + +**Good (concrete first):** +> You've got a spreadsheet. Cell A1 contains "10". Cell B1 contains "=A1 * 2". Change A1 to "20", and B1 instantly shows "40". +> +> That's the Observer pattern. B1 is *observing* A1. When A1 changes, B1 gets notified and updates itself. +> +> In code, you might have an Order that needs to notify Inventory, Shipping, and EmailService when it's placed. Instead of the Order calling all three directly... + +## 2. Physical Analogies Catalog + +### Software Abstraction β†’ Physical Tool + +- **Interface** β†’ Power outlet (anything with the right plug works) +- **Caching** β†’ Keeping frequently used tools on your workbench +- **Load balancing** β†’ Multiple checkout lanes at a grocery store +- **Queue** β†’ Line at the DMV +- **Stack** β†’ Stack of plates (last one on is first one off) + +### Design Pattern β†’ Architectural Pattern + +- **Factory** β†’ Bakery (you order "bread", they handle the recipe) +- **Singleton** β†’ The President (only one at a time) +- **Decorator** β†’ Gift wrapping (adds features without changing the gift) +- **Adapter** β†’ Travel power adapter (makes incompatible things work) + +### System Design β†’ Everyday System + +- **Microservices** β†’ Restaurant kitchen (grill station, salad station, dessert station) +- **Monolith** β†’ Home kitchen (one person does everything) +- **Event sourcing** β†’ Bank statement (every transaction recorded, balance calculated) +- **API Gateway** β†’ Hotel concierge (single point of contact, routes requests) + +## 3. Conversational Register Markers + +### Use These + +- "Let's say..." (introduces scenarios) +- "Here's the thing..." (pivots to key insight) +- "Now, you might be thinking..." (addresses objections) +- "I've seen this go wrong when..." (shares experience) +- "The trick is..." (reveals technique) + +### Avoid These + +- "It should be noted that..." +- "One must consider..." +- "The implementation thereof..." +- "As previously mentioned..." +- "In conclusion..." + +## 4. Humor Patterns + +### The Absurdist Example + +Show a bad pattern taken to its extreme: + +> If we followed this logic, we'd have a `StringUtils` class with methods like `addOneToNumber(String s)` that parses the string to an int, adds one, and converts back to a string. +> +> Don't laugh. I've seen it in production code. + +### The Self-Deprecating Admission + +> I spent three hours debugging a race condition before noticing I'd typed `=` instead of `==`. We've all been there. That's why we have linters. + +### The Unexpected Comparison + +> Debugging is like being the detective in a crime movie where you are also the murderer. + +## 5. The "Aha!" Structure Template + +```markdown +## [Problem Statement as Question] + +You've probably encountered [familiar situation]. + +The obvious approach is [common solution]: + +```code +[naive implementation] +``` + +This works... until [edge case or scale issue]. + +[Show the failure scenario] + +The insight is: [key realization] + +Instead, we can: + +```code +[better implementation] +``` + +Notice how [specific improvement]. This is the principle of [named concept]: + +> **[Principle Box]**: [One-sentence version of the insight] +``` + +## 6. Paragraph Length Guide + +### One-sentence paragraphs for: +- Key insights +- Dramatic revelations +- Punchy conclusions +- Transitions + +### Two-sentence paragraphs for: +- Quick examples +- Brief asides +- Setup before code + +### Three-four sentence paragraphs for: +- Explanations +- Scenarios +- Analysis + +### Never more than four sentences. + +## 7. Code Example Guidelines + +### Minimal +Remove everything not essential to the point. + +```ruby +# ❌ Too much +class UserService + def initialize(repository, logger, cache, config) + @repository = repository + @logger = logger + @cache = cache + @config = config + end + + def find_user(id) + @logger.info("Finding user #{id}") + cached = @cache.get("user:#{id}") + return cached if cached + user = @repository.find(id) + @cache.set("user:#{id}", user, ttl: @config.cache_ttl) + user + end +end + +# βœ… Just enough +class UserService + def initialize(repository) + @repository = repository # Injected, not created + end + + def find_user(id) + @repository.find(id) + end +end +``` + +### Progressive +Show evolution from broken to fixed. + +```ruby +# First attempt (broken) +def process(items) + items.each { |i| save(i) } # What if one fails? +end + +# Second attempt (better) +def process(items) + items.each do |i| + save(i) + rescue => e + log_error(e) # But we continue with bad data... + end +end + +# Final (robust) +def process(items) + results = items.map { |i| [i, safely_save(i)] } + failures = results.select { |_, success| !success } + raise BatchError, failures if failures.any? +end +``` + +## 8. Principle Box Formats + +### Numbered Tip +> **Tip 23: Don't Repeat Yourself** +> Every piece of knowledge must have a single, unambiguous, authoritative representation within a system. + +### Highlighted Insight +> πŸ’‘ **The key insight**: Complexity isn't the enemy. *Unnecessary* complexity is. + +### Warning Box +> ⚠️ **Watch out**: If you find yourself adding a boolean parameter, you probably need two methods. + +## 9. Friendly Warning Pattern + +```markdown +It's tempting to [common mistake] because [why it seems reasonable]. + +I've done this. [Brief admission of your own mistake] + +The problem emerges when [specific failure scenario]: + +[Show what goes wrong] + +Instead, [better approach]: + +[Show the fix] +``` + +## 10. Callback Examples + +### Open with question, close with answer + +**Opening**: "Why do we bother with tests if we're just going to rewrite everything?" + +**Closing**: "So why bother with tests? Because they're not protecting the code. They're protecting the behavior. The code can change; the contract shouldn't." + +### Open with scenario, close with transformation + +**Opening**: "It's 3 AM. Your pager goes off. The database is on fire." + +**Closing**: "Now when your pager goes off at 3 AMβ€”and it willβ€”you'll have the logs, the metrics, and the runbooks to handle it. You might even get back to sleep." diff --git a/plugins/compound-writing/skills/voice/source-code-guide/SKILL.md b/plugins/compound-writing/skills/voice/source-code-guide/SKILL.md new file mode 100644 index 00000000..0d00af2e --- /dev/null +++ b/plugins/compound-writing/skills/voice/source-code-guide/SKILL.md @@ -0,0 +1,325 @@ +--- +name: source-code-guide +description: This skill should be used when writing for Every's Source Code series - essays on the craft of building in the AI era. It provides the vision, strategy, sensibility, and structural templates for pieces that coin language, demonstrate workflows, and shape how the industry thinks about building with AI. +--- + +# Source Code Style Guide + +Source Code is Every's series on the craft of building in the AI era. These essays document, define, and brand new ways of workingβ€”not just with code, but with design, product philosophy, and the entire creative process of making software. + +## Vision + +**We coin language, demonstrate workflows, and shape how the industry thinks about building with AI.** + +Our purpose: +- Establish Source Code as the cultural and technical reference for AI-native creation +- Coin and circulate the vocabulary that defines new disciplines (compounding engineering, vibe design, selfish software) +- Transform Every's practices into public intellectual property: frameworks, metaphors, and playbooks + +--- + +## Part 1: The Source Code Gradient + +Not every piece needs to be purely technical. We publish across a spectrum: + +| Type | Focus | Examples | +|------|-------|----------| +| **Engineering-Heavy** | Deep technical workflows, system architecture, code-first narratives | Claude Code delegation, parallel orchestration | +| **Practice-Focused** | New methodologies, workflow innovations, tool orchestration | Compounding engineering, vibe coding | +| **Philosophy-Driven** | Design as engineering, personal software manifestos, ethics/aesthetics | Atmosphere-first development, selfish software | +| **Journey-Centered** | Career transformation, origin stories, personal cost and reward | Finding your way back to what you love | + +**All are valid Source Code pieces if they illuminate new ways of building in the AI age.** + +--- + +## Part 2: Strategy Principles + +### 1. Anchor in First-Person Authority + +Source Code is written by the builders themselves: Kieran Klaassen on Claude Code and compounding engineering, Yash Poojary on Sparkle's rebuild, Lucas on design philosophy. + +**Tone:** Personal but authoritativeβ€”"field notes" from people shipping real products. + +### 2. Personal Stakes as Foundation + +Every piece needs to show what the author risks or sacrifices: + +| Stake Type | Example | +|------------|---------| +| **Origin stories** | Why you started building this way | +| **Rediscovery narratives** | Finding your way back to what you love | +| **Career pivots** | When conventional success isn't enough | +| **The cost of the practice** | Late nights, failed experiments, $100 fines | + +**Stakes make the practice real, not theoretical.** + +### 3. The "One Big Idea" Rule + +Each piece must coin, claim, or crystallize ONE memorable concept: + +- A new discipline (compounding engineering) +- A practice philosophy (vibe design, selfish software) +- A controversial stance (AI wrappers are the future) +- A workflow innovation (parallel Claude orchestration) + +**This builds Every's intellectual property one term at a time.** + +### 4. Blend Narrative with Intellectual Rigor + +1. **Open with a scene:** PRs reviewing themselves, a weekend rebuild of Sparkle, a debugging breakthrough +2. **Zoom out to the universal:** How engineering work, careers, or creativity itself are changing +3. **Ground in data or stakes:** Sparkle has organized 10M+ files; compounding engineering cuts ship times from weeks to days + +### 5. Build Playbooks, Not Just Opinions + +Every piece delivers frameworks and heuristics readers can try. Playbooks come in many forms: + +| Playbook Type | Description | +|---------------|-------------| +| **Technical frameworks** | Commands, workflows, step-by-step processes | +| **Philosophical principles** | Mindset shifts and new ways of thinking | +| **Tool stacks** | Specific setup and why it matters | +| **Challenges/Provocations** | "Start your experiment log today" | +| **Visual systems** | Atmosphere kits, VIBE.md files | + +**Not every piece needs explicit steps, but all should leave readers with something actionable.** + +### 6. The ELI5 Rule + +Our pieces must be specific enough to be interesting to an advanced AI user AND descriptive enough to be accessible to a smart newcomer. + +**When to apply:** +- Using a technical term or tool name for the first time +- Describing how we built or tested something +- Explaining an editing, research, or publishing workflow +- Recounting "how I got from A β†’ B" in an anecdote + +#### Examples that BREAK the ELI5 rule + +❌ **Vague workflow:** +> "We spun up a retrieval pipeline with subagents, chunked the corpus, hydrated the cache, and it just worked." + +Why it breaks: Jargon, no steps, missing clicks/inputs. + +❌ **Hand-wavy editing:** +> "I ran the draft through our editor, then tuned it until it felt right." + +Why it breaks: No start state, no actions, no success check. + +❌ **A β†’ B without the bridge:** +> "I started with a messy free write and ended with a clean memo. I played around until the ideas clicked." + +Why it breaks: Skips the actual moves that made the change. + +#### Examples that FOLLOW the ELI5 rule + +| Term | ELI5 Explanation | +|------|------------------| +| Agent vs. slash command | "An agent (a specialized AI worker) versus a slash command (a simple shortcut)" | +| Context window | "Each agent has its own separate conversation history and memory, so they can't see each other's work unless you pass it along" | +| Prompt engineering | "The process of designing laser-specific prompts so large language models produce the output you want" | +| Context engineering | "Prompt engineering is asking your brilliant intern the right question. Context engineering is giving that intern access to the right filing cabinets… and examples of what 'good' looks like" | +| Vibe coding | "Coding with AI-powered tools that convert natural-language instructions into working code" | +| Bridge job | "Roles that appear when a new technology needs human translatorsβ€”essential at first, then absorbed once the interface gets easier" | + +--- + +## Part 3: Sensibility + +Source Code inherits Every's tonal DNA: + +| Quality | Application | +|---------|-------------| +| **Optimistic Realism** | AI as leverage, with quirks surfaced (Claude over-testing, Gemini over-engineering) | +| **Practical Optimism** | Constructive frameworks, not contrarian rants | +| **Personal Stakes** | Exhaustion, late-night ramen rebuilds, nitpicky "feel checks" | +| **Accessible Rigor** | Technical enough for engineers, clear enough for curious non-tech readers | +| **Taste as Core Value** | Coding isn't just implementationβ€”it's about "sparkle," vibe, and design choices | + +### Voice Spectrum + +Different pieces call for different voices, all valid: + +| Voice | Example Line | +|-------|--------------| +| **Technical authority** | "I haven't typed a function in weeks, yet I'm shipping faster than ever" | +| **Philosophical builder** | "Software is a place; make it worth visiting" | +| **Vulnerable founder** | "The questions still haunt me sometimes" | +| **Rediscovered enthusiast** | "Code was like magic, but betterβ€”it was real" | +| **Defiant craftsperson** | "You don't need permission to make the internet beautiful" | + +**Choose the voice that serves the story.** + +--- + +## Part 4: Craft Checklist + +### Opening Patterns + +Start strong with one of these proven patterns: + +#### The Charged Anecdote +- "The PR that reviewed itself" +- "Opening email and flinching at the fluorescent void" +- "Seeing your design aesthetic stolen" + +#### The Manifesto Declaration +- "I'd like to introduce a concept I call selfish software" +- "Software should conform to you, not the other way around" + +#### The Sensory Contrast +- Fluorescent Gmail vs. outside air +- Conference room software vs. somewhere you want to be + +#### The Confession +- "Two months ago, I chose chaos over comfort" +- "I haven't typed a function in weeks" + +#### The Pattern Recognition +- Multiple Claude instances like mission control +- Your feed full of your workβ€”except it isn't + +### Throughout the Piece + +**Mix registers and materials:** +- Technical exposition + personal narrative +- Code/prompts/screenshots + human reflection +- Philosophy + practical application +- Data/metrics + sensory details + +**Use concrete language:** + +| ❌ Vague | βœ… Concrete | +|----------|-------------| +| "Optimized workflows" | "Claude spun up five PRs while I drank coffee" | +| "Enhanced backgrounds" | "8k oil-painted skies" | +| "Cost-effective" | "$400/month replacing $400k/year" | + +**Create memorable subheads:** +Not just organizational but evocative: +- "The Gravity of Sameness" +- "Escaping the Golden Handcuffs" +- "Ship the Atmosphere" + +**Address the skeptics:** + +| Objection | Response Pattern | +|-----------|------------------| +| "Ugly products win" | Sometimes, but... | +| "We can't afford this" | You can't afford not to | +| "AI wrappers are overdone" | The opportunity is just beginning | + +--- + +## Part 5: Structural Templates + +### The Discovery Arc +1. Problem/frustration encountered +2. Conventional solution inadequate +3. Breakthrough moment +4. New practice developed +5. Results and transformation +6. How readers can adopt it + +### The Philosophy-Practice Bridge +1. Philosophical observation about building +2. Why the current approach falls short +3. New framework/lens introduced +4. Concrete application shown +5. Broader implications explored +6. Call to adopt the mindset + +### The Journey Narrative +1. Where I was (comfortable but unfulfilled) +2. The catalyst for change +3. The leap and its costs +4. What I'm building now +5. Early results and learnings +6. Why others should consider this path + +### The Technical Deep-Dive +1. The surprising behavior/result +2. How we got here (workflow detail) +3. Why this matters (efficiency gain) +4. System architecture explained +5. Iterations and improvements +6. Your turn to implement + +--- + +## Part 6: Source Code Commandments + +1. **Show the mess** β€” Include failures, frustrations, and false starts +2. **Coin deliberately** β€” If you name it, define it clearly and defend it +3. **Connect to canon** β€” Reference other Source Code concepts where relevant +4. **Start from joy** β€” Even technical pieces should convey enthusiasm +5. **End with action** β€” Give readers something specific to try +6. **Prove with examples** β€” Show actual workflows, real metrics, screenshots +7. **Write the future** β€” Describe the world where this practice is normal +8. **Honor the craft** β€” Respect both technical excellence and human creativity +9. **Make it memorable** β€” One takeaway phrase or framework they'll quote +10. **Build in public** β€” Share tools, frameworks, and code where possible + +--- + +## Why It Matters + +Source Code is Every's claim on the future of building. In a world where: +- AI can generate competent code in seconds +- Templates and patterns are free +- Technical barriers are falling daily + +...the differentiators become: +- **Taste and curation** +- **Joy and personal connection** +- **Systems that compound** +- **Philosophy that guides practice** +- **Character that can't be averaged away** + +Source Code documents the builders who understand this shift and are creating the disciplines, tools, and mindsets for what comes next. + +--- + +## Quick Reference Card + +``` +SOURCE CODE DNA +=============== +First-person authority (builders writing) +Personal stakes (show what you risk) +One Big Idea (coin it, claim it) +Narrative + rigor (scene to universal) +Playbooks (actionable frameworks) +ELI5 (accessible to newcomers) + +GRADIENT SPECTRUM +================= +Engineering-Heavy β†’ Practice-Focused β†’ Philosophy-Driven β†’ Journey-Centered + +OPENING PATTERNS +================ +β–‘ Charged anecdote (the PR that reviewed itself) +β–‘ Manifesto declaration (I call this selfish software) +β–‘ Sensory contrast (fluorescent void vs. outside air) +β–‘ Confession (I haven't typed a function in weeks) +β–‘ Pattern recognition (multiple Claudes like mission control) + +10 COMMANDMENTS +=============== +Show the mess | Coin deliberately | Connect to canon +Start from joy | End with action | Prove with examples +Write the future | Honor the craft | Make it memorable +Build in public +``` + +--- + +## Integration with Other Skills + +| Skill | Relationship | +|-------|--------------| +| `every-essay-guide` | General Every voice and best practices | +| `every-style-editor` | Mechanical editing after drafting | +| `pragmatic-writing` | Hunt/Thomas accessibility for technical sections | +| `dhh-writing` | Direct, opinionated voice for manifestos |