Imported from whichguy/skill-craft (plugins/c-plan/skills/c-plan/SKILL.md). Install upstream with npx skills add whichguy/skill-craft --skill c-plan. Copyright stays with the author (MIT).

skill-craft port of the claude-craft planning-suite skill. Host-neutral: use repo-root search instead of Claude plugin paths. SoT: this package under whichguy/skill-craft.

Bayesian Clarifier

Purpose

Produce the best useful answer with the fewest clarifying questions.

Default mode is normal.

Do not turn ordinary prompts into discovery interviews. Run only the lightest process that improves the answer.

Core hierarchy:

Possible meanings seed the search.
Families/facets allocate search breadth.
Questions compete on expected value.
Response plans decide action.

Core control law:

Ask only when EVQ > best(answer now, answer with assumptions, compare top interpretations) + friction/delay/complexity cost.

Where:

EVQ = expected value of question
ΔAnswer = how much the final answer changes if uncertainty is resolved

Information gain is useful, but it is only one input to EVQ. Do not ask a question merely because it is interesting or uncertainty remains.

Four Gates

Use these gates in order.

1. FASTPATH GATE
   Can I answer now?

2. EVQ GATE
   Is asking, researching, tool use, or agent delegation better than answering with assumptions?

3. REPLAN GATE
   Did new evidence change the task shape?

4. PLAN DELTA GATE
   If replanned, does the new response plan materially beat the incumbent?

Everything else supports these gates.

Runtime Vocabulary

Use these symbols internally:

H  = hypothesis / possible meaning
F  = family / facet / uncertainty axis
Q  = probe / candidate clarification question
B  = branch / possible answer to Q
E  = evidence / user answer or stated constraint
R  = response plan / answer strategy before final prose
T  = tombstone / ruled-out path with resurrection condition
TC = terminal condition / reason to stop asking

Runtime kernel:

FASTPATH
  → if ambiguity matters: lightweight H sketch
  → F/facet breadth scan
  → family-weighted Q budget if needed
  → branch-simulate representative Qs
  → EVQ Gate
  → ask user / run selected agent(s) / use tools / answer with assumptions
  → E update
  → Replan Gate
  → Plan Delta Gate if replanned
  → T only if useful
  → choose R
  → TC
  → final answer

In normal mode, keep H/F/Q/B/E/R/T implicit unless needed. Think compactly; answer quickly.

Modes

Use the lightest mode that can produce a good answer.

Escalate only for the current turn or unresolved fork. De-escalate immediately once enough evidence exists.

normal:
  0–1 clarification round
  3–5 internal Q candidates only if needed
  no formal state

structured:
  0–1 clarification round
  7 internal Q candidates
  lightweight H/F/Q/B/R internally

deep:
  up to 2 clarification rounds
  13 internal Q candidates
  explicit H/F/Q/B/E/R/T if useful
  optional state file

discovery:
  up to 3 rounds only if the user asks for discovery/interview/requirements work

Deep mode requires explicit user request, high-stakes task, artifact-level output, complex multi-turn work, or materially ambiguous task where premature answering would likely produce the wrong result.

Gate 1 — FASTPATH

Use FASTPATH when the prompt is clear enough, ambiguity is low-impact, or user momentum matters.

Behavior:

Answer directly.
Optionally state one key assumption.
No state file.
No formal tables.

Escalate only if a missing fact would materially change the response.

Gate 2 — EVQ: Expected Value of Next Action

Before asking or researching, compare actions:

A1 answer now
A2 answer with assumptions
A3 compare top interpretations
A4 ask one Q
A5 ask two Qs
A6 run Explore for repo/codebase evidence
A7 run WebResearch for current external evidence
A8 run another selected agent whose description/tools fit the evidence gap
A9 run multiple selected agents in parallel when evidence streams are independent
A10 constrained / warning / refusal if risk boundary exists

Ask or research only if that action clearly beats answering or assumption-answering.

Use this practical EVQ judgment:

EVQ =
  expected response-plan improvement
  + risk avoided
  + contrary/minority-rescue value
  + correctness/freshness gain if research is needed
  - friction/delay/complexity cost
  - token/tool cost
  - source reliability risk

Approximate question value:

question_value =
    information_gain
    × ΔAnswer
    × risk_if_wrong
    ÷ user_friction
    + contrary_or_minority_rescue_bonus

Use qualitative bands in normal mode:

high / medium / low

Ask only when:

high ΔAnswer
and low enough friction
and answer would change R

Do not ask, research, or spawn agents because a field is blank.

Research / Agent Assist Gate

Treat agents as evidence/action helpers inside EVQ, not as separate workflows.

Parent remains controller.

Ask the user for intent/preference.
Ask Explore for repo/codebase truth.
Ask WebResearch for current external truth.
Ask any other suitable agent for its specialized evidence or review.
Parent decides the final answer.

Use research or agent delegation only when:

Agent_EVQ > best(answer now, answer with assumptions, ask user, direct parent work) + friction/delay/complexity/tool cost

Agent Action Selector

Missing evidence / work type          Best action
------------------------------------------------------------------
User intent / preference              Ask user
Repo structure / code behavior        Explore
Current docs / external facts         WebResearch
Architecture / design critique        Architect / planner / reviewer agent if available
Security or risk review               Security reviewer agent if available
Test strategy / failure analysis      Test/debug agent if available
Docs / writing review                 Documentation agent if available
Repo + current docs                   Explore + WebResearch if independent
Low-impact uncertainty                Answer with assumptions
High-risk uncertainty                 Ask, research, or delegate before answering

Use Explore When

answer depends on existing code behavior
repo structure or conventions matter
implementation touches multiple files
file discovery or code search is needed
current parent context lacks code evidence

Explore should be read-only and return evidence, not final prose.

Use WebResearch When

answer depends on current docs or external facts
version behavior may have changed
API/library/product status matters
security advisories or release notes matter
market/pricing/recommendations matter
user asks to research, verify, latest, docs, Reddit/forums, or current information

Prefer official or primary sources first.

Use Other Agents When

Use any available agent when its description, tool access, and specialization match a material evidence gap better than the parent can handle directly.

Examples:

architect/planner agent:
  compare response plans, architecture options, tradeoffs

security reviewer agent:
  identify threat/risk/compliance concerns

test/debug agent:
  inspect failure paths, logs, repro strategy

docs/writer agent:
  improve docs, examples, user-facing clarity

code reviewer agent:
  review implementation quality, maintainability, regressions

Do not delegate just because an agent exists. Delegate only when the agent has higher EVQ than direct parent work.

In this repo: Explore is built-in. code-reviewer (review-suite) covers code review and security-adjacent work. system-architect (planning-suite) covers planner/architect work. qa-analyst (planning-suite) covers test/debug strategy. There is no dedicated WebResearch/web-researcher, security-reviewer, or docs-writer agent — treat references to those as capability descriptions, not literal agent names. Use WebSearch/WebFetch tools directly for external research instead of spawning a web-researcher subagent.

Parallel Agent Work

Run multiple agents in parallel only when their evidence streams are independent and each has a distinct question.

Good:

Explore: how this repo currently handles auth
WebResearch: current docs/best practices for the auth library version
Security reviewer: risks in the proposed auth change

Bad:

multiple agents reading the same files without distinct questions
multiple agents producing final answers independently
agents launched because they are available, not because EVQ warrants them

Agent Evidence Packet Contract

Agents return compact evidence packets only:

1. direct finding
2. sources: file paths/line refs or URLs
3. confidence: high / medium / low
4. conflicts, uncertainty, or staleness
5. impact on R
6. recommended next action
7. open questions, if any

Agents must not:

write the final answer unless explicitly assigned
edit files unless explicitly authorized by parent/user
ask the user unless explicitly authorized
return raw scratch work
keep browsing/exploring after evidence is sufficient
expand scope beyond assigned question

Agent Selection Rules

Use the most specific suitable agent available.

Prefer:

read-only agents for research/review
specialized agents over general-purpose agents when fit is clear
general-purpose only when no specific agent fits
parallel agents only for independent evidence streams

When selecting an agent, check:

description matches the task
tools are appropriate and not excessive
agent can return compact evidence
expected value exceeds overhead

Use built-in Explore for codebase research.

Use or create a custom web-researcher agent for web research:

name: web-researcher
purpose: current external evidence
allowed tools: WebSearch, WebFetch
output: evidence packet only
sources: official/primary first

If using forked skill execution, the skill body must contain an explicit task. Passive guidelines alone are not enough for a useful forked run.

Possible Meanings / Hypotheses

Use H as lightweight scaffolding, not ceremony.

H answers:

What materially different meanings could this prompt have?

Relationship:

H = possible worlds
F = axes where those worlds differ
Q = probes that test the highest-value differences
R = action chosen after evidence

If the prompt is clear, skip explicit H and answer.

If ambiguity matters:

normal: infer 2–4 likely Hs silently
structured: sketch 3–5 Hs if needed
deep: generate 3–7 explicit Hs

Each H must imply a different answer. Avoid trivial variants.

For each meaningful H, know just enough:

label
answer implication
what would confirm it
what would disconfirm it

Use H only to seed F and R. If F/Q generation already makes the possible meanings obvious, do not separately materialize H.

Preserve plausible minority Hs until a disconfirming Q has been considered.

Families / Facets

Use F to define breadth, not final judgment.

F is an uncertainty axis separating Hs.

Useful F examples:

audience / user type
scope / ambition
job-to-be-done
maturity level
output format
implementation target
risk / compliance / safety
data / integration
cost or time constraint

Rule:

Use F to allocate candidate-Q budget.
Use Q scoring to choose actual Qs.
Use R scoring to decide action.

Do not deeply score F. Do not let one F consume all candidate budget. Do not sum redundant Qs inside one F.

Lightly rate F only enough to allocate exploration:

ΔAnswer: high / medium / low
Risk-if-wrong: high / medium / low
Answerability: high / medium / low
Friction: high / medium / low
Minority-rescue value: yes / no
Redundancy: high / medium / low

Ignore F with low ΔAnswer and low risk unless it has strong minority-rescue value.

Family-Weighted Q Budget

Use formal family-weighted allocation only in structured/deep mode, or when normal FASTPATH is clearly insufficient.

Normal mode usually does not need formal allocation. Think of 3–5 ad hoc Q candidates, then ask only if EVQ beats assumption-answering.

Budgets:

normal:      3–5 ad hoc internal Q candidates, no formal allocation unless needed
structured:  7 internal Q candidates weighted across F/facets
deep:        13 internal Q candidates weighted across F/facets

Allocation heuristic:

High-value F:    2–3 Q candidates
Medium-value F:  1–2 Q candidates
Low-value F:     0–1 Q candidates
Ignored F:       0 Q candidates

Caps/floors:

max 3 Qs per F
min 1 Q for high-value F
min 1 Q for strong minority-rescue F
0 Q for low ΔAnswer + low risk F

Optional deep-mode approximate weight:

F_weight ≈
    ΔAnswer
    × Risk-if-wrong
    × Answerability
    ÷ Friction
    - Redundancy
    + Minority-rescue bonus

Use H/M/L bands by default. Numeric-looking weights are only rough ordering aids, not calibrated scores.

Question funnel:

Generate broad F set.
Allocate Q candidates across F.
Generate Qs inside each F.
Dedupe near-equivalent Qs.
Keep best representative Q per useful F.
Branch-simulate representatives.
Deep-score top 3–7 representative Qs.
Ask top 0–2 non-redundant Qs.

Operating principle:

Generate many lightly.
Score few deeply.
Ask almost none.

Candidate Questions

Every Q must pass this test:

Would different answers produce meaningfully different final responses?

If not, discard the Q.

For each serious Q, know:

question text
F
answer choices
what each answer changes in R
which H/R each answer supports
which H/R each answer weakens
friction
whether it disconfirms current top H/R
whether it rescues a plausible minority H/R

Prefer world-splitting Qs over detail-tuning Qs.

Bad early Q:

Do you want dark mode?

Good early Q:

Is this mainly for personal use, a team workflow, or integration into another product?

Counterfactual Branches

Before asking a serious Q, simulate B branches.

Do not ask Q unless at least one B would materially disconfirm the current plan or rescue a plausible minority plan.

Use four B types:

Expected B:
  answer most likely under current top H/R

Contrary B:
  answer that weakens or disproves current top H/R

Minority-rescue B:
  answer that makes a low-probability H/R important

Ambiguous B:
  answer such as "not sure", "both", or "it depends"

For each B, estimate qualitatively:

which H/R gains
which H/R loses
what answer path changes
what gets tombstoned
what could be resurrected

Use likelihood-style thinking when helpful:

Estimate P(answer | hypothesis), then update belief from prior × likelihood.

Do not pretend probabilities are calibrated. Use qualitative movement in normal mode.

IG as EVQ Input

Use information gain as an input to EVQ, not as the final decision.

Deep-mode approximation:

IG(Q) = prior_entropy - weighted_expected_posterior_entropy

Where:

weighted_expected_posterior_entropy =
  sum over B: P(B) × entropy(posterior after B)

Contrary branch value:

contrary_branch_score =
    P(contrary B)
    × drop in current top H/R if contrary B occurs
    × risk avoided if current top H/R was wrong

Minority-rescue value:

minority_rescue_score =
    plausibility
    × risk_if_missed
    × response_plan_delta

A strong Q usually has:

high ΔAnswer
high contrary or minority-rescue value
low friction

A Q that only confirms the current favorite is usually refinement, not clarification.

Evidence Update

After the user answers:

record E
update H/R confidence
reduce contradicted H/R
check T resurrection
run Replan Gate
refresh R
run Plan Delta Gate if replanned
check TC
answer unless another Q clearly wins EVQ

Do not loop just because uncertainty remains.

Gate 3 — Replan

Every E updates state. Not every E triggers replan.

Replan only when E changes the task shape.

Replan triggers:

current top H/R is contradicted
new high-impact constraint appears
T path is resurrected
new hybrid path appears
risk / privacy / compliance boundary appears
current R no longer dominates
current Q set is obsolete
user changes desired output or success criteria

Replan levels:

Level 0: no replan; update E only
Level 1: local replan; adjust R only
Level 2: regenerate F/Q because new uncertainty axis appeared
Level 3: regenerate H/F/Q/B/T/R because task meaning changed

Use the lightest replan level that restores a good answer path.

Gate 4 — Plan Delta

After replanning, do not automatically follow the new plan.

Compare incumbent R vs best new R.

Qualitative gate:

materially better → switch
slightly better → hybridize/caveat
not better → keep incumbent
close + high ΔAnswer/risk → ask one plan-separating Q

Deep-mode conceptual test:

plan_delta =
    best_new_R_score
    - incumbent_R_score
    - switching_cost

Switching cost includes:

lost momentum
extra complexity
extra user friction
more verbose answer
risk of overfitting to one ambiguous answer
implementation burden

After replanning, score Q by plan separation:

post_replan_question_value =
    plan_separation
    × ΔAnswer
    × risk_if_wrong
    ÷ user_friction

A good post-replan Q separates top R plans, not merely top Hs.

Tombstones

Use T mostly in structured/deep or multi-turn work.

T records a discarded path without forgetting how to revive it.

Format:

item
type: hypothesis | family | question | assumption | response_plan
reason ruled out
confidence
resurrection condition

Example:

Item: Team accountability SaaS
Reason: User said this is for personal use.
Resurrection: user later mentions managers, teams, shared progress, roles, or reporting.

Tombstones are reversible.

State File

Only create state for deep, complex, high-stakes, artifact-level, or multi-turn work.

Preferred path:

<host-data-dir>/c-plan/<slug>/state.md

Record only useful state:

original prompt
current objective
H
F
Q/B considered
questions asked
E
T
R
TC
final assumptions

State files are for durable decisions, not transient exploration.

State files should summarize decisions, not store raw reasoning, scratch work, or long candidate lists.

Do not persist secrets, credentials, or sensitive private data unless necessary and appropriate.

LLM Leverage Techniques

Use only when they improve quality without making the interaction heavy.

Skeptic Pass

Ask:

What assumption could be wrong?
What user answer would invalidate current R?
What minority H/R am I underweighting?

Use to generate contrary B and prevent premature convergence.

Branch Simulation

Before asking Q:

If user says A → answer path 1
If user says B → answer path 2
If user says "both/not sure" → assumption or comparison path

Discard Q if B outcomes do not materially change R.

Pairwise Plan Comparison

When R plans are close, compare pairwise:

Which R better fits E?
Which R has lower risk if wrong?
Which R preserves momentum?
What one fact would decide between them?

Prefer this over global ranking.

Advanced techniques — self-consistency sampling, red-team review, assumption ledger, decision journal, compression-before-return — belong in companion docs or deep mode, not normal runtime.

Subagents / Forked Context

Use any available subagent or forked context only when its EVQ beats direct parent work.

Default rule:

normal mode: avoid subagents unless evidence/action gap is clearly material
structured mode: use selected agents when evidence gaps are material
deep mode: use selected agents/forked context for noisy independent work

Useful delegations:

Explore: repo/file/codebase research
WebResearch: current external evidence
planner/architect: architecture and tradeoff review
security reviewer: threat/risk/compliance review
test/debug agent: failure analysis and test strategy
docs/writer agent: docs clarity and examples
skeptic reviewer: hidden assumptions and contrary branches
question generator: family/facet discovery and Q candidates
response-plan reviewer: pairwise R comparison

Parent remains controller.

Subagents return evidence packets or compact summaries only.

The parent should merge results, resolve conflicts, update R, and produce the final answer.

Do not use subagents for tiny decisions where delegation overhead exceeds value.

Terminal Conditions

Stop asking and answer when any TC is true:

TC1: one R clearly dominates
TC2: best remaining Q/research action has low ΔAnswer / low EVQ
TC3: top Hs lead to substantially the same answer
TC4: friction/delay/complexity cost exceeds expected improvement
TC5: loop budget reached
TC6: user says proceed / best guess / good enough
TC7: safety or policy boundary requires constrained answer
TC8: user answer is partial but sufficient for useful response
TC9: evidence packet is sufficient; stop researching/delegating

Never keep asking just to fill blanks.

Some uncertainty is acceptable.

Final Answer Pattern

When assumptions matter:

I’ll assume <primary assumption>.
If <alternate interpretation>, the main change would be <delta>.
Under that assumption...

When prior clarification ruled out branches:

Given your answer, I’m treating <branch> as out of scope unless you later mention <resurrection condition>.

Keep the final answer focused on the user’s task, not this machinery.

Quality Bar

A successful run should:

answer simple prompts directly
use H as lightweight scaffolding
use F/facets for breadth, not over-analysis
use EVQ, not raw IG, to decide asking
ask fewer but better questions
avoid premature convergence
avoid endless clarification
preserve momentum
state assumptions when useful
produce a better final response than guessing

Minimal Invocation

Default mode is normal.

Normal use:

Use c-plan. FASTPATH first; ask/research/delegate only if EVQ beats assumption-answering; otherwise answer.

Structured use:

Use c-plan in structured mode. Generate 7 internal Q candidates weighted across F/facets, branch-score representatives, ask at most two non-redundant Qs, then answer.

Deep use:

Use c-plan in deep mode. Generate 13 internal Q candidates weighted across family/facet space, maintain H/F/Q/B/E/R/T state only if useful, use EVQ and counterfactual branch scoring, run selected agents for material evidence gaps, replan only when task shape changes, run Plan Delta Gate after replanning, and stop when a terminal condition fires.