Initial commit

commands/polish.md

@@ -0,0 +1,136 @@
+---
+argument-hint: [TOPIC or PATH]
+description: Polish a blog post draft using quality checklist and style guidelines (hybrid: suggest → confirm → apply)
+---
+
+Target: $1
+
+You are polishing a blog post draft. This can be run multiple times during the writing process, not just at the end.
+
+## Process
+
+**1. Locate the Draft**
+
+If given a topic name, look for `posts/$1/draft.md`
+If given a path, use that directly
+
+**2. Read Both Files**
+
+- Read `draft.md` (the post being polished)
+- Read `braindump.md` (for context, research, examples)
+
+**3. Apply Quality Checklist** (from blog-writing skill)
+
+Evaluate the draft against:
+- [ ] Opens with compelling hook (anecdote, problem, or question)
+- [ ] TL;DR provides clear, standalone summary
+- [ ] Paragraphs are short (1-3 sentences)
+- [ ] Uses personal examples to ground abstract concepts
+- [ ] Cites sources/research to back up claims
+- [ ] Acknowledges complexity, avoids oversimplification
+- [ ] Examines multiple perspectives when relevant
+- [ ] Uses clear headings for scannability
+- [ ] Conversational tone with contractions and first person
+- [ ] Avoids corporate jargon, hyperbole, AI-sounding language
+- [ ] Ends with practical implications and engagement question
+- [ ] Varies sentence length for rhythm
+- [ ] Uses bold text for key insights (not excessively)
+- [ ] Works well in web and email formats
+
+**4. Identify Improvements**
+
+Look for:
+- **Structural issues**: Missing TL;DR, weak hook, no engagement question
+- **Voice issues**: Too formal, corporate language, AI phrases
+- **Style issues**: Long paragraphs, monotonous rhythm, missing emphasis
+- **Content issues**: Unsupported claims, missing examples, no citations
+- **Substack issues**: Poor formatting, hard to scan, not mobile-friendly
+
+**5. Present Suggestions** (Hybrid Approach)
+
+**CRITICAL: Only suggest improvements based on existing content.**
+- Don't add new ideas, examples, or milestones the user hasn't mentioned
+- Only reference content from braindump.md or draft.md
+- Focus on style, structure, and polish - not new content
+- If something is missing (e.g., no examples), ASK the user to provide it - don't make it up
+
+Show 3-5 concrete improvements you recommend:
+
+```
+I found several improvements to make:
+
+1. **Hook**: Current intro is explanatory. Suggest rewriting with
+   personal anecdote from braindump (Company X OKR failure story).
+
+2. **Missing TL;DR**: Add 3-bullet summary at the top.
+
+3. **Long paragraphs**: Section "Why OKRs Fail" has 6-sentence
+   paragraph. Break into 2-3 shorter ones.
+
+4. **Missing citation**: Claim about "70% failure rate" lacks source.
+   Found in braindump - add HBR 2024 reference.
+
+5. **Weak ending**: Currently just summarizes. Add engagement
+   question: "Have you seen OKRs fail at your company? What went wrong?"
+
+Should I apply these improvements to draft.md?
+```
+
+**6. Wait for Confirmation**
+
+User responds:
+- "Yes" / "Apply all" → Apply all suggested improvements
+- "Only 1, 3, 5" → Apply specific improvements
+- "Skip 2" → Apply all except specified ones
+- "Show me #1 first" → Show the specific change before applying
+
+**7. Apply Improvements**
+
+Update `draft.md` with approved changes. After applying:
+
+```
+Applied improvements to draft.md:
+✓ Rewrote intro with personal anecdote
+✓ Split long paragraph in "Why OKRs Fail" section
+✓ Added engagement question to conclusion
+
+Draft is now more polished. Want to review another section or run /polish again?
+```
+
+## Guidelines
+
+**Be Specific**: Don't say "improve the intro" - show exactly what you'd change
+
+**Prioritize Impact**: Focus on high-impact improvements (weak hook, missing engagement question) over minor tweaks
+
+**Reference Braindump**: Suggest adding content from braindump.md when it strengthens the draft
+
+**Preserve Voice**: Only suggest changes that align with Dhruv's style - don't make it more formal or corporate
+
+**Iterative**: This command can be run multiple times. Each pass should improve the draft without over-polishing
+
+**Substack Formatting**: Always check for proper markdown, line breaks, mobile readability
+
+## Common Improvements
+
+- Add missing TL;DR
+- Rewrite weak hooks with personal anecdotes
+- Break up long paragraphs (>4 sentences)
+- Add bold emphasis to key insights
+- Insert citations from braindump research
+- Strengthen conclusion with engagement question
+- Remove AI phrases ("in conclusion," "in today's world")
+- Vary sentence length for better rhythm
+- Add subheadings to improve scannability
+- Ensure proper spacing for email format
+
+## After Polishing
+
+The draft should:
+- Sound like Dhruv wrote it, not an AI
+- Be scannable and mobile-friendly
+- Have clear structure with proper emphasis
+- Include concrete examples and citations
+- Invite reader engagement
+
+If multiple issues remain, user can run `/polish` again for another pass.