Initial commit

2025-11-30 08:37:11 +08:00
commit 20b36ca9b1
56 changed files with 14530 additions and 0 deletions
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -0,0 +1,270 @@
+---
+name: brainstorming
+description: |
+  Socratic design refinement - transforms rough ideas into validated designs through
+  structured questioning, alternative exploration, and incremental validation.
+
+trigger: |
+  - New feature or product idea (requirements unclear)
+  - User says "plan", "design", or "architect" something
+  - Multiple approaches seem possible
+  - Design hasn't been validated by user
+
+skip_when: |
+  - Design already complete and validated → use writing-plans
+  - Have detailed plan ready to execute → use executing-plans
+  - Just need task breakdown from existing design → use writing-plans
+
+sequence:
+  before: [writing-plans, using-git-worktrees]
+
+related:
+  similar: [writing-plans]
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
+
+**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."
+
+## Quick Reference
+
+| Phase | Key Activities | Tool Usage | Output |
+|-------|---------------|------------|--------|
+| **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/ |
+| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
+| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
+
+## The Process
+
+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)
+- [ ] Phase 4: Design Documentation (design written to docs/plans/)
+- [ ] Phase 5: Worktree Setup (if implementing)
+- [ ] Phase 6: Planning Handoff (if implementing)
+```
+
+### Prep: Autonomous Recon
+
+**MANDATORY evidence (paste ALL):**
+
+```
+Recon Checklist:
+□ Project structure:
+  $ ls -la
+  [PASTE OUTPUT]
+
+□ Recent activity:
+  $ git log --oneline -10
+  [PASTE OUTPUT]
+
+□ Documentation:
+  $ head -50 README.md
+  [PASTE OUTPUT]
+
+□ Test coverage:
+  $ find . -name "*test*" -type f | wc -l
+  [PASTE OUTPUT]
+
+□ Key frameworks/tools:
+  $ [Check package.json, requirements.txt, go.mod, etc.]
+  [PASTE RELEVANT SECTIONS]
+```
+
+**Only after ALL evidence pasted:** Form your model and share findings.
+
+**Skip any evidence = not following the skill**
+
+### Question Budget
+
+**Maximum 3 questions per phase.** More = insufficient research.
+
+Question count:
+- Phase 1: ___/3
+- Phase 2: ___/3
+- Phase 3: ___/3
+
+Hit limit? Do research instead of asking.
+
+### 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:**
+```
+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?
+```
+
+### Phase Lock Rules
+
+**CRITICAL:** Once you enter a phase, you CANNOT skip ahead.
+
+- Asked a question? → WAIT for answer before solutions
+- Proposed approaches? → WAIT for selection before design
+- Started design? → COMPLETE before documentation
+
+**Violations:**
+- "While you consider that, here's my design..." → WRONG
+- "I'll proceed with option 1 unless..." → WRONG
+- "Moving forward with the assumption..." → WRONG
+
+**WAIT means WAIT. No assumptions.**
+
+### Phase 2: Exploration
+- Propose 2-3 different approaches
+- For each: Core architecture, trade-offs, complexity assessment, and your recommendation
+- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call
+- 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)
+  - "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 coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
+- Cover: Architecture, components, data flow, error handling, testing
+- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
+- Use open-ended questions to allow freeform feedback
+- Assume ownership and proceed unless your partner redirects you
+
+**Design Acceptance Gate:**
+
+Design is NOT approved until human EXPLICITLY says one of:
+- "Approved" / "Looks good" / "Proceed"
+- "Let's implement that" / "Ship it"
+- "Yes" (in response to "Shall I proceed?")
+
+**These do NOT mean approval:**
+- Silence / No response
+- "Interesting" / "I see" / "Hmm"
+- Questions about the design
+- "What about X?" (that's requesting changes)
+
+**No explicit approval = keep refining**
+
+### Phase 4: Design Documentation
+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 sections that emerged from the conversation
+- Commit the design document to git before proceeding
+
+### Phase 5: Worktree Setup (for implementation)
+When design is approved and implementation will follow:
+- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
+- **REQUIRED SUB-SKILL:** Use ring-default:using-git-worktrees
+- Follow that skill's process for directory selection, safety verification, and setup
+- Return here when worktree ready
+
+### Phase 6: Planning Handoff
+Ask: "Ready to create the implementation plan?"
+
+When your human partner confirms (any affirmative response):
+- Announce: "I'm using the writing-plans skill to create the implementation plan."
+- **REQUIRED SUB-SKILL:** Use ring-default:writing-plans
+- Create detailed plan in the worktree
+
+## Question Patterns
+
+### When to Use AskUserQuestion Tool
+
+**Use AskUserQuestion when:**
+- You need your partner to make a judgement call among real alternatives
+- You have a recommendation and can explain why it’s your preference
+- Prioritization is ambiguous and cannot be inferred from existing materials
+
+**Best practices:**
+- State your preferred option and rationale inside the question so your partner can agree or redirect
+- If you know the answer from repo/docs, state it as fact and proceed—no question needed
+- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner
+
+### When to Use Open-Ended Questions
+
+**Use open-ended questions for:**
+- Phase 3: Design validation ("Does this look right so far?")
+- When you need detailed feedback or explanation
+- 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)
+
+## When to Revisit Earlier Phases
+
+```dot
+digraph revisit_phases {
+    rankdir=LR;
+    "New constraint revealed?" [shape=diamond];
+    "Partner questions approach?" [shape=diamond];
+    "Requirements unclear?" [shape=diamond];
+    "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
+    "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
+    "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];
+
+    "New constraint revealed?" -> "Return to Phase 1" [label="yes"];
+    "New constraint revealed?" -> "Partner questions approach?" [label="no"];
+    "Partner questions approach?" -> "Return to Phase 2" [label="yes"];
+    "Partner questions approach?" -> "Requirements unclear?" [label="no"];
+    "Requirements unclear?" -> "Return to Phase 1" [label="yes"];
+    "Requirements unclear?" -> "Continue forward" [label="no"];
+}
+```
+
+**You can and should go backward when:**
+- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
+- Validation shows fundamental gap in requirements → Return to Phase 1
+- Partner questions approach during Phase 3 → Return to Phase 2
+- Something doesn't make sense → Go back and clarify
+
+**Avoid forcing forward linearly** when going backward would give better results.
+
+## Required Patterns
+
+This skill uses these universal patterns:
+- **State Tracking:** See `skills/shared-patterns/state-tracking.md`
+- **Failure Recovery:** See `skills/shared-patterns/failure-recovery.md`
+- **Exit Criteria:** See `skills/shared-patterns/exit-criteria.md`
+- **TodoWrite:** See `skills/shared-patterns/todowrite-integration.md`
+
+Apply ALL patterns when using this skill.
+
+## Key Principles
+
+| Principle | Application |
+|-----------|-------------|
+| **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 |