📦 deps(skills): sync pathfinding dependency for codebase-recon
This commit is contained in:
+262
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: pathfinding
|
||||
description: This skill should be used when requirements are unclear, brainstorming ideas, or when "pathfind", "brainstorm", "figure out", "clarify requirements", or "work through" are mentioned.
|
||||
metadata:
|
||||
version: "2.0.0"
|
||||
---
|
||||
|
||||
# Pathfinding
|
||||
|
||||
Adaptive Q&A → unclear requirements → clear path.
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Ambiguous/incomplete requirements
|
||||
- Complex features needing exploration
|
||||
- Greenfield projects with open questions
|
||||
- Collaborative brainstorming or problem solving
|
||||
|
||||
NOT for: time-critical bugs, well-defined tasks, obvious questions
|
||||
|
||||
</when_to_use>
|
||||
|
||||
<confidence>
|
||||
|
||||
| Bar | Lvl | % | Name | Action |
|
||||
|-----|-----|---|------|--------|
|
||||
| `░░░░░` | 0 | 0–19 | Prepping | Gather foundational context |
|
||||
| `▓░░░░` | 1 | 20–39 | Scouting | Ask broad questions |
|
||||
| `▓▓░░░` | 2 | 40–59 | Exploring | Ask focusing questions |
|
||||
| `▓▓▓░░` | 3 | 60–74 | Charting | Risky to proceed; gaps remain |
|
||||
| `▓▓▓▓░` | 4 | 75–89 | Mapped | Viable; push toward 5 |
|
||||
| `▓▓▓▓▓` | 5 | 90–100 | Ready | Deliver |
|
||||
|
||||
Start honest. Clear request → level 4–5. Vague → level 0–2.
|
||||
|
||||
At level 4: "Can proceed, but 1–2 more questions would reach full confidence. Continue or deliver now?"
|
||||
|
||||
Below level 5: include `△ Caveats` section.
|
||||
|
||||
</confidence>
|
||||
|
||||
<stages>
|
||||
|
||||
Load the **maintain-tasks** skill for stage tracking. Stages advance only, never regress.
|
||||
|
||||
| Stage | Trigger | activeForm |
|
||||
|-------|---------|------------|
|
||||
| Prep | level 0–1 | "Prepping" |
|
||||
| Explore | level 2–3 | "Exploring" |
|
||||
| Clarify | level 4 | "Clarifying" |
|
||||
| Deliver | level 5 | "Delivering" |
|
||||
|
||||
Task format — each stage gets context-specific title:
|
||||
|
||||
```text
|
||||
- Prep { domain } requirements
|
||||
- Explore { approach } options
|
||||
- Clarify { key unknowns, 3-4 words }
|
||||
- Deliver { artifact type }
|
||||
```
|
||||
|
||||
Situational (insert before Deliver when triggered):
|
||||
- Resolve Conflicts → `◆ Caution` or `◆◆ Hazard` pushback
|
||||
- Validate Assumptions → high-risk assumptions before delivery
|
||||
|
||||
Workflow:
|
||||
- Start: Create stage matching initial confidence `in_progress`
|
||||
- Transition: Mark current `completed`, add next `in_progress`
|
||||
- High start (4+): Skip directly to `Clarify` or `Deliver`
|
||||
- Early delivery: Skip to `Deliver` + `△ Caveats`
|
||||
|
||||
</stages>
|
||||
|
||||
<gather>
|
||||
|
||||
Calibrate first — user may have already provided context (docs, prior conversation, pointed you at files). If enough context exists, skip to level 3–4. Don't re-ask what's already clear.
|
||||
|
||||
If gaps remain, explore focus areas (pick what's relevant):
|
||||
- Purpose: What problem? Why now?
|
||||
- Constraints: Time, tech, team, dependencies
|
||||
- Success: How will we know it works?
|
||||
- Scope: What's in, what's out?
|
||||
|
||||
When multiple approaches exist:
|
||||
- Propose 2–3 options with trade-offs
|
||||
- Lead with recommendation ★ and reasoning
|
||||
- Let user pick, combine, or redirect
|
||||
|
||||
Principles:
|
||||
- YAGNI — cut what's not needed
|
||||
- DRY — don't duplicate effort or logic
|
||||
- Simplest thing — prefer boring solutions
|
||||
|
||||
</gather>
|
||||
|
||||
<questions>
|
||||
|
||||
Use `EnterPlanMode` for each question — enables keyboard navigation of options.
|
||||
|
||||
Structure:
|
||||
- Prose above tool: context, reasoning, ★ recommendation if clear lean
|
||||
- Inside tool: options only (concise, scannable)
|
||||
|
||||
At level 0 — start with session intent:
|
||||
- Quick pulse check vs deep dive?
|
||||
- Exploring possibilities or solving a specific problem?
|
||||
- What does "done" look like?
|
||||
|
||||
Levels 1–4 — focus on substance:
|
||||
- 2–4 options per question + "5. Something else"
|
||||
- Inline `[★]` on recommended option + *italicized rationale*
|
||||
- User replies: number, modifications, or combos
|
||||
|
||||
</questions>
|
||||
|
||||
<workflow>
|
||||
|
||||
Loop: Answer → Restate → Update Confidence → Next action
|
||||
|
||||
After each answer emit:
|
||||
- Confidence: {BAR} {NAME}
|
||||
- Assumptions: { if material }
|
||||
- Unknowns: { what we can clarify; note unknowables when relevant }
|
||||
- Decisions: { what's locked in }
|
||||
- Concerns: { what feels off + why }
|
||||
|
||||
Next action by level:
|
||||
- 0–2: Ask clarifying questions
|
||||
- 3: Summarize (3 bullets max), fork toward 5
|
||||
- 4: Offer choice: refine or proceed
|
||||
- 5: Deliver
|
||||
|
||||
</workflow>
|
||||
|
||||
<issues>
|
||||
|
||||
When answer reveals a concern mid-stream:
|
||||
- Pause before next question
|
||||
- Surface with `△` + brief description
|
||||
- Ask: clarify now, note for later, or proceed with assumption?
|
||||
|
||||
Example: "△ This assumes the API supports batch operations — clarify now, note for later, or proceed?"
|
||||
|
||||
If user proceeds despite significant gap → escalate to `pushback` protocol.
|
||||
|
||||
</issues>
|
||||
|
||||
<pushback>
|
||||
|
||||
Escalate when choice conflicts with goals/constraints/best practices:
|
||||
|
||||
- `◇ Alternative`: Minor misalignment. Present option + reasoning.
|
||||
- `◆ Caution`: Clear conflict. Recommend alternative, explain risks, ask to proceed. Triggers Resolve Conflicts.
|
||||
- `◆◆ Hazard`: High failure risk. Require mitigation or explicit override. Triggers Resolve Conflicts.
|
||||
|
||||
Override: Accept "Proceed anyway: {REASON}" → log in next reflection → mark Resolve Conflicts complete.
|
||||
|
||||
</pushback>
|
||||
|
||||
<skeptic>
|
||||
|
||||
Integrate skeptic agent for complexity sanity checks:
|
||||
|
||||
**Recommend** (offer choice):
|
||||
- Level 5 reached with △ Caveats > 2
|
||||
- Red flag language in decisions: "might need later", "more flexible", "best practice"
|
||||
|
||||
```text
|
||||
Before finalizing — you have {N} caveats. Want to run skeptic for a sanity check?
|
||||
[AskUserQuestion]
|
||||
1. Yes, quick check [★] — I'll challenge complexity interactively
|
||||
2. Yes, deep analysis — launch skeptic agent in background
|
||||
3. No, proceed — deliver as-is
|
||||
```
|
||||
|
||||
**Auto-invoke** (no choice):
|
||||
- Level 4+ with 3+ unknowns persisting across 2+ question cycles
|
||||
- ◆◆ Hazard escalation triggered during session
|
||||
|
||||
When auto-invoking:
|
||||
|
||||
```text
|
||||
[Auto-invoking skeptic — {REASON}]
|
||||
```
|
||||
|
||||
Launch with Task tool:
|
||||
- subagent_type: "outfitter:skeptic"
|
||||
- prompt: Include current decisions, unknowns, and caveats
|
||||
- run_in_background: false (wait for findings before delivery)
|
||||
|
||||
After skeptic returns:
|
||||
- Present findings to user
|
||||
- If verdict is `block` → add Resolve Conflicts stage
|
||||
- If verdict is `caution` → offer choice to address or acknowledge
|
||||
- If verdict is `proceed` → continue to delivery
|
||||
|
||||
</skeptic>
|
||||
|
||||
<completion>
|
||||
|
||||
Level 5: Produce artifact immediately (doc, plan, code, outline). If none specified, suggest one.
|
||||
|
||||
After delivering, ask where to persist (if applicable):
|
||||
|
||||
```text
|
||||
[EnterPlanMode]
|
||||
1. { discovered path } [★] — { source: `CLAUDE.md` preference | existing directory | convention }
|
||||
2. Create issue — { Linear/GitHub/Beads based on project context }
|
||||
3. ADR — { if architectural decision }
|
||||
4. Don't persist — keep in conversation only
|
||||
5. Something else — different location or format
|
||||
```
|
||||
|
||||
Discovery order for option 1:
|
||||
1. `CLAUDE.md` or project instructions with explicit plan storage preference
|
||||
2. Existing `.agents/plans/` directory
|
||||
3. Existing `docs/plans/` directory
|
||||
4. Fall back to `.agents/plans/` if nothing found
|
||||
|
||||
Always suggest filename based on topic. Match existing conventions if present.
|
||||
|
||||
Mark Deliver `completed` after artifact is delivered (persistence is optional follow-up).
|
||||
|
||||
Below 5: Append `△ Caveats`:
|
||||
- Open questions + context
|
||||
- Assumed decisions + defaults
|
||||
- Known concerns + impact
|
||||
- Deferred items + revisit timing
|
||||
|
||||
</completion>
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Task stage matching initial confidence at start
|
||||
- `EnterPlanMode` for each question (keyboard nav)
|
||||
- Prose above tool for context + ★ recommendation
|
||||
- One question at a time, wait for response
|
||||
- Restate + update confidence before next move
|
||||
- Update todos at level 4, level 5 thresholds
|
||||
- Apply pushback protocol on conflicts
|
||||
- Check skeptic triggers at level 4+ (unknowns, caveats, red flags)
|
||||
|
||||
NEVER:
|
||||
- Proceed from 0–3 without clarifying questions
|
||||
- Hide uncertainty below level 5
|
||||
- Stack questions or bury decisions in paragraphs
|
||||
- Put recommendation inside plan tool (keep in prose)
|
||||
- Skip reflection after answer
|
||||
- Regress stages
|
||||
- Ignore skeptic auto-invoke triggers
|
||||
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
|
||||
- [confidence.md](references/confidence.md) — confidence deep dive
|
||||
- [questions.md](references/questions.md) — question crafting
|
||||
- [examples/](examples/) — session examples
|
||||
- skeptic agent (outfitter:skeptic) — complexity sanity checks
|
||||
|
||||
</references>
|
||||
Reference in New Issue
Block a user