Walkthrough: a traced, cited account of one business process

[peopleworks]

Walkthrough — a traced, cited account of one business process

What it is

Today the tool answers what exists: this entity, that controller, these rules. It cannot answer
how does commission get calculated — because a process is not a declaration. It is a path across
several declarations, and nothing in the extractor walks a path.

A walkthrough takes a seed the user names — an action, a controller, an entity, a method — walks
the code that participates, and produces three things:

1. an ordered account of what happens, every claim carrying file:line
2. a Mermaid diagram of the flow, drawn from the walk
3. a list of what the walk could not resolve, named rather than hidden

The governing decision: the graph is extracted, only the prose is generated

If a model decides what belongs in "the commission process", the result is a document that is
beautiful, authoritative, wrong in places, and uncheckable. If the extractor decides the scope with
a deterministic walk and the model only narrates what was found, then the scope is reviewable, the
document diffs, and a bad sentence is fixable without touching the structure.

The diagram is never drawn by the model. Ask an LLM for a Mermaid flow and it invents edges,
with a confidence indistinguishable from the true ones. Mermaid emitted from a real subgraph is
correct by construction. The model may write labels; it may not add arrows.

The consequence is the plan's backbone: the valuable half needs no AI at all.

Phase 0 — AI access has to stop meaning "PeopleWorks Copilot" (prerequisite, small)

Every AI path in the repo today requires a PW Copilot account. --enrich reads config.ApiUrl and
config.Token, then calls GetAiProviderAsync() to obtain the model's API key from PW Copilot
(Program.cs:1978-2011). The DescriptionAnnotator does the same through COPILOT_* environment
variables. There is no bring-your-own-key path anywhere.

So on a public MIT repo, no outside user can run any AI feature — Martin included. That is
tolerable while enrichment is a side dish. It is not tolerable if a narrated walkthrough becomes the
headline feature, because the headline would be unusable by everyone who is not us.

• accept --api-key / OPENAI_API_KEY / ANTHROPIC_API_KEY and a --base-url, any
  OpenAI-compatible endpoint
• keep the PW Copilot provider as one option among them, not the gate
• one resolution point shared by --enrich, the annotator and the walkthrough

Worth doing on its own merits regardless of this feature: it unblocks --enrich for every user the
project has.

Phase 1 — the slice (Core, deterministic, no AI, the substantial work)

The extractor already holds the raw material: ExecuteMethodBody, Methods[].Body,
ReferencedEntities, EnabledCriteria, TargetObjectsCriteria, plus every entity, rule and
relationship. What it lacks is a call and reference graph — EntityGraph is entity-to-entity
only.

New in Core/Walkthrough/:

• ProcessSlice.From(project, seed, depth) — breadth-first from the seed over
  method-calls-method, method-touches-entity, action-belongs-to-controller,
  controller-targets-entity, entity-carries-rule.
• Resolution is syntax-only, like everything else here: a call is matched by name against
  methods the project declares. No compilation, no DevExpress, no symbol table.
• Every node carries its file:line and the kind of thing it is.
• Bounded by depth, because in a real application everything eventually reaches everything.

Honesty about what syntax cannot see. A virtual call, an interface dispatch, a handler wired
through the framework — these cannot be resolved from syntax. The slice must record them as
unresolved edges, with the candidates it knows of, and the walkthrough must print them. Naming the
gap is the project's existing ethic: rules name their declarer, a criteria-less rule reads always.
A walkthrough that quietly stops at an interface would be the first output here that lies by
omission.

Tests. A fixture whose process is several hops long — action → service method → entity write →
validation rule — and assertions on the exact node set and the exact edge set. This is the muscle
the repo already has.

Phase 2 — the document (still no AI, and already worth shipping)

• Mermaid from the subgraph. Deterministic, and the first Mermaid in the project — there is none
  today.
• Markdown walkthrough: the ordered account, each step cited, unresolved edges listed at the end.
• CLI: xaflogic walkthrough --from CalculateCommissions [--depth N] [--out FILE]
• MCP: xaf_walkthrough. Worth its own line — the eleven existing tools return atoms
  (xaf_entity, xaf_controller). An agent asked "how does commission work" has to grep and guess.
  The slice serves the agent at least as well as it serves the human, and once it exists the tool is
  nearly free.

At the end of phase 2 the feature is complete for anyone who can read a diagram, works offline, has
no API key, and is fully covered by tests.

Phase 3 — narration (opt-in AI, on top of a fixed structure)

--narrate sends the already-computed slice to the model and asks for prose over it: what the
process is for, in business terms, in the order the walk found.

• the model receives the facts; it does not choose them
• every paragraph must cite the step it came from — a sentence that cannot cite does not ship
• failure is graceful and visible: no narration, structure intact, as --enrich already behaves
• reuses BusinessLogicEnricher's shape and the phase 0 client

Phase 4 — the part no chat can imitate

xaflogic walkthrough --from X --since <ref> — regenerate the slice against a previous snapshot and
report what changed in this process: a step added, a rule now governing it, a branch removed.

The project already has hash-based change detection, snapshots and diff. No conversational agent
can answer "what changed in the commission calculation since 0.14" because it has no yesterday.
This is the reason the walkthrough is a document rather than a question, and it should be stated as
the goal from the start even though it is built last.

Order, and why

0 → 1 → 2 ship something usable with no AI dependency at all. 3 and 4 are additive.
If the project only ever completes phase 2, it has gained the ability to explain a process — which
is the thing that started it — without taking on a single new runtime dependency.

Risks

Risk	Answer
The slice reaches everything	Depth bound, plus ranking by distance from the seed; report the bound
The slice misses a hop through an interface	Record and print unresolved edges with candidates
Narration is confidently wrong	Model narrates, never discovers; every claim cites; prose is opt-in
The AI feature is unusable by outside users	Phase 0, before any of this
A generated document goes stale	Phase 4 is the answer, and change detection already exists

Naming

Work Book reads like an exercise book. In this project's vocabulary the thing is a
walkthrough — the traced account of one process. xaflogic walkthrough, xaf_walkthrough.

[peopleworks]

Complete, and shipped in 0.15.0.

Phase
0	AI access stops meaning PeopleWorks Copilot	#24 → #26
1	The slice — a bounded, syntax-only walk	#30, #31
2	The document, the diagram, xaflogic walkthrough, xaf_walkthrough	#32
3	--narrate	#33
4	--since	#34

The three decisions the design rested on all survived contact:

The graph is extracted; only the prose is generated. No model chooses what belongs in a process. A test counts the arrows in the Mermaid against the edges in the walk and the boxes against the nodes, because an invented arrow is exactly what a glance at a diagram that looks right would miss.

A call it cannot follow is printed, not dropped. The fixture built for this — one action, one handler, a Recalculate two controllers override — produces a slice containing no entities at all, and the document says so. No existing fixture could reach that case; every one of them resolved cleanly, which is how a blind spot stays invisible.

The valuable half needs no AI. --narrate is opt-in and the least load-bearing thing in the release: a paragraph that cannot name a real step is dropped before rendering, and a document generated with an empty narration is byte-for-byte the one generated with none.

One thing the design did not anticipate: nothing in the model knew a line number. The extraction knew which file a class was in and nothing narrower, so there was nothing to cite with. #30 fixed that, taking the line from the identifier token rather than the declaration's span — Customer sits behind a doc comment and four attributes, so the two answers are four lines apart and only one of them is the line anybody means. Worth having on its own: xaf_entity used to hand an agent a name and leave it to search.

Four defects were found by reading the rendered output rather than the assertions, and one by building a fixture that did not exist yet. They are listed in the pull requests.

Closing. What is not here is anything that needed an XAF licence, a compilation, or a network.