Update release notes for v3.3.1 writing improvements

Applied Strunk's "Elements of Style" principles:
- Rule 13: Omitted needless words (removed "already", "genuinely", etc.)
- Rule 11: Converted negative to positive form ("don't ask" → "ask only when")
- Rule 10: Used active voice where appropriate
- Rule 15: Improved parallel construction in lists
- General: Made language more direct and concrete

Changes maintain the skill's functionality while improving readability.

RELEASE-NOTES.md

@@ -1,5 +1,16 @@
 # Superpowers Release Notes
 
+## v3.3.1 (2025-10-28)
+
+### Improvements
+
+- Updated `brainstorming` skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans.
+- Applied writing clarity improvements to `brainstorming` skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction).
+
+### Bug Fixes
+
+- Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex).
+
 ## v3.3.0 (2025-10-28)
 
 ### New Features

skills/brainstorming/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating or developing anything, before writing code or im
 
 Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
 
-**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
+**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.
 
 **Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."
 
@@ -17,7 +17,8 @@ Transform rough ideas into fully-formed designs through structured questioning a
 
 | Phase | Key Activities | Tool Usage | Output |
 |-------|---------------|------------|--------|
-| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
+| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |
+| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |
 | **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
 | **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
 | **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
@@ -30,6 +31,7 @@ Copy this checklist to track progress:
 
 ```
 Brainstorming Progress:
+- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)
 - [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
 - [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
 - [ ] Phase 3: Design Presentation (design validated in sections)
@@ -38,47 +40,53 @@ Brainstorming Progress:
 - [ ] Phase 6: Planning Handoff (if implementing)
 ```
 
-### Phase 1: Understanding
+### Prep: Autonomous Recon
-- Check current project state in working directory
+- Use existing tools (file browsing, docs, git history, tests) to understand current project state before asking anything.
-- Ask ONE question at a time to refine the idea
+- Form your draft model: what problem you're solving, what artifacts exist, and what questions remain.
-- **Use AskUserQuestion tool** when you have multiple choice options
+- Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…"
-- Gather: Purpose, constraints, success criteria
+- Ask follow-up questions only for information you cannot infer from available materials.
 
-**Example using AskUserQuestion:**
+### Phase 1: Understanding
+- Share your synthesized understanding first, then invite corrections or additions.
+- Ask one focused question at a time, only for gaps you cannot close yourself.
+- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.
+- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)
+
+**Example summary + targeted question:**
 ```
-Question: "Where should the authentication data be stored?"
+Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?
-Options:
-  - "Session storage" (clears on tab close, more secure)
-  - "Local storage" (persists across sessions, more convenient)
-  - "Cookies" (works with SSR, compatible with older approach)
 ```
 
 ### Phase 2: Exploration
 - Propose 2-3 different approaches
-- For each: Core architecture, trade-offs, complexity assessment
+- For each: Core architecture, trade-offs, complexity assessment, and your recommendation
-- **Use AskUserQuestion tool** to present approaches as structured choices
+- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call
-- Ask your human partner which approach resonates
+- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
+- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking
 
 **Example using AskUserQuestion:**
 ```
 Question: "Which architectural approach should we use?"
 Options:
+  - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
   - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
-  - "Direct API calls with retry logic" (simple, synchronous, easier to debug)
   - "Hybrid with background jobs" (balanced, moderate complexity, best of both)
+
+I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.
 ```
 
 ### Phase 3: Design Presentation
-- Present in 200-300 word sections
+- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
 - Cover: Architecture, components, data flow, error handling, testing
-- Ask after each section: "Does this look right so far?" (open-ended)
+- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
-- Use open-ended questions here to allow freeform feedback
+- Use open-ended questions to allow freeform feedback
+- Assume ownership and proceed unless your partner redirects you
 
 ### Phase 4: Design Documentation
-After design is validated, write it to a permanent document:
+After validating the design, write it to a permanent document:
 - **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
 - **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
-- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
+- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
 - Commit the design document to git before proceeding
 
 ### Phase 5: Worktree Setup (for implementation)
@@ -100,16 +108,15 @@ When your human partner confirms (any affirmative response):
 
 ### When to Use AskUserQuestion Tool
 
-**Use AskUserQuestion for:**
+**Use AskUserQuestion when:**
-- Phase 1: Clarifying questions with 2-4 clear options
+- You need your partner to make a judgement call among real alternatives
-- Phase 2: Architectural approach selection (2-3 alternatives)
+- You have a recommendation and can explain why it’s your preference
-- Any decision with distinct, mutually exclusive choices
+- Prioritization is ambiguous and cannot be inferred from existing materials
-- When options have clear trade-offs to explain
 
-**Benefits:**
+**Best practices:**
-- Structured presentation of options with descriptions
+- State your preferred option and rationale inside the question so your partner can agree or redirect
-- Clear trade-off visibility for partner
+- If you know the answer from repo/docs, state it as fact and proceed—no question needed
-- Forces explicit choice (prevents vague "maybe both" responses)
+- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner
 
 ### When to Use Open-Ended Questions
 
@@ -119,6 +126,8 @@ When your human partner confirms (any affirmative response):
 - When partner should describe their own requirements
 - When structured options would limit creative input
 
+Frame them to confirm or expand your current understanding rather than reopening settled topics.
+
 **Example decision flow:**
 - "What authentication method?" → Use AskUserQuestion (2-4 options)
 - "Does this design handle your use case?" → Open-ended (validation)
@@ -150,16 +159,17 @@ digraph revisit_phases {
 - Partner questions approach during Phase 3 → Return to Phase 2
 - Something doesn't make sense → Go back and clarify
 
-**Don't force forward linearly** when going backward would give better results.
+**Avoid forcing forward linearly** when going backward would give better results.
 
 ## Key Principles
 
 | Principle | Application |
 |-----------|-------------|
-| **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices |
+| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself |
 | **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
 | **YAGNI ruthlessly** | Remove unnecessary features from all designs |
 | **Explore alternatives** | Always propose 2-3 approaches before settling |
 | **Incremental validation** | Present design in sections, validate each |
 | **Flexible progression** | Go backward when needed - flexibility > rigidity |
+| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |
 | **Announce usage** | State skill usage at start of session |

skills/writing-skills/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills are written to `~/.claude/skills`** 
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** 
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).