📦 deps(skills): sync pathfinding dependency for codebase-recon
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
# Confidence
|
||||
|
||||
Confidence reflects certainty that you can deliver the requested outcome with the available information.
|
||||
|
||||
## Philosophy
|
||||
|
||||
Balance two goals:
|
||||
1. **Gather enough** to deliver quality results
|
||||
2. **Avoid over-questioning** that frustrates user
|
||||
|
||||
Consider:
|
||||
- **Clarity**: How well-defined is the ask?
|
||||
- **Risk**: What happens if assumptions are wrong?
|
||||
- **Complexity**: How many moving parts?
|
||||
- **Ambiguity**: How many valid interpretations?
|
||||
|
||||
## Level Overview
|
||||
|
||||
| Bar | Level | Name | Internal % |
|
||||
| --------- | ----- | ------------ | ---------- |
|
||||
| `░░░░░` | 0 | **Prepping** | 0–19% |
|
||||
| `▓░░░░` | 1 | **Scouting** | 20–39% |
|
||||
| `▓▓░░░` | 2 | **Exploring**| 40–59% |
|
||||
| `▓▓▓░░` | 3 | **Charting** | 60–74% |
|
||||
| `▓▓▓▓░` | 4 | **Mapped** | 75–89% |
|
||||
| `▓▓▓▓▓` | 5 | **Ready** | 90–100% |
|
||||
|
||||
## Stage Transitions
|
||||
|
||||
Confidence levels trigger stage transitions. Stages always advance, never regress.
|
||||
|
||||
### Stage-Confidence Mapping
|
||||
|
||||
| Level | Stage | activeForm |
|
||||
|-------|-------|------------|
|
||||
| 0–1 | Prep | "Prepping" |
|
||||
| 2–3 | Explore | "Exploring" |
|
||||
| 4 | Clarify | "Clarifying" |
|
||||
| 5 | Deliver | "Delivering" |
|
||||
|
||||
### Rules
|
||||
|
||||
1. **No regression**: If confidence drops (4 → 3), stay in current stage
|
||||
2. **Skip when starting high**: Level 5 start → go directly to Deliver
|
||||
3. **Stage independence**: Confidence can fluctuate within a stage
|
||||
4. **Early delivery**: User can request delivery at any stage → add `△ Caveats`
|
||||
|
||||
### Edge Cases
|
||||
|
||||
**High start**: Clear requirements → Start at Ready, go directly to Deliver
|
||||
|
||||
**Confidence drop**: Reach Mapped (4), enter Clarify, then realize gap (drops to 3) → Stay in Clarify, ask targeted questions
|
||||
|
||||
**Rapid ascent**: Start at Exploring (2) → one answer jumps to Mapped (4) → next to Ready (5) → transition through stages quickly
|
||||
|
||||
### Level 0: Prepping `░░░░░`
|
||||
|
||||
**Stage**: Prep
|
||||
|
||||
**When**: Request completely unclear, no domain context, pure guessing
|
||||
|
||||
**Ask**: Scope, constraints, goals, background
|
||||
|
||||
**Example**: "Make it better" with no context about what "it" is.
|
||||
|
||||
### Level 1: Scouting `▓░░░░`
|
||||
|
||||
**Stage**: Prep
|
||||
|
||||
**When**: Vague direction, domain clear but specifics aren't
|
||||
|
||||
**Ask**: What system? How big? What's in place?
|
||||
|
||||
**Example**: "Improvements to the dashboard" — which kind?
|
||||
|
||||
### Level 2: Exploring `▓▓░░░`
|
||||
|
||||
**Stage**: Explore
|
||||
|
||||
**When**: General area understood, lack critical details, multiple approaches possible
|
||||
|
||||
**Ask**: Which approach? What about X? What matters most? Speed vs quality?
|
||||
|
||||
**Example**: "Authentication" — method, scale, existing system unknown.
|
||||
|
||||
### Level 3: Charting `▓▓▓░░`
|
||||
|
||||
**Stage**: Explore
|
||||
|
||||
**When**: Reasonable understanding, could deliver with notable assumptions
|
||||
|
||||
**Do**:
|
||||
1. Summarize (3 bullets max)
|
||||
2. Ask 2–3 targeted questions toward level 4–5
|
||||
3. If user proceeds early → add `△ Caveats`
|
||||
|
||||
**Example**: OAuth login — general approach known, need providers + fallback strategy.
|
||||
|
||||
### Level 4: Mapped `▓▓▓▓░`
|
||||
|
||||
**Stage**: Clarify
|
||||
|
||||
**When**: Solid understanding, few clarifications would reach Ready, low risk
|
||||
|
||||
**Do**: Offer choice — "Can proceed, but 1–2 more questions would reach full confidence. Continue or deliver now?"
|
||||
|
||||
**Example**: New API endpoint — data model understood, need error handling approach.
|
||||
|
||||
### Level 5: Ready `▓▓▓▓▓`
|
||||
|
||||
**Stage**: Deliver
|
||||
|
||||
**When**: Clear understanding, no major assumptions, minimal risk
|
||||
|
||||
**Do**: Produce artifact immediately, succinct next steps, no more questions unless something emerges
|
||||
|
||||
**Example**: "Add logout button to header" — clear, specific, low-risk.
|
||||
|
||||
## Special Cases
|
||||
|
||||
### Starting Confidence
|
||||
|
||||
Start honest. Don't artificially start low if the request is clear.
|
||||
|
||||
- **Clear request** → level 4–5
|
||||
- **Vague request** → level 0–2
|
||||
|
||||
### Delivering Below Level 5
|
||||
|
||||
User wants quick delivery at lower confidence:
|
||||
|
||||
1. Confirm they want to proceed
|
||||
2. Add `△ Caveats` section
|
||||
3. List assumptions, concerns, unknowns
|
||||
|
||||
### Calibration
|
||||
|
||||
- Deliver at 5, goes well → calibrated
|
||||
- Deliver at 5, miss the mark → overconfident
|
||||
- Stay at 0–2 too long → underconfident
|
||||
|
||||
## Tuning
|
||||
|
||||
Percentage boundaries can adjust based on risk tolerance:
|
||||
- **Higher risk tolerance** → shift boundaries down
|
||||
- **Lower risk tolerance** → shift boundaries up
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user