zeno

name	zeno
description	Evidence-first, read-only Zeno workflow for huge corpora via an external JSONL REPL server (list_files/read_file/peek/grep/extract_symbols). Minimize context bloat, prevent drift, and produce a cited architecture + audit report.

Zeno -- Read-only, Evidence-first

Core idea (1 paragraph)

The corpus (repo/docs/logs) is too large to paste into the model. Treat it as external environment state accessed through a JSONL REPL server. Retrieve only the minimum evidence needed (paths + small line ranges), optionally "recursing" by producing per-slice capsules, then consolidate into a report.

How this skill is triggered (and when to use it)

Zeno activates when the user explicitly asks for Zeno or names a mode. Common triggers:

• "Use Zeno codebase-archaeology to trace across the repo."
• "Run Zeno security-audit on src/ and build evidence chains."
• "Use Zeno architecture-mapping to document entrypoints and lifecycle."
• "Zeno pr-review these changed files: ... with downstream impact."
• "Zeno skill-generation on this repo and draft SKILL.md."
• "Zeno deep-research on this project question: ..."

Full use cases and mode details are defined in references/modes.md.

Non-negotiables (hard guardrails)

• READ-ONLY: never modify files. Never propose "just change X" unless user explicitly requests edits later.
• No evidence, no claim: every non-trivial statement must cite evidence as path:Lx-Ly or a grep hit.
• Small bites: prefer peek + targeted read_file slices over whole-file reads.
• Be deterministic: when unsure, retrieve more evidence; do not guess.

Tools available (only these ops)

• list_files(args: {glob|regex, max, include_hidden, exclude_dirs, exclude_globs, max_files})
• peek(args: {path, head_lines, tail_lines})
• read_file(args: {path, start_line, end_line, max_lines})
• grep(args: {pattern, paths?, max_hits, context, include_hidden, exclude_dirs, exclude_globs, max_files, max_bytes})
• extract_symbols(args: {path, max_symbols})
• stat(args: {path?, paths?})

Budgets (to prevent tail-cost blowups)

You MUST enforce these caps unless user explicitly requests deeper coverage:

• Retrieval ops: <= 30 total per answer, <= 12 per section
• read_file: <= 400 lines per call, <= 2000 lines total returned across the whole answer
• grep: <= 200 hits, always narrow with paths or a more specific pattern if truncated
• Recursion (capsules): <= 12 file capsules, depth <= 2 (capsule -> sub-capsule), then consolidate
• If you hit any budget: STOP, summarize, and output Next Retrieval Plan (max 10 ops)

Default excludes (reduce noise)

Unless user requests otherwise, pass these as excludes when listing/grepping:

• exclude_dirs: [".git",".hg",".svn",".venv","venv","node_modules","dist","build",".next",".turbo",".cache",".pytest_cache"]
• exclude_globs: ["/.min.","/*.map","/generated/","/vendor/"]

---

Mode profiles (choose one when asked)

Zeno supports six explicit modes. Pick the closest mode when the user asks for one of these outcomes. If unsure, ask a brief clarifying question and default to architecture-mapping.

Mode quick selector:

• codebase-archaeology: trace a symbol across a monorepo with file:line citations.
• security-audit: pattern-based vulnerability triage with evidence chains.
• architecture-mapping: lifecycle and boundary mapping without losing context.
• pr-review: full-context review for large diffs and ripple effects.
• skill-generation: draft SKILL.md from a new tool's codebase with citations.
• deep-research: evidence-first research report without hallucination.

Mode selection workflow:

1. Confirm the mode and required inputs (symbol name, changed_files, or research question).
2. Announce budgets and scope explicitly.
3. Use the default retrieval plan for the chosen mode (see references/modes.md).
4. Produce the standard Output schema plus mode-specific add-ons below.

If the user asks for multiple modes, run them sequentially and keep evidence ledgers separate per mode.

---

Operating procedure (the playbook)

Phase 0 -- Frame the task (always do this)

1. Restate the user's goal in 1-2 lines.
2. Declare budgets you'll enforce.
3. Declare what "done" looks like using the Output Schema below.

Phase 1 -- Repo map (fast scan)

Goal: build a working mental index without reading everything.

1. list_files (glob) for key file types (language + configs).
2. Identify likely entrypoints + orchestration files:
   • build manifests (Package.swift, package.json, pyproject.toml, Cargo.toml, etc.)
   • app bootstrap (main., App, AppDelegate/SceneDelegate, CLI entry)
   • routing (router, routes, navigation)
   • dependency injection / wiring (container, module, registry)
3. peek the top candidates to confirm relevance.

Phase 2 -- Entrypoints and lifecycle (evidence-backed)

Goal: answer "what runs first" and "how requests/events flow."

1. grep for entry symbols ("main", "App", "init", "run", "serve", "router", "register", "bootstrap").
2. read_file only the line ranges that define:
   • startup sequence
   • primary event loop / request loop
   • global configuration loading
3. Capture evidence excerpts for the lifecycle narrative.

Phase 3 -- Wiring map (dependencies + boundaries)

Goal: map interactions without pretending you read the whole repo.

1. For each core module/file:
   • extract_symbols
   • grep for imports / references to/from it
   • read_file only the minimal blocks that show how it is called and what it calls
2. Produce a wiring edge list: A -> B (why) with evidence.

Phase 4 -- Cross-cutting audits (security / concurrency / dead code)

Goal: detect "unpriced risk" areas with evidence. Use focused greps and short reads:

• Security: auth checks, token parsing, crypto usage, secrets, unsafe eval, injection risks
• Concurrency: shared mutable state, locks, async boundaries, cancellation, reentrancy
• Dead/orphan: unused symbols, duplicate modules, old feature flags, unused routes
• Layering: cycles, "UI calls DB directly", config scattered, global singletons

If you cannot prove something, move it to Open Questions.

Phase 5 -- Consolidate and deliver

Stop retrieving when:

• you have entrypoints + lifecycle + top-level module map
• additional retrieval mostly repeats patterns
• budgets are close to limit Then produce the report with strict schema + claim-evidence ledger.

---

Output schema (STRICT)

1) Executive Summary

• What this system is (1-2 lines)
• Primary entrypoints
• 3-8 key architectural facts (each with evidence IDs)

2) System Map (Lifecycle Narrative)

• Startup sequence (ordered steps)
• Main runtime loop / routing
• Configuration and environment assumptions (Each step must cite evidence.)

3) File Capsules (table)

Columns:

• File
• Role / responsibility
• Key symbols
• Calls into / calls out
• Risks / smells
• Evidence

4) Wiring Map (edges)

List A -> B edges with short explanation + evidence.

5) Risks and Smells (prioritized)

For each:

• Severity (High/Med/Low)
• What could go wrong
• Where seen (evidence)
• Suggested next evidence to confirm or refute

6) Evidence Ledger (required)

List evidence items only (no claims in this section). Each evidence entry must include the location and a one-line rationale for why it supports a claim. Evidence items must be formatted:

• E1 = path/to/file.ext:L10-L44
• E1_why = One-line reason this excerpt supports a claim.
• E2 = grep(pattern="AuthMiddleware", hit=src/security.py:L123)
• E2_why = One-line reason this grep hit supports a claim. Optional: group evidence by file when it improves readability.

7) Claim Ledger (required)

Map claims to evidence IDs:

• C1: -> [E1, E3]
• C2: -> [E2]

8) Open Questions + Next Retrieval Plan

• Open questions (only those lacking proof)
• Next retrieval plan (max 10 ops, each fully specified)

---

Mode-specific add-ons (required)

When a mode is active, include these extra sections in the report. These do not replace the standard Output schema.

codebase-archaeology add-ons

• Definition capsule: file, signature, and minimal excerpt with evidence IDs.
• Usage table: path, line, short context, evidence IDs.
• Coverage statement: files scanned, grep hits, read lines.

security-audit add-ons

• Risk table: severity, pattern, file:line, evidence IDs.
• Evidence chains: Source -> Validation -> Sink (if visible), each step cited.
• Remediation questions: what to verify next, with retrieval plan items.

architecture-mapping add-ons

• Component map: components, responsibilities, and boundaries with evidence.
• Lifecycle narrative: ordered steps with evidence IDs.
• Cross-cutting concerns: auth, storage, telemetry, config.

pr-review add-ons

• Change summary: what changed and where, with evidence IDs.
• Impact map: changed file -> dependents with evidence.
• Test coverage notes: existing tests or gaps with evidence.

skill-generation add-ons

• Draft SKILL.md (inline) with citations for key claims.
• Allowed tools policy and guardrails based on evidence.
• Open questions where docs are missing.

deep-research add-ons

• Claim ledger with confidence and evidence IDs.
• Evidence snapshot list (files and sections read).
• Open questions and next retrieval plan.

---

Mandatory end-of-turn blocks (Pattern A)

At the end of every response while this skill is active, append the three machine-parseable blocks below. These are consumed by notify_persist.py on agent-turn-complete to persist state, evidence, and claims.

Hard rules:

• The blocks must be valid JSON/JSONL with no commentary inside.
• The blocks must appear in the exact order below.
• Do not include trailing commas.

Required format:

===ZENO_STATE_UPDATE_JSON===
{ "thread_id":"T1", "turn_id":"U4", "mode":"read-only", "budgets":{"retrieval_ops_max":30,"retrieval_ops_used":12,"read_lines_max":2000,"read_lines_used":740,"grep_hits_max":200,"grep_hits_used":55}, "high_level_summary":"Mapped entrypoints and routing", "open_questions":["Where is auth middleware registered?"], "next_retrieval_plan":[{"op":"grep","args":{"pattern":"Auth","paths":["**/*.py"],"max_hits":50},"purpose":"Locate auth wiring"}] }
===/ZENO_STATE_UPDATE_JSON===

===ZENO_EVIDENCE_LEDGER_JSONL===
{"evidence_id":"E1","kind":"read","path":"src/app.py","lines":[10,44],"why":"Defines the FastAPI app construction","hash":"","timestamp":"2026-01-04T18:11:30Z"}
{"evidence_id":"E2","kind":"grep","pattern":"AuthMiddleware","hit":"src/security.py:L123","why":"Shows auth middleware registration","hash":"","timestamp":"2026-01-04T18:11:30Z"}
===/ZENO_EVIDENCE_LEDGER_JSONL===

===ZENO_CLAIM_LEDGER_JSONL===
{"claim_id":"C1","claim":"App starts in app.py with FastAPI","evidence":["E1"],"confidence":"high","timestamp":"2026-01-04T18:11:30Z"}
{"claim_id":"C2","claim":"Auth middleware registers in security.py","evidence":["E2"],"confidence":"med","timestamp":"2026-01-04T18:11:30Z"}
===/ZENO_CLAIM_LEDGER_JSONL===

If you are missing any field, leave it as an empty string or empty list rather than omitting the field.

---

Pattern A persistence (notify checkpoints)

The notify hook writes state and ledgers after every turn. This is the authoritative checkpoint when telemetry is unavailable. Follow the block format exactly so notify_persist.py can extract and persist data to .codex/zeno/ under state/, evidence/, and claims/.

---

Pattern B telemetry (OTEL)

If OpenTelemetry is enabled, tool-level events are exported to an OTEL collector for audit and replay. Default privacy: otel.log_user_prompt = false unless the user explicitly asks to enable prompt logging.

---

NON-NEGOTIABLE: Read the full manual

Before using Zeno in a real task, you MUST read the full manual and follow it. This SKILL file is intentionally dense; the references are the source of truth.

Read these in order:

• references/modes.md (mode specs and required add-ons)
• references/operator_instructions_and_review.md (operator-grade rules)
• references/recipes.md (copy/paste retrieval plans)
• references/protocol.md (JSONL REPL protocol)
• references/security.md and references/otel.md

---

Anti-drift checklist (run before finalizing)

• Did I exceed budgets? If yes, did I stop and provide next plan?
• Does every non-trivial claim map to evidence?
• Did I accidentally assume behavior not supported by retrieved lines?
• Is the report complete per schema, even if partial coverage is noted?

---

Improvements and extensions (do not skip if asked to extend the skill)

Evidence registry (mechanical)

Maintain an evidence registry while working:

• E1, E2, E3, E4 each is a path + line range or a grep hit. Then output a Claim Ledger (separate from the Evidence Ledger):
• C1 -> [E1, E4]
• C2 -> [E2] If you cannot attach an E#, the statement must become an Open Question.

Stop rules (prevent infinite exploring)

Stop retrieval and write the report when:

• you have entrypoints + lifecycle + top module map
• additional retrieval repeats the same patterns
• you are within 20 percent of any budget Always include Open Questions + Next Retrieval Plan.

Failure-mode playbooks

• grep truncated -> narrow by paths and specificity
• big file -> peek then targeted read_file slices
• uncertainty -> Open Questions + next 3-10 retrieval ops

Coverage report (required when sampling)

Include explicit coverage numbers:

• files sampled
• greps executed
• lines read total
• list_files filters applied

Subcall templates (for recursion)

File capsule:

• Purpose (1-2 sentences)
• Key types/functions
• Imports and dependencies
• Internal dependencies (callers/callees)
• Risks: security, concurrency, error handling
• TODO/dead code signals
• 3-8 evidence excerpts (line ranges)

Wiring map:

• Lifecycle order
• Runtime path narrative
• Dependency edges (A -> B)
• Cyclic risks

Determinism and safety

• Never read outside --root.
• Sort paths and hits.
• Respect max_files and max_bytes to avoid huge scans.
• Prefer literal grep patterns unless regex is required.

References

• references/protocol.md
• references/operator_instructions_and_review.md
• references/recipes.md
• references/data_model.md
• references/security.md
• references/otel.md
• references/troubleshooting.md

Acknowledgments

This skill is inspired by and references:

• Zhang et al., "Recursive Language Models" (arXiv:2512.24601v1): https://arxiv.org/abs/2512.24601v1
• Alex Zhang's reference implementation: https://github.com/alexzhang13/rlm
• Original announcement thread: https://x.com/a1zhang/status/2007566581409144852?s=46

Thank you to Alex Zhang and collaborators for the Zeno concept and open resources that informed this work.