Ask va oracle

Ask VA Oracle

Use this skill when this Zo should consult a stronger partner Zo instead of spending local model tokens on deep reasoning.

The goal is deliberately simple:

1. Put large context in a URL-accessible place such as zopub, GitHub, a gist, or an internal file link the oracle can access.
2. Send a short, self-contained prompt to the partner Zo's /zo/ask endpoint using an access token.
3. Use the answer as planning guidance, LLM-judge output, debugging advice, or adjacent strategic thinking.

Do not build a relay system, bundle protocol, audit stack, or confidence-scoring framework unless the user explicitly asks for that heavier system.

Requirements

• A Zo access token for the oracle Zo, stored as an environment variable on the calling Zo.
• Recommended env var name: VA_ORACLE_TOKEN.
• Optional: a return token for the partner Zo to call back, stored only as a secret on the oracle Zo. Do not paste token values into prompts, files, logs, or Git.

When To Ask

Ask the oracle for:

• planning a multi-step task before the local Zo executes it
• judging or scoring candidate outputs against a rubric
• debugging after one or two local attempts have failed
• architecture or strategy tradeoffs where a stronger model is worth the spend
• adjacent thinking: "what am I missing?", "what is the best frame?", "what should I do next?"

Handle locally for:

• simple file edits
• obvious command syntax
• routine summarization
• tasks where all required context is tiny and low stakes
• actions that require local credentials, local UI state, or external writes

Context Transfer

Prefer URLs over pasted bulk.

Good context references:

• zopub collection URLs for files or folders
• GitHub blob, commit, issue, or PR URLs
• public docs, specs, and pages
• short inline excerpts when the relevant context is under about 100 lines

Bad context references:

• "you know the thing from earlier" without restating it
• massive pasted logs when a URL would work
• secrets, credentials, tokens, private keys, or unredacted sensitive records

If the oracle cannot access a URL, paste the smallest relevant excerpt and say what was omitted.

Basic Call

Use the token as a bearer token. Keep prompts self-contained because each /zo/ask call may start a fresh session unless a conversation_id is supplied.

curl -s https://api.zo.computer/zo/ask \
  -H "Authorization: Bearer ${VA_ORACLE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @- <<'JSON'
{
  "input": "You are advising a separate Zo instance. Task: ... Context: ... Return concise, executable guidance."
}
JSON

Model Selection

The calling Zo may request a specific oracle model per call by adding model_name to the /zo/ask JSON payload. Do not hard-code one model in the skill; make model choice explicit at the call site so the caller can trade off cost, speed, and reasoning quality.

Recommended caller behavior:

1. Accept a model alias from the local task or operator, such as default, fable, opus, or gpt-5.5.
2. Translate the alias to the exact model string supported by the oracle Zo.
3. Include model_name only when the caller intentionally wants to override the oracle default.
4. If /zo/ask rejects a requested model, preserve the error and retry once without model_name or with a configured fallback. Do not silently pretend the requested model was used.

Known example aliases for VA's oracle Zo:

Alias	model_name
default	omit model_name
fable	anthropic:claude-code-fable
gpt-5.5	openai:gpt-5.5-2026-04-23

Treat this table as configuration, not universal platform truth. A different oracle Zo may expose different model strings.

Example Fable request:

curl -s https://api.zo.computer/zo/ask \
  -H "Authorization: Bearer ${VA_ORACLE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @- <<'JSON'
{
  "model_name": "anthropic:claude-code-fable",
  "input": "You are advising a separate Zo instance. Task: ... Context: ... Return concise, executable guidance."
}
JSON

If the platform supports it for your token, include persona_id or conversation_id only when there is a concrete reason:

• persona_id: ask a specific oracle persona such as Debugger, Strategist, Writer, or Builder.
• conversation_id: continue a thread and avoid re-sending context.

When unsure, omit optional fields and let the oracle Zo use its configured default.

Prompt Templates

Planner

Use this when the local Zo needs an execution plan.

You are the planning oracle for a separate Zo instance.

Goal:
<one-sentence goal>

Context:
<short context or URL(s)>

Constraints:
<time, tools, files, external action limits, privacy constraints>

Return:
1. Recommended approach
2. Step-by-step execution plan the local Zo can follow
3. Key assumptions and unknowns
4. Risks and what to verify

Be concise. Do not perform external actions. Do not assume access to the local Zo's files unless they are included or linked.

Judge

Use this when the local Zo needs scoring, ranking, or critique.

Act as an LLM judge for a separate Zo instance.

Subject:
<what is being evaluated>

Candidate output(s):
<text or URL(s)>

Rubric:
<criteria, weights if any, acceptance bar>

Return:
1. Verdict
2. Score per criterion
3. Top 3 fixes, in priority order
4. Any disqualifying issue or uncertainty

Be decisive. Do not rewrite unless asked.

Debug Adviser

Use this when the local Zo is stuck or has failed twice.

You are debugging adviser for a separate Zo instance.

System expected:
<what should happen>

Observed:
<error, logs, screenshots, or URL(s)>

Already tried:
<attempts and outcomes>

Relevant files or docs:
<URLs or excerpts>

Return:
1. Most likely root cause
2. Evidence for that hypothesis
3. Smallest next test
4. If that test passes/fails, what to do next

Do not guess past the evidence. If context is insufficient, say exactly what evidence is missing.

Output Handling

The local Zo should treat oracle output as advice, not permission to mutate external state.

Before executing any irreversible, public, outbound, or credential-sensitive step, the local Zo must still follow its local operating policy and ask the user when required.

For useful reusable answers, save a short local note with:

• timestamp
• question
• context URL(s)
• oracle answer
• follow-up action taken

This can be a plain markdown or JSONL log. Do not create a complex audit system by default.

Token Discipline

• Send links instead of bulk text.
• Ask one clear question at a time.
• Reuse conversation_id for follow-ups when available.
• Ask for text-only answers unless structured JSON is genuinely needed by a script.
• Cache good plans and judge rubrics locally so they can be reused without another oracle call.

Security

• Never commit token values.
• Never print token values.
• Never send secrets in oracle prompts.
• Redact private customer, patient, employee, or financial data unless the user has explicitly authorized sharing it with the oracle Zo.
• Remember that zopub is public file sharing. Do not use it for sensitive context.

Minimal Success Test

Run a harmless connectivity check:

curl -s https://api.zo.computer/zo/ask \
  -H "Authorization: Bearer ${VA_ORACLE_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"input":"Reply with exactly: oracle-ok"}'

Expected result: the response contains oracle-ok.

If it fails, check:

1. VA_ORACLE_TOKEN exists in the calling Zo secrets.
2. The token has not expired or been revoked.
3. The request uses a bearer authorization header.
4. The endpoint is reachable from the calling Zo.