📦 deps(skills): sync pathfinding dependency for codebase-recon

2026-05-29 23:12:17 +08:00
parent b4c88b32be
commit c1bce2fb72
13 changed files with 1503 additions and 7 deletions
@@ -0,0 +1,132 @@
+# Question Format
+
+## Anatomy of a Good Question
+
+**Components**:
+1. **Q{N}**: Question number (for tracking)
+2. **Question**: Clear, specific, focused on one decision
+3. **Why it matters**: One sentence explaining impact
+4. **Options**: 2–4 meaningful choices
+5. **Nuance**: Brief context for each option
+6. **★ Recommendation** (optional): Your lean with reasoning
+
+## Delivery via EnterPlanMode
+
+Use `EnterPlanMode` for each question — enables keyboard navigation.
+
+**Structure**:
+- **Prose above tool**: context, reasoning, ★ recommendation
+- **Inside tool**: options only (concise, scannable)
+
+Don't bury recommendations inside the tool — keep them visible in prose.
+
+## Crafting Options
+
+### Option Count Guidelines
+
+**2 options**: Use when choices are binary or you want to keep it simple
+- Good: "Web app or mobile app?"
+- Avoid: Forcing false dichotomy when more options exist
+
+**3 options**: Sweet spot for most questions
+- Good: Covers main approaches plus one alternative
+- Avoid: Making options too similar
+
+**4 options**: Use when you need a combination or "other"
+- Good: Three distinct approaches + a hybrid option
+- Avoid: Analysis paralysis with too many choices
+
+### Option Quality
+
+**Good options**:
+- Mutually exclusive (can pick only one)
+- Collectively exhaustive (covers reasonable space)
+- Clearly differentiated (not subtle variations)
+- Actionable (leads to concrete next steps)
+
+**Bad options**:
+- Overlapping: "Option 1: Use React. Option 2: Use modern framework."
+- Too similar: "Option 1: 100ms timeout. Option 2: 150ms timeout."
+- Vague: "Option 1: Do it the normal way."
+- Open-ended: "Option 1: Whatever you think is best."
+
+## Why It Matters
+
+The one-sentence explanation serves multiple purposes:
+1. **Context**: Helps user understand why you're asking
+2. **Priority**: Shows this isn't arbitrary
+3. **Decision framing**: Clarifies what depends on this choice
+4. **Respect**: Demonstrates you're not just asking for the sake of asking
+
+**Good examples**:
+- "Why it matters — determines database schema design"
+- "Why it matters — affects performance characteristics and scaling strategy"
+- "Why it matters — impacts user experience for first-time visitors"
+
+**Weak examples**:
+- "Why it matters — I need to know"
+- "Why it matters — this is important"
+- "Why it matters — because"
+
+## Adding Nuance
+
+Each option should include helpful context:
+
+**Good nuance**:
+- Trade-offs: "Faster to implement but less flexible long-term"
+- Implications: "Requires HTTPS and external dependency"
+- Prerequisites: "Need existing user database"
+- Typical use case: "Best for high-traffic applications"
+
+**Weak nuance**:
+- Restating the obvious: "Uses OAuth" (when option says OAuth)
+- Generic statements: "Good option"
+- No information: Just the option name with no context
+
+## Recommendations (★)
+
+Use recommendations when:
+- You have genuine expertise or insight
+- One option clearly fits better for typical cases
+- User seems uncertain or asks for guidance
+
+**Don't recommend when**:
+- Purely user preference (e.g., color scheme)
+- Not enough context yet
+- All options equally valid
+
+**Good**: `1. React [★] — mature ecosystem *best starting point for most teams*`
+
+**Weak**:
+- ★ I like this one
+- ★ Most popular
+- Recommendation buried in prose above options
+
+## User Replies
+
+Number is a shorthand, not a constraint:
+- `2` → selects option 2
+- `2, but with caching` → selection + modification
+- `2 and 3` → combo
+- `What's the difference?` → clarification request
+
+All valid.
+
+## Adaptive Cadence
+
+**Baseline** (~80% of questions):
+- Clear question + one-sentence "why"
+- 2–4 options with brief nuance
+- Inline `[★]` on recommended option
+- Optional: `[★] { expanded reasoning }` in prose above if helpful
+
+**Expand when**:
+- High ambiguity or risk
+- User uncertain or asks for detail
+- Technical complexity needs explanation
+
+**Simplify when**:
+- Straightforward question
+- User shows expertise
+- Question 6+ in session
+- User wants to move faster