genesis — скилл для Claude Code: карта бизнес-процессов
Скилл genesis для Claude Code строит карту бизнес-процессов проекта по исходному коду. Он включается, когда нужно понять влияние изменений на процессы или проверить, что покрывают существующие тесты.
Apache-2.0 ★ 52 обновлён 2026-11-16
npx skills add GenesisAgentInfra/genesis --skill genesis -a claude-codeЧто делает genesis
genesis строит карту бизнес-процессов по Python-коду и показывает, какие шаги затрагивает изменение. CLI анализирует структуру репозитория, а агент описывает смысл процессов; CLI принимает или отклоняет описания целиком и формирует страницы view.html и graph.html.
Для запуска нужен доверенный интерпретатор Python 3 и окружение Genesis, созданное при установке. Команды запускают через scripts/run_genesis.py с полным путём и флагом -I; отдельную команду genesis запускать нельзя. Если подготовка сообщает unsupported_repository, репозиторий не подходит для анализа.
Карта описывает поведение кода, но не подтверждает выполнение тестов. Оценка покрытия тестами основана на чтении исходников: запускать тесты и импортировать данные покрытия скилл не умеет.
Какие задачи решает
- составить карту бизнес-процессов из Python-кода
- показать, какие шаги процессов меняет ветка или коммит
- сопоставить изменение с существующими тестами
- объяснить готовую карту по её файлам
Примеры запросов агенту
- Построй карту бизнес-процессов этого проекта.
- Покажи, что изменилось в процессах между текущей веткой и
main. - Объясни существующую карту Genesis по её файлам.
Как установить genesis
1Через Skills CLI (Vercel)
npx skills add GenesisAgentInfra/genesis --skill genesis -a claude-code2Вручную: положить файлы
~/.claude/skills/genesis/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/genesis/
1Через Skills CLI (Vercel)
npx skills add GenesisAgentInfra/genesis --skill genesis -a codex2Вручную: положить файлы
.agents/skills/genesis/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add GenesisAgentInfra/genesis --skill genesis -a cursor2Вручную: положить файлы
.cursor/skills/genesis/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install GenesisAgentInfra/genesis packages/genesis_ci/src/genesis_ci/assets/skills/genesis2Вручную: положить файлы
.github/skills/genesis/SKILL.md1Через Skills CLI (Vercel)
npx skills add GenesisAgentInfra/genesis --skill genesis -a gemini-cli2Командой платформы
gemini skills install https://github.com/GenesisAgentInfra/genesis --path packages/genesis_ci/src/genesis_ci/assets/skills/genesisВручную: положить файлы
.devin/skills/genesis/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о genesis
Как установить genesis в Claude Code?
Выполни npx skills add GenesisAgentInfra/genesis --skill genesis -a claude-code. Файл скилла находится по пути ~/.claude/skills/genesis/SKILL.md.
Что делает genesis?
Он превращает Python-код репозитория в карту бизнес-процессов и показывает, какие шаги затрагивают изменения. Отдельно оценивает покрытие изменений существующими тестами по исходникам.
Что нужно для работы genesis?
Нужны доверенный интерпретатор Python 3 и окружение Genesis, созданное при установке скилла. CLI запускается через scripts/run_genesis.py с полным путём и флагом -I.
Исходный текст
SKILL.md · Apache-2.0
---
name: genesis
description: Map the business flows of a codebase with Genesis, backed by code evidence, and show what a change does to them. Use 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 what a branch, commit range or uncommitted change alters in business terms, asks whether existing tests cover a change, asks to update or continue such a map, or asks about an existing Genesis map. Match the intent in any language, not exact keywords. Explain an existing map from its files without starting a new analysis.
---
# 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, and the CLI accepts
or rejects each 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.
## What is supported today
- Python source. On a repository without analyzable Python, `map prepare` fails with
`unsupported_repository`; tell the user what it reported and stop.
- A full map of the current code.
- The changes since a revision, placed on the steps of that map, with an assessment of
whether existing tests cover each one (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`; `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. If there are many flows,
propose starting with the area the user cares about.
## 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`.
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.
## 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 branch, a commit range or their uncommitted work
changes, where a change lands in the business flows, or whether tests cover it.
```
genesis map prepare --repo /absolute/app --base main
genesis map diff --repo /absolute/app --session SESSION_ID
```
`--base REV` compares that revision with the working tree, or with `--head REV`. The...
© GenesisAgentInfra · Apache-2.0 · GenesisAgentInfra/genesis