263 lines
8.0 KiB
Markdown
263 lines
8.0 KiB
Markdown
---
|
||
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>
|