zirkel-explore-branches
Explores multiple genuinely-distinct approaches to a scoped problem in parallel, scores each on Feasibility/Impact/Risk, and selects a winner — so the work does not anchor on the first idea. Use when a task has more than one viable approach and picking the first that comes to mind would be a mistake: "what are our options here", "don't just do the obvious thing", "weigh a few approaches", "explore alternatives", or the Explore phase of zirkel-solve.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- zirkel-explore-branches
- description
- Explores multiple genuinely-distinct approaches to a scoped problem in parallel, scores each on Feasibility/Impact/Risk, and selects a winner — so the work does not anchor on the first idea. Use when a task has more than one viable approach and picking the first that comes to mind would be a mistake: "what are our options here", "don't just do the obvious thing", "weigh a few approaches", "explore alternatives", or the Explore phase of zirkel-solve.
03 SKILL.md 正文
zirkel-explore-branches
Generate branches independently and in parallel, score each in isolation, then select by the fixed rule. Parallel independence is what prevents anchoring — it is structural, not a suggestion.
The guard is python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py", typed in full in each command below.
0. Build or reuse the shared research snapshot
Before dispatching any branch-proposer, build (or reuse) zirkel's symbol-index
snapshot once, so every parallel proposer can query the same cached index instead
of each re-scanning the codebase independently:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_symbol_index.py" --repo-path . --plugin-name zirkel
This is a no-op if analysis/zirkel/current.json's source_fingerprint already
matches the repo (see references/parallel-safe-research-protocol.md). Skip this
step for a repository well under roughly 50 tracked files — this is a judgment call
the script itself does not make (see "Scale guidance" in references/parallel-safe-research-protocol.md).
Preferred path: the workflow
When the Workflow tool is available, run
${CLAUDE_PLUGIN_ROOT}/workflows/explore-branches.js
(args { problem, requestedBranches?, maxBranchCount? }). It dispatches one
branch-proposer agent per angle in parallel (propose), scores each in a separate
comparison-free dispatch, and selects the winner — all bounds enforced in code.
Workflow scripts have no filesystem access. The workflow returns
{ branches, scores, selected, rationale } in memory and stops there — it
cannot write state.json and cannot render a report. Run
the Persist and Render steps below after it returns; do not skip them
because "the workflow already did the work" silently drops both the
persisted run and its report, the same "ends without a trace" failure the
Manual path would have if its own step 5 were skipped.
Manual path
1. Decide the branch count (guarded)
echo '{"requested":<n or null>,"max_branch_count":<from config or null>}' | python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py" branch-cap -
- Default is 3 branches. The cap is min(6,
max_branch_count) wheremax_branch_countcomes from.claude/zirkel.local.mdif present. The guard returns the effectivecap; produce exactly that many.
2. Propose in parallel
Dispatch one branch-proposer agent per angle (conservative/ambitious/pragmatic/…)
in a single message so they run concurrently and never see each other. Each
commits fully to its angle. Do not score here.
3. Score each in isolation
Dispatch scoring separately — a proposer never scores its own branch, and no scorer compares branches. Each returns Feasibility, Impact, Risk (each 1-10) and its biggest blocker.
4. Select (guarded)
echo '{"branches":[
{"name":"A","feasibility":7,"impact":8,"risk":4,"biggest_blocker":"…"},
{"name":"B","feasibility":6,"impact":9,"risk":6,"biggest_blocker":"…"}
]}' | python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py" branch-scores -
The guard computes Total = Feasibility + Impact + Risk (Risk NOT inverted),
selects the highest total, and breaks ties by lower risk. Use its
selected — do not re-derive the winner by hand.
Persist (so a later zirkel-solve can reuse this, and so Render below has
something to render)
Regardless of which path produced the branches and scores above, generate a
run id (python3 -c "import uuid; print(uuid.uuid4())"), then merge each
branch's description (from Propose / step 2) back onto its scored object
(from Score+Select / step 3-4, or the workflow's scores array) by name
before writing — the guard does not require description, but the
branch-comparison report below does, and this is the only point where the
two ever meet:
echo '{
"run_id": "<run-id>",
"raw_task": "<the exact `problem` text you were given>",
"phase": "Explore",
"explore_ran": true,
"explore": {"branches": [
{"name":"A","description":"<A'\''s Propose description>","feasibility":7,"impact":8,"risk":4,"biggest_blocker":"…"},
{"name":"B","description":"<B'\''s Propose description>","feasibility":6,"impact":9,"risk":6,"biggest_blocker":"…"}
]}
}' | python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/zirkel.py" state-write - --output-dir .zirkel --to runs/<run-id>/state.json
raw_task here is the problem text this invocation actually scored branches for.
A later zirkel-solve run only reuses this if its own Explore step is about to
score branches for that exact same text (see zirkel-solve's own "Reuse a
prior run" step) — matching is byte-for-byte, never fuzzy.
Render the branch-comparison report
Every run that reaches Persist also gets a report — not optional, not gated on being asked for one:
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/build_branch_comparison_html.py" . \
--run-id <run-id> \
--template "${CLAUDE_PLUGIN_ROOT}/assets/branch-comparison-viewer.html" \
--d3 "${CLAUDE_PLUGIN_ROOT}/assets/inline-d3.html" \
--tokens "${CLAUDE_PLUGIN_ROOT}/assets/tokens.css"
This re-validates runs/<run-id>/state.json with the same guard state-write
used to accept it, recomputes Total and the winner from the 3 raw axes (never
trusts a stored field — none is persisted), and writes
.zirkel/runs/<run-id>/branch-comparison.html. Mention this path when
presenting the selected branch to the user.
Output
- branches (name + description)
- scores table: branch, Feasibility, Impact, Risk, Total, biggest blocker
- selected branch name + rationale
- path to the rendered branch-comparison report
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.