pathfinding

# 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>