repo study · v0.6

Understand the code before your AI changes it.

Took over a codebase, or about to touch logic you don't know well? One command maps a flow from the code itself and writes a living document your team and your AI can both use.

Map the flow

terminal

stet study "reconciliation"

output

✓ Studied "reconciliation" → docs/flows/reconciliation.md
  5 key files · 2 supporting · 3 entry points · 1 tests · flow diagram (mermaid)
    src/recon/engine.js
    src/integrations/xero.js
    api/recon_service.py
  ! 6 of 7 files in this flow aren't protected by a lock — suggestions are in the doc.
  Next: stet context --flow reconciliation and ask your AI to explain it (prompt in the doc).

Use the words your code uses: "reconciliation", "xero sync", "checkout", "export".

What's in the document

At a glanceHow many key files, supporting files, entry points and tests, and how much of it is protected.

Entry pointsThe routes that lead into it: Express, Fastify, FastAPI, Flask, NestJS and Django path().

FlowA Mermaid diagram of which file uses which. GitHub, GitLab and most editors render it.

Key files + supporting filesThe files about the topic, and the files they depend on — often where the actual rules live — with their main functions.

Tests that cover itTest files that import these files or are about the topic.

What protects itWhich files are covered by a lock or a protected path, and ready-to-run stet lock commands for the gaps.

Recent changes + decisionsThe last commits that touched these files, and decisions in your log about the topic.

How it works + NotesYour sections. Paste your AI's explanation and add gotchas; Stet keeps them on every refresh.

docs/flows/reconciliation.md · flow

flowchart LR
  r0["POST /reconcile"] --> routes/recon.js
  routes/recon.js --> recon/engine.js
  integrations/xero.js --> recon/engine.js
  recon/engine.js --> recon/rules.js
  recon/engine.js --> money/round.js

Get the explanation from your AI

terminal

stet context --flow reconciliation     # the doc + every file in the flow, copied to your clipboard

Paste it into ChatGPT or Claude with the prompt at the bottom of the doc. It asks the AI to explain the flow step by step from the entry points, naming files and functions, listing business rules and edge cases, and flagging what looks risky or untested — using only the code provided. Paste the answer into the doc's How it works section.

Protect what you just understood

The doc lists unprotected files and gives you the commands, for example:

terminal

stet lock add "Reconciliation works" --cmd "node --test tests/recon.test.js" --protect "src/recon/**"
stet lock add "Reconciliation output is stable" --snapshot "node scripts/recon-sample.js"

See snapshot locks for locking behaviour without writing a test.

Keep it true

terminal

stet study                     # lists flows; flags ones whose code changed since written
stet study "reconciliation"    # refresh: the generated part updates, your notes stay

stet status shows out-of-date flows, and stet handoff links every flow, so a new developer or CTO starts from them. Imports and routes are understood for JavaScript/TypeScript and Python; other languages get key files, functions and tests.