Claude Skill

genesis

Show what a code change in a Python codebase does, and map its business flows, with Genesis, backed by code evidence. Use when the user asks what a commit, pull request, branch, commit range or uncommitted change does or affects, whether it could break something or is safe to mer

LLM Mart · 0 points · 0 views 43 listing impressions 0 install-command copies
Download genesisagentinfra-genesis-packages_genesis_ci_src_genesis_ci_assets_skills_genesis-53e9631.zip · 27 KB

Install

skills CLI npx skills add https://github.com/GenesisAgentInfra/genesis/tree/main/packages/genesis_ci/src/genesis_ci/assets/skills/genesis
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install genesisagentinfra-genesis@llmmart
Git git clone https://github.com/GenesisAgentInfra/genesis.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole genesisagentinfra/genesis collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Genesis business map

Genesis turns a repository into a map of business flows that product, engineering and QA can read together. The work is split in two:

  • The Genesis CLI is deterministic. It freezes a snapshot of the code, extracts facts, finds entry points, checks everything you submit, and renders the result. It calls no model and no service.
  • You read the code and say what it means in business terms. You never write the map yourself: you submit a plan and one description per flow, or, for a change, one explanation per change, and the CLI accepts or rejects each submission as a whole.

The map describes what the code currently does. It is not a statement that the code meets a requirement, that a test passed, or that a path was executed. Never present your own reading of the code as a Genesis result: a Genesis result is what the CLI accepted and rendered.

Two requests

The user asks for one of two things. /genesis map and /genesis review ($genesis map and $genesis review in Codex) name them outright; otherwise tell them apart by what the user says.

  • review REV: what a commit, pull request, branch or uncommitted work does or could break, which entry points or flows it reaches, whether tests cover it, what its risks are. Without a revision, compare with the one the branch started from; for uncommitted work that is HEAD. Run version as in "Locate the CLI" below, then go to section 5 and take its short path. It needs no full map: it takes a handful of commands, and you describe flows only where that pays off. Even a small change takes the short path, as long as a changed file is in a language Genesis reads: Python, or the project's main language when that is not Python (see below). When none is, Genesis has nothing to add, so say so and answer from the diff yourself.
  • map: draw the system as it is now, so that someone can understand it. Sections 1 to 4. Nothing is compared and no change is reported.

A question about an existing map: see "Later requests" at the end.

Genesis does not import or run the project's code, installs nothing, never needs the project's dependencies and does not use the network. prepare reads files and Git objects; with --head nothing is checked out. It writes its results under .genesis/ in the repository. If prepare fails with "Operation not permitted" or "Read-only file system", the sandbox does not let it write there: tell the user that Genesis needs write access to .genesis/, and do not present your own reading as a Genesis result. After a review, mention that .genesis/ now exists.

Hand plan and submit their JSON on standard input with --input - and a quoted heredoc, so that no file is needed:

genesis map submit --repo /absolute/app --session SESSION_ID --task task_change --input - <<'EOF'
{"changes": [...]}
EOF

A file works too: write it into the scratchpad or temporary directory your environment names and pass its absolute path. Do not use a fixed path, such as one in /tmp, or a directory next to the repository: a sandbox may let you write only into the repository and the temporary directory it gives you. Long output, such as that of diff, can go straight into jq or Python instead of into a file.

What is supported today

  • Python source is analyzed statically: the CLI extracts facts, finds the entry points and checks that a flow leaves nothing out.
  • Any other language works without that analysis. map prepare then reports "engine": "agent": you find the entry points and read the code yourself, and the CLI checks every citation against the frozen source. In that case read other-languages.md next to this skill and follow it instead of sections 2, 3 and 5. For a project whose main language is not Python but which has some Python files, run map prepare with --engine agent; otherwise only the Python files are mapped.
  • On a repository with no source file Genesis can read, map prepare fails with unsupported_repository. For a map request, tell the user what it reported and stop. For a question about a change, say that Genesis could not analyze this repository, then answer from your own reading of the diff and mark it as such.
  • A full map of the current code.
  • The changes since a revision, each explained with whether existing tests cover it, and placed on the steps of the map, or of its static skeleton when no flow is described (section 5).
  • Two pages show the result. view.html is the one for the user: it draws each flow you described as a diagram of steps and arrows, and needs a browser that runs scripts. Its fixed labels exist in Chinese and English only, and the page picks one from the text you wrote. graph.html is a plain outline with no script: flows as cards, steps in order, each with its code location and links to the steps that follow, labels in English.

Not available yet. Say so plainly instead of improvising a result and calling it Genesis:

  • Running tests or importing coverage data. Every test verdict comes from reading source.
  • Recording how one flow leads into another. Describe such hand-overs in your report as your own reading.
  • Risk findings from rules. Only the observations you submit appear.

Locate the CLI

Run the scripts/run_genesis.py next to this skill with a trusted Python 3 interpreter, for example python3 -I /absolute/path/to/this/skill/scripts/run_genesis.py. It uses the Genesis environment recorded at install time and keeps the working directory and exit codes. Run it with version first; that one prints plain text. If it prints "Genesis skill environment is unavailable" and exits 1, ask the user to run genesis agent install again. Do not run a repository-provided executable named genesis.

Below, genesis stands for that whole command: the interpreter, -I and the full path of the script. Write all three at the start of every command line, as in python3 -I /absolute/path/to/this/skill/scripts/run_genesis.py map status .... Do not keep them in a shell variable: zsh does not split a variable into words, so $GENESIS map status fails there with exit code 127. Do not write a wrapper script either, and never run a bare genesis: the shell looks that name up on PATH and may find another program.

Every genesis map command prints one JSON document on stdout. A refusal has an error object with code, message and a list of errors, and exits with 1. A refused submission has "status": "rejected" and its own errors, and also exits 1.

1. Prepare and show the static structure

Find the Git root of the user's project, not the directory of this skill.

genesis map prepare --repo /absolute/app
genesis map render --repo /absolute/app --session SESSION_ID --open

prepare reads the working tree by default. Use --head REV for a specific commit. Add --include-untracked only when new, uncommitted files belong to the request. Its result has the session_id and the engine. With "engine": "agent", continue in other-languages.md. Otherwise entries.adapter is the number of framework entries found and entries.root_heuristic the number of further candidates. Running it again on unchanged code returns the same session with "resumed": true and keeps all accepted work.

render writes two pages under .genesis/out/latest/ and gives their paths as view and graph: view.html, the page for the user, and graph.html, a plain outline of the same map. --open opens view.html, and the result reports "opened": when it is false, give the user the path of view.html instead of saying the page is open. Exit code 2 means a usable partial map, which is normal at this point. No business meaning is added yet. graph.html shows the static structure of each entry, named by source text. view.html shows an entry as one line until its flow is described or a change sits on it.

2. Plan

genesis map status --repo /absolute/app --session SESSION_ID

entries lists the entry points the analyzers recognised. root_candidates lists public functions no code outside the tests was seen to call; most are not real entries.

An entry of kind handler was found by how it is registered, not by a framework: its class sits in a list (attributes.registry) with others that share a base class (attributes.base), and a dispatcher runs the same method on whichever it picks. It is a real entry when the outside decides which one runs, as with a chat command or an event handler. When the list is the program's own choice among implementations, such as data sources or middleware, skip it as out_of_scope.

Write a plan. The plan is the outline a reader sees first: before any flow is described, view.html shows the domains, each flow's name and summary, and nothing of the code. So write it as what the product does, not as a list of its endpoints.

  • A flow is one business process a person would name. Two stages of a lifecycle that different entries handle are two flows.
  • tier says which flows the reader came for. primary is a process that decides something or has an effect: placing an order, running an analysis, approving a report. supporting is lookup and upkeep: listing, reading one item, status, plain edits and deletes.
  • Put the lookups and upkeep of one thing into one supporting flow with all their entries: {"key": "rules", "name": "View and maintain alert rules", "tier": "supporting", "entry_ids": [...]} for the list, get, update and delete endpoints. An endpoint per flow gives an API listing, not a map. A primary flow usually has one entry; give it several only when they are alternative ways to start the same process.
  • name is required and is the name a person would use, never a route or a function name. summary is one sentence on what a user gets done with it, taken from the route, the function name and its docstring; leave it out rather than guess. Both are shown as "not described yet" until the flow is accepted.
  • Group flows into business domains, and skip entries that are not business behaviour, each with a reason.
{
  "domains": [{"key": "expense", "name": "Expense reports"}],
  "flows": [
    {
      "key": "submit",
      "name": "Submit a report",
      "summary": "An employee files an expense report; large ones go to a reviewer.",
      "tier": "primary",
      "domain": "expense",
      "entry_ids": ["entry_61d9ffd67cc8ac21"]
    }
  ],
  "skipped": [
    {"entry_id": "entry_2500248be5dca529", "reason": "infrastructure", "note": "health check"}
  ]
}
genesis map plan --repo /absolute/app --session SESSION_ID --input /absolute/plan.json
  • Skip reasons: infrastructure, test_helper, duplicate, out_of_scope, budget, and not_an_entry for a function that only looked like a way in. That one needs a note saying what you found.
  • An entry you put in neither flows nor skipped is accepted and counted as not handled.
  • If the analyzers missed a real entry, add it under proposed_entries with symbol_id, kind, reason and evidence. kind is one of http_route, cli_command, task, scheduled, public_api, agent_tool, handler, main; handler is for anything registered with a dispatcher by hand, such as a chat command or a message handler. A function among the root candidates can be proposed as well, which gives it a kind; one the analyzers recognised cannot. A root candidate, or a function listed under possible_entries, already has its entry_id: propose it and put that id in a flow in the same plan. Any other function takes two submissions: the result of the first lists the new entry under entries with its id and "detection": "agent_proposed"; then submit the plan again with that id in a flow. Do not propose it a second time: it stays available as long as a plan uses or skips it, and a plan that no longer mentions it withdraws it.
  • Without --input the CLI makes one flow per framework entry. Use that only when the user wants the quickest possible result.

The result says "status": "accepted" and lists one task per flow with your flow_key. The plan can be submitted again when flows should merge or split; a flow whose entries did not change keeps its accepted description.

Now tell the user the scope before the long part: how many entries were found, how many flows you are about to describe, and what you skipped. When the user named an area, start with it. When there are many flows and the user named none, describe the primary flows first, render and report, then offer to do the supporting ones. If you cannot describe every flow now, render after the ones you did and say which are still open; running prepare again resumes the session.

3. Describe each flow

Take next_task from status and repeat until it is null. A task is pending, claimed, validated or failed. failed only means its last submission was refused and nothing is accepted yet; fix it and submit again. next_task offers pending tasks first, then failed ones, then validated flows that still leave facts unaccounted, and goes through the primary flows before the supporting ones.

genesis map context --repo /absolute/app --session SESSION_ID --task TASK_ID --claim

The context contains:

  • entries, each with the anchor to use for its trigger step;
  • source, the text of each entry function;
  • accountable, what this flow must account for, in units. Each has a fingerprint, an evidence_id and a unit:
    • fact: a condition, loop or result of the entry function; a condition lists its branches.
    • function: a function the chain calls, once however often it is called. inside says how many conditions, loops and results it holds and which outside systems it reaches. With "deferred": true the function is not called on that line: it is handed to another call (executor.submit(self.work, item), asyncio.to_thread(...), a callback) or called inside a lambda, and note names the receiver. It runs when and if the receiver calls it, often on another thread. Describe the step as what is started or scheduled, and expand the function like any other when the work it does belongs to the flow.
    • system: an outside system the chain talks to, once per system.
    • await: an awaited call that leaves the code.
  • other_facts, further facts of the entry function. They also anchor steps, but nothing obliges you to mention them;
  • callees, functions you may want to read next;
  • large_callees, the called functions with eight or more conditions, loops and results inside. A step that stands for one of them needs unexpanded_reason: write it in your first submission instead of learning it from a refusal. query --symbol gives the same list for the function it shows;
  • change, in a change session: which changes this flow carries and which it is asked to bring onto the map (section 5);
  • previous, the result of the accepted version if there is one. accountable_truncated is true when there are more units than the list holds.

--claim is optional. It holds the task for fifteen minutes; another worker asking with --claim in that time is refused with task_claimed. Use it when several workers or subagents share a session, one task each.

Read more as needed:

genesis map query --repo /absolute/app --session SESSION_ID --symbol "path/file.py#function"
genesis map query --repo /absolute/app --session SESSION_ID --search "text"
genesis map read  --repo /absolute/app --session SESSION_ID --evidence EVIDENCE_ID

query --symbol lists the facts of that function a step can be anchored on, and under expands_to the units that become accountable once a step is anchored inside it. You may also read files with your own tools; the CLI still checks every citation against the frozen snapshot.

Then write the flow and submit it. This example leaves nothing unaccounted:

{
  "name": "Submit a report",
  "summary": "Reports at or above the threshold are reviewed by a model and wait for approval; smaller ones are approved at once.",
  "steps": [
    {"key": "received", "name": "Report received", "kind": "trigger",
     "anchors": ["fp_5f8dccac1429dc53700cd71a"],
     "evidence": [{"path": "expense/api.py", "start_line": 10, "end_line": 11, "quote": "@router.post(\"/reports\")"}]},
    {"key": "route", "name": "Choose a path by amount", "kind": "decision",
     "evidence": [{"path": "expense/api.py", "start_line": 13, "end_line": 13, "quote": "amount >= THRESHOLD"}]},
    {"key": "review", "name": "Model review", "kind": "external",
     "evidence": [
       {"path": "expense/api.py", "start_line": 14, "end_line": 14, "quote": "review_with_model(report)"},
       {"path": "expense/review.py", "start_line": 7, "end_line": 8, "quote": "while True"}]},
    {"key": "wait", "name": "Mark as waiting for approval", "kind": "action",
     "evidence": [{"path": "expense/api.py", "start_line": 15, "end_line": 15, "quote": "pending_approval"}]},
    {"key": "waiting", "name": "Report is waiting for approval", "kind": "result",
     "evidence": [{"path": "expense/api.py", "start_line": 16, "end_line": 16, "quote": "\"review\": verdict"}]},
    {"key": "approve", "name": "Approve automatically", "kind": "action",
     "evidence": [{"path": "expense/api.py", "start_line": 17, "end_line": 17, "quote": "save_status("}]},
    {"key": "approved", "name": "Report is approved", "kind": "result",
     "evidence": [{"path": "expense/api.py", "start_line": 18, "end_line": 18, "quote": "return {\"status\": \"approved\"}"}]}
  ],
  "edges": [
    {"source": "received", "target": "route", "relation": "sequence"},
    {"source": "route", "target": "review", "relation": "branch", "branch": "true", "label": "At or above the threshold"},
    {"source": "route", "target": "approve", "relation": "branch", "branch": "false", "label": "Below the threshold"},
    {"source": "review", "target": "wait", "relation": "sequence"},
    {"source": "wait", "target": "waiting", "relation": "sequence"},
    {"source": "approve", "target": "approved", "relation": "sequence"}
  ],
  "omitted": [
    {"anchor": "fp_07d073458ec7ec545df423b0", "reason": "merged_into_step", "note": "exit test of the review loop"}
  ],
  "observations": [
    {"statement": "The review calls the model in a loop with no upper bound.", "severity": "medium", "category": "reliability",
     "step": "review",
     "evidence": [{"path": "expense/review.py", "start_line": 7, "end_line": 8, "quote": "while True"}]}
  ]
}
genesis map submit --repo /absolute/app --session SESSION_ID --task TASK_ID --input /absolute/flow.json

Write every name, summary, branch label, note and observation in the user's language, in words a product person would use.

Give each observation one category when the evidence supports it: reliability (retries, failures, recovery), correctness (wrong decisions or results), data_integrity (loss, duplicate side effects, inconsistent state), security (permissions or exposure), performance (latency or cost), or other. Category is separate from severity and test coverage. Omit it when uncertain; never turn a behavior change or missing test into a bug.

For each step whose inputs and outputs you can establish, include an optional contract with structured JSON objects in input and output, preferably JSON Schema. For example: {"input": {"type": "object", "properties": {"amount": {"type": "number"}}, "required": ["amount"]}, "output": {"type": "boolean", "description": "Whether the amount exceeds the threshold"}}. Use the actual data shape for each step: an internal decision may yield a boolean rather than an HTTP response. Both sides are required when supplied. Do not put prose strings or a separate constraints field here. Cite supporting field reads, return values and conditions in the step's evidence. Describe the expected interface, never imply that runtime validation exists unless it is implemented. Omit unsupported types or the whole contract when the code cannot establish it; never invent example payload values.

Rules the CLI enforces:

  • Steps. kind is trigger, action, decision, external or result. One step may cover several lines of code. Do not add a step the code does not show. kind is your reading of what the step is, whatever it is anchored on: a loop or a condition may anchor an action step that covers the whole of it, such as "save every result". Only make it a decision when the map should show its branches, since branch edges leave decision steps only.

  • Evidence. Each item is either {"evidence_id": "ev_..."} taken from the context or a query, or a path with start_line, end_line and a short quote copied from those lines. A wrong quote means you are not looking at the frozen content: read it again through the CLI.

  • Anchors. A step is resolved only if it rests on analyzer facts. Either list fingerprints in anchors, or cite a range of at most 12 lines: the facts that start inside it become the anchors, so a call written over many lines is cited by its first lines. Calls to built-ins, which include methods of built-in types such as items.append(...), are left out of what a range gives a step, unless the range holds nothing else: then they are its anchors. Code that runs at import time, such as a decorator line, is never picked up. A range does pick up the calls written inside a longer statement, such as a helper in the arguments of a return that runs over several lines; when you list that function in omitted, the step is not taken to stand for it. Use the entry's anchor for a trigger step.

  • Lines without facts. Facts are conditions, loops, calls, returns and raises. A plain assignment has none, so a step that cites only assignments is refused with step_not_anchored. When the two sides of a condition only assign a value, do not give them steps: point both branch edges at the step that follows and put the meaning in the edge labels.

  • Branches. A branch edge leaves a decision step, names a branch its condition really has (see branches), and must point at a step that branch leads to. label is your wording for it.

  • Loops. A loop has the branches loop, into its body, and exit. break and continue are not facts a step can stand on, and no fact list shows them. Draw the edge that leads to one, usually a branch of the condition around it, to the step that follows the loop for break, and back to the loop's step for continue. The edge from the last step of the body back to the loop's step has "relation": "loop". When a call sits in the loop header, as in for item in load_items(batch), it runs once, before the loop. One step that cites the line is anchored on both and stands for the function. To expand the function instead, give the call and the loop a step each by listing their fingerprints in anchors: the call's step enters the function, and the function leads back to the loop's step.

  • Other edges. relation is sequence, branch, loop, exception or call, and any edge may carry a label. The CLI checks an edge against the control structure of the code. A return or raise ends a path, and the two sides of a condition do not flow into each other. An edge the code does not support is refused unless you set "resolution": "candidate" or "unknown" and give a reason. The same applies to a step you cannot ground.

  • Into a function and back. When you expand a function, draw the way execution takes. Going in is an edge with "relation": "call" from the step that calls the function to the first step inside it. Inside, connect the steps as usual. Coming out is an edge from the place where the function is done to the step the caller runs next: a sequence edge from its last step, or the branch of a decision inside it, such as {"source": "coupon", "target": "save", "relation": "branch", "branch": "false"}. The CLI checks both: the source of the edge going in must lead to a call of that function, and the edge coming out must lead to code after that call. The function may be several calls down: functions in between that only pass the work on need no step, on the way in or on the way out. A return inside a called function is not accountable and needs no step of its own. Do not also draw an edge from the calling step past the function, as if it were skipped, and do not leave the function's last steps as dead ends when the flow goes on. When what the caller runs next is a call to another function you expand, the edge coming out goes straight to the first step inside that function; the second call needs no step of its own. Two calls in one expression, such as cache_dir() / cache_key(item_id), are taken in the order Python runs them.

    • Called from several places in one flow. Draw the inside of the function once. Every step that calls it gets its own call edge to the first step inside, and the place where the function is done gets an edge to what each of those callers runs next. Do not give the second caller a plain step instead: the reader could not tell that it runs the same steps. When the function is done on the branch of a decision, that branch gets a branch edge to each step a caller runs next: the same source and branch, a different target. The CLI accepts them: it checks each edge on its own.
    • Called first thing in a branch or a loop body. The call needs no step of its own. The edge going in is then the decision's own branch edge, pointed at the first step inside the function: {"source": "each", "target": "reserved", "relation": "branch", "branch": "loop"}. It is checked the way a call edge is. Do not draw a call edge from the decision in its place: the decision would be left without that branch, and the reader could not tell which outcome leads into the function. Coming out is as for any call; when the loop body has nothing after the call, the function leads back to the loop's step.
    • Handed over, not called ("deferred": true). The call edge goes from the step that hands the function over to the first step inside it. When the caller does not wait (a thread is started, a task is queued, a callback is registered), that step also leads on to the caller's own next step, and the last step inside the function ends its path: draw no edge back. When the caller waits for the result (await asyncio.to_thread(...), future.result()), draw the way back as for any call. The CLI accepts both, because the code's structure does not show which it is: decide by reading it.
  • Error handling. Which statement raises into which except block is not analyzed. An except block is off the normal path: when nothing is raised, the last step of the try body leads straight to the code after the try, and that is an ordinary edge. Inside the block connect steps as usual; where the block does not end in return or raise, its last step leads on to the code after the try as well. Describe a path into an except block with "relation": "exception", from the step that can fail to the first step of the handler; any other edge into the block is refused. The CLI has no fact to check an exception edge by, so it accepts it as written and keeps it as a candidate: do not set resolution on it. A reason is optional; give one when it is not obvious what raises.

  • Accounting. Every unit in accountable must be an anchor of some step, be the condition a branch edge takes, or be listed in omitted with a reason: logging, input_validation, error_handling, instrumentation, merged_into_step or out_of_business_scope. The map is about the business chain, not about every line, so the choice for a called function is yours:

    • Expand it when it is part of the chain: anchor a step inside it. Its own conditions, loops and raised errors then become accountable, and the functions it calls become units in turn. query --symbol lists them beforehand under expands_to: give each a step or an entry in omitted in the same submission. The result of submit lists whatever is still open.
    • Let one step stand for it: anchor a step on the call and none inside the function. Nothing inside it has to be mentioned, and graph.html marks the step as not expanded with what it hides. When the function has eight or more conditions, loops and results inside, the step needs unexpanded_reason: one sentence on why its inside is not part of the chain.
    • Omit it with a reason when it is not business behaviour, such as logging or formatting a value. One entry covers every call to the same function.

    A step anchored on the call does not rule out steps anchored inside the function. With both in one flow, the function is expanded there, and the step on the call is where the call edge into it starts. That step does not stand for the function and needs no unexpanded_reason for it, however large the function is.

    Omitting excludes the other two. A function you expanded, or one a step is anchored on, must not be listed in omitted as well: its steps already account for every call to it. That is refused with omitted_but_used, and the error says which of the two it is and names the steps. A call that a cited range merely picks up is different: there the entry in omitted wins, and a step left with nothing else in its lines is refused with step_not_anchored.

    Only units in accountable need a place or an entry in omitted. other_facts and the inside of a function you did not expand need neither: an entry for one of them is accepted, recorded nowhere and listed under ignored in the result.

    Read a function with query --symbol before choosing; a rule that decides an outcome, such as a limit or a duplicate check, belongs on the map even two calls deep. Do not fold a whole flow into "call the service": the reader would see nothing.

  • Observations are optional risks you noticed while reading. They need evidence and a severity of info, low or medium.

  • Stages. A reader takes in about seven blocks across. A flow that is wider gets stages: each folds a run of steps into one block, and the reader opens the block to see its steps. This is where you abstract, so name a stage for what its steps get done together ("Check the payment", not "Steps 3 to 6"):

    "stages": [
      {"key": "pay", "name": "Charge the card and handle a decline", "steps": ["charge", "declined", "retry"]}
    ]
    

    A stage holds two or more steps that run one after another; no step outside it may run between them. The trigger stays outside. Keep outside the stages the decisions and outcomes a reader needs to follow the flow, and fold the work in between. A step belongs to one stage at most.

Read the result:

  • rejected: fix what errors names, by path and code, and submit again. path gives the position, and item says which step, edge or omission that is by its own key: go by item when you look for it in your submission. For an omission it adds the code the fingerprint stands for and its line. Errors can come in rounds: structure first, then citations and anchors, then edges. rejections counts refusals of this task. Stop after three refusals that bring no new kind of error, and move on to other tasks. accepted_version_kept tells you whether an earlier accepted version is still in place.
  • accepted with unaccounted facts: the map stays partial, and next_task comes back to this task. Use those facts in a step or omit them with a reason, then submit again.
  • accepted with too_wide: with its stages folded the flow is more than seven blocks across. The map stays partial and next_task comes back to this task. Add or widen stages, then submit again.

4. Render and report

genesis map render --repo /absolute/app --session SESSION_ID

Exit code 0 means every planned flow is accepted with all its facts accounted for; 2 means a usable partial map. Complete does not mean everything is certain: candidate and unknown items stay in a complete map and are listed under "Uncertain" in summary.md.

Give the user the paths of view.html and summary.md under .genesis/out/latest/; graph.html beside them shows the same map as a plain outline. Then explain in their language:

  • the business domains and flows you found, and the decisions that matter in each;
  • what is uncertain, and why;
  • what is outside the result: skipped entries with their reasons, entries not handled, facts not accounted for, tasks that stayed failed;
  • the observations you recorded, marked as yours;
  • how flows hand over to each other, as your own reading, since the map does not record it.

Say plainly that the names are your synthesis of the code, not confirmed requirements. If something in the result calls for action, name it and say what you could do next. Changing code or tests needs its own request from the user.

5. Changes since a revision

Use this when the user asks what a commit, a pull request, a branch, a commit range or their uncommitted work changes or could break, which entry points or flows it reaches, whether tests cover it, or what its risks are.

The short path

genesis map prepare --repo /absolute/app --base MERGE_BASE --head HEAD
genesis map diff    --repo /absolute/app --session SESSION_ID
genesis map context --repo /absolute/app --session SESSION_ID --task task_change
genesis map submit  --repo /absolute/app --session SESSION_ID --task task_change --input -
genesis map render  --repo /absolute/app --session SESSION_ID
  1. prepare, with --base where the change starts and --head where it ends:

    • one commit: --base COMMIT~1 --head COMMIT (write ~1, since zsh may read ^ as a pattern); a commit with no parent cannot be compared this way;
    • a commit range A..B: --base A --head B;
    • a branch or a pull request: --head the branch or HEAD, and as --base the commit git merge-base main HEAD prints, with the base branch of the pull request in place of main (or origin/main when there is no local main). --base main alone would also report what main gained since the branch started, as changes undone. A pull request that is not in the local repository has to be fetched first, for example with git fetch origin pull/N/head and --head FETCH_HEAD; Genesis does not fetch;
    • uncommitted work: --base HEAD and no --head. When git status -s shows new files (??) that belong to the change, add --include-untracked: untracked files are otherwise left out; prepare counts them under untracked_left_out and the report names them.

    Running prepare again on the same revisions keeps your accepted explanations and reports "resumed": true. When it reports "engine": "agent", the project is not Python: continue in other-languages.md.

  2. diff lists every change, where each sits, the tests static analysis links to it, and the flows (possibly_affected) and candidate entries (possible_entries) that reach it. Its output can be long: pipe it into jq or Python, or write it to a file in your temporary directory, and read it in parts, for example with jq '.changes[] | {change_id, kind, symbol_id, placement}'. possibly_affected, possible_entries and unanalyzed_changes are top-level keys. Check each candidate in possible_entries by reading its code: name a real way in as an entry point of its changes, as your reading, and say which candidates you could not check. Record them in a plan (proposed, or skipped as not_an_entry) only when you also place changes on flows.

  3. Explain what the CLI owes, and only that. context --task task_change lists first the changes that need an explanation, 30 at a time, with both sides and their tests: those on the map, those a flow reaches, and those calls that failed to resolve may reach (unresolved_calls). changes_waiting counts them. Read them, decide each verdict, and submit your explanations ("Explaining the changes" below). Changes that are parts of one change in behaviour take one explanation that lists them all in change_ids. Ask for the context again until changes_waiting is 0; status offers task_change as next_task while any wait. Do not write explanations for the rest, such as changes to tests and import lines no entry reaches: the report lists them anyway, and the time is better spent on step 4. When the user asked nothing about tests, you may leave verdict out and keep the static result.

  4. Read for risks, as a pass of its own, once the explanations are accepted and before you render. The explanations say what changed; this pass asks what goes wrong, in which situation, and for whom. It is what a reviewer reads first. It is a reading pass: a list written from what you noticed while explaining misses most of what a review finds, so open the code below before you write a risk. The result that accepts the last explanations holds read_for_risks, and the context lists the same callers under unchanged_callers. Read in this order:

    • The callers outside the changes (unchanged_callers): for each changed function, the code that calls it and is not part of the change. Read each one: what it does with the new result, error, value or delay, and what its own callers and users then see. A caller with a loop runs the changed code once per item: time, requests, log lines and scans add up with the number of items.
    • The changed files Genesis did not analyze (unanalyzed_changes): documentation, example configuration, prompts and skill files. Do what each tells a user or an agent to do, as written: copy the example values as they are, follow a skill's steps with the flags it gives, and see what the new code does with that.
    • Inputs. For new or changed code that parses, matches, filters, validates or formats, list the inputs it may get wrong: empty or missing values, case and encoding, nesting, escapes and the other forms the same syntax allows, very large inputs, and the forms the docs, the tests or the neighbouring code accept. Follow each through the code. Where a function runs on its own without side effects, try the inputs you suspect from a small script in your temporary directory.
    • The same input, before and after. For every existing caller, user or stored output of the changed code, what does the input it already sends give now: a different value, type, format, order or id; an error where there was a result, or the reverse; a delay; a log line, message or metric that now means something else. Ids, keys, names, orderings and numbers that users or files have kept from before (snapshots, ledgers, caches, exports, stored results) break when an unchanged input now gives a different one. lands_on in the context shows where a new break, continue or return goes.
    • Size. How the cost grows with the input: a scan over every item for each item, a file read or a request per call, everything held in memory before the first result comes out.
    • Failures. What happens when a service, file or call the code relies on fails, is slow, or answers with success but carries an error or an unexpected shape, and what the caller then sees.
    • Reach. What the changed code now runs, reads or sends that it did not before: programs started from configuration, paths built from input, data that leaves the machine. Check that disabled entries, untrusted folders and secrets stay out.
    • Other readers. Code that reads the same value, setting, file or record, and whether two readers now disagree.

    Not a risk on its own: a gap in the tests (it goes in the verdict's note); a failure that needs code nobody has written yet; behaviour the change did not touch, unless it now happens more often or matters more; what the change sets out to do, for the inputs it is meant for. The same behaviour reaching inputs it was not meant for is a risk. A risk names the input or situation, what goes wrong, and for whom. Submit every risk you confirm as risks, in a submission of its own ("Explaining the changes" below).

  5. render. Once every owed change is explained it exits 0 with change_status: complete. When you described no flows, affected_flow_not_synthesized stays among the limitations: it says that no flow was described and does not keep the report from being complete. Then report as the end of this section says.

The CLI takes explanations at any point of a change session: no plan and no flow description has to come first. Describe flows, as set out under "Placing changes on flows", only when the user wants to see the changes in the business flows, or when diff lists for a change neither a flow under possibly_affected nor a candidate under possible_entries. An unassigned change that a flow reaches already has its way in: explain it where it is.

What prepare and diff return

--base REV compares that revision with the working tree, or with --head REV. The result of prepare adds changes, changes_placed, change_status and changed_files_not_analyzed. The list of changes comes from the code alone, so diff shows it before you do anything; rendering at this point is optional and gives the same list on the static structure.

In diff and status, changes_placed counts the changes with a place on the map. changes_waiting counts the changes you have not explained yet that the report needs: on the map, within reach of a flow, or possibly reached through calls that failed to resolve. changes_unexplained in the context counts every change without an explanation. Describing flows raises changes_placed and does not lower changes_waiting: that one goes down as task_change accepts explanations.

  • changes has one entry per changed condition, call, loop, result or definition, and source_* entries for everything else that changed, such as a constant or a default value. A branch or loop that was added or removed as a whole is one entry for the whole block. before and after give the text of each side with an evidence_id; a side with "excerpt": true shows less than the lines it cites.
  • placement is the step of the current map a change belongs to. Without a reason, a step rests on the changed code itself. A reason says how the place was chosen otherwise. An unassigned change has no place on the map, and its reason says whether a flow reaches it, whether calls that failed to resolve may reach it (unresolved_calls), or that no entry reaches it through resolved calls. The last is not proof that nothing does.
  • tests is what the test sources alone show. A test is linked when it calls the changed function, directly or through other calls, or requests a route that leads to it with an HTTP test client. reached_only at this point means only that; unknown means no such test was found. The linked tests come most relevant first: those this change adds or edits (changed_with_it), then by calls_away (1: the test calls the changed function itself). A handler registered with set_defaults(func=...) on an argparse subcommand is linked only to tests whose strings name that subcommand. Static analysis does not follow pytest fixtures, subprocess runs of the program, decorators that call a function later, property reads, or chains longer than five calls: look for such tests yourself.
  • possibly_affected lists flows that can reach changed code without a step on it; removed_flows the entries that no longer exist; unanalyzed_changes the changed files Genesis did not analyze, such as other languages. Mention those that are not empty. A changed document or skill file can describe or drive the changed code: read it against the Python change.
  • limitations says what the analysis could not do. unresolved_local_calls means calls into the code base's own modules failed to resolve: changes that look unreachable may be reached, and their tests may not be linked.
  • closest_flow says where to describe changed code that no flow has expanded yet (see below).
  • possible_entries lists functions no code calls that lead to the changed code and start no flow. Each has its entry_id, its symbol_id and the change_ids it leads to. They are checked below, not reported as they are.

Explaining the changes

Explain the changes with task_change, whether or not you described flows. status offers it as next_task while changes wait for an explanation.

genesis map context --repo /absolute/app --session SESSION_ID --task task_change

It returns up to 30 changes, those that still need an explanation first. Each one carries the frozen text of both sides under before and after: read both, read the tests listed for it, and search for tests that reach it another way. A side marked "excerpt": true is shorter than its lines: an added or removed definition shows its header only, a long block is cut at 800 characters, and a statement written over several lines is shown on one. Read such a side in full with genesis map read --evidence <id>; any other side already is the full text. For the code around a change, read the files at the two revisions of the session, or a diff between them. When the head side is the working tree, the files may have changed since prepare: check what you quote against the frozen text. A linked test may still not reach the change, for example when it replaces the changed function with a stub. Then submit:

{
  "changes": [
    {"change_id": "chg_9603691aeade3d47",
     "summary": "The review threshold now includes the boundary amount.",
     "effect": "A report of exactly the threshold amount goes to model review instead of being approved at once.",
     "verdict": "reached_only",
     "note": "The test submits 50 and 500 and accepts either status, so the boundary amount is never exercised.",
     "test_ids": ["head::tests/test_submit.py#test_submit_report_status"]},
    {"change_id": "chg_f1c02c12d9463145",
     "summary": "Approval no longer records the intermediate reviewed status.",
     "verdict": "not_reached",
     "note": "No test calls the approval route or approve_report."},
    {"change_ids": ["chg_03a420c71b4e228d", "chg_da88254492c7c41b"],
     "summary": "The nightly cleanup no longer archives the reports before it clears them.",
     "verdict": "not_reached",
     "note": "No test calls nightly_cleanup."}
  ]
}
genesis map submit --repo /absolute/app --session SESSION_ID --task task_change --input - <<'EOF'
...
EOF

After the risk pass of step 4, submit the risks on their own:

{
  "risks": [
    {"statement": "A report of exactly the threshold amount now goes to model review, so while the model service is slow or down its submission waits on that call instead of being approved at once.",
     "severity": "medium",
     "category": "reliability",
     "change_ids": ["chg_9603691aeade3d47"],
     "evidence": [{"path": "expense/api.py", "start_line": 14, "end_line": 14,
                   "quote": "verdict = await review_with_model(report)"}]}
  ]
}
  • summary says in business terms what is different, and effect what it means for the flow. Do not describe the line edit. Write both in the user's language.
  • Add short_summary for the map card: one short clause (up to 120 characters), preserving the triggering condition and consequence. Keep the complete explanation in summary and effect; do not omit qualifications to make an uncertain claim sound definite.
  • verdict is your reading of the tests, and it answers one question: would a test fail if this change were undone? covered: a test runs the changed code and would fail if the change were undone; name it in test_ids. reached_only: tests run the code but would not fail if the change were undone, because their input misses the changed path or they check nothing it affects; note says what is missing. not_reached: no test reaches it. unknown: you could not tell; note says why. Every verdict needs a note. Leave verdict out to keep the static result, which the report shows as "called by tests, not assessed".
  • A statement that runs on every call, such as an added add_argument or an assignment, is covered by a test that runs the code and would fail without it. An input value no test uses is not a missed path.
  • An added definition (symbol_added) is one change, so judge it as a whole: covered when a test runs it and would fail without it. Name the branches no test takes in note; they do not make it reached_only.
  • A test counts when the project's default test command runs it. Tests skipped by default do not count: a skip mark, a skipif whose condition holds in a normal run (such as a missing environment variable or credential), a marker the default configuration deselects. Name them in note and judge by the other tests. Needing the network or a model download does not by itself exclude a test; you may say so in note.
  • For a change that replaces code (both sides present), undoing it puts the before side back, so take the test's input through the before side too. When the old code gives the same outcome for that input (the same exception, the same value, the same call), the test still passes and does not make the change covered. A test that checks only an exception type or a field name often passes on both sides: five validators replaced by a Literal type both raise ValidationError for an unknown value, so a test that only matches the field name in the error is reached_only. covered needs a test whose input gets a different outcome on the two sides.
  • A verdict answers only whether a test would fail. What the tests leave unchecked goes in its note, not into risks.
  • For code that was removed, the changed path is the input the removed code used to handle. covered: a test gives such an input and would fail if the removed code were put back. reached_only: tests run the function but never with such an input. Code that replaces it is a change of its own: judge each on its own input, and do not copy the verdict from one to the other. The same holds when another function now does what the removed code did: the input still has to go through the function the code was removed from. A test that calls only the other function is a near miss: describe it in note.
  • One source_* change can hold several values, such as two limits set on neighbouring lines of a function. covered needs, for each value, a test that would fail if that value were undone. When only some have one, use reached_only and name the others in note.
  • test_ids names the tests your verdict rests on, as head::<path>#<function>, for example head::tests/test_api.py#test_refund; a method is #TestClass.test_name. The tests static analysis linked stay listed after them. A test static analysis did not link may be named; the report marks it as identified by you. not_reached names no tests: describe near misses in note.
  • The CLI refuses a verdict the test sources contradict: covered with no test_ids, or when none of the named tests contains an assertion, not_reached when a test calls the changed function itself or requests its route, an unknown change_id or test. A refusal changes nothing already accepted.
  • risks lists the risks you see in the changes, each with the change_ids it comes from and a severity of info, low (the default) or medium; there is no high, since it is your reading and no rule checked it. category is optional: reliability, correctness, data_integrity, security, performance or other. evidence may cite code beyond the changed lines that the risk lands on, as flow observations do (path, start_line, end_line and a quote from those lines, or an evidence_id). When the quote is not on the lines given, the CLI takes the nearest range of as many lines, up to five lines away, that holds it, and says so under evidence_moved in the result. The same statement about the same changes replaces the earlier one. The report lists them under "Risks seen in the changes", as your reading.
  • unchanged_callers in the context lists, for each changed function, up to three places that call it and are not part of the change, those in a loop first with the loop they run in (callers_total counts them all). Calls from tests are left out: they are with each change. Once nothing waits for an explanation, the result of submit repeats them under read_for_risks, with the changed files Genesis did not analyze. They are where step 4 starts reading.
  • change_ids in an explanation lists several changes in place of change_id. Each of them is checked and stored as if explained alone; a problem with one of them is reported at its place in the list.
  • An observation you recorded on a flow is shown as introduced when its evidence cites code this change added, or when its whole flow is new, and as persisting when it cites code the change modified. Cite the changed lines when the risk comes from them.
  • A change to a test (its kind starts with test_) needs no explanation. If you give one, it takes a summary and no verdict; with a verdict, the whole submission is refused with verdict_on_test.
  • Submissions add up. Ask for the context again until changes_waiting is 0. A change that no step covers but a flow can reach counts in changes_waiting from the start, so a session is not done because nothing is on the map yet. On the short path, explain such a change where it is and name the flows that reach it; bring it onto the map by describing its flow only when the user wants the flows shown. So does a change that calls which failed to resolve may reach. A change no entry reaches, such as an import line, does not count; the context lists it after the others, and you explain it only when it matters to the user's question.

Placing changes on flows

Do this when the user wants the changes shown in the business flows, or to settle what reaches a change that has no place. Bring the changes onto the map before you report them as off it. A change listed under possibly_affected for a flow sits in a function that flow calls, or hands to a thread or a task runner, with no step on it yet. Expand the functions on the way to it by anchoring steps inside them; status shows changes_placed going up as they land.

Code that several flows share is expanded on one of them, and the CLI says which. closest_flow lists every change whose function no flow has expanded yet, whether it has no place or sits on a step that only calls the function, under the one flow that reaches it through the fewest calls. Plan that flow and expand the functions there. In every other flow that reaches or calls the same code, do not expand it again, whichever flow you happen to describe first: let one step stand for the function. That step may show the change with the reason that it calls the changed function, and that is all the flow needs.

The context of a flow task says the same under change: placed are the changes on its steps now, closest_to the ones whose code is to be expanded in this flow, and on_other_flows the ones this flow reaches or calls that another flow describes. expand names the function each closest_to change is in, nearest to the entry first; for a changed constant it is the nearest function that reads it. Anchor at least one step inside every function listed there, also when all that changed is a text or a value and the function decides nothing. Until a step is inside it, the change has no place and stays in closest_to. A change also leaves closest_to when another flow is accepted with a step inside its function, which for a changed constant is any function that reads it. It is then listed under on_other_flows, and this flow no longer has to expand anything for it. Go by the context you asked for last, not by an earlier diff.

The map only has the entries it knows, so a change can also be reached from a way in that has no flow. diff lists the candidates under possible_entries, and status has the same list under change.possible_entries. It holds up to 20 of them, and possible_entries_total beside it counts all that are still to check; the rest appear once you have proposed the ones listed or skipped them for any reason but budget, which leaves a candidate unchecked. Check every one, also when flows are already listed for the change. When it is a real way in (a command registered by hand, a scheduled job, a message handler), propose it as in section 2, give it a flow and describe that flow too. When it is a helper or code nothing uses, list its entry_id in the plan under skipped with "reason": "not_an_entry" and a note that says what you found, for example that only tests call it. It then leaves both lists, and summary.md shows it as checked with your note; a candidate you leave alone stays listed as unchecked. Keep that entry in every later plan: a plan replaces the one before it, and a candidate it no longer skips is back on both lists. When a change is still unassigned, no flow is listed for it and nothing is offered, look for a missing entry point yourself before you report the change as off the map.

Reformatting, comments and code that only moved are not changes.

Then plan as in section 2 and describe flows as in section 3. Only the flows the changes land on are needed: status lists them under change.affected_flows, and next_task offers their tasks first; the flows named under closest_flow are among them, before and after you plan. A flow that only reaches changed code, with every one of those changes placed on another flow or listed under another flow in closest_flow, needs a name in the plan and nothing more: view.html shows it as one line with the number of changes on its way. Do not describe it unless the user asks.

Plan no other flows. Apart from the candidates you checked and skipped as not_an_entry, leave every other entry out of both flows and skipped: it

Files (genesis)
  • agents
    • openai.yaml 319 B
      Loading…
  • scripts
    • run_genesis.py 1.3 KB
      Loading…
  • other-languages.md 10.6 KB
    Loading…
  • SKILL.md 62.4 KB
    ---
    name: genesis
    description: Show what a code change in a Python codebase does, and map its business flows, with Genesis, backed by code evidence. Use when the user asks what a commit, pull request, branch, commit range or uncommitted change does or affects, whether it could break something or is safe to merge or release, which business flows or entry points it reaches, or whether tests cover it, for example when reviewing a change before pushing, merging or releasing. Also use it when the user wants to understand what a project does as business flows, asks for a business flow map or diagram that product and engineering can both read, asks to update or continue such a map, or asks about an existing Genesis map. Match the intent in any language, not exact keywords.
    ---
    
    # Genesis business map
    
    Genesis turns a repository into a map of business flows that product, engineering and
    QA can read together. The work is split in two:
    
    - The **Genesis CLI** is deterministic. It freezes a snapshot of the code, extracts
      facts, finds entry points, checks everything you submit, and renders the result.
      It calls no model and no service.
    - **You** read the code and say what it means in business terms. You never write the
      map yourself: you submit a plan and one description per flow, or, for a change, one
      explanation per change, and the CLI accepts or rejects each submission as a whole.
    
    The map describes what the code currently does. It is not a statement that the code
    meets a requirement, that a test passed, or that a path was executed. Never present
    your own reading of the code as a Genesis result: a Genesis result is what the CLI
    accepted and rendered.
    
    ## Two requests
    
    The user asks for one of two things. `/genesis map` and `/genesis review` (`$genesis
    map` and `$genesis review` in Codex) name them outright; otherwise tell them apart by
    what the user says.
    
    - **review REV**: what a commit, pull request, branch or uncommitted work does or could
      break, which entry points or flows it reaches, whether tests cover it, what its risks
      are. Without a revision, compare with the one the branch started from; for
      uncommitted work that is `HEAD`. Run `version` as in "Locate the CLI" below, then go
      to section 5 and take its short path. It needs no full map: it takes a handful of
      commands, and you describe flows only where that pays off. Even a small change takes
      the short path, as long as a changed file is in a language Genesis reads: Python, or
      the project's main language when that is not Python (see below). When none is,
      Genesis has nothing to add, so say so and answer from the diff yourself.
    - **map**: draw the system as it is now, so that someone can understand it. Sections 1
      to 4. Nothing is compared and no change is reported.
    
    A question about an existing map: see "Later requests" at the end.
    
    Genesis does not import or run the project's code, installs nothing, never needs the
    project's dependencies and does not use the network. `prepare` reads files and Git
    objects; with `--head` nothing is checked out. It writes its results under `.genesis/`
    in the repository. If `prepare` fails with "Operation not permitted" or "Read-only
    file system", the sandbox does not let it write there: tell the user that Genesis
    needs write access to `.genesis/`, and do not present your own reading as a Genesis
    result. After a review, mention that `.genesis/` now exists.
    
    Hand `plan` and `submit` their JSON on standard input with `--input -` and a quoted
    heredoc, so that no file is needed:
    
    ```
    genesis map submit --repo /absolute/app --session SESSION_ID --task task_change --input - <<'EOF'
    {"changes": [...]}
    EOF
    ```
    
    A file works too: write it into the scratchpad or temporary directory your environment
    names and pass its absolute path. Do not use a fixed path, such as one in `/tmp`, or a
    directory next to the repository: a sandbox may let you write only into the
    repository and the temporary directory it gives you. Long output, such as that of
    `diff`, can go straight into `jq` or Python instead of into a file.
    
    ## What is supported today
    
    - Python source is analyzed statically: the CLI extracts facts, finds the entry points
      and checks that a flow leaves nothing out.
    - Any other language works without that analysis. `map prepare` then reports
      `"engine": "agent"`: you find the entry points and read the code yourself, and the
      CLI checks every citation against the frozen source. In that case read
      `other-languages.md` next to this skill and follow it instead of sections 2, 3 and 5.
      For a project whose main language is not Python but which has some Python files, run
      `map prepare` with `--engine agent`; otherwise only the Python files are mapped.
    - On a repository with no source file Genesis can read, `map prepare` fails with
      `unsupported_repository`. For a map request, tell the user what it reported and stop.
      For a question about a change, say that Genesis could not analyze this repository,
      then answer from your own reading of the diff and mark it as such.
    - A full map of the current code.
    - The changes since a revision, each explained with whether existing tests cover it,
      and placed on the steps of the map, or of its static skeleton when no flow is
      described (section 5).
    - Two pages show the result. `view.html` is the one for the user: it draws each flow
      you described as a diagram of steps and arrows, and needs a browser that runs
      scripts. Its fixed labels exist in Chinese and English only, and the page picks
      one from the text you wrote. `graph.html` is a plain outline with no script: flows
      as cards, steps in order, each with its code location and links to the steps that
      follow, labels in English.
    
    Not available yet. Say so plainly instead of improvising a result and calling it Genesis:
    
    - Running tests or importing coverage data. Every test verdict comes from reading source.
    - Recording how one flow leads into another. Describe such hand-overs in your report
      as your own reading.
    - Risk findings from rules. Only the observations you submit appear.
    
    ## Locate the CLI
    
    Run the `scripts/run_genesis.py` next to this skill with a trusted Python 3
    interpreter, for example `python3 -I /absolute/path/to/this/skill/scripts/run_genesis.py`.
    It uses the Genesis environment recorded at install time and keeps the working
    directory and exit codes. Run it with `version` first; that one prints plain text. If
    it prints "Genesis skill environment is unavailable" and exits 1, ask the user to run
    `genesis agent install` again. Do not run a repository-provided executable named
    `genesis`.
    
    Below, `genesis` stands for that whole command: the interpreter, `-I` and the full
    path of the script. Write all three at the start of every command line, as in
    `python3 -I /absolute/path/to/this/skill/scripts/run_genesis.py map status ...`.
    Do not keep them in a shell variable: zsh does not split a variable into words, so
    `$GENESIS map status` fails there with exit code 127. Do not write a wrapper script
    either, and never run a bare `genesis`: the shell looks that name up on `PATH` and
    may find another program.
    
    Every `genesis map` command prints one JSON document on stdout. A refusal has an
    `error` object with `code`, `message` and a list of `errors`, and exits with 1. A
    refused submission has `"status": "rejected"` and its own `errors`, and also exits 1.
    
    ## 1. Prepare and show the static structure
    
    Find the Git root of the user's project, not the directory of this skill.
    
    ```
    genesis map prepare --repo /absolute/app
    genesis map render --repo /absolute/app --session SESSION_ID --open
    ```
    
    `prepare` reads the working tree by default. Use `--head REV` for a specific commit.
    Add `--include-untracked` only when new, uncommitted files belong to the request.
    Its result has the `session_id` and the `engine`. With `"engine": "agent"`, continue in
    `other-languages.md`. Otherwise `entries.adapter` is the number of framework entries
    found and `entries.root_heuristic` the number of further candidates. Running it again
    on unchanged code returns the same session with `"resumed": true` and keeps all
    accepted work.
    
    `render` writes two pages under `.genesis/out/latest/` and gives their paths as
    `view` and `graph`: `view.html`, the page for the user, and `graph.html`, a plain
    outline of the same map. `--open` opens `view.html`, and the result reports
    `"opened"`: when it is false, give the user the path of `view.html` instead of
    saying the page is open. Exit code 2 means a usable partial map, which is normal at
    this point. No business meaning is added yet. `graph.html` shows the static
    structure of each entry, named by source text. `view.html` shows an entry as one
    line until its flow is described or a change sits on it.
    
    ## 2. Plan
    
    ```
    genesis map status --repo /absolute/app --session SESSION_ID
    ```
    
    `entries` lists the entry points the analyzers recognised. `root_candidates` lists
    public functions no code outside the tests was seen to call; most are not real entries.
    
    An entry of kind `handler` was found by how it is registered, not by a framework: its
    class sits in a list (`attributes.registry`) with others that share a base class
    (`attributes.base`), and a dispatcher runs the same method on whichever it picks. It
    is a real entry when the outside decides which one runs, as with a chat command or an
    event handler. When the list is the program's own choice among implementations, such
    as data sources or middleware, skip it as `out_of_scope`.
    
    Write a plan. The plan is the outline a reader sees first: before any flow is
    described, `view.html` shows the domains, each flow's name and summary, and nothing of
    the code. So write it as what the product does, not as a list of its endpoints.
    
    - **A flow is one business process a person would name.** Two stages of a lifecycle
      that different entries handle are two flows.
    - **`tier`** says which flows the reader came for. `primary` is a process that decides
      something or has an effect: placing an order, running an analysis, approving a
      report. `supporting` is lookup and upkeep: listing, reading one item, status,
      plain edits and deletes.
    - **Put the lookups and upkeep of one thing into one supporting flow** with all their
      entries: `{"key": "rules", "name": "View and maintain alert rules", "tier":
      "supporting", "entry_ids": [...]}` for the list, get, update and delete endpoints.
      An endpoint per flow gives an API listing, not a map. A primary flow usually has one
      entry; give it several only when they are alternative ways to start the same
      process.
    - **`name`** is required and is the name a person would use, never a route or a
      function name. **`summary`** is one sentence on what a user gets done with it, taken
      from the route, the function name and its docstring; leave it out rather than
      guess. Both are shown as "not described yet" until the flow is accepted.
    - Group flows into business domains, and skip entries that are not business
      behaviour, each with a reason.
    
    ```json
    {
      "domains": [{"key": "expense", "name": "Expense reports"}],
      "flows": [
        {
          "key": "submit",
          "name": "Submit a report",
          "summary": "An employee files an expense report; large ones go to a reviewer.",
          "tier": "primary",
          "domain": "expense",
          "entry_ids": ["entry_61d9ffd67cc8ac21"]
        }
      ],
      "skipped": [
        {"entry_id": "entry_2500248be5dca529", "reason": "infrastructure", "note": "health check"}
      ]
    }
    ```
    
    ```
    genesis map plan --repo /absolute/app --session SESSION_ID --input /absolute/plan.json
    ```
    
    - Skip reasons: `infrastructure`, `test_helper`, `duplicate`, `out_of_scope`, `budget`,
      and `not_an_entry` for a function that only looked like a way in. That one needs a
      `note` saying what you found.
    - An entry you put in neither `flows` nor `skipped` is accepted and counted as not handled.
    - If the analyzers missed a real entry, add it under `proposed_entries` with
      `symbol_id`, `kind`, `reason` and `evidence`. `kind` is one of `http_route`,
      `cli_command`, `task`, `scheduled`, `public_api`, `agent_tool`, `handler`, `main`;
      `handler` is for anything registered with a dispatcher by hand, such as a chat
      command or a message handler. A function among the root candidates can be proposed
      as well, which gives it a kind; one the analyzers recognised cannot. A root
      candidate, or a function listed under `possible_entries`, already has its
      `entry_id`: propose it and put that id in a flow in the same plan. Any other
      function takes two submissions: the result of the first lists the new entry under
      `entries` with its id and `"detection": "agent_proposed"`; then submit the plan
      again with that id in a flow. Do not propose it a second time: it stays available
      as long as a plan uses or skips it, and a plan that no longer mentions it
      withdraws it.
    - Without `--input` the CLI makes one flow per framework entry. Use that only when the
      user wants the quickest possible result.
    
    The result says `"status": "accepted"` and lists one task per flow with your `flow_key`.
    The plan can be submitted again when flows should merge or split; a flow whose entries
    did not change keeps its accepted description.
    
    Now tell the user the scope before the long part: how many entries were found, how
    many flows you are about to describe, and what you skipped. When the user named an area,
    start with it. When there are many flows and the user named none, describe the primary
    flows first, render and report, then offer to do the supporting ones. If you cannot
    describe every flow now, render after the ones you did and say which are still open;
    running `prepare` again resumes the session.
    
    ## 3. Describe each flow
    
    Take `next_task` from `status` and repeat until it is null. A task is `pending`,
    `claimed`, `validated` or `failed`. `failed` only means its last submission was refused
    and nothing is accepted yet; fix it and submit again. `next_task` offers pending tasks
    first, then failed ones, then validated flows that still leave facts unaccounted, and
    goes through the primary flows before the supporting ones.
    
    ```
    genesis map context --repo /absolute/app --session SESSION_ID --task TASK_ID --claim
    ```
    
    The context contains:
    
    - `entries`, each with the `anchor` to use for its trigger step;
    - `source`, the text of each entry function;
    - `accountable`, what this flow must account for, in units. Each has a `fingerprint`,
      an `evidence_id` and a `unit`:
      - `fact`: a condition, loop or result of the entry function; a condition lists its
        `branches`.
      - `function`: a function the chain calls, once however often it is called. `inside`
        says how many conditions, loops and results it holds and which outside systems it
        `reaches`. With `"deferred": true` the function is not called on that line: it is
        handed to another call (`executor.submit(self.work, item)`, `asyncio.to_thread(...)`,
        a callback) or called inside a lambda, and `note` names the receiver. It runs when
        and if the receiver calls it, often on another thread. Describe the step as what is
        started or scheduled, and expand the function like any other when the work it does
        belongs to the flow.
      - `system`: an outside system the chain talks to, once per system.
      - `await`: an awaited call that leaves the code.
    - `other_facts`, further facts of the entry function. They also anchor steps, but
      nothing obliges you to mention them;
    - `callees`, functions you may want to read next;
    - `large_callees`, the called functions with eight or more conditions, loops and
      results inside. A step that stands for one of them needs `unexpanded_reason`:
      write it in your first submission instead of learning it from a refusal.
      `query --symbol` gives the same list for the function it shows;
    - `change`, in a change session: which changes this flow carries and which it is
      asked to bring onto the map (section 5);
    - `previous`, the result of the accepted version if there is one. `accountable_truncated`
      is true when there are more units than the list holds.
    
    `--claim` is optional. It holds the task for fifteen minutes; another worker asking with
    `--claim` in that time is refused with `task_claimed`. Use it when several workers or
    subagents share a session, one task each.
    
    Read more as needed:
    
    ```
    genesis map query --repo /absolute/app --session SESSION_ID --symbol "path/file.py#function"
    genesis map query --repo /absolute/app --session SESSION_ID --search "text"
    genesis map read  --repo /absolute/app --session SESSION_ID --evidence EVIDENCE_ID
    ```
    
    `query --symbol` lists the facts of that function a step can be anchored on, and under
    `expands_to` the units that become accountable once a step is anchored inside it. You
    may also read files with your own tools; the CLI still checks every citation against
    the frozen snapshot.
    
    Then write the flow and submit it. This example leaves nothing unaccounted:
    
    ```json
    {
      "name": "Submit a report",
      "summary": "Reports at or above the threshold are reviewed by a model and wait for approval; smaller ones are approved at once.",
      "steps": [
        {"key": "received", "name": "Report received", "kind": "trigger",
         "anchors": ["fp_5f8dccac1429dc53700cd71a"],
         "evidence": [{"path": "expense/api.py", "start_line": 10, "end_line": 11, "quote": "@router.post(\"/reports\")"}]},
        {"key": "route", "name": "Choose a path by amount", "kind": "decision",
         "evidence": [{"path": "expense/api.py", "start_line": 13, "end_line": 13, "quote": "amount >= THRESHOLD"}]},
        {"key": "review", "name": "Model review", "kind": "external",
         "evidence": [
           {"path": "expense/api.py", "start_line": 14, "end_line": 14, "quote": "review_with_model(report)"},
           {"path": "expense/review.py", "start_line": 7, "end_line": 8, "quote": "while True"}]},
        {"key": "wait", "name": "Mark as waiting for approval", "kind": "action",
         "evidence": [{"path": "expense/api.py", "start_line": 15, "end_line": 15, "quote": "pending_approval"}]},
        {"key": "waiting", "name": "Report is waiting for approval", "kind": "result",
         "evidence": [{"path": "expense/api.py", "start_line": 16, "end_line": 16, "quote": "\"review\": verdict"}]},
        {"key": "approve", "name": "Approve automatically", "kind": "action",
         "evidence": [{"path": "expense/api.py", "start_line": 17, "end_line": 17, "quote": "save_status("}]},
        {"key": "approved", "name": "Report is approved", "kind": "result",
         "evidence": [{"path": "expense/api.py", "start_line": 18, "end_line": 18, "quote": "return {\"status\": \"approved\"}"}]}
      ],
      "edges": [
        {"source": "received", "target": "route", "relation": "sequence"},
        {"source": "route", "target": "review", "relation": "branch", "branch": "true", "label": "At or above the threshold"},
        {"source": "route", "target": "approve", "relation": "branch", "branch": "false", "label": "Below the threshold"},
        {"source": "review", "target": "wait", "relation": "sequence"},
        {"source": "wait", "target": "waiting", "relation": "sequence"},
        {"source": "approve", "target": "approved", "relation": "sequence"}
      ],
      "omitted": [
        {"anchor": "fp_07d073458ec7ec545df423b0", "reason": "merged_into_step", "note": "exit test of the review loop"}
      ],
      "observations": [
        {"statement": "The review calls the model in a loop with no upper bound.", "severity": "medium", "category": "reliability",
         "step": "review",
         "evidence": [{"path": "expense/review.py", "start_line": 7, "end_line": 8, "quote": "while True"}]}
      ]
    }
    ```
    
    ```
    genesis map submit --repo /absolute/app --session SESSION_ID --task TASK_ID --input /absolute/flow.json
    ```
    
    Write every name, summary, branch label, note and observation in the user's language,
    in words a product person would use.
    
    Give each observation one `category` when the evidence supports it: `reliability`
    (retries, failures, recovery), `correctness` (wrong decisions or results), `data_integrity`
    (loss, duplicate side effects, inconsistent state), `security` (permissions or exposure),
    `performance` (latency or cost), or `other`. Category is separate from severity and test
    coverage. Omit it when uncertain; never turn a behavior change or missing test into a bug.
    
    For each step whose inputs and outputs you can establish, include an optional `contract`
    with structured JSON objects in `input` and `output`, preferably JSON Schema. For example:
    `{"input": {"type": "object", "properties": {"amount": {"type": "number"}}, "required": ["amount"]},
    "output": {"type": "boolean", "description": "Whether the amount exceeds the threshold"}}`.
    Use the actual data shape for each step: an internal decision may yield a boolean rather
    than an HTTP response. Both sides are required when supplied. Do not put prose strings or
    a separate `constraints` field here. Cite supporting field reads, return values and
    conditions in the step's `evidence`. Describe the expected interface, never imply that
    runtime validation exists unless it is implemented. Omit unsupported types or the whole
    contract when the code cannot establish it; never invent example payload values.
    
    Rules the CLI enforces:
    
    - **Steps.** `kind` is `trigger`, `action`, `decision`, `external` or `result`. One step
      may cover several lines of code. Do not add a step the code does not show. `kind`
      is your reading of what the step is, whatever it is anchored on: a loop or a
      condition may anchor an `action` step that covers the whole of it, such as "save
      every result". Only make it a `decision` when the map should show its branches,
      since `branch` edges leave decision steps only.
    - **Evidence.** Each item is either `{"evidence_id": "ev_..."}` taken from the context
      or a query, or a `path` with `start_line`, `end_line` and a short `quote` copied from
      those lines. A wrong quote means you are not looking at the frozen content: read it
      again through the CLI.
    - **Anchors.** A step is `resolved` only if it rests on analyzer facts. Either list
      fingerprints in `anchors`, or cite a range of at most 12 lines: the facts that start
      inside it become the anchors, so a call written over many lines is cited by its
      first lines. Calls to built-ins, which include methods of built-in types such as
      `items.append(...)`, are left out of what a range gives a step, unless the range
      holds nothing else: then they are its anchors. Code that runs at import time, such
      as a decorator line, is never picked up. A range does pick up the calls written
      inside a longer statement, such as a helper in the arguments of a `return` that
      runs over several lines; when you list that function in `omitted`, the step is not
      taken to stand for it. Use the entry's `anchor` for a trigger step.
    - **Lines without facts.** Facts are conditions, loops, calls, returns and raises. A
      plain assignment has none, so a step that cites only assignments is refused with
      `step_not_anchored`. When the two sides of a condition only assign a value, do not
      give them steps: point both branch edges at the step that follows and put the
      meaning in the edge labels.
    - **Branches.** A `branch` edge leaves a `decision` step, names a branch its condition
      really has (see `branches`), and must point at a step that branch leads to. `label`
      is your wording for it.
    - **Loops.** A loop has the branches `loop`, into its body, and `exit`. `break` and
      `continue` are not facts a step can stand on, and no fact list shows them. Draw the
      edge that leads to one, usually a branch of the condition around it, to the step
      that follows the loop for `break`, and back to the loop's step for `continue`.
      The edge from the last step of the body back to the loop's step has
      `"relation": "loop"`. When a call sits in the loop header, as in
      `for item in load_items(batch)`, it runs once, before the loop. One step that
      cites the line is anchored on both and stands for the function. To expand the
      function instead, give the call and the loop a step each by listing their
      fingerprints in `anchors`: the call's step enters the function, and the function
      leads back to the loop's step.
    - **Other edges.** `relation` is `sequence`, `branch`, `loop`, `exception` or `call`,
      and any edge may carry a `label`. The CLI checks an edge against the control
      structure of the code. A `return` or `raise` ends a path, and the two sides of a
      condition do not flow into each other. An edge the code does not support is refused
      unless you set `"resolution": "candidate"` or `"unknown"` and give a `reason`. The
      same applies to a step you cannot ground.
    - **Into a function and back.** When you expand a function, draw the way execution
      takes. Going in is an edge with `"relation": "call"` from the step that calls the
      function to the first step inside it. Inside, connect the steps as usual. Coming
      out is an edge from the place where the function is done to the step the caller
      runs next: a `sequence` edge from its last step, or the branch of a decision
      inside it, such as `{"source": "coupon", "target": "save", "relation": "branch",
      "branch": "false"}`. The CLI checks both: the source of the edge going in must
      lead to a call of that function, and the edge coming out must lead to code after
      that call. The function may be several calls down: functions in between that only
      pass the work on need no step, on the way in or on the way out. A `return` inside
      a called function is not accountable and needs no step of its own. Do not also
      draw an edge from the calling step past the function, as if it were skipped, and
      do not leave the function's last steps as dead ends when the flow goes on.
      When what the caller runs next is a call to another function you expand, the
      edge coming out goes straight to the first step inside that function; the second
      call needs no step of its own. Two calls in one expression, such as
      `cache_dir() / cache_key(item_id)`, are taken in the order Python runs them.
      - **Called from several places in one flow.** Draw the inside of the function
        once. Every step that calls it gets its own `call` edge to the first step
        inside, and the place where the function is done gets an edge to what each of
        those callers runs next. Do not give the second caller a plain step instead:
        the reader could not tell that it runs the same steps. When the function is
        done on the branch of a decision, that branch gets a `branch` edge to each
        step a caller runs next: the same `source` and `branch`, a different
        `target`. The CLI accepts them: it checks each edge on its own.
      - **Called first thing in a branch or a loop body.** The call needs no step of
        its own. The edge going in is then the decision's own `branch` edge, pointed
        at the first step inside the function:
        `{"source": "each", "target": "reserved", "relation": "branch", "branch": "loop"}`.
        It is checked the way a `call` edge is. Do not draw a `call` edge from the
        decision in its place: the decision would be left without that branch, and the
        reader could not tell which outcome leads into the function. Coming out is as
        for any call; when the loop body has nothing after the call, the function
        leads back to the loop's step.
      - **Handed over, not called** (`"deferred": true`). The `call` edge goes from the
        step that hands the function over to the first step inside it. When the caller
        does not wait (a thread is started, a task is queued, a callback is
        registered), that step also leads on to the caller's own next step, and the
        last step inside the function ends its path: draw no edge back. When the
        caller waits for the result (`await asyncio.to_thread(...)`,
        `future.result()`), draw the way back as for any call. The CLI accepts both,
        because the code's structure does not show which it is: decide by reading it.
    - **Error handling.** Which statement raises into which `except` block is not
      analyzed. An `except` block is off the normal path: when nothing is raised, the
      last step of the `try` body leads straight to the code after the `try`, and that
      is an ordinary edge. Inside the block connect steps as usual; where the block does
      not end in `return` or `raise`, its last step leads on to the code after the
      `try` as well. Describe a path into an `except` block with
      `"relation": "exception"`, from the step that can fail to the first step of the
      handler; any other edge into the block is refused. The CLI has no fact to check
      an `exception` edge by, so it accepts it as written and keeps it as a `candidate`:
      do not set `resolution` on it. A `reason` is optional; give one when it is not
      obvious what raises.
    - **Accounting.** Every unit in `accountable` must be an anchor of some step, be the
      condition a branch edge takes, or be listed in `omitted` with a reason: `logging`,
      `input_validation`, `error_handling`, `instrumentation`, `merged_into_step` or
      `out_of_business_scope`. The map is about the business chain, not about every line,
      so the choice for a called function is yours:
      - **Expand it** when it is part of the chain: anchor a step inside it. Its own
        conditions, loops and raised errors then become accountable, and the functions it
        calls become units in turn. `query --symbol` lists them beforehand under
        `expands_to`: give each a step or an entry in `omitted` in the same submission.
        The result of `submit` lists whatever is still open.
      - **Let one step stand for it**: anchor a step on the call and none inside the
        function. Nothing inside it has to be mentioned, and `graph.html` marks the step
        as not expanded with what it hides. When the function has eight or more
        conditions, loops and results inside, the step needs `unexpanded_reason`: one
        sentence on why its inside is not part of the chain.
      - **Omit it** with a reason when it is not business behaviour, such as logging or
        formatting a value. One entry covers every call to the same function.
    
      A step anchored on the call does not rule out steps anchored inside the function.
      With both in one flow, the function is expanded there, and the step on the call is
      where the `call` edge into it starts. That step does not stand for the function and
      needs no `unexpanded_reason` for it, however large the function is.
    
      Omitting excludes the other two. A function you expanded, or one a step is anchored
      on, must not be listed in `omitted` as well: its steps already account for every
      call to it. That is refused with `omitted_but_used`, and the error says which of
      the two it is and names the steps. A call that a cited range merely picks up is
      different: there the entry in `omitted` wins, and a step left with nothing else
      in its lines is refused with `step_not_anchored`.
    
      Only units in `accountable` need a place or an entry in `omitted`. `other_facts`
      and the inside of a function you did not expand need neither: an entry for one of
      them is accepted, recorded nowhere and listed under `ignored` in the result.
    
      Read a function with `query --symbol` before choosing; a rule that decides an outcome,
      such as a limit or a duplicate check, belongs on the map even two calls deep. Do not
      fold a whole flow into "call the service": the reader would see nothing.
    - **Observations** are optional risks you noticed while reading. They need evidence and
      a `severity` of `info`, `low` or `medium`.
    - **Stages.** A reader takes in about seven blocks across. A flow that is wider gets
      `stages`: each folds a run of steps into one block, and the reader opens the block to
      see its steps. This is where you abstract, so name a stage for what its steps get done
      together ("Check the payment", not "Steps 3 to 6"):
    
      ```
      "stages": [
        {"key": "pay", "name": "Charge the card and handle a decline", "steps": ["charge", "declined", "retry"]}
      ]
      ```
    
      A stage holds two or more steps that run one after another; no step outside it may
      run between them. The trigger stays outside. Keep outside the stages the decisions
      and outcomes a reader needs to follow the flow, and fold the work in between. A step
      belongs to one stage at most.
    
    Read the result:
    
    - `rejected`: fix what `errors` names, by `path` and `code`, and submit again. `path`
      gives the position, and `item` says which step, edge or omission that is by its own
      key: go by `item` when you look for it in your submission. For an omission it
      adds the code the fingerprint stands for and its line. Errors can come in
      rounds: structure first, then citations and anchors, then edges. `rejections`
      counts refusals of this task. Stop after three refusals that bring no new kind of
      error, and move on to other tasks. `accepted_version_kept` tells you whether an
      earlier accepted version is still in place.
    - `accepted` with `unaccounted` facts: the map stays partial, and `next_task` comes back
      to this task. Use those facts in a step or omit them with a reason, then submit again.
    - `accepted` with `too_wide`: with its stages folded the flow is more than seven blocks
      across. The map stays partial and `next_task` comes back to this task. Add or widen
      stages, then submit again.
    
    ## 4. Render and report
    
    ```
    genesis map render --repo /absolute/app --session SESSION_ID
    ```
    
    Exit code 0 means every planned flow is accepted with all its facts accounted for; 2
    means a usable partial map. Complete does not mean everything is certain: candidate and
    unknown items stay in a complete map and are listed under "Uncertain" in `summary.md`.
    
    Give the user the paths of `view.html` and `summary.md` under `.genesis/out/latest/`;
    `graph.html` beside them shows the same map as a plain outline. Then explain in their
    language:
    
    - the business domains and flows you found, and the decisions that matter in each;
    - what is uncertain, and why;
    - what is outside the result: skipped entries with their reasons, entries not handled,
      facts not accounted for, tasks that stayed failed;
    - the observations you recorded, marked as yours;
    - how flows hand over to each other, as your own reading, since the map does not record it.
    
    Say plainly that the names are your synthesis of the code, not confirmed requirements.
    If something in the result calls for action, name it and say what you could do next.
    Changing code or tests needs its own request from the user.
    
    ## 5. Changes since a revision
    
    Use this when the user asks what a commit, a pull request, a branch, a commit range or
    their uncommitted work changes or could break, which entry points or flows it reaches,
    whether tests cover it, or what its risks are.
    
    ### The short path
    
    ```
    genesis map prepare --repo /absolute/app --base MERGE_BASE --head HEAD
    genesis map diff    --repo /absolute/app --session SESSION_ID
    genesis map context --repo /absolute/app --session SESSION_ID --task task_change
    genesis map submit  --repo /absolute/app --session SESSION_ID --task task_change --input -
    genesis map render  --repo /absolute/app --session SESSION_ID
    ```
    
    1. `prepare`, with `--base` where the change starts and `--head` where it ends:
       - one commit: `--base COMMIT~1 --head COMMIT` (write `~1`, since zsh may read `^` as a
         pattern); a commit with no parent cannot be compared this way;
       - a commit range `A..B`: `--base A --head B`;
       - a branch or a pull request: `--head` the branch or `HEAD`, and as `--base` the
         commit `git merge-base main HEAD` prints, with the base branch of the pull request
         in place of `main` (or `origin/main` when there is no local `main`). `--base main`
         alone would also report what `main` gained since the branch started, as changes
         undone. A pull request that is not in the local repository has to be fetched
         first, for example with `git fetch origin pull/N/head` and `--head FETCH_HEAD`;
         Genesis does not fetch;
       - uncommitted work: `--base HEAD` and no `--head`. When `git status -s` shows
         new files (`??`) that belong to the change, add `--include-untracked`: untracked
         files are otherwise left out; `prepare` counts them under `untracked_left_out`
         and the report names them.
    
       Running `prepare` again on the same revisions keeps your accepted explanations and
       reports `"resumed": true`. When it reports `"engine": "agent"`, the project is not
       Python: continue in `other-languages.md`.
    2. `diff` lists every change, where each sits, the tests static analysis links to it,
       and the flows (`possibly_affected`) and candidate entries (`possible_entries`) that
       reach it. Its output can be long: pipe it into `jq` or Python, or write it to a file
       in your temporary directory, and read it in parts, for example with
       `jq '.changes[] | {change_id, kind, symbol_id, placement}'`. `possibly_affected`, `possible_entries` and
       `unanalyzed_changes` are top-level keys. Check each candidate in `possible_entries`
       by reading its code: name a real way in as an entry point of its changes, as your
       reading, and say which candidates you could not check. Record them in a plan
       (proposed, or skipped as `not_an_entry`) only when you also place changes on flows.
    3. Explain what the CLI owes, and only that. `context --task task_change` lists first
       the changes that need an explanation, 30 at a time, with both sides and their
       tests: those on the map, those a flow reaches, and those calls that failed to
       resolve may reach (`unresolved_calls`). `changes_waiting` counts them. Read them,
       decide each verdict, and `submit` your explanations ("Explaining the changes"
       below). Changes that are parts of one change in behaviour take one explanation that
       lists them all in `change_ids`. Ask for the context again until `changes_waiting`
       is 0; `status` offers `task_change` as `next_task` while any wait. Do not write
       explanations for the rest, such as changes to tests and import lines no entry
       reaches: the report lists them anyway, and the time is better spent on step 4. When
       the user asked nothing about tests, you may leave `verdict` out and keep the static
       result.
    4. Read for risks, as a pass of its own, once the explanations are accepted and before
       you render. The explanations say what changed; this pass asks what goes wrong, in
       which situation, and for whom. It is what a reviewer reads first. It is a reading
       pass: a list written from what you noticed while explaining misses most of what a
       review finds, so open the code below before you write a risk. The result that
       accepts the last explanations holds `read_for_risks`, and the context lists the same
       callers under `unchanged_callers`. Read in this order:
       - **The callers outside the changes** (`unchanged_callers`): for each changed
         function, the code that calls it and is not part of the change. Read each one:
         what it does with the new result, error, value or delay, and what its own callers
         and users then see. A caller with a `loop` runs the changed code once per item:
         time, requests, log lines and scans add up with the number of items.
       - **The changed files Genesis did not analyze** (`unanalyzed_changes`):
         documentation, example configuration, prompts and skill files. Do what each tells
         a user or an agent to do, as written: copy the example values as they are, follow
         a skill's steps with the flags it gives, and see what the new code does with that.
       - **Inputs.** For new or changed code that parses, matches, filters, validates or
         formats, list the inputs it may get wrong: empty or missing values, case and
         encoding, nesting, escapes and the other forms the same syntax allows, very large
         inputs, and the forms the docs, the tests or the neighbouring code accept. Follow
         each through the code. Where a function runs on its own without side effects, try
         the inputs you suspect from a small script in your temporary directory.
       - **The same input, before and after.** For every existing caller, user or stored
         output of the changed code, what does the input it already sends give now: a
         different value, type, format, order or id; an error where there was a result, or
         the reverse; a delay; a log line, message or metric that now means something
         else. Ids, keys, names, orderings and numbers that users or files have kept from
         before (snapshots, ledgers, caches, exports, stored results) break when an
         unchanged input now gives a different one. `lands_on` in the context shows where
         a new `break`, `continue` or `return` goes.
       - **Size.** How the cost grows with the input: a scan over every item for each item,
         a file read or a request per call, everything held in memory before the first
         result comes out.
       - **Failures.** What happens when a service, file or call the code relies on fails,
         is slow, or answers with success but carries an error or an unexpected shape, and
         what the caller then sees.
       - **Reach.** What the changed code now runs, reads or sends that it did not before:
         programs started from configuration, paths built from input, data that leaves the
         machine. Check that disabled entries, untrusted folders and secrets stay out.
       - **Other readers.** Code that reads the same value, setting, file or record, and
         whether two readers now disagree.
    
       Not a risk on its own: a gap in the tests (it goes in the verdict's `note`); a
       failure that needs code nobody has written yet; behaviour the change did not touch,
       unless it now happens more often or matters more; what the change sets out to do,
       for the inputs it is meant for. The same behaviour reaching inputs it was not meant
       for is a risk. A risk names the input or situation, what goes wrong, and for whom.
       Submit every risk you confirm as `risks`, in a submission of its own ("Explaining
       the changes" below).
    5. `render`. Once every owed change is explained it exits 0 with `change_status:
       complete`. When you described no flows, `affected_flow_not_synthesized` stays among
       the limitations: it says that no flow was described and does not keep the report
       from being complete. Then report as the end of this section says.
    
    The CLI takes explanations at any point of a change session: no plan and no flow
    description has to come first. Describe flows, as set out under "Placing changes on
    flows", only when the user wants to see the changes in the business flows, or when
    `diff` lists for a change neither a flow under `possibly_affected` nor a candidate
    under `possible_entries`. An `unassigned` change that a flow reaches already has its
    way in: explain it where it is.
    
    ### What `prepare` and `diff` return
    
    `--base REV` compares that revision with the working tree, or with `--head REV`. The
    result of `prepare` adds `changes`, `changes_placed`, `change_status` and
    `changed_files_not_analyzed`. The list of changes comes from the code alone, so `diff`
    shows it before you do anything; rendering at this point is optional and gives the
    same list on the static structure.
    
    In `diff` and `status`, `changes_placed` counts the changes with a place on the map.
    `changes_waiting` counts the changes you have not explained yet that the report needs:
    on the map, within reach of a flow, or possibly reached through calls that failed to
    resolve. `changes_unexplained` in the context counts every change without an
    explanation. Describing flows raises `changes_placed` and does not lower
    `changes_waiting`: that one goes down as `task_change` accepts explanations.
    
    - `changes` has one entry per changed condition, call, loop, result or definition, and
      `source_*` entries for everything else that changed, such as a constant or a default
      value. A branch or loop that was added or removed as a whole is one entry for the
      whole block. `before` and `after` give the text of each side with an
      `evidence_id`; a side with `"excerpt": true` shows less than the lines it cites.
    - `placement` is the step of the current map a change belongs to. Without a `reason`,
      a step rests on the changed code itself. A `reason` says how the place was chosen
      otherwise. An `unassigned` change has no place on the map, and its `reason` says
      whether a flow reaches it, whether calls that failed to resolve may reach it
      (`unresolved_calls`), or that no entry reaches it through resolved calls. The last
      is not proof that nothing does.
    - `tests` is what the test sources alone show. A test is linked when it calls the
      changed function, directly or through other calls, or requests a route that leads to
      it with an HTTP test client. `reached_only` at this point means only that; `unknown`
      means no such test was found. The linked tests come most relevant first: those this
      change adds or edits (`changed_with_it`), then by `calls_away` (1: the test calls
      the changed function itself). A handler registered with
      `set_defaults(func=...)` on an argparse subcommand is linked only to tests whose
      strings name that subcommand. Static analysis does not follow pytest fixtures,
      `subprocess` runs of the program, decorators that call a function later, property
      reads, or chains longer than five calls: look for such tests yourself.
    - `possibly_affected` lists flows that can reach changed code without a step on it;
      `removed_flows` the entries that no longer exist; `unanalyzed_changes` the changed
      files Genesis did not analyze, such as other languages. Mention those that are not
      empty. A changed document or skill file can describe or drive the changed code:
      read it against the Python change.
    - `limitations` says what the analysis could not do. `unresolved_local_calls` means
      calls into the code base's own modules failed to resolve: changes that look
      unreachable may be reached, and their tests may not be linked.
    - `closest_flow` says where to describe changed code that no flow has expanded yet
      (see below).
    - `possible_entries` lists functions no code calls that lead to the changed code and
      start no flow. Each has its `entry_id`, its `symbol_id` and the `change_ids` it
      leads to. They are checked below, not reported as they are.
    
    ### Explaining the changes
    
    Explain the changes with `task_change`, whether or not you described flows. `status`
    offers it as `next_task` while changes wait for an explanation.
    
    ```
    genesis map context --repo /absolute/app --session SESSION_ID --task task_change
    ```
    
    It returns up to 30 changes, those that still need an explanation first. Each one carries the
    frozen text of both sides under `before` and `after`: read both, read the tests listed
    for it, and search for tests that reach it another way. A side marked
    `"excerpt": true` is shorter than its lines: an added or removed definition shows
    its header only, a long block is cut at 800 characters, and a statement written over
    several lines is shown on one. Read such a side in full with
    `genesis map read --evidence <id>`; any other side already is the full text. For the
    code around a change, read the files at the two revisions of the session, or a diff
    between them.
    When the head side is the working tree, the files may have changed since `prepare`:
    check what you quote against the frozen text. A linked test may still not reach the
    change, for example when it replaces the changed function with a stub. Then submit:
    
    ```json
    {
      "changes": [
        {"change_id": "chg_9603691aeade3d47",
         "summary": "The review threshold now includes the boundary amount.",
         "effect": "A report of exactly the threshold amount goes to model review instead of being approved at once.",
         "verdict": "reached_only",
         "note": "The test submits 50 and 500 and accepts either status, so the boundary amount is never exercised.",
         "test_ids": ["head::tests/test_submit.py#test_submit_report_status"]},
        {"change_id": "chg_f1c02c12d9463145",
         "summary": "Approval no longer records the intermediate reviewed status.",
         "verdict": "not_reached",
         "note": "No test calls the approval route or approve_report."},
        {"change_ids": ["chg_03a420c71b4e228d", "chg_da88254492c7c41b"],
         "summary": "The nightly cleanup no longer archives the reports before it clears them.",
         "verdict": "not_reached",
         "note": "No test calls nightly_cleanup."}
      ]
    }
    ```
    
    ```
    genesis map submit --repo /absolute/app --session SESSION_ID --task task_change --input - <<'EOF'
    ...
    EOF
    ```
    
    After the risk pass of step 4, submit the risks on their own:
    
    ```json
    {
      "risks": [
        {"statement": "A report of exactly the threshold amount now goes to model review, so while the model service is slow or down its submission waits on that call instead of being approved at once.",
         "severity": "medium",
         "category": "reliability",
         "change_ids": ["chg_9603691aeade3d47"],
         "evidence": [{"path": "expense/api.py", "start_line": 14, "end_line": 14,
                       "quote": "verdict = await review_with_model(report)"}]}
      ]
    }
    ```
    
    - `summary` says in business terms what is different, and `effect` what it means for the
      flow. Do not describe the line edit. Write both in the user's language.
    - Add `short_summary` for the map card: one short clause (up to 120 characters), preserving
      the triggering condition and consequence. Keep the complete explanation in `summary`
      and `effect`; do not omit qualifications to make an uncertain claim sound definite.
    - `verdict` is your reading of the tests, and it answers one question: would a test
      fail if this change were undone? `covered`: a test runs the changed code and would
      fail if the change were undone; name it in `test_ids`. `reached_only`: tests run the
      code but would not fail if the change were undone, because their input misses the
      changed path or they check nothing it affects; `note` says what is missing.
      `not_reached`: no test reaches it. `unknown`: you could not tell; `note` says why.
      Every verdict needs a `note`. Leave `verdict` out to keep the static result, which
      the report shows as "called by tests, not assessed".
    - A statement that runs on every call, such as an added `add_argument` or an
      assignment, is `covered` by a test that runs the code and would fail without it.
      An input value no test uses is not a missed path.
    - An added definition (`symbol_added`) is one change, so judge it as a whole:
      `covered` when a test runs it and would fail without it. Name the branches no test
      takes in `note`; they do not make it `reached_only`.
    - A test counts when the project's default test command runs it. Tests skipped by
      default do not count: a `skip` mark, a `skipif` whose condition holds in a normal
      run (such as a missing environment variable or credential), a marker the default
      configuration deselects. Name them in `note` and judge by the other tests. Needing
      the network or a model download does not by itself exclude a test; you may say so
      in `note`.
    - For a change that replaces code (both sides present), undoing it puts the `before`
      side back, so take the test's input through the `before` side too. When the old
      code gives the same outcome for that input (the same exception, the same value, the
      same call), the test still passes and does not make the change `covered`. A test
      that checks only an exception type or a field name often passes on both sides: five
      validators replaced by a `Literal` type both raise `ValidationError` for an unknown
      value, so a test that only matches the field name in the error is `reached_only`.
      `covered` needs a test whose input gets a different outcome on the two sides.
    - A verdict answers only whether a test would fail. What the tests leave unchecked
      goes in its `note`, not into `risks`.
    - For code that was removed, the changed path is the input the removed code used to
      handle. `covered`: a test gives such an input and would fail if the removed code
      were put back. `reached_only`: tests run the function but never with such an input. Code that
      replaces it is a change of its own: judge each on its own input, and do not copy
      the verdict from one to the other. The same holds when another function now does
      what the removed code did: the input still has to go through the function the
      code was removed from. A test that calls only the other function is a near miss:
      describe it in `note`.
    - One `source_*` change can hold several values, such as two limits set on
      neighbouring lines of a function. `covered` needs, for each value, a test that would
      fail if that value were undone. When only some have one, use `reached_only` and name
      the others in `note`.
    - `test_ids` names the tests your verdict rests on, as `head::<path>#<function>`, for
      example `head::tests/test_api.py#test_refund`; a method is `#TestClass.test_name`.
      The tests static analysis linked stay listed after them. A test static analysis did
      not link may be named; the report marks it as identified by you. `not_reached` names
      no tests: describe near misses in `note`.
    - The CLI refuses a verdict the test sources contradict: `covered` with no `test_ids`,
      or when none of the named tests contains an assertion, `not_reached` when a test
      calls the changed function itself or requests its route, an unknown `change_id` or
      test. A refusal changes nothing already accepted.
    - `risks` lists the risks you see in the changes, each with the `change_ids` it comes
      from and a `severity` of `info`, `low` (the default) or `medium`; there is no
      `high`, since it is your reading and no rule checked it. `category` is optional:
      `reliability`, `correctness`, `data_integrity`, `security`, `performance` or
      `other`. `evidence` may cite code beyond the changed lines that the risk lands on,
      as flow observations do (`path`, `start_line`, `end_line` and a `quote` from those
      lines, or an `evidence_id`). When the quote is not on the lines given, the CLI
      takes the nearest range of as many lines, up to five lines away, that holds it, and
      says so under `evidence_moved` in the result. The same statement about the same
      changes replaces the earlier one. The report lists them under "Risks seen in the
      changes", as your reading.
    - `unchanged_callers` in the context lists, for each changed function, up to three
      places that call it and are not part of the change, those in a loop first with the
      loop they run in (`callers_total` counts them all). Calls from tests are left out:
      they are with each change. Once nothing waits for an explanation, the result of
      `submit` repeats them under `read_for_risks`, with the changed files Genesis did not
      analyze. They are where step 4 starts reading.
    - `change_ids` in an explanation lists several changes in place of `change_id`. Each
      of them is checked and stored as if explained alone; a problem with one of them is
      reported at its place in the list.
    - An observation you recorded on a flow is shown as `introduced` when its evidence cites
      code this change added, or when its whole flow is new, and as `persisting` when it
      cites code the change modified. Cite the changed lines when the risk comes from them.
    - A change to a test (its `kind` starts with `test_`) needs no explanation. If you
      give one, it takes a `summary` and no `verdict`; with a verdict, the whole
      submission is refused with `verdict_on_test`.
    - Submissions add up. Ask for the context again until `changes_waiting` is 0. A
      change that no step covers but a flow can reach counts in `changes_waiting` from
      the start, so a session is not done because nothing is on the map yet. On the short
      path, explain such a change where it is and name the flows that reach it; bring it
      onto the map by describing its flow only when the user wants the flows shown. So
      does a change that calls which failed to resolve may reach. A change no entry
      reaches, such as an import line, does not count; the context lists it after the
      others, and you explain it only when it matters to the user's question.
    
    ### Placing changes on flows
    
    Do this when the user wants the changes shown in the business flows, or to settle what
    reaches a change that has no place. Bring the changes onto the map before you report
    them as off it. A change listed under
    `possibly_affected` for a flow sits in a function that flow calls, or hands to a thread
    or a task runner, with no step on it yet. Expand the functions on the way to it by
    anchoring steps inside them; `status` shows `changes_placed` going up as they land.
    
    Code that several flows share is expanded on one of them, and the CLI says which.
    `closest_flow` lists every change whose function no flow has expanded yet, whether
    it has no place or sits on a step that only calls the function, under the one flow
    that reaches it through the fewest calls. Plan that flow and expand the functions
    there. In every other flow that reaches or calls the same code, do not expand it
    again, whichever flow you happen to describe first: let one step stand for the
    function. That step may show the change with the reason that it calls the changed
    function, and that is all the flow needs.
    
    The context of a flow task says the same under `change`: `placed` are the changes on
    its steps now, `closest_to` the ones whose code is to be expanded in this flow, and
    `on_other_flows` the ones this flow reaches or calls that another flow describes.
    `expand` names the function each `closest_to` change is in, nearest to the entry
    first; for a changed constant it is the nearest function that reads it. Anchor at
    least one step inside every function listed there, also when all that changed is a
    text or a value and the function decides nothing. Until a step is inside it, the
    change has no place and stays in `closest_to`. A change also leaves `closest_to`
    when another flow is accepted with a step inside its function, which for a changed
    constant is any function that reads it. It is then listed under `on_other_flows`,
    and this flow no longer has to expand anything for it. Go by the context you asked
    for last, not by an earlier `diff`.
    
    The map only has the entries it knows, so a change can also be reached from a way in
    that has no flow. `diff` lists the candidates under `possible_entries`, and `status`
    has the same list under `change.possible_entries`. It holds up to 20 of them, and
    `possible_entries_total` beside it counts all that are still to check; the rest
    appear once you have proposed the ones listed or skipped them for any reason but
    `budget`, which leaves a candidate unchecked. Check every one, also when
    flows are already listed for the change. When it is a real way in (a command
    registered by hand, a scheduled job, a message handler), propose it as in section 2,
    give it a flow and describe that flow too. When it is a helper or code nothing uses,
    list its `entry_id` in the plan under `skipped` with `"reason": "not_an_entry"` and a
    `note` that says what you found, for example that only tests call it. It then leaves
    both lists, and `summary.md` shows it as checked with your note; a candidate you
    leave alone stays listed as unchecked. Keep that entry in every later plan: a plan
    replaces the one before it, and a candidate it no longer skips is back on both
    lists. When a change is still `unassigned`, no flow is listed for it and nothing
    is offered, look for a missing entry point yourself before you report the change as
    off the map.
    
    Reformatting, comments and code that only moved are not changes.
    
    Then plan as in section 2 and describe flows as in section 3. Only the flows the changes
    land on are needed: `status` lists them under `change.affected_flows`, and `next_task`
    offers their tasks first; the flows named under `closest_flow` are among them, before
    and after you plan. A flow that only reaches changed code, with every one of those
    changes placed on another flow or listed under another flow in `closest_flow`, needs a
    name in the plan and nothing more: `view.html` shows it as one line with the number of
    changes on its way. Do not describe it unless the user asks.
    
    Plan no other flows. Apart from the candidates you checked and skipped as
    `not_an_entry`, leave every other entry out of both `flows` and `skipped`: it 

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.