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
Install
npx skills add https://github.com/GenesisAgentInfra/genesis/tree/main/packages/genesis_ci/src/genesis_ci/assets/skills/genesis
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install genesisagentinfra-genesis@llmmart
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. Runversionas 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 preparethen 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 readother-languages.mdnext 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, runmap preparewith--engine agent; otherwise only the Python files are mapped. - On a repository with no source file Genesis can read,
map preparefails withunsupported_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.htmlis 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.htmlis 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.
tiersays which flows the reader came for.primaryis a process that decides something or has an effect: placing an order, running an analysis, approving a report.supportingis 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. nameis required and is the name a person would use, never a route or a function name.summaryis 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, andnot_an_entryfor a function that only looked like a way in. That one needs anotesaying what you found. - An entry you put in neither
flowsnorskippedis accepted and counted as not handled. - If the analyzers missed a real entry, add it under
proposed_entrieswithsymbol_id,kind,reasonandevidence.kindis one ofhttp_route,cli_command,task,scheduled,public_api,agent_tool,handler,main;handleris 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 underpossible_entries, already has itsentry_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 underentrieswith 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
--inputthe 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 theanchorto use for its trigger step;source, the text of each entry function;accountable, what this flow must account for, in units. Each has afingerprint, anevidence_idand aunit:fact: a condition, loop or result of the entry function; a condition lists itsbranches.function: a function the chain calls, once however often it is called.insidesays how many conditions, loops and results it holds and which outside systems itreaches. With"deferred": truethe 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, andnotenames 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 needsunexpanded_reason: write it in your first submission instead of learning it from a refusal.query --symbolgives 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_truncatedis 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.
kindistrigger,action,decision,externalorresult. One step may cover several lines of code. Do not add a step the code does not show.kindis your reading of what the step is, whatever it is anchored on: a loop or a condition may anchor anactionstep that covers the whole of it, such as "save every result". Only make it adecisionwhen the map should show its branches, sincebranchedges leave decision steps only.Evidence. Each item is either
{"evidence_id": "ev_..."}taken from the context or a query, or apathwithstart_line,end_lineand a shortquotecopied 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
resolvedonly if it rests on analyzer facts. Either list fingerprints inanchors, 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 asitems.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 areturnthat runs over several lines; when you list that function inomitted, the step is not taken to stand for it. Use the entry'sanchorfor 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
branchedge leaves adecisionstep, names a branch its condition really has (seebranches), and must point at a step that branch leads to.labelis your wording for it.Loops. A loop has the branches
loop, into its body, andexit.breakandcontinueare 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 forbreak, and back to the loop's step forcontinue. 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 infor 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 inanchors: the call's step enters the function, and the function leads back to the loop's step.Other edges.
relationissequence,branch,loop,exceptionorcall, and any edge may carry alabel. The CLI checks an edge against the control structure of the code. Areturnorraiseends 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 areason. 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: asequenceedge 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. Areturninside 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 ascache_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
calledge 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 abranchedge to each step a caller runs next: the samesourceandbranch, a differenttarget. 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
branchedge, pointed at the first step inside the function:{"source": "each", "target": "reserved", "relation": "branch", "branch": "loop"}. It is checked the way acalledge is. Do not draw acalledge 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). Thecalledge 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.
- Called from several places in one flow. Draw the inside of the function
once. Every step that calls it gets its own
Error handling. Which statement raises into which
exceptblock is not analyzed. Anexceptblock is off the normal path: when nothing is raised, the last step of thetrybody leads straight to the code after thetry, and that is an ordinary edge. Inside the block connect steps as usual; where the block does not end inreturnorraise, its last step leads on to the code after thetryas well. Describe a path into anexceptblock 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 anexceptionedge by, so it accepts it as written and keeps it as acandidate: do not setresolutionon it. Areasonis optional; give one when it is not obvious what raises.Accounting. Every unit in
accountablemust be an anchor of some step, be the condition a branch edge takes, or be listed inomittedwith a reason:logging,input_validation,error_handling,instrumentation,merged_into_steporout_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 --symbollists them beforehand underexpands_to: give each a step or an entry inomittedin the same submission. The result ofsubmitlists 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.htmlmarks the step as not expanded with what it hides. When the function has eight or more conditions, loops and results inside, the step needsunexpanded_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
calledge into it starts. That step does not stand for the function and needs nounexpanded_reasonfor 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
omittedas well: its steps already account for every call to it. That is refused withomitted_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 inomittedwins, and a step left with nothing else in its lines is refused withstep_not_anchored.Only units in
accountableneed a place or an entry inomitted.other_factsand the inside of a function you did not expand need neither: an entry for one of them is accepted, recorded nowhere and listed underignoredin the result.Read a function with
query --symbolbefore 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.- 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.
Observations are optional risks you noticed while reading. They need evidence and a
severityofinfo,lowormedium.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 whaterrorsnames, bypathandcode, and submit again.pathgives the position, anditemsays which step, edge or omission that is by its own key: go byitemwhen 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.rejectionscounts refusals of this task. Stop after three refusals that bring no new kind of error, and move on to other tasks.accepted_version_kepttells you whether an earlier accepted version is still in place.acceptedwithunaccountedfacts: the map stays partial, andnext_taskcomes back to this task. Use those facts in a step or omit them with a reason, then submit again.acceptedwithtoo_wide: with its stages folded the flow is more than seven blocks across. The map stays partial andnext_taskcomes 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
prepare, with--basewhere the change starts and--headwhere 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:
--headthe branch orHEAD, and as--basethe commitgit merge-base main HEADprints, with the base branch of the pull request in place ofmain(ororigin/mainwhen there is no localmain).--base mainalone would also report whatmaingained since the branch started, as changes undone. A pull request that is not in the local repository has to be fetched first, for example withgit fetch origin pull/N/headand--head FETCH_HEAD; Genesis does not fetch; - uncommitted work:
--base HEADand no--head. Whengit status -sshows new files (??) that belong to the change, add--include-untracked: untracked files are otherwise left out;preparecounts them underuntracked_left_outand the report names them.
Running
prepareagain on the same revisions keeps your accepted explanations and reports"resumed": true. When it reports"engine": "agent", the project is not Python: continue inother-languages.md.- one commit:
difflists 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 intojqor Python, or write it to a file in your temporary directory, and read it in parts, for example withjq '.changes[] | {change_id, kind, symbol_id, placement}'.possibly_affected,possible_entriesandunanalyzed_changesare top-level keys. Check each candidate inpossible_entriesby 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 asnot_an_entry) only when you also place changes on flows.Explain what the CLI owes, and only that.
context --task task_changelists 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_waitingcounts them. Read them, decide each verdict, andsubmityour explanations ("Explaining the changes" below). Changes that are parts of one change in behaviour take one explanation that lists them all inchange_ids. Ask for the context again untilchanges_waitingis 0;statusofferstask_changeasnext_taskwhile 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 leaveverdictout and keep the static result.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 underunchanged_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 aloopruns 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_onin the context shows where a newbreak,continueorreturngoes. - 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 asrisks, in a submission of its own ("Explaining the changes" below).- The callers outside the changes (
render. Once every owed change is explained it exits 0 withchange_status: complete. When you described no flows,affected_flow_not_synthesizedstays 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.
changeshas one entry per changed condition, call, loop, result or definition, andsource_*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.beforeandaftergive the text of each side with anevidence_id; a side with"excerpt": trueshows less than the lines it cites.placementis the step of the current map a change belongs to. Without areason, a step rests on the changed code itself. Areasonsays how the place was chosen otherwise. Anunassignedchange has no place on the map, and itsreasonsays 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.testsis 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_onlyat this point means only that;unknownmeans no such test was found. The linked tests come most relevant first: those this change adds or edits (changed_with_it), then bycalls_away(1: the test calls the changed function itself). A handler registered withset_defaults(func=...)on an argparse subcommand is linked only to tests whose strings name that subcommand. Static analysis does not follow pytest fixtures,subprocessruns of the program, decorators that call a function later, property reads, or chains longer than five calls: look for such tests yourself.possibly_affectedlists flows that can reach changed code without a step on it;removed_flowsthe entries that no longer exist;unanalyzed_changesthe 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.limitationssays what the analysis could not do.unresolved_local_callsmeans 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_flowsays where to describe changed code that no flow has expanded yet (see below).possible_entrieslists functions no code calls that lead to the changed code and start no flow. Each has itsentry_id, itssymbol_idand thechange_idsit 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)"}]}
]
}
summarysays in business terms what is different, andeffectwhat it means for the flow. Do not describe the line edit. Write both in the user's language.- Add
short_summaryfor the map card: one short clause (up to 120 characters), preserving the triggering condition and consequence. Keep the complete explanation insummaryandeffect; do not omit qualifications to make an uncertain claim sound definite. verdictis 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 intest_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;notesays what is missing.not_reached: no test reaches it.unknown: you could not tell;notesays why. Every verdict needs anote. Leaveverdictout 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_argumentor an assignment, iscoveredby 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:coveredwhen a test runs it and would fail without it. Name the branches no test takes innote; they do not make itreached_only. - A test counts when the project's default test command runs it. Tests skipped by
default do not count: a
skipmark, askipifwhose condition holds in a normal run (such as a missing environment variable or credential), a marker the default configuration deselects. Name them innoteand judge by the other tests. Needing the network or a model download does not by itself exclude a test; you may say so innote. - For a change that replaces code (both sides present), undoing it puts the
beforeside back, so take the test's input through thebeforeside 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 changecovered. A test that checks only an exception type or a field name often passes on both sides: five validators replaced by aLiteraltype both raiseValidationErrorfor an unknown value, so a test that only matches the field name in the error isreached_only.coveredneeds 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 intorisks. - 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 innote. - One
source_*change can hold several values, such as two limits set on neighbouring lines of a function.coveredneeds, for each value, a test that would fail if that value were undone. When only some have one, usereached_onlyand name the others innote. test_idsnames the tests your verdict rests on, ashead::<path>#<function>, for examplehead::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_reachednames no tests: describe near misses innote.- The CLI refuses a verdict the test sources contradict:
coveredwith notest_ids, or when none of the named tests contains an assertion,not_reachedwhen a test calls the changed function itself or requests its route, an unknownchange_idor test. A refusal changes nothing already accepted. riskslists the risks you see in the changes, each with thechange_idsit comes from and aseverityofinfo,low(the default) ormedium; there is nohigh, since it is your reading and no rule checked it.categoryis optional:reliability,correctness,data_integrity,security,performanceorother.evidencemay cite code beyond the changed lines that the risk lands on, as flow observations do (path,start_line,end_lineand aquotefrom those lines, or anevidence_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 underevidence_movedin 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_callersin 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_totalcounts them all). Calls from tests are left out: they are with each change. Once nothing waits for an explanation, the result ofsubmitrepeats them underread_for_risks, with the changed files Genesis did not analyze. They are where step 4 starts reading.change_idsin an explanation lists several changes in place ofchange_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
introducedwhen its evidence cites code this change added, or when its whole flow is new, and aspersistingwhen it cites code the change modified. Cite the changed lines when the risk comes from them. - A change to a test (its
kindstarts withtest_) needs no explanation. If you give one, it takes asummaryand noverdict; with a verdict, the whole submission is refused withverdict_on_test. - Submissions add up. Ask for the context again until
changes_waitingis 0. A change that no step covers but a flow can reach counts inchanges_waitingfrom 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.
Reviews (0)
No reviews yet.
No comments yet.